StructArray를 사용한 범위 검색

이 페이지를 사용하여 StructArray 벡터 하위 필드에 대해 범위 검색을 실행할 수 있습니다. 범위 검색은 점수 또는 거리가 지정된 범위 내에 속하는 벡터 일치 결과를 반환합니다. StructArray 필드의 경우, 각 Struct 요소를 독립적으로 검색하는 요소 수준 벡터 검색과 함께 범위 검색을 사용하십시오.

이 페이지에서는 ‘StructArray 필드 생성’의 tech_articles 컬렉션을 사용합니다. 이 컬렉션에는 chunks 라는 StructArray 필드가 있습니다. chunks[emb] 벡터 하위 필드는 COSINE, IP 또는 L2 와 같은 일반 벡터 메트릭을 사용하여 요소 수준 검색이 가능하도록 인덱싱되어 있습니다.

StructArray에 범위 검색이 적용되는 방식

검색 모드	범위 검색 동작	결과 세분화 수준
EmbeddingList 검색	지원되지 않습니다.	해당 사항 없음.
요소 수준 검색	radius 및 선택적으로 range_filter 을 사용하여 일반 벡터 쿼리를 사용하십시오.	구조체 요소 수준.
하이브리드 검색	StructArray 요청이 요소 수준 벡터 필드를 대상으로 할 때 지원됩니다. EmbeddingList 수준 요청은 범위 검색을 지원하지 않습니다.	요소 수준 하위 검색 후 하이브리드 재순위 지정.

시작하기 전에

범위 검색을 실행하기 전에 컬렉션, 데이터 및 인덱스를 준비하십시오.

요구 사항	세부 정보
StructArray 필드	컬렉션에는 chunks 와 같은 StructArray 필드가 포함되어 있습니다.
요소 수준 벡터 하위 필드	chunks[emb]대상 벡터 하위 필드는 chunks[emb_list_vector] 이며, 가 아닙니다.
인덱스 메트릭	벡터 하위 필드는 COSINE, IP 또는 L2 와 같은 일반 벡터 메트릭으로 인덱싱됩니다.
쿼리 데이터	쿼리는 EmbeddingList 가 아닌 일반 벡터입니다.

인덱스 설정에 대해서는 StructArray 필드 인덱싱을 참조하십시오.

radius 및 range_filter 사용

radius 을 설정하여 검색 경계를 정의합니다. 내부 경계도 필요한 경우 range_filter 을 설정하십시오. 방향은 더 짧은 거리가 더 좋은지, 아니면 더 높은 유사도 점수가 더 좋은지에 따라 달라집니다.

메트릭 유형	점수가 높을수록 좋은가요?	range_filter 를 사용할 때의 범위 조건
L2	아니요. 거리가 더 짧을수록 좋습니다.	range_filter <= distance < radius
IP, COSINE	네. 점수가 높을수록 좋습니다.	radius < distance <= range_filter

radius 만 설정된 경우, 범위 검색은 해당 메트릭의 외부 경계를 만족하는 히트를 반환합니다. 임베딩의 점수 또는 거리 척도에 따라 값을 선택하십시오.

요소 수준 범위 검색 실행

다음 예제는 chunks[emb] 벡터가 쿼리 벡터와 충분히 유사한 개별 청크를 검색합니다. 각 검색 결과는 일치하는 Struct 요소를 나타냅니다.

from pymilvus import MilvusClient

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

query_vector = [0.19, 0.24, 0.30, 0.37]

results = client.search(
    collection_name="tech_articles",
    data=[query_vector],
    anns_field="chunks[emb]",
    search_params={
        "params": {
            "radius": 0.80,
            "range_filter": 0.95,
        },
    },
    limit=10,
    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"],
        )

이 예제에서 ` COSINE `는 유사도 방식의 메트릭이므로, 결과 범위는 ` radius `보다 크고 ` range_filter` 이하입니다. ` offset ` 값은 결과가 반환될 때 ` chunks ` 배열 내에서 일치하는 Struct 요소를 식별합니다.

스칼라 필터 추가

요소 수준 범위 검색을 StructArray 스칼라 필터링과 결합할 수 있습니다. 상위 엔티티 필드에는 최상위 술어를 사용하고, element_filter 를 사용하여 벡터 범위 검색에 포함될 Struct 요소를 제한합니다.

filter_expr = (
    'category == "search" && '
    'element_filter(chunks, '
    '$[section] == "index" && '
    '$[quality_score] > 0.9)'
)

