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

Neural Search API

원문 보기 위키 갱신

출처: 문서

본문

Neural Search API

Neural Search 플러그인은 시맨틱 검색과 하이브리드 검색 기능을 모니터링하기 위한 여러 APIs를 제공해요.

Stats

Neural Search Stats API는 Neural Search 플러그인의 현재 상태에 대한 정보를 제공해요. 여기에는 클러스터 수준과 노드 수준 통계가 모두 포함돼요. 클러스터 수준 통계는 전체 클러스터에 대해 하나의 값을 가지고, 노드 수준 통계는 클러스터의 각 노드에 대해 하나의 값을 가져요.

기본적으로 Neural Search Stats API는 클러스터 설정을 통해 비활성화되어 있어요. 통계 수집을 활성화하려면 다음 명령어를 사용하세요:

PUT /_cluster/settings
{
  "persistent": {
    "plugins.neural_search.stats_enabled": true
  }
}

{% include copy-curl.html %}

통계 수집을 비활성화하려면 클러스터 설정을 false로 설정하세요. 비활성화되면 모든 값이 재설정되고 새로운 통계가 수집되지 않아요.

엔드포인트

GET /_plugins/_neural/stats
GET /_plugins/_neural/stats/{stats}
GET /_plugins/_neural/{nodes}/stats
GET /_plugins/_neural/{nodes}/stats/{stats}

경로 매개변수

다음 표는 사용 가능한 경로 매개변수를 나열해요. 모든 경로 매개변수는 선택 사항이에요.

Parameter Data type Description
nodes String 통계를 필터링할 노드 또는 노드 목록(쉼표로 구분)이에요. 기본값은 모든 노드예요.
stats String 반환할 통계 이름 또는 이름들(쉼표로 구분)이에요. 기본값은 모든 통계예요.

쿼리 매개변수

다음 표는 사용 가능한 쿼리 매개변수를 나열해요. 모든 쿼리 매개변수는 선택 사항이에요.

Parameter Data type Description
include_metadata Boolean true로 설정하면 각 통계에 추가 메타데이터 필드가 포함돼요(사용 가능한 메타데이터 참조). 기본값은 false예요.
flat_stat_paths Boolean true로 설정하면 JSON 응답 구조를 평탄화하여 더 쉽게 파싱할 수 있어요. 기본값은 false예요.
include_individual_nodes Boolean true로 설정하면 nodes 카테고리에 개별 노드의 통계가 포함돼요. false로 설정하면 응답에서 nodes 카테고리가 제외돼요. 기본값은 true예요.
include_all_nodes Boolean true로 설정하면 all_nodes 카테고리에 모든 노드의 집계 통계가 포함돼요. false로 설정하면 응답에서 all_nodes 카테고리가 제외돼요. 기본값은 true예요.
include_info Boolean true로 설정하면 info 카테고리에 클러스터 전체 정보가 포함돼요. false로 설정하면 응답에서 info 카테고리가 제외돼요. 기본값은 true예요.

예제 요청

GET /_plugins/_neural/node1,node2/stats/stat1,stat2?include_metadata=true,flat_stat_paths=true

{% include copy-curl.html %}

예제 응답

