Búsqueda vectorial básica con StructArray

Utiliza esta página para realizar búsquedas vectoriales en subcampos vectoriales dentro de un campo StructArray. StructArray admite dos modos básicos de búsqueda vectorial: la búsqueda en EmbeddingList, que evalúa una lista de incrustaciones almacenada en cada entidad, y la búsqueda a nivel de elemento, que busca en cada elemento de Struct de forma independiente.

Esta página utiliza la colección « tech_articles » de la sección «Crear un campo StructArray». La colección cuenta con un campo StructArray denominado « chunks ». Cada fragmento contiene texto, metadatos escalares, un subcampo vectorial denominado « emb_list_vector » con un índice para la búsqueda en EmbeddingList y un subcampo vectorial denominado « emb » con un índice para la búsqueda a nivel de elemento.

Antes de empezar

Asegúrate de que el esquema de la colección, los datos y los índices ya estén preparados.

Requisitos	Dónde prepararlo
Crea un campo StructArray, como chunks.	Crear un campo StructArray
Inserta entidades cuyo campo « chunks » contenga objetos Struct.	Insertar datos en campos StructArray
Crea un índice « MAX_SIM* » en « chunks[emb_list_vector] » para la búsqueda en «EmbeddingList».	Indexar campos «StructArray»
Crear un índice vectorial-métrico normal en « chunks[emb] » para la búsqueda a nivel de elemento.	Indexar campos de StructArray

Elige un modo de búsqueda

Aspecto	Búsqueda en EmbeddingList	Búsqueda a nivel de elemento
Subcampo de destino	chunks[emb_list_vector]	chunks[emb]
Datos de consulta	Una lista de incrustaciones que contiene uno o más vectores.	Un vector normal.
Familia de métricas	MAX_SIM*, como MAX_SIM_COSINE.	Métricas vectoriales habituales, como COSINE, IP o L2.
Qué representa un resultado	Una entidad coincidente cuyo subcampo vectorial StructArray es similar a la lista de incrustaciones de la consulta.	Un elemento Struct coincidente dentro del campo StructArray.
Granularidad de los resultados	Nivel de entidad.	Nivel de elemento Struct.
Desplazamiento	No aplicable.	Identifica la posición, contada a partir de cero, del elemento Struct coincidente cuando se devuelve.
Uso habitual	ColBERT, ColPali y otros patrones de recuperación de interacción tardía.	Recuperación a nivel de fragmento, de pasaje, de clip, de parche o de dato.

Ejecutar una búsqueda con EmbeddingList

Utiliza la búsqueda EmbeddingList cuando la propia consulta contenga varios vectores y el subcampo del vector StructArray de destino esté indexado con una métrica « MAX_SIM* ». El resultado es una coincidencia a nivel de entidad.

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"])

En este modo de búsqueda, « limit » controla cuántas entidades se devuelven para cada consulta. El resultado puede incluir subcampos de StructArray, pero la coincidencia en sí representa la entidad principal con la que coincide, en lugar de un elemento Struct específico.

Realizar una búsqueda a nivel de elemento

Utilice la búsqueda a nivel de elemento cuando cada elemento de Struct deba participar en la búsqueda vectorial de forma independiente. La consulta es un vector normal, y el subcampo del vector de destino debe estar indexado con una métrica vectorial normal.

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"],
        )

En la búsqueda a nivel de elemento, cada resultado representa un elemento Struct coincidente. El valor « offset » es la posición, contada a partir de cero, de ese elemento en el campo StructArray. La misma entidad puede aparecer más de una vez si hay más de un elemento Struct que coincide con la consulta. El valor « limit » se aplica a los resultados de los elementos, no a entidades principales únicas.

Interpretación de los resultados

Elemento de resultado	Búsqueda en EmbeddingList	Búsqueda a nivel de elemento
id	Clave primaria de la entidad coincidente.	Clave primaria de la entidad que contiene el elemento Struct coincidente.
distance o puntuación	Puntuación o distancia entre la lista de incrustaciones de la consulta y la lista de incrustaciones almacenada.	Puntuación o distancia entre el vector de consulta y el vector del elemento Struct coincidente.
offset	No aplicable.	Posición, contada a partir de cero, del elemento Struct coincidente cuando se devuelve.
Claves primarias repetidas	No es de esperar en una sola consulta, ya que los resultados son a nivel de entidad.	Es posible, ya que pueden coincidir varios elementos Struct de la misma entidad.
Campos de salida solicitados de StructArray	Devueltos desde la entidad coincidente.	Se devuelven con la forma de coincidencia a nivel de elemento admitida por la API y el SDK de destino.

Errores comunes

• Utilizar « chunks.emb » en lugar de la sintaxis de ruta de subcampo requerida: « chunks[emb] ».

• Utilizar una consulta EmbeddingList sobre un subcampo vectorial indexado con una métrica vectorial normal.

• Utilizar una consulta vectorial normal contra un subcampo vectorial indexado con una métrica de « MAX_SIM* ».

• Esperar que la búsqueda a nivel de elemento « limit » devuelva ese número de entidades principales únicas. Lo que devuelve son coincidencias de elementos.

• Esperar que la búsqueda EmbeddingList devuelva un desplazamiento de elemento específico. Devuelve coincidencias a nivel de entidad.

• Reutilizar un mismo subcampo vectorial para ambos modos de búsqueda. Utilice subcampos vectoriales independientes, ya que cada subcampo vectorial solo admite un índice.

Próximos pasos

1. Para restringir la búsqueda a nivel de elemento mediante condiciones escalares, consulta «Búsqueda filtrada con StructArray».

2. Para realizar búsquedas por puntuación o límites de distancia, consulta «Búsqueda por rango con StructArray».

3. Para devolver como máximo un resultado por entidad principal tras una búsqueda a nivel de elemento, consulta «Búsqueda agrupada con StructArray».

4. Para combinar la búsqueda con StructArray con otras búsquedas vectoriales, consulta «Búsqueda híbrida con StructArray».

5. Para consultar los tipos de datos, métricas, filtros y límites específicos de cada versión compatibles, consulta «Límites de StructArray».