StructArray 필드 인덱싱

벡터 검색을 실행하거나 스칼라 필터링 속도를 높이기 전에 StructArray 하위 필드에 인덱스를 생성하십시오. StructArray 필드의 경우 인덱스 대상은 chunks[emb_list_vector], chunks[emb] 또는 chunks[section] 와 같은 하위 필드 경로입니다.

이 페이지에서는 ‘StructArray 필드 생성’의 tech_articles 컬렉션을 사용합니다. chunks StructArray 필드에는 필터링용 스칼라 하위 필드와 검색용 벡터 하위 필드가 포함되어 있습니다.

시작하기 전에

컬렉션 스키마에 이미 chunks StructArray 필드가 포함되어 있고 데이터가 삽입되었는지 확인하십시오.

서브필드 경로	유형	인덱스 용도
chunks[emb_list_vector]	FLOAT_VECTOR	MAX_SIM* 메트릭을 사용한 EmbeddingList 검색.
chunks[emb]	FLOAT_VECTOR	일반 벡터 메트릭을 사용한 요소 수준 검색.
chunks[section]	VARCHAR	범주형 필터링.
chunks[quality_score]	FLOAT	숫자 필터링 및 범위형 술어.
chunks[has_code]	BOOL	부울 필터링.

인덱스 선택

검색 모드를 사용하여 벡터 메트릭 계열을 선택하십시오.

검색 또는 필터링 목표	대상 경로	선택 사항
EmbeddingList 검색	chunks[emb_list_vector]	MAX_SIM* 메트릭 패밀리.
요소 수준 벡터 검색	chunks[emb]	COSINE, IP 또는 L2 과 같은 일반 벡터 메트릭 계열입니다.
문자열 또는 범주별로 필터링	chunks[section]	대상에서 지원하는 스칼라 인덱스입니다.
숫자 범위별로 필터링	chunks[quality_score], chunks[page]	대상에서 지원하는 스칼라 인덱스.
부울 값으로 필터링	chunks[has_code]	대상에서 지원하는 스칼라 인덱스입니다.

EmbeddingList 검색은 StructArray 벡터 하위 필드의 벡터들을 임베딩 목록으로 취급하여 엔티티 수준의 결과를 반환합니다. 요소 수준 검색은 각 Struct 요소를 독립적으로 검색하며, 일치하는 요소의 오프셋을 반환할 수 있습니다.

벡터 인덱스 생성

다음 예제는 두 개의 벡터 인덱스를 생성합니다. 첫 번째 인덱스는 EmbeddingList 검색을 위해 MAX_SIM* 메트릭을 사용합니다. 두 번째 인덱스는 요소 수준 검색을 위해 일반 벡터 메트릭을 사용합니다.

from pymilvus import MilvusClient

client = MilvusClient(
    uri="http://localhost:19530",
    token="root:Milvus",
)

index_params = client.prepare_index_params()

# Index for EmbeddingList search.
index_params.add_index(
    field_name="chunks[emb_list_vector]",
    index_name="chunks_emb_list_max_sim",
    index_type="HNSW",
    metric_type="MAX_SIM_COSINE",
    params={
        "M": 16,
        "efConstruction": 200,
    },
)

# Index for element-level search.
index_params.add_index(
    field_name="chunks[emb]",
    index_name="chunks_emb_cosine",
    index_type="HNSW",
    metric_type="COSINE",
    params={
        "M": 16,
        "efConstruction": 200,
    },
)

client.create_index(
    collection_name="tech_articles",
    index_params=index_params,
)

스칼라 인덱스 생성

필터에서 StructArray 스칼라 하위 필드를 사용할 때는 해당 필드에 대한 스칼라 인덱스를 생성하십시오. structArray[subfield] 경로 구문을 동일하게 사용하십시오.

index_params = client.prepare_index_params()

index_params.add_index(
    field_name="chunks[section]",
    index_name="chunks_section_inverted",
    index_type="INVERTED",
)

index_params.add_index(
    field_name="chunks[has_code]",
    index_name="chunks_has_code_inverted",
    index_type="INVERTED",
)

index_params.add_index(
    field_name="chunks[quality_score]",
    index_name="chunks_quality_score_sort",
    index_type="STL_SORT",
)

index_params.add_index(
    field_name="chunks[page]",
    index_name="chunks_page_sort",
    index_type="STL_SORT",
)

client.create_index(
    collection_name="tech_articles",
    index_params=index_params,
)

스칼라 인덱스는 선택 사항이지만, ` element_filter(chunks, $[quality_score] > 0.9) `이나 ` MATCH_ANY(chunks, $[section] == "index")`과 같은 필터에서 StructArray 스칼라 서브필드가 자주 등장할 때 유용합니다.

인덱스 메트릭 호환성

다음 표를 참조하여 StructArray 벡터 하위 필드에 대한 인덱스 유형과 메트릭 유형을 선택하십시오. 대상부터 시작하여 검색 모드에 따라 메트릭 계열을 선택하십시오.

다음 호환성 표에서 Milvus 인덱스 유형과 메트릭 유형을 선택하십시오.

EmbeddingList 검색

EmbeddingList 검색은 MAX_SIM* 메트릭을 사용합니다. 이 검색은 StructArray 벡터 하위 필드의 벡터를 임베딩 목록으로 취급하며, 엔티티 수준의 결과를 반환합니다.

