StructArray를 사용한 기본 벡터 검색

이 페이지를 사용하여 StructArray 필드 내의 벡터 하위 필드에 대해 벡터 검색을 실행할 수 있습니다. StructArray는 두 가지 기본 벡터 검색 모드를 지원합니다. 하나는 각 엔티티에 저장된 임베딩 목록에 점수를 매기는 EmbeddingList 검색이고, 다른 하나는 각 Struct 요소를 독립적으로 검색하는 요소 수준 검색입니다.

이 페이지에서는 ‘StructArray 필드 생성’의 tech_articles 컬렉션을 사용합니다. 이 컬렉션에는 chunks 라는 StructArray 필드가 있습니다. 각 청크에는 텍스트, 스칼라 메타데이터, EmbeddingList 검색용 인덱스가 포함된 emb_list_vector 라는 벡터 하위 필드, 그리고 요소 수준 검색용 인덱스가 포함된 emb 라는 벡터 하위 필드가 포함되어 있습니다.

시작하기 전에

컬렉션 스키마, 데이터 및 인덱스가 이미 준비되어 있는지 확인하십시오.

필수 조건	준비 위치
chunks 와 같은 StructArray 필드를 생성합니다.	StructArray 필드 생성
chunks 필드에 Struct 객체가 포함된 엔티티를 삽입합니다.	StructArray 필드에 데이터 삽입
EmbeddingList 검색을 위해 chunks[emb_list_vector] 에 MAX_SIM* 인덱스를 생성합니다.	StructArray 필드 인덱싱
요소 수준 검색을 위해 ` chunks[emb] `에 일반 벡터-메트릭 인덱스를 생성합니다.	StructArray 필드 인덱싱

검색 모드 선택

Aspect	EmbeddingList 검색	요소 수준 검색
대상 하위 필드	chunks[emb_list_vector]	chunks[emb]
쿼리 데이터	하나 이상의 벡터를 포함하는 임베딩 리스트.	일반 벡터.
메트릭 패밀리	MAX_SIM*(예: MAX_SIM_COSINE).	COSINE, IP 또는 L2 과 같은 일반 벡터 메트릭.
하나의 검색 결과가 나타내는 것	StructArray 벡터 하위 필드가 쿼리 임베딩 목록과 유사한, 일치하는 엔티티.	StructArray 필드 내의 일치하는 Struct 요소.
결과 세분화	엔티티 수준.	Struct 요소 수준.
오프셋	해당 사항 없음.	반환 시 일치하는 구조체 요소의 0을 기준으로 한 위치를 식별합니다.
일반적인 사용 예	ColBERT, ColPali 및 기타 후기 상호작용 검색 패턴.	청크 수준, 패시지 수준, 클립 수준, 패치 수준 또는 팩트 수준의 검색.

EmbeddingList 검색 실행

쿼리 자체에 여러 벡터가 포함되어 있고 대상 StructArray 벡터 하위 필드가 MAX_SIM* 메트릭으로 인덱싱된 경우 EmbeddingList 검색을 사용합니다. 결과는 엔티티 수준 일치입니다.

from pymilvus import MilvusClient
from pymilvus.client.embedding_list import EmbeddingList

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

query = EmbeddingList()
query.add([0.12, 0.21, 0.32, 0.44])
query.add([0.18, 0.23, 0.29, 0.36])

results = client.search(
    collection_name="tech_articles",
    data=[query],
    anns_field="chunks[emb_list_vector]",
    limit=3,
    output_fields=[
        "doc_id",
        "title",
        "category",
        "chunks[text]",
        "chunks[section]",
    ],
)

for hits in results:
    for hit in hits:
        print(hit["id"], hit["distance"], hit["entity"])

이 검색 모드에서 limit 는 각 쿼리에 대해 반환되는 엔티티의 수를 제어합니다. 출력에는 StructArray 하위 필드가 포함될 수 있지만, 검색 결과 자체는 특정 Struct 요소가 아닌 일치한 상위 엔티티를 나타냅니다.

요소 수준 검색 실행

