본문 바로가기
WIKI 기술 지식 베이스

Vector search settings

원문 보기 위키 갱신

출처: 문서

본문

벡터 검색 설정

OpenSearch는 다음과 같은 벡터 검색 설정을 지원해요. 동적 설정은 Cluster Settings API를 사용해 업데이트하고, 정적 설정은 각 노드의 opensearch.yml에서 구성해야 해요. 정적 설정과 동적 설정에 대해 더 자세히 알아보려면 OpenSearch 구성을 참고하세요.

k-NN 플러그인 설정

k-NN 플러그인은 다음과 같은 설정을 지원해요.

클러스터 설정

다음 k-NN 플러그인 설정은 클러스터 수준에서 적용돼요:

  • knn.algo_param.index_thread_qty (Dynamic, integer): 네이티브 라이브러리와 Lucene 라이브러리(OpenSearch 버전 2.19 이상)의 인덱스 생성에 사용되는 스레드 수예요. 이 값을 낮게 유지하면 k-NN 플러그인의 CPU 영향은 줄어들지만 인덱싱 성능도 떨어져요. CPU 코어가 32개 미만인 시스템에서는 기본값이 1이고, 32개 이상인 시스템에서는 4예요.

  • knn.cache.item.expiry.enabled (Dynamic, Boolean): 지정된 기간 동안 접근하지 않은 네이티브 라이브러리 인덱스를 메모리에서 제거할지 여부예요. 기본값은 false예요.

  • knn.cache.item.expiry.minutes (Dynamic, time unit): 네이티브 라이브러리 인덱스가 메모리에서 제거되기까지의 유휴 시간이에요. knn.cache.item.expiry.enabled가 true일 때만 적용돼요. 기본값은 3h예요.

  • knn.circuit_breaker.unset.percentage (Dynamic, percentage): 서킷 브레이커의 네이티브 메모리 사용량 임계값이에요. knn.circuit_breaker.triggered가 false로 유지되려면 메모리 사용량이 knn.memory.circuit_breaker.limit의 이 백분율보다 낮아야 해요. 기본값은 75예요.

  • knn.circuit_breaker.triggered (Dynamic, Boolean): 메모리 사용량이 knn.circuit_breaker.unset.percentage 값을 초과하면 true로 설정돼요. 기본값은 false예요.

  • knn.memory.circuit_breaker.limit (Dynamic, percentage or byte unit): 네이티브 라이브러리 인덱스의 네이티브 메모리 한도예요. 기본값 기준으로, 머신의 메모리가 100 GB이고 JVM이 32 GB를 사용한다면 k-NN 플러그인은 나머지 68 GB의 50%(34 GB)를 사용해요. 메모리 사용량이 이 값을 초과하면 플러그인은 가장 오래 사용되지 않은 네이티브 라이브러리 인덱스를 제거해요. 이 한도를 노드 수준에서 구성하려면 opensearch.yml에 node.attr.knn_cb_tier: "<tier-name>"을 추가하고 클러스터 설정에서 knn.memory.circuit_breaker.limit.<tier-name>을 설정하세요. 예를 들어 노드 티어를 node.attr.knn_cb_tier: "integ"로 정의하고 knn.memory.circuit_breaker.limit.integ: "80%"으로 설정할 수 있어요. 노드는 티어별 서킷 브레이커 한도가 구성되어 있으면 그 한도를 사용하고, 노드별 값이 설정되어 있지 않으면 클러스터 전체 설정을 사용해요. 기본값은 50%예요.

  • knn.memory.circuit_breaker.enabled (Dynamic, Boolean): k-NN 메모리 서킷 브레이커를 활성화할지 여부예요. 기본값은 true예요.

  • knn.model.index.number_of_shards (Dynamic, integer): 모델 시스템 인덱스에 사용할 샤드 수예요. 모델 시스템 인덱스는 근사 최근접 이웃(ANN) 검색에 사용되는 모델을 저장하는 OpenSearch 인덱스예요. 기본값은 1이에요.

  • knn.model.index.number_of_replicas (Dynamic, integer): 모델 시스템 인덱스에 사용할 레플리카 샤드 수예요. 멀티 노드 클러스터에서는 안정성을 높이려면 이 값을 최소 1로 설정하세요. 기본값은 1이에요.

  • knn.model.cache.size.limit (Dynamic, percentage): 모델 캐시 한도예요. JVM 힙의 25%를 초과할 수 없어요. 기본값은 10%예요.

  • knn.faiss.avx2.disabled (Static, Boolean): x64 아키텍처 머신에서 Faiss 엔진에 대해 SIMD 기반 libopensearchknn_faiss_avx2.so 라이브러리를 비활성화하고 최적화되지 않은 libopensearchknn_faiss.so 라이브러리를 로드할지 여부예요. 기본값은 false예요. 자세한 내용은 Single Instruction Multiple Data(SIMD) 최적화를 참고하세요.

  • knn.faiss.avx512.disabled (Static, Boolean): x64 아키텍처 머신에서 Faiss 엔진에 대해 SIMD 기반 libopensearchknn_faiss_avx512.so 라이브러리를 비활성화하고 libopensearchknn_faiss_avx2.so 또는 최적화되지 않은 libopensearchknn_faiss.so 라이브러리를 로드할지 여부예요. 기본값은 false예요. 자세한 내용은 SIMD 최적화를 참고하세요.

  • knn.faiss.avx512_spr.disabled (Static, Boolean): x64 아키텍처 머신에서 Faiss 엔진에 대해 SIMD 기반 libopensearchknn_faiss_avx512_spr.so 라이브러리를 비활성화하고 libopensearchknn_faiss_avx512.so, libopensearchknn_faiss_avx2.so, 또는 최적화되지 않은 libopensearchknn_faiss.so 라이브러리 중 하나를 로드할지 여부예요. 기본값은 false예요. 자세한 내용은 SIMD 최적화를 참고하세요.

  • knn.dynamic_mapping.enabled (Dynamic, Boolean): knn_vector 필드의 동적 매핑을 활성화할지 여부예요. 여기에는 매핑되지 않은 flat 숫자 배열에 대한 추론과 knn_vector를 match_mapping_type으로 참조하는 동적 템플릿이 포함돼요. 기본값은 false예요.