응답 {: .text-delta} 
GET /_plugins/_neural/stats/
{
	"_nodes": {
		"total": 1,
		"successful": 1,
		"failed": 0
	},
	"cluster_name": "integTest",
	"info": {
		"cluster_version": "3.1.0",
		"processors": {
			"search": {
				"hybrid": {
					"comb_geometric_processors": 0,
					"comb_rrf_processors": 0,
					"norm_l2_processors": 0,
					"norm_minmax_processors": 0,
					"comb_harmonic_processors": 0,
					"comb_arithmetic_processors": 0,
					"norm_zscore_processors": 0,
					"rank_based_normalization_processors": 0,
					"normalization_processors": 0
				},
				"rerank_ml_processors": 0,
				"rerank_by_field_processors": 0,
				"neural_sparse_two_phase_processors": 0,
				"neural_query_enricher_processors": 0
			},
			"ingest": {
				"sparse_encoding_processors": 0,
				"skip_existing_processors": 0,
				"text_image_embedding_processors": 0,
				"text_chunking_delimiter_processors": 0,
				"text_embedding_processors_in_pipelines": 0,
				"text_chunking_fixed_token_length_processors": 0,
				"text_chunking_fixed_char_length_processors": 0,
				"text_chunking_processors": 0
			}
		}
	},
	"all_nodes": {
		"query": {
			"hybrid": {
				"hybrid_query_with_pagination_requests": 0,
				"hybrid_query_with_filter_requests": 0,
				"hybrid_query_with_inner_hits_requests": 0,
				"hybrid_query_requests": 0
			},
			"neural": {
				"neural_query_against_semantic_sparse_requests": 0,
				"neural_query_requests": 0,
				"neural_query_against_semantic_dense_requests": 0,
				"neural_query_against_knn_requests": 0
			},
			"neural_sparse": {
				"neural_sparse_query_requests": 0,
                "seismic_query_requests": 0
			}
		},
		"semantic_highlighting": {
			"semantic_highlighting_request_count": 0,
			"semantic_highlighting_batch_request_count": 0
		},
		"processors": {
			"search": {
				"neural_sparse_two_phase_executions": 0,
				"hybrid": {
					"comb_harmonic_executions": 0,
					"norm_zscore_executions": 0,
					"comb_rrf_executions": 0,
					"norm_l2_executions": 0,
					"rank_based_normalization_processor_executions": 0,
					"comb_arithmetic_executions": 0,
					"normalization_processor_executions": 0,
					"comb_geometric_executions": 0,
					"norm_minmax_executions": 0
				},
				"rerank_by_field_executions": 0,
				"neural_query_enricher_executions": 0,
				"rerank_ml_executions": 0
			},
			"ingest": {
				"skip_existing_executions": 0,
				"text_chunking_fixed_token_length_executions": 0,
				"sparse_encoding_executions": 0,
				"text_chunking_fixed_char_length_executions": 0,
				"text_chunking_executions": 0,
				"text_embedding_executions": 0,
				"semantic_field_executions": 0,
				"semantic_field_chunking_executions": 0,
				"text_chunking_delimiter_executions": 0,
				"text_image_embedding_executions": 0
			}
		},
        "memory": {
            "sparse": {
                "sparse_memory_usage": 0.13,
                "clustered_posting_usage": 0.06,
                "forward_index_usage": 0.06
            }
        }
	},
	"nodes": {
		"_cONimhxS6KdedymRZr6xg": {
			"query": {
				"hybrid": {
					"hybrid_query_with_pagination_requests": 0,
					"hybrid_query_with_filter_requests": 0,
					"hybrid_query_with_inner_hits_requests": 0,
					"hybrid_query_requests": 0
				},
				"neural": {
					"neural_query_against_semantic_sparse_requests": 0,
					"neural_query_requests": 0,
					"neural_query_against_semantic_dense_requests": 0,
					"neural_query_against_knn_requests": 0
				},
				"neural_sparse": {
					"neural_sparse_query_requests": 0,
                    "seismic_query_requests": 0
				},
                "memory": {
                    "sparse": {
                        "sparse_memory_usage_percentage": 0,
                        "sparse_memory_usage": 0.13,
                        "clustered_posting_usage": 0.06,
                        "forward_index_usage": 0.06
                    }
                }
			},
			"semantic_highlighting": {
				"semantic_highlighting_request_count": 0,
				"semantic_highlighting_batch_request_count": 0
			},
			"processors": {
				"search": {
					"neural_sparse_two_phase_executions": 0,
					"hybrid": {
						"comb_harmonic_executions": 0,
						"norm_zscore_executions": 0,
						"comb_rrf_executions": 0,
						"norm_l2_executions": 0,
						"rank_based_normalization_processor_executions": 0,
						"comb_arithmetic_executions": 0,
						"normalization_processor_executions": 0,
						"comb_geometric_executions": 0,
						"norm_minmax_executions": 0
					},
					"rerank_by_field_executions": 0,
					"neural_query_enricher_executions": 0,
					"rerank_ml_executions": 0
				},
				"ingest": {
					"skip_existing_executions": 0,
					"text_chunking_fixed_token_length_executions": 0,
					"sparse_encoding_executions": 0,
					"text_chunking_fixed_char_length_executions": 0,
					"text_chunking_executions": 0,
					"text_embedding_executions": 0,
					"semantic_field_executions": 0,
					"semantic_field_chunking_executions": 0,
					"text_chunking_delimiter_executions": 0,
					"text_image_embedding_executions": 0
				}
			}
		}
	}
}

