perform a similarity search in a collection by using the python sdk - DashVector

Collection.query() busca en una colección de DashVector los documentos similares a un vector dado o al vector de un documento almacenado. También puede recuperar documentos únicamente con un filtro de metadatos.

Modos de consulta

Collection.query() admite cinco modos de consulta según los parámetros que proporcione:

Modo	Parámetros obligatorios	Descripción
Búsqueda por vector	`vector`	Encuentra los documentos más cercanos a un vector denso determinado.
Búsqueda por clave primaria	`id`	Encuentra los documentos más cercanos al vector de un documento existente.
Búsqueda por vector filtrada	`vector` o `id` + `filter`	Combina la búsqueda por similitud con el filtrado de metadatos.
Búsqueda híbrida	`vector` + `sparse_vector`	Combina vectores densos y dispersos para una búsqueda semántica que reconoce palabras clave.
Consulta por coincidencia	Solo `filter`	Recupera documentos mediante un filtro de metadatos, sin ordenarlos por similitud.

Si no se especifican ni vector ni id, query() ejecuta una consulta por coincidencia que usa únicamente el filtro condicional.

Requisitos previos

Antes de empezar, asegúrese de contar con lo siguiente:

Un clúster de DashVector. Consulte Create a cluster
Una clave de API. Consulte Manage API keys
El SDK de DashVector (versión más reciente). Consulte Install DashVector SDK
Una colección con documentos ya insertados. Consulte Create a collection y Insert documents

Firma de la API

Collection.query(
    vector: Optional[Union[List[Union[int, float]], np.ndarray]] = None,
    id: Optional[str] = None,
    topk: int = 10,
    filter: Optional[str] = None,
    include_vector: bool = False,
    partition: Optional[str] = None,
    output_fields: Optional[List[str]] = None,
    sparse_vector: Optional[Dict[int, float]] = None,
    async_req: False
) -> DashVectorResponse

Parámetros de solicitud

Parámetro	Tipo	Valor predeterminado	Descripción
`vector`	`Optional[Union[List[Union[int, float]], np.ndarray]]`	`None`	Vector denso para la búsqueda por similitud.
`id`	`Optional[str]`	`None`	Clave primaria de un documento existente. La búsqueda utiliza el vector de ese documento.
`topk`	`int`	`10`	Número máximo de resultados que se devuelven, ordenados por similitud.
`filter`	`Optional[str]`	`None`	Filtro condicional con sintaxis de cláusula WHERE de SQL. Consulte Conditional filtering.
`include_vector`	`bool`	`False`	Indica si se incluyen los datos del vector en la respuesta.
`partition`	`Optional[str]`	`None`	Nombre de la partición. Limita el alcance de la búsqueda a una partición específica.
`output_fields`	`Optional[List[str]]`	`None`	Campos que se devuelven. De forma predeterminada, se devuelven todos los campos.
`sparse_vector`	`Optional[Dict[int, float]]`	`None`	Vector disperso para keyword-aware semantic search. Cada clave es un índice de dimensión y cada valor es el peso.
`async_req`	`bool`	`False`	Indica si se habilita el modo asíncrono.

Respuesta

query() devuelve un objeto DashVectorResponse:

Campo	Tipo	Descripción	Ejemplo
`code`	`int`	Código de estado. El valor `0` indica que la operación se completó correctamente. Consulte Status codes.	`0`
`message`	`str`	Mensaje de estado.	`success`
`request_id`	`str`	Identificador único de la solicitud.	`19215409-ea66-4db9-8764-26ce2eb5bb99`
`output`	`List[`<code data-tag="code" class="inline-code___exakR" id="code_d6787a3c">Doc</code>`]`	Resultados de la búsqueda por similitud.	--

Ejemplos

Todos los ejemplos siguientes usan la configuración de cliente que se muestra a continuación. Reemplace los marcadores de posición con sus valores reales:

Marcador de posición	Descripción
`YOUR_API_KEY`	Su clave de API de la consola de DashVector
`YOUR_CLUSTER_ENDPOINT`	La URL del endpoint de su clúster

import dashvector
import numpy as np

client = dashvector.Client(
    api_key='YOUR_API_KEY',
    endpoint='YOUR_CLUSTER_ENDPOINT'
)

# Get the target collection
collection = client.get(name='quickstart')

Cree la colección quickstart e inserte documentos antes de ejecutar estos ejemplos. Consulte Create a collection y Insert documents .

Búsqueda por vector

Pase un vector denso para encontrar los documentos más similares.

ret = collection.query(
    vector=[0.1, 0.2, 0.3, 0.4]
)
# Check whether the query method is successfully called.
if ret:
    print('query success')
    print(len(ret))
    for doc in ret:
        print(doc)
        print(doc.id)
        print(doc.vector)
        print(doc.fields)

Para personalizar el conjunto de resultados, especifique topk, output_fields e include_vector:

ret = collection.query(
    vector=[0.1, 0.2, 0.3, 0.4],
    topk=100,
    output_fields=['name', 'age'],  # Only the name and age fields need to be returned.
    include_vector=True
)

Búsqueda por clave primaria

Use el parámetro id para buscar con el vector de un documento almacenado, sin proporcionar los valores del vector directamente.

ret = collection.query(
    id='1'
)
# Check whether the query method is successfully called.
if ret:
    print('query success')
    print(len(ret))
    for doc in ret:
        print(doc)
        print(doc.id)
        print(doc.vector)
        print(doc.fields)

Combine id con topk y output_fields de la misma manera que en la búsqueda por vector:

ret = collection.query(
    id='1',
    topk=100,
    output_fields=['name', 'age'],  # Only the name and age fields need to be returned.
    include_vector=True
)

Búsqueda con filtro condicional

Agregue el parámetro filter para acotar los resultados por metadatos. Este filtro sigue la sintaxis de la cláusula WHERE de SQL.

# Perform a similarity search by using the vector or primary key and a conditional filter.
ret = collection.query(
    vector=[0.1, 0.2, 0.3, 0.4],   # Specify a vector for search. Alternatively, you can specify a primary key for search.
    topk=100,
    filter='age > 18',             # Specify a conditional filter to perform a match query on documents whose value of the age field is greater than 18.
    output_fields=['name', 'age'], # Only the name and age fields need to be returned.
    include_vector=True
)

Sugerencia: Combine filter con id en lugar de vector para filtrar los resultados de una búsqueda basada en la clave primaria.

Búsqueda híbrida con vectores densos y dispersos

Combine un vector denso con un vector disperso para ejecutar una búsqueda semántica que reconoce palabras clave. El vector disperso representa los pesos de las palabras clave que complementan el embedding denso.

# Perform a similarity search by using both dense and sparse vectors.
ret = collection.query(
    vector=[0.1, 0.2, 0.3, 0.4],   # Specify a vector for search.
    sparse_vector={1: 0.3, 20: 0.7}
)

Consulte Keyword-aware semantic search para conocer los detalles de configuración.

Consulta por coincidencia solo con filtro

Omita tanto vector como id para recuperar documentos basándose únicamente en condiciones de metadatos, sin ordenarlos por similitud.

# Perform a match query only by using a conditional filter without specifying a vector or primary key.
ret = collection.query(
    topk=100,
    filter='age > 18',             # Specify a conditional filter to perform a match query on documents whose value of the age field is greater than 18.
    output_fields=['name', 'age'], # Only the name and age fields need to be returned.
    include_vector=True
)

Pasos siguientes

Keyword-aware semantic search: mejore la precisión de recuperación al combinar vectores densos y dispersos.
Conditional filtering: referencia completa de la sintaxis de expresiones de filtro.