인덱스 설정

인덱스 설정에 정의된 여러 파라미터는 현재 지원 중단 단계를 거치고 있어요. 해당 파라미터는 인덱스 설정이 아닌 매핑에 설정하세요. 매핑에 설정된 파라미터는 인덱스 설정에 지정된 파라미터를 재정의하며, 인덱스가 서로 다른 파라미터를 가진 여러 knn_vector 필드를 가질 수 있도록 해줘요.

다음 k-NN 플러그인 설정은 인덱스 수준에서 적용돼요. 이 설정을 업데이트하는 방법은 인덱스 설정을 참고하세요:

  • index.knn (Static, Boolean): 인덱스가 자신의 knn_vector 필드를 위해 네이티브 라이브러리 인덱스를 빌드할지 여부예요. false이면 knn_vector 필드가 doc values에 저장되지만 근사 k-NN 검색은 비활성화돼요. 기본값은 false예요.

  • index.knn.algo_param.ef_search (Dynamic, integer): 검색 시 사용되는 최근접 이웃 동적 리스트의 크기예요(ef 또는 efSearch). 값이 높을수록 더 정확하지만 느린 검색이 돼요. 이 값은 조회하려는 최근접 이웃 수인 k보다 작을 수 없으며, k부터 데이터셋 크기까지의 어떤 값이든 될 수 있어요. 기본값은 100이에요.

  • index.knn.advanced.approximate_threshold (Dynamic, integer): OpenSearch가 ANN 검색을 위한 특수 데이터 구조를 만들기 전에 세그먼트가 담고 있어야 하는 벡터 수예요. 벡터 데이터 구조 생성을 비활성화하려면 -1로, 항상 생성하려면 0으로 설정하세요. 기본값은 0이에요.

  • index.knn.advanced.filtered_exact_search_threshold (Dynamic, integer): 필터링된 ANN 검색 중 OpenSearch가 exact search로 전환하는 필터링된 ID 임계값이에요. 세그먼트 내 필터링된 ID 수가 이 값보다 작으면 필터링된 ID에 대해 exact search가 수행돼요. 기본값은 -1이며, 이 경우 임계값이 적용되지 않아요.

  • index.knn.faiss.efficient_filter.disable_exact_search (Dynamic, Boolean): true이면 Faiss 효율적 필터링 근사 최근접 이웃(ANN) 검색이 k개 미만의 결과를 반환할 때 발생하는 exact search 폴백을 비활성화해요. 기본값은 false예요. 자세한 내용은 exact search 폴백 비활성화를 참고하세요.

  • index.knn.derived_source.enabled (Static, Boolean): 벡터가 _source에 저장되지 않도록 막아 벡터 인덱스의 디스크 사용량을 줄여요. index.knn을 true로 설정해 생성한 인덱스에서는 기본값이 true이고, 그 외 모든 인덱스에서는 false예요.

  • index.knn.memory_optimized_search (Static, Boolean): 인덱스에서 메모리 최적화 검색을 활성화해요. 기본값은 false예요.