include_metadata가 true이면 각 통계 객체에 추가 메타데이터가 포함돼요:

{
    ...,
    "text_embedding_executions": {
      "value": 0,
      "stat_type": "timestamped_event_counter",
      "trailing_interval_value": 0,
      "minutes_since_last_event": 29061801
    },
    ...
}

자세한 내용은 사용 가능한 메타데이터를 참조하세요.

응답 본문 필드

다음 섹션에서는 응답 본문 필드를 설명해요.

통계 카테고리

다음 표는 모든 통계 카테고리를 나열해요.

Category Data type Description
info Object 클러스터 전체 정보와 개별 노드에 특화되지 않은 통계를 포함해요.
all_nodes Object 클러스터의 모든 노드에 대한 집계 통계를 제공해요.
nodes Object 노드별 통계를 포함하며, 각 노드는 고유 노드 ID로 식별돼요.

사용 가능한 통계

다음 표는 사용 가능한 통계를 나열해요. 경로가 nodes.<node_id>로 시작하는 통계의 경우, all_nodes로 시작하는 동일한 경로에서 집계 클러스터 수준 통계도 사용할 수 있어요.

Statistic name Category Statistic path within category Description
cluster_version info cluster_version 클러스터 버전이에요.

정보 통계: 프로세서

Statistic name Category Statistic path within category Description
text_embedding_processors_in_pipelines info processors.ingest.text_embedding_processors_in_pipelines 수집 파이프라인의 text_embedding 프로세서 수예요.
sparse_encoding_processors info processors.ingest.sparse_encoding_processors 수집 파이프라인의 sparse_encoding 프로세서 수예요.
skip_existing_processors info processors.ingest.skip_existing_processors 수집 파이프라인에서 skip_existing이 true로 설정된 프로세서 수예요.
text_image_embedding_processors info processors.ingest.text_image_embedding_processors 수집 파이프라인의 text_image_embedding 프로세서 수예요.
text_chunking_delimiter_processors info processors.ingest.text_chunking_delimiter_processors 수집 파이프라인에서 delimiter 알고리즘을 사용하는 text_chunking 프로세서 수예요.
text_chunking_fixed_token_length_processors info processors.ingest.text_chunking_fixed_token_length_processors 수집 파이프라인에서 fixed_token_length 알고리즘을 사용하는 text_chunking 프로세서 수예요.
text_chunking_fixed_char_length_processors info processors.ingest.text_chunking_fixed_char_length_processors 수집 파이프라인에서 fixed_character_length 알고리즘을 사용하는 text_chunking 프로세서 수예요.
text_chunking_processors info processors.ingest.text_chunking_processors 수집 파이프라인의 text_chunking 프로세서 수예요.
rerank_ml_processors info processors.search.rerank_ml_processors 검색 파이프라인에서 ml_opensearch 유형의 rerank 프로세서 수예요.
rerank_by_field_processors info processors.search.rerank_by_field_processors by_field 유형의 rerank 프로세서 수예요.
neural_sparse_two_phase_processors info processors.search.neural_sparse_two_phase_processors 검색 파이프라인의 neural_sparse_two_phase_processor 프로세서 수예요.
neural_query_enricher_processors info processors.search.neural_query_enricher_processors 검색 파이프라인의 neural_query_enricher 프로세서 수예요.

정보 통계: 하이브리드 프로세서

Statistic name Category Statistic path within category Description
normalization_processors info processors.search.hybrid.normalization_processors normalization-processor 프로세서 수예요.
norm_minmax_processors info processors.search.hybrid.norm_minmax_processors normalization.technique가 min_max로 설정된 normalization-processor 프로세서 수예요.
norm_l2_processors info processors.search.hybrid.norm_l2_processors normalization.technique가 l2로 설정된 normalization-processor 프로세서 수예요.
norm_zscore_processors info processors.search.hybrid.norm_zscore_processors normalization.technique가 z_score로 설정된 normalization-processor 프로세서 수예요.
comb_arithmetic_processors info processors.search.hybrid.comb_arithmetic_processors combination.technique가 arithmetic_mean으로 설정된 normalization-processor 프로세서 수예요.
comb_geometric_processors info processors.search.hybrid.comb_geometric_processors combination.technique가 geometric_mean으로 설정된 normalization-processor 프로세서 수예요.
comb_harmonic_processors info processors.search.hybrid.comb_harmonic_processors combination.technique가 harmonic_mean으로 설정된 normalization-processor 프로세서 수예요.
rank_based_normalization_processors info processors.search.hybrid.rank_based_normalization_processors score-ranker-processor 프로세서 수예요.
comb_rrf_processors info processors.search.hybrid.comb_rrf_processors combination.technique가 rrf로 설정된 score-ranker-processor 프로세서 수예요.