results = client.search(
    collection_name="tech_articles",
    data=[query_vector],
    anns_field="chunks[emb]",
    search_params={
        "params": {
            "radius": 0.80,
            "range_filter": 0.95,
        },
    },
    filter=filter_expr,
    limit=10,
    output_fields=[
        "doc_id",
        "title",
        "category",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

최상위 술어는 후보 엔티티를 선택합니다. ` element_filter ` 술어는 벡터 범위 검색을 일치하는 Struct 요소로만 제한합니다. 더 많은 필터링 예제는 ‘StructArray를 사용한 필터링 검색’을 참조하십시오.

하이브리드 검색에서 범위 검색 사용

StructArray 요소 수준 벡터 필드는 하이브리드 검색에서 범위 검색을 지원합니다. StructArray 요소 수준 벡터 필드를 대상으로 하는 AnnSearchRequest 에 radius 를 추가하고, 선택적으로 range_filter 를 추가하십시오.

from pymilvus import AnnSearchRequest, RRFRanker

title_req = AnnSearchRequest(
    data=[query_vector],
    anns_field="title_vector",
    limit=10,
)

chunk_req = AnnSearchRequest(
    data=[query_vector],
    anns_field="chunks[emb]",
    param={
        "params": {
            "radius": 0.80,
            "range_filter": 0.95,
        },
    },
    limit=10,
    expr='element_filter(chunks, $[section] == "index")',
)

results = client.hybrid_search(
    collection_name="tech_articles",
    reqs=[title_req, chunk_req],
    ranker=RRFRanker(),
    limit=5,
    output_fields=[
        "doc_id",
        "title",
        "chunks[text]",
        "chunks[section]",
        "chunks[quality_score]",
    ],
)

이 예제에서는 chunks[emb] 하위 요청만 범위 검색 매개변수를 사용합니다. StructArray 요청은 여전히 요소 수준 의미 체계를 따릅니다. 즉, 하이브리드 검색이 결과를 결합하고 재순위를 매기기 전에 범위 경계가 Struct 요소 일치 항목에 적용됩니다.

범위 결과 해석

결과 항목	의미
id	일치하는 Struct 요소를 포함하는 엔티티의 기본 키입니다.
distance 또는 점수	쿼리 벡터와 일치하는 Struct 요소 벡터 간의 점수 또는 거리입니다.
offset	반환 시 StructArray 필드 내에서 일치하는 Struct 요소의 0을 기준으로 한 위치.
중복된 기본 키	가능합니다. 동일한 엔티티 내의 두 개 이상의 Struct 요소가 지정된 범위에 포함될 수 있습니다.
limit	이는 고유한 상위 엔티티가 아닌 요소 일치에 적용됩니다.

제한 사항

• StructArray 벡터 하위 필드에 대한 범위 검색에는 EmbeddingList 쿼리나 MAX_SIM* 메트릭을 사용하지 마십시오. EmbeddingList 수준 검색은 범위 검색을 지원하지 않습니다.

• 범위 검색을 그룹화 검색과 결합하지 마십시오. 부모 엔티티당 하나의 결과가 필요한 경우, 범위 매개변수 없이 요소 수준 검색을 실행하고 지원되는 경우 그룹화를 사용하십시오.

• StructArray 요소 수준 벡터 필드에 대해서는 하이브리드 범위 검색이 지원됩니다. EmbeddingList 수준 StructArray 요청의 경우 지원되지 않습니다.

흔히 저지르는 실수

• chunks[emb_list_vector] 에 대해 범위 검색을 실행하는 경우. 이 메트릭은 EmbeddingList 검색용으로 설계되었습니다.

• 요소 수준 범위 검색에 COSINE 와 같은 일반 메트릭 대신 MAX_SIM_COSINE 를 사용하는 경우.

• 일반 벡터 쿼리 대신 EmbeddingList 쿼리를 사용하는 경우.

• 범위 검색 결과가 상위 엔티티별로 고유할 것으로 기대하는 경우. 범위 검색은 일치하는 Struct 요소 히트를 반환합니다.

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

다음 단계

1. 두 가지 기본 StructArray 벡터 검색 모드에 대해 알아보려면 ‘StructArray를 사용한 기본 벡터 검색’을 참조하십시오.

2. 범위 검색에 스칼라 필터를 추가하려면 'StructArray를 사용한 필터링 검색'을 참조하십시오.

3. 지원되는 경우 상위 엔티티당 최대 하나의 결과만 반환하려면 ‘StructArray를 사용한 그룹화 검색’을 참조하십시오.

4. 버전별 검색 제한 사항을 확인하려면 StructArray 제한 사항을 참조하십시오.