k-NN 쿼리

k-NN 쿼리

knn 쿼리를 사용해 벡터 필드에서 최근접 이웃(nearest neighbor) 검색을 실행할 수 있어요.

출처: 문서

본문

전송 프로토콜 (Transport protocols)

k-NN 쿼리는 두 가지 전송 프로토콜로 실행할 수 있어요.

• HTTP/REST API: 이 섹션에서 설명하는 표준 접근 방식이에요.
• gRPC API (3.2 버전에서 GA): k-NN (gRPC) API를 사용하는 고성능 이진 프로토콜이에요.

높은 처리량의 벡터 검색 애플리케이션에서는 gRPC k-NN API를 사용하는 것을 고려해 보세요. 이 API는 HTTP 기반 쿼리보다 더 낮은 지연 시간과 더 높은 처리량을 제공합니다.

요청 본문 필드 (Request body fields)

knn 쿼리에 벡터 필드를 제공하고 벡터 필드 객체에 추가 요청 필드를 지정해요.

"knn": {
  "": {
    "vector": [],
    "k": ,
    ...
  }
}

최상위 vector_field는 검색 쿼리를 실행할 벡터 필드를 지정해요. 다음 표는 지원되는 모든 요청 필드를 나열해요.

• vector (Float 또는 bytes 배열, 필수): 벡터 검색에 사용할 쿼리 벡터예요. 벡터 요소의 데이터 유형은 검색되는 knn_vector 필드에 인덱싱된 벡터의 데이터 유형과 일치해야 해요.
• k (Integer, 선택): 반환할 최근접 이웃의 수예요. 유효 값은 [1, 10,000] 범위예요. max_distance나 min_score 중 하나가 지정되지 않는 한 필수예요.
• max_distance (Float, 선택): 검색 결과의 최대 거리 임계값이에요. k, max_distance, min_score 중 하나만 지정할 수 있어요. 자세한 내용은 Radial search를 참고하세요.
• min_score (Float, 선택): 검색 결과의 최소 점수 임계값이에요. k, max_distance, min_score 중 하나만 지정할 수 있어요. 자세한 내용은 Radial search를 참고하세요.
• filter (Object, 선택): k-NN 검색에 적용할 필터예요. 자세한 내용은 Vector search with filters를 참고하세요. 중요: 필터는 faiss 또는 lucene 엔진에서만 사용할 수 있어요.
• method_parameters (Object, 선택): 검색을 미세 조정하기 위한 추가 파라미터예요.
  • ef_search (Integer): 검사할 벡터 수예요(hnsw 방식용).
  • nprobes (Integer): 검사할 버킷 수예요(ivf 방식용). 자세한 내용은 "쿼리에서 방식 파라미터 지정"을 참고하세요.
• rescore (Object 또는 Boolean, 선택): 리스코어링 기능을 구성하는 파라미터예요.
  • oversample_factor (Float): 리스코어링 전에 검색할 후보 벡터 수를 제어해요. 유효 값은 [1.0, 100.0] 범위예요. in_memory 모드 필드(리스코어링 없음)에서는 기본값이 false이고, on_disk 모드 필드에서는 동적 값으로 활성화돼요. on_disk 모드에서 기본 oversample_factor는 compression_level로 결정됩니다. 자세한 내용은 compression level 표를 참고하세요. 기본 oversample_factor 1.0으로 리스코어링을 명시적으로 활성화하려면 rescore를 true로 설정하세요. 자세한 내용은 "리스코어링 결과"를 참고하세요.
• expand_nested_docs (Boolean, 선택): true일 때 각 부모 문서 안의 모든 중첩 필드 문서에 대한 점수를 검색해요. nested 쿼리와 함께 사용돼요. 자세한 내용은 Vector search with nested fields를 참고하세요.

예제 요청 (Example request)

GET /my-vector-index/_search
{
  "query": {
    "knn": {
      "my_vector": {
        "vector": [1.5, 2.5],
        "k": 3
      }
    }
  }
}

예제 요청: 중첩 필드 (Nested fields)

GET /my-vector-index/_search
{
  "_source": false,
  "query": {
    "nested": {
      "path": "nested_field",
      "query": {
        "knn": {
          "nested_field.my_vector": {
            "vector": [1,1,1],
            "k": 2,
            "expand_nested_docs": true
          }
        }
      },
      "inner_hits": {
        "_source": false,
        "fields":["nested_field.color"]
      },
      "score_mode": "max"
    }
  }
}

예제 요청: max_distance를 사용한 방사형 검색