노드 수준 통계: 프로세서

Statistic name Category Statistic path within category Description
text_embedding_executions nodes, all_nodes processors.ingest.text_embedding_executions text_embedding 프로세서 실행 횟수예요.
skip_existing_executions nodes, all_nodes processors.ingest.skip_existing_executions skip_existing이 true로 설정된 프로세서 실행 횟수예요.
text_chunking_fixed_token_length_executions nodes, all_nodes processors.ingest.text_chunking_fixed_token_length_executions fixed_token_length 알고리즘을 사용하는 text_chunking 프로세서 실행 횟수예요.
sparse_encoding_executions nodes, all_nodes processors.ingest.sparse_encoding_executions sparse_encoding 프로세서 실행 횟수예요.
text_chunking_fixed_char_length_executions nodes, all_nodes processors.ingest.text_chunking_fixed_char_length_executions fixed_character_length 알고리즘을 사용하는 text_chunking 프로세서 실행 횟수예요.
text_chunking_executions nodes, all_nodes processors.ingest.text_chunking_executions text_chunking 프로세서 실행 횟수예요.
semantic_field_executions nodes, all_nodes processors.ingest.semantic_field_executions semantic 필드 시스템 프로세서 실행 횟수예요.
semantic_field_chunking_executions nodes, all_nodes processors.ingest.semantic_field_chunking_executions semantic 필드 시스템 청킹 프로세서 실행 횟수예요.
text_chunking_delimiter_executions nodes, all_nodes processors.ingest.text_chunking_delimiter_executions delimiter 알고리즘을 사용하는 text_chunking 프로세서 실행 횟수예요.
text_image_embedding_executions nodes, all_nodes processors.ingest.text_image_embedding_executions text_image_embedding 프로세서 실행 횟수예요.
neural_sparse_two_phase_executions nodes, all_nodes processors.search.neural_sparse_two_phase_executions neural_sparse_two_phase_processor 프로세서 실행 횟수예요.
rerank_by_field_executions nodes, all_nodes processors.search.rerank_by_field_executions by_field 유형의 rerank 프로세서 실행 횟수예요.
neural_query_enricher_executions nodes, all_nodes processors.search.neural_query_enricher_executions neural_query_enricher 프로세서 실행 횟수예요.
rerank_ml_executions nodes, all_nodes processors.search.rerank_ml_executions ml_opensearch 유형의 rerank 프로세서 실행 횟수예요.

노드 수준 통계: 하이브리드 프로세서

Statistic name Category Statistic path within category Description
normalization_processor_executions nodes, all_nodes processors.search.hybrid.normalization_processor_executions normalization-processor 프로세서 실행 횟수예요.
rank_based_normalization_processor_executions nodes, all_nodes processors.search.hybrid.rank_based_normalization_processor_executions score-ranker-processor 프로세서 실행 횟수예요.
comb_harmonic_executions nodes, all_nodes processors.search.hybrid.comb_harmonic_executions combination.technique가 harmonic_mean으로 설정된 normalization-processor 프로세서 실행 횟수예요.
norm_zscore_executions nodes, all_nodes processors.search.hybrid.norm_zscore_executions normalization.technique가 z_score로 설정된 normalization-processor 프로세서 실행 횟수예요.
comb_rrf_executions nodes, all_nodes processors.search.hybrid.comb_rrf_executions combination.technique가 rrf로 설정된 score-ranker-processor 프로세서 실행 횟수예요.
norm_l2_executions nodes, all_nodes processors.search.hybrid.norm_l2_executions normalization.technique가 l2로 설정된 normalization-processor 프로세서 실행 횟수예요.
comb_arithmetic_executions nodes, all_nodes processors.search.hybrid.comb_arithmetic_executions combination.technique가 arithmetic_mean으로 설정된 normalization-processor 프로세서 실행 횟수예요.
comb_geometric_executions nodes, all_nodes processors.search.hybrid.comb_geometric_executions combination.technique가 geometric_mean으로 설정된 normalization-processor 프로세서 실행 횟수예요.
norm_minmax_executions nodes, all_nodes processors.search.hybrid.norm_minmax_executions normalization.technique가 min_max로 설정된 normalization-processor 프로세서 실행 횟수예요.