벡터 하위 필드 데이터 유형	인덱스 유형	메트릭 유형
FLOAT_VECTOR, FLOAT16_VECTOR, BFLOAT16_VECTOR	IVF_FLAT, IVF_FLAT_CC, HNSW, HNSW_SQ, HNSW_PQ, HNSW_PRQ, DISKANN	MAX_SIM, MAX_SIM_COSINE, MAX_SIM_IP, MAX_SIM_L2
INT8_VECTOR	HNSW, HNSW_SQ, HNSW_PQ, HNSW_PRQ	MAX_SIM, MAX_SIM_COSINE, MAX_SIM_IP, MAX_SIM_L2
BINARY_VECTOR	HNSW	MAX_SIM_HAMMING, MAX_SIM_JACCARD

요소 수준 검색

요소 수준 검색은 일반적인 벡터 메트릭을 사용합니다. 각 Struct 요소를 독립적으로 검색하며, 일치하는 요소의 오프셋을 반환할 수 있습니다.

벡터 서브필드 데이터 유형	인덱스 유형	메트릭 유형
FLOAT_VECTOR, FLOAT16_VECTOR, BFLOAT16_VECTOR	FLAT, IVF_FLAT, IVF_FLAT_CC, IVF_SQ8, IVF_SQ_CC, IVF_PQ, SCANN, IVF_RABITQ, IVF_RABITQ_FASTSCAN, HNSW, HNSW_SQ, HNSW_PQ, HNSW_PRQ, DISKANN	L2, IP, COSINE
INT8_VECTOR	HNSW, HNSW_SQ, HNSW_PQ, HNSW_PRQ	L2, IP, COSINE
BINARY_VECTOR	HNSW	HAMMING, JACCARD
BINARY_VECTOR	BIN_FLAT	HAMMING, JACCARD, SUBSTRUCTURE, SUPERSTRUCTURE, MHJACCARD
BINARY_VECTOR	BIN_IVF_FLAT	HAMMING, JACCARD

버전별 지원 사항 및 기타 제한 사항에 대해서는 StructArray 제한 사항을 참조하십시오.

인덱스 확인

인덱스를 생성한 후, 컬렉션 또는 목록 인덱스를 조회하여 예상한 하위 필드 경로가 인덱싱되었는지 확인하십시오.

indexes = client.list_indexes(
    collection_name="tech_articles",
)

print(indexes)

SDK 버전에 인덱스 설명 API가 제공되는 경우, 특정 인덱스를 설명할 수도 있습니다.

index = client.describe_index(
    collection_name="tech_articles",
    index_name="chunks_emb_cosine",
)

print(index)

인덱스 규칙

규칙	설명
서브필드 인덱스에는 경로 구문을 사용하십시오.	emb 이나 chunks.emb 대신 chunks[emb] 을 인덱스로 사용하십시오.
하나의 벡터 하위 필드에는 하나의 인덱스만 사용할 수 있습니다.	서로 다른 메트릭 계열이 필요한 경우 별도의 벡터 서브필드를 사용하십시오.
EmbeddingList 검색에는 MAX_SIM* 메트릭을 사용하십시오.	EmbeddingList 쿼리 데이터에는 MAX_SIM* 메트릭으로 구축된 인덱스가 필요합니다.
요소 수준 검색에는 일반 벡터 메트릭을 사용하십시오.	요소 수준 검색은 일반 벡터 쿼리 데이터와 COSINE, IP 또는 L2 와 같은 메트릭을 사용합니다.
필터에 나타나는 스칼라 하위 필드는 인덱싱하십시오.	대상에서 지원하는 스칼라 인덱스 유형을 사용하십시오.
벡터 필드 제한 사항을 염두에 두십시오.	벡터 필드와 벡터 하위 필드의 총 개수에는 제한이 있습니다. 벡터 하위 필드를 많이 추가하기 전에 StructArray 제한 사항을 참조하십시오.

흔히 저지르는 실수

• chunks[emb] 대신 chunks.emb 에 인덱스를 생성하는 경우.

• MAX_SIM* 인덱스만 생성한 후, 동일한 서브필드에서 요소 수준 검색을 실행하려고 시도하는 경우.

• 일반 벡터 인덱스만 생성한 후, 동일한 서브필드에서 EmbeddingList 검색을 실행하려는 경우.

• MAX_SIM* 와 일반 벡터 메트릭 모두에 하나의 벡터 하위 필드를 재사용하는 경우.

• 자주 사용되는 StructArray 필터에 대한 스칼라 인덱스를 생략하는 경우.

• Struct 스키마에 존재하지 않는 StructArray 서브필드에 인덱싱을 수행하는 경우.

다음 단계

1. 엔티티 수준 EmbeddingList 검색 또는 요소 수준 벡터 검색을 실행하려면 ‘StructArray를 사용한 기본 벡터 검색’을 참조하십시오.

2. 검색 중에 StructArray 스칼라 하위 필드를 필터링하려면 ‘StructArray를 사용한 필터링 검색’을 참조하십시오.

3. 인덱스 및 메트릭 제한 사항을 확인하려면 ‘StructArray 제한 사항’을 참조하십시오.