OpenSearch 버전 2.11 이하에서 생성된 인덱스는 여전히 이전 ef_construction 및 ef_search 값(512)을 사용해요. {: .note}

index.knn을 true로 설정한 상태에서 인덱스를 생성하면 k-NN 플러그인이 티어드 병합 정책 설정 두 가지도 낮춰서 병합이 검색과 CPU를 놓고 경쟁하는 정도를 줄여요. 즉 index.merge.policy.max_merge_at_once를 기본값인 30 대신 10으로, index.merge.policy.floor_segment를 기본값인 16mb 대신 2mb로 설정해요. 두 설정 모두 동적이므로 인덱스를 생성한 후에 변경할 수 있어요.

원격 인덱스 빌드 설정

다음 설정은 원격 벡터 인덱스 빌드를 제어해요.

클러스터 설정

다음 원격 인덱스 빌드 설정은 클러스터 수준에서 적용돼요:

  • knn.remote_index_build.enabled (Dynamic, Boolean): 클러스터에 대해 원격 벡터 인덱스 빌드를 활성화해요. 기본값은 false예요.

  • knn.remote_index_build.repository (Dynamic, string): 원격 인덱스 빌더가 쓰기를 수행할 등록된 리포지토리의 이름이에요. 기본값이 없으므로 원격 인덱스 빌드 서비스를 사용하기 전에 이 설정을 지정해야 해요.

  • knn.remote_index_build.service.endpoint (Dynamic, string): 원격 빌드 서비스의 엔드포인트 URL이에요. 기본값이 없으므로 원격 인덱스 빌드 서비스를 사용하기 전에 이 설정을 지정해야 해요.

  • knn.remote_index_build.poll.interval (Dynamic, time unit): 클라이언트가 작업 상태를 원격 빌드 서비스에 폴링하는 빈도예요. 기본값은 5s예요.

  • knn.remote_index_build.client.timeout (Dynamic, time unit): 원격 빌드가 완료되기를 기다리는 최대 시간이에요. 이 시간 안에 빌드가 완료되지 않으면 OpenSearch가 CPU에서 로컬로 인덱스를 빌드해요. 기본값은 60m이에요.

  • knn.remote_index_build.size.max (Dynamic, byte unit): 원격 인덱스 빌드 서비스가 허용하는 최대 세그먼트 크기예요. 이 설정은 사용 중인 원격 빌드 서비스 구현의 제약 조건에 맞게 설정하세요. 기본값은 0이며, 이 경우 세그먼트 크기에 상한이 없어요.

인덱스 설정

다음 원격 인덱스 빌드 설정은 인덱스 수준에서 적용돼요. 이 설정을 업데이트하는 방법은 인덱스 설정을 참고하세요:

  • index.knn.remote_index_build.enabled (Dynamic, Boolean): 인덱스에 대해 원격 인덱스 빌드를 활성화해요. knn.remote_index_build.enabled가 true일 때만 적용돼요. 기본값은 true예요.

  • index.knn.remote_index_build.size.min (Dynamic, byte unit): OpenSearch가 원격 인덱스 빌드 서비스를 사용하는 세그먼트의 최소 크기예요. 이보다 작은 세그먼트는 로컬에서 빌드돼요. 기본값은 50mb예요.

원격 빌드 인증

원격 빌드 서비스의 사용자 이름과 비밀번호는 OpenSearch keystore에 다음과 같이 설정해야 하는 보안 설정이에요:

./bin/opensearch-keystore add knn.remote_index_build.service.username
./bin/opensearch-keystore add knn.remote_index_build.service.password

{% include copy.html %}

Nodes Reload Secure Settings API를 사용하면 노드를 재시작하지 않고도 보안 설정을 다시 로드할 수 있어요.

Neural Search 플러그인 설정

Neural Search 플러그인은 다음 설정을 지원해요.

클러스터 설정