노드 수준 통계: 쿼리

통계 이름 카테고리 카테고리 내 통계 경로 설명
hybrid_query_with_pagination_requests nodes, all_nodes query.hybrid.hybrid_query_with_pagination_requests 페이지네이션이 있는 hybrid 쿼리 요청 수입니다.
hybrid_query_with_filter_requests nodes, all_nodes query.hybrid.hybrid_query_with_filter_requests 필터가 있는 hybrid 쿼리 요청 수입니다.
hybrid_query_with_inner_hits_requests nodes, all_nodes query.hybrid.hybrid_query_with_inner_hits_requests inner hits가 있는 hybrid 쿼리 요청 수입니다.
hybrid_query_requests nodes, all_nodes query.hybrid.hybrid_query_requests hybrid 쿼리 요청의 총 수입니다.
neural_query_against_semantic_sparse_requests nodes, all_nodes query.neural.neural_query_against_semantic_sparse_requests 시맨틱 희소 필드에 대한 neural 쿼리 요청 수입니다.
neural_query_requests nodes, all_nodes query.neural.neural_query_requests neural 쿼리 요청의 총 수입니다.
neural_query_against_semantic_dense_requests nodes, all_nodes query.neural.neural_query_against_semantic_dense_requests 시맨틱 밀집 필드에 대한 neural 쿼리 요청 수입니다.
neural_query_against_knn_requests nodes, all_nodes query.neural.neural_query_against_knn_requests k-NN 필드에 대한 neural 쿼리 요청 수입니다.
neural_sparse_query_requests nodes, all_nodes query.neural_sparse.neural_sparse_query_requests rank_features 필드에 대한 neural_sparse 쿼리 요청 수입니다(기존 신경 희소 검색).
seismic_query_requests nodes, all_nodes query.neural_sparse.seismic_query_requests sparse_vector 필드에 대한 neural_sparse 쿼리 요청 수입니다(SEISMIC 알고리즘을 사용한 신경 희소 근사 최근접 이웃(ANN) 검색).

노드 수준 통계: 메모리

통계 이름 카테고리 카테고리 내 통계 경로 설명
sparse_memory_usage_percentage nodes memory.sparse.sparse_memory_usage_percentage 최대 JVM 메모리 대비 노드의 희소 데이터 저장에 사용된 JVM 힙 메모리 비율입니다.
sparse_memory_usage nodes, all_nodes memory.sparse.sparse_memory_usage 노드의 희소 데이터 저장에 사용된 JVM 힙 메모리 양(킬로바이트)입니다.
clustered_posting_usage nodes, all_nodes memory.sparse.clustered_posting_usage 노드의 클러스터된 포스팅 저장에 사용된 JVM 힙 메모리 양(킬로바이트)입니다.
forward_index_usage nodes, all_nodes memory.sparse.forward_index_usage 노드의 순방향 인덱스 저장에 사용된 JVM 힙 메모리 양(킬로바이트)입니다.

이 메모리 통계는 Lucene 엔진 캐시만 보고합니다. 네이티브 엔진은 인덱스를 디스크의 메모리 매핑 파일에 저장하므로 네이티브 엔진 인덱스 메모리는 이 통계에 반영되지 않습니다. 자세한 내용은 Engines를 참조하세요. {: .note}

노드 수준 통계: 시맨틱 하이라이팅

통계 이름 카테고리 카테고리 내 통계 경로 설명
semantic_highlighting_request_count nodes, all_nodes semantic_highlighting.semantic_highlighting_request_count 단일 추론 semantic 하이라이팅 요청 수입니다(문서당 한 번의 추론 호출). 단일 추론 모드를 참조하세요.
semantic_highlighting_batch_request_count nodes, all_nodes semantic_highlighting.semantic_highlighting_batch_request_count 배치 추론 semantic 하이라이팅 요청 수입니다(단일 추론 호출에서 여러 문서 처리). 배치 추론 모드를 참조하세요.

사용 가능한 메타데이터

include_metadata가 true인 경우 응답의 필드 값은 각각의 메타데이터 객체로 대체되며, 여기에는 다음 표에 설명된 대로 통계 유형에 대한 추가 정보가 포함됩니다.