각 Struct 요소가 벡터 검색에 독립적으로 참여해야 하는 경우 요소 수준 검색을 사용합니다. 쿼리는 일반 벡터이며, 대상 벡터 하위 필드는 일반 벡터 메트릭으로 인덱싱되어야 합니다.

query_vector = [0.19, 0.24, 0.30, 0.37]

results = client.search(
    collection_name="tech_articles",
    data=[query_vector],
    anns_field="chunks[emb]",
    limit=5,
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[page]",
        "chunks[quality_score]",
    ],
)

for hits in results:
    for hit in hits:
        print(
            "doc_id:", hit["id"],
            "distance:", hit["distance"],
            "offset:", hit.get("offset"),
            "entity:", hit["entity"],
        )

요소 수준 검색에서 각 검색 결과는 일치하는 Struct 요소를 나타냅니다. ` offset ` 값은 StructArray 필드 내에서 해당 요소의 0을 기준으로 한 위치입니다. 쿼리와 일치하는 Struct 요소가 두 개 이상인 경우, 동일한 엔티티가 여러 번 나타날 수 있습니다. ` limit ` 값은 고유한 상위 엔티티가 아닌 요소 검색 결과에 적용됩니다.

결과 해석

결과 항목	EmbeddingList 검색	요소 수준 검색
id	일치하는 엔티티의 기본 키.	일치하는 Struct 요소를 포함하는 엔티티의 기본 키.
distance 또는 점수	쿼리 임베딩 목록과 저장된 임베딩 목록 간의 점수 또는 거리.	쿼리 벡터와 일치하는 Struct 요소 벡터 간의 점수 또는 거리.
offset	해당 사항 없음.	반환 시 일치하는 Struct 요소의 0을 기준으로 한 위치.
반복된 기본 키	결과가 엔티티 수준이므로 단일 쿼리의 경우 발생하지 않을 것으로 예상됩니다.	동일한 엔티티 내의 여러 Struct 요소가 일치할 수 있으므로 가능합니다.
요청된 StructArray 출력 필드	일치하는 엔티티에서 반환됩니다.	대상 API 및 SDK에서 지원하는 요소 수준 히트 셰이프와 함께 반환됩니다.

흔히 저지르는 실수

• 필수 하위 필드 경로 구문 chunks[emb] 대신 chunks.emb 을 사용하는 경우.

• 일반 벡터 메트릭으로 인덱싱된 벡터 하위 필드에 대해 EmbeddingList 쿼리를 사용하는 경우.

• MAX_SIM* 메트릭으로 인덱싱된 벡터 하위 필드에 일반 벡터 쿼리를 사용하는 경우.

• 요소 수준 검색 limit 이 그만큼의 고유한 상위 엔티티를 반환할 것이라고 기대하는 경우. 이 검색은 요소 일치 결과를 반환합니다.

• EmbeddingList 검색이 하나의 특정 요소 오프셋을 반환할 것으로 예상했으나, 엔티티 수준의 일치 결과를 반환합니다.

• 두 검색 모드 모두에 하나의 벡터 하위 필드를 재사용하는 경우. 각 벡터 하위 필드는 하나의 인덱스만 허용하므로 별도의 벡터 하위 필드를 사용해야 합니다.

다음 단계

1. 스칼라 조건으로 요소 수준 검색을 제한하려면 ‘StructArray를 사용한 필터링 검색’을 참조하십시오.

2. 점수 또는 거리 범위를 기준으로 검색하려면 StructArray를 사용한 범위 검색을 참조하십시오.

3. 요소 수준 검색 후 부모 엔티티당 최대 하나의 결과만 반환하려면, StructArray를 사용한 그룹화 검색을 참조하십시오.

4. StructArray 검색을 다른 벡터 검색과 결합하려면 ‘StructArray를 사용한 하이브리드 검색’을 참조하십시오.

5. 지원되는 데이터 유형, 메트릭, 필터 및 버전별 제한 사항을 확인하려면 ‘StructArray 제한 사항’을 참조하십시오.