다음 Neural Search 플러그인 설정은 클러스터 수준에서 적용돼요. 동적 설정은 Cluster Settings API를 사용해 업데이트하고, 정적 설정은 각 노드의 opensearch.yml에서 구성해야 해요:

  • plugins.neural_search.stats_enabled (Dynamic, Boolean): Neural Search Stats API를 활성화해요. 기본값은 false예요.
  • plugins.neural_search.circuit_breaker.limit (Dynamic, percentage): neural sparse ANN search 서킷 브레이커의 JVM 메모리 한도를 지정해요. 이 한도는 Lucene 엔진이 사용하는 JVM 힙 캐시에만 적용되며, 운영체제 페이지 캐시에 의존하는 네이티브 엔진에는 영향을 주지 않아요. 기본값은 JVM 힙의 10%예요. 자세한 내용은 메모리 및 캐싱 설정을 참고하세요.
  • plugins.neural_search.circuit_breaker.overhead (Dynamic, Float): neural sparse ANN search의 메모리 사용량 추정값을 조정하는 데 사용하는 배수예요. 값이 클수록 더 보수적인 메모리 추정값을 제공해요. plugins.neural_search.circuit_breaker.limit와 마찬가지로 이 설정도 Lucene 엔진에만 적용돼요. 기본값은 1.0이에요.
  • plugins.neural_search.sparse.algo_param.index_thread_qty (Dynamic, Integer): neural sparse ANN search의 인덱스를 빌드하는 데 사용하는 스레드 수예요. 이 값을 늘리면 인덱스 빌드 작업에 더 많은 CPU가 할당되어 인덱싱 성능이 향상돼요. 유효한 값의 범위는 1부터 1024까지예요. 이 설정은 Lucene 엔진과 네이티브 엔진 모두에 적용돼요. 기본값은 1이에요. 자세한 내용은 스레드 풀 구성을 참고하세요.
  • plugins.neural_search.sparse.native_engine_feature_enabled (Static, Boolean): neural sparse ANN search용 네이티브 엔진을 사용할 수 있는지 여부예요. 이 설정은 정적 설정이므로 각 노드의 opensearch.yml에서 구성해야 하고, 변경하려면 노드를 재시작해야 해요. 기본값은 true예요.
  • plugins.neural_search.sparse.native_engine_enabled (Dynamic, Boolean): neural sparse ANN search용 네이티브 엔진이 런타임에 활성화되어 있는지 여부예요. 필드가 네이티브 엔진을 사용하려면 이 설정과 plugins.neural_search.sparse.native_engine_feature_enabled가 모두 true여야 해요. 기본값은 false예요. 자세한 내용은 네이티브 엔진 활성화를 참고하세요.

네이티브 엔진 인덱스가 사용하는 메모리 양을 제한하는 설정은 없어요. 네이티브 엔진은 메모리 매핑 파일에서 인덱스를 읽어 오기 때문에, 네이티브 엔진에 맞춰 노드 크기를 산정할 때는 다른 메모리 매핑 Lucene 데이터와 마찬가지로 운영체제 페이지 캐시를 위해 충분한 RAM을 남겨 두어야 해요. {: .note}

인덱스 설정

다음 Neural Search 플러그인 설정은 인덱스 수준에서 적용돼요:

  • index.neural_search.semantic_ingest_batch_size (Dynamic, integer): 수집 과정에서 semantic 필드의 임베딩을 생성할 때 한 번에 묶는 문서 수를 지정해요. 기본값은 10이에요.

  • index.neural_search.hybrid_collapse_distinct_groups_enabled (Dynamic, Boolean): true이면 collapse 파라미터를 포함하는 하이브리드 쿼리가 상위 size개의 고유한 그룹을 반환해요. false이면 점수는 collapse 파라미터가 제공되지 않았을 때 동일한 하이브리드 쿼리가 반환하는 점수와 일치하지만, 응답에 size개보다 적은 수의 그룹이 포함될 수 있어요. 기본값은 false예요. 자세한 내용은 고유한 그룹 반환을 참고하세요.

  • index.neural_search.hybrid_collapse_docs_per_group_per_subquery (Deprecated): 이 설정은 더 이상 사용되지 않으며 더 이상 어떤 영향도 미치지 않아요. 반환되는 문서 수는 전적으로 size 파라미터에 의해 결정돼요.

더 알아보기 (Learn more)

함께 읽는 실무 이야기

우리 조직에도 적용하고 싶다면, AI 시스템 구축 서비스를 살펴보세요.