통계 유형 설명
info_string 버전이나 이름과 같은 정보 콘텐츠를 제공하는 기본 문자열 값입니다. info_string을 참조하세요.
info_counter 정적이거나 느리게 변경되는 값을 나타내는 숫자 카운터입니다. info_counter를 참조하세요.
timestamped_event_counter 최근 활동에 대한 정보를 포함하여 시간 경과에 따른 이벤트를 추적하는 카운터입니다. timestamped_event_counter를 참조하세요.

info_string 객체에는 다음 메타데이터 필드가 포함됩니다.

메타데이터 필드 데이터 유형 설명
value String 통계의 실제 문자열 값입니다.
stat_type String 항상 info_string으로 설정됩니다.

info_counter 객체에는 다음 메타데이터 필드가 포함됩니다.

메타데이터 필드 데이터 유형 설명
value Integer 현재 카운트 값입니다.
stat_type String 항상 info_counter로 설정됩니다.

timestamped_event_counter 객체에는 다음 메타데이터 필드가 포함됩니다.

메타데이터 필드 데이터 유형 설명
value Integer 노드가 시작된 이후 발생한 총 이벤트 수입니다.
stat_type String 항상 timestamped_event_counter로 설정됩니다.
trailing_interval_value Integer 지난 5분 동안 발생한 이벤트 수입니다.
minutes_since_last_event Integer 마지막으로 기록된 이벤트 이후의 시간(분)입니다.

워밍업

3.3에서 도입됨 {: .label .label-purple }

희소 인덱스는 neural sparse ANN 검색을 지원합니다. 검색 효율성을 극대화하기 위해 OpenSearch는 희소 데이터를 JVM 메모리에 캐싱합니다.

초기 검색 시 높은 지연 시간을 피하기 위해 워밍업 기간 동안 무작위 쿼리를 실행할 수 있습니다. 워밍업 기간이 지나면 희소 데이터가 JVM 메모리에 저장되며, 프로덕션 워크로드를 시작할 수 있습니다. 하지만 이 방법은 간접적이며 추가 노력이 필요합니다.

대안으로, 워밍업 API 작업을 사용하여 초기 검색 시 지연 시간을 피할 수 있습니다. 이 작업은 지정된 인덱스의 프라이머리 샤드와 복제본 샤드에 대한 모든 희소 데이터를 JVM 메모리에 로드합니다. 워밍업 API 작업은 멱등적입니다. 세그먼트의 희소 데이터가 이미 메모리에 로드되어 있으면 이 작업은 아무 효과가 없습니다. 현재 메모리에 저장되지 않은 파일만 로드합니다.

이 API 작업은 필드가 Lucene 엔진을 사용하는 희소 인덱스(index.sparse가 true로 설정된 인덱스)에서만 작동합니다. 네이티브 엔진은 JVM 힙 캐시 대신 메모리 매핑된 파일에서 인덱스를 읽으므로 워밍업할 내용이 없습니다. 자세한 내용은 엔진을 참조하세요. {: .note}

엔드포인트

POST /_plugins/_neural/warmup/{index}

경로 매개변수

다음 표는 사용 가능한 경로 매개변수를 나열합니다.

매개변수 데이터 타입 설명
<index> String 워밍업할 인덱스 이름 또는 이름(쉼표로 구분)입니다. 와일드카드(*)를 지원합니다. 필수입니다.

요청 예시

다음 요청은 세 개의 인덱스에 대해 워밍업 작업을 수행합니다:

POST /_plugins/_neural/warmup/index1,index2,index3

{% include copy-curl.html %}

인덱스 패턴과 함께 워밍업 API 작업을 사용하여 지정된 패턴과 일치하는 하나 이상의 인덱스를 캐시에 로드할 수 있습니다:

POST /_plugins/_neural/warmup/index*

{% include copy-curl.html %}

응답 예시

API 호출은 워밍업 작업이 완료되거나 요청이 시간 초과된 후에만 결과를 반환합니다:

{
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "failed" : 0
  }
}

요청이 시간 초과되면 작업은 클러스터에서 계속됩니다.

워밍업 작업을 모니터링하려면 Tasks API를 사용하세요:

GET /_tasks

{% include copy-curl.html %}

작업이 완료된 후에는 neural stats API 작업을 사용하여 업데이트된 메모리 사용량을 모니터링하세요.

응답 본문 필드