다음 예제는 max_distance를 사용해 수행된 방사형(radial) 검색을 보여줘요.

GET /my-vector-index/_search
{
    "query": {
        "knn": {
            "my_vector": {
                "vector": [
                    7.1,
                    8.3
                ],
                "max_distance": 2
            }
        }
    }
}

예제 요청: min_score를 사용한 방사형 검색

다음 예제는 min_score를 사용해 수행된 방사형 검색을 보여줘요.

GET /my-vector-index/_search
{
  "query": {
    "knn": {
      "my_vector": {
        "vector": [7.1, 8.3],
        "min_score": 0.95
      }
    }
  }
}

쿼리에서 방식 파라미터 지정하기 (Specifying method parameters in the query)

2.16 버전부터 검색 요청에서 method_parameters를 제공할 수 있어요.

GET /my-vector-index/_search
{
  "size": 2,
  "query": {
    "knn": {
      "target-field": {
        "vector": [2, 3, 5, 6],
        "k": 2,
        "method_parameters" : {
          "ef_search": 100
        }
      }
    }
  }
}

이 파라미터는 인덱스를 만드는 데 사용된 엔진과 방식의 조합에 따라 달라요. 다음 섹션에서는 지원되는 method_parameters에 대한 정보를 제공해요.

ef_search

hnsw 방식을 사용해 만든 인덱스를 검색할 때 ef_search 파라미터를 제공할 수 있어요. ef_search 파라미터는 상위 k개의 최근접 이웃을 찾기 위해 검사할 벡터 수를 지정해요. ef_search 값이 높을수록 검색 지연 시간이 증가하는 대신 재현율(recall)이 개선됩니다. 값은 양수여야 해요.

다음 표는 지원되는 엔진에 대한 ef_search 파라미터 정보를 제공해요.

• nmslib (Deprecated): 방사형 쿼리 미지원. 쿼리에 ef_search가 있으면 index.knn.algo_param.ef_search 인덱스 설정을 덮어써요.
• faiss: 방사형 쿼리 지원. 쿼리에 ef_search가 있으면 index.knn.algo_param.ef_search 인덱스 설정을 덮어써요.
• lucene: 방사형 쿼리 미지원. 검색 쿼리를 만들 때 k를 지정해야 해요. k와 ef_search를 모두 제공하면 더 큰 값이 엔진에 전달돼요. ef_search가 k보다 크면 size 파라미터를 제공해 최종 결과 수를 k로 제한할 수 있어요.

nprobes

ivf 방식을 사용해 만든 인덱스를 검색할 때 nprobes 파라미터를 제공할 수 있어요. nprobes 파라미터는 상위 k개의 최근접 이웃을 찾기 위해 검사할 버킷 수를 지정해요. nprobes 값이 높을수록 검색 지연 시간이 증가하는 대신 재현율이 개선됩니다. 값은 양수여야 해요.

다음 표는 지원되는 엔진에 대한 nprobes 파라미터 정보를 제공해요.

• faiss: 쿼리에 nprobes가 있으면 인덱스를 만들 때 제공된 값을 덮어써요.

리스코어링 결과 (Rescoring results)

ef_search와 oversample_factor 파라미터를 제공해 검색을 미세 조정할 수 있어요.

oversample_factor 파라미터는 순위를 매기기 전에 검색이 후보 벡터를 오버샘플링하는 비율을 제어해요. 높은 oversample 비율을 사용하면 순위를 매기기 전에 더 많은 후보가 고려되어 정확도는 개선되지만 검색 시간도 늘어나요. oversample_factor 값을 선택할 때는 정확도와 효율 사이의 절충을 고려하세요. 예를 들어 oversample_factor를 2.0으로 설정하면 순위 계산 단계에서 고려되는 후보 수가 두 배로 늘어나 더 나은 결과를 얻는 데 도움이 될 수 있어요.

다음 요청은 ef_search와 oversample_factor 파라미터를 지정해요.

GET /my-vector-index/_search
{
  "size": 2,
  "query": {
    "knn": {
      "my_vector_field": {
        "vector": [1.5, 5.5, 1.5, 5.5, 1.5, 5.5, 1.5, 5.5],
        "k": 10,
        "method_parameters": {
            "ef_search": 10
        },
        "rescore": {
            "oversample_factor": 10.0
        }
      }
    }
  }
}

다음 단계 (Next steps)

• k-NN vector
• Rescoring quantized results to full precision

관련 문서 (Related documentation)

• k-NN query explain

더 알아보기 (Learn more)

• OpenSearch 공식 문서