다음 표는 모든 응답 본문 필드를 나열합니다.

필드 데이터 타입 설명
_shards.total Integer OpenSearch가 워밍업을 시도한 총 샤드 수입니다.
_shards.successful Integer 성공적으로 워밍업된 샤드 수입니다.
_shards.failed Integer 워밍업에 실패한 샤드 수입니다.

모범 사례

워밍업 작업이 제대로 작동하도록 하려면 다음 모범 사례를 따르세요:

  • 워밍업하려는 인덱스에서 병합 작업을 실행하지 마세요: 병합 작업 중에 OpenSearch는 새 세그먼트를 생성하고 이전 세그먼트를 삭제할 수 있습니다. 예를 들어, 워밍업 API 작업이 희소 인덱스 A와 B를 네이티브 메모리에 로드했지만, 병합이 A와 B에서 새 세그먼트 C를 생성하면 A와 B는 메모리에서 제거되지만 C는 아직 로드되지 않습니다. 이 경우 희소 인덱스 C에 대한 초기 로딩 지연이 여전히 발생합니다.

  • 워밍업하려는 모든 희소 인덱스가 JVM 메모리에 맞는지 확인하세요. 메모리 제한에 대한 자세한 내용은 neural_search.circuit_breaker.limit를 참조하세요.

캐시 지우기

3.3에서 도입됨 {: .label .label-purple }

neural sparse ANN 검색 또는 워밍업 작업 중에 희소 데이터가 JVM 메모리에 로드됩니다. 해당 인덱스를 삭제하여 이 데이터를 제거할 수 있습니다.

반면, neural search circuit breaker limit을 낮춰도 캐시된 희소 데이터가 즉시 제거되지는 않습니다. 캐시된 데이터를 수동으로 지우려면 neural search clear cache API 작업을 사용하세요. 이 작업은 요청에 지정된 인덱스의 모든 샤드(프라이머리 및 복제본)에 대한 모든 인메모리 희소 데이터를 제거합니다.

워밍업 작업과 유사하게, clear cache 작업은 멱등적입니다. 이미 제거된 인덱스의 캐시를 지우려고 시도하면 작업이 추가 효과를 내지 않습니다.

이 API 작업은 필드가 Lucene 엔진을 사용하는 희소 인덱스(index.sparse가 true로 설정된 인덱스)에서만 작동합니다. 네이티브 엔진은 플러그인 관리 캐시를 사용하지 않으므로 지울 내용이 없습니다. 자세한 내용은 엔진을 참조하세요. {: .note}

엔드포인트

POST /_plugins/_neural/clear_cache/{index}

경로 매개변수

다음 표는 사용 가능한 경로 매개변수를 나열합니다.

매개변수 데이터 타입 설명
<index> String 캐시를 지울 인덱스 이름 또는 이름(쉼표로 구분)입니다. 와일드카드(*)를 지원합니다. 필수입니다.

요청 예시

다음 요청은 지정된 세 개 인덱스의 희소 데이터를 JVM 메모리에서 지웁니다:

POST /_plugins/_neural/clear_cache/index1,index2,index3

{% include copy-curl.html %}

인덱스 패턴을 사용하여 패턴과 일치하는 하나 이상의 인덱스를 지울 수도 있습니다:

POST /_plugins/_neural/clear_cache/index*

{% include copy-curl.html %}

응답 예시

API 호출은 clear cache 작업이 완료되거나 요청이 시간 초과된 후에만 결과를 반환합니다:

{
  "_shards" : {
    "total" : 6,
    "successful" : 6,
    "failed" : 0
  }
}

요청이 시간 초과되면 작업은 클러스터에서 계속 실행됩니다.

clear cache 작업의 진행 상황을 모니터링하려면 Tasks API를 사용하세요:

GET /_tasks

{% include copy-curl.html %}

작업이 완료된 후에는 neural stats API 작업을 사용하여 업데이트된 메모리 사용량을 확인하세요.

응답 본문 필드

다음 표는 모든 응답 본문 필드를 나열합니다.

필드 데이터 타입 설명
_shards.total Integer OpenSearch가 캐시 지우기를 시도한 총 샤드 수입니다.
_shards.successful Integer 캐시가 성공적으로 지워진 샤드 수입니다.
_shards.failed Integer 캐시 지우기에 실패한 샤드 수입니다.

더 알아보기 (Learn more)

함께 읽는 실무 이야기

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