Consulta de un índice de búsqueda vectorial

En esta página se describe cómo consultar un índice de búsqueda vectorial, incluida la paginación, los filtros y el reordenamiento.

Para obtener cuadernos de ejemplo que ilustran cómo crear y consultar puntos de conexión e índices de búsqueda vectorial, consulte Cuadernos de ejemplo de búsqueda vectorial. Para obtener información de referencia, consulte la referencia del SDK de Python.

Installation

Para usar el SDK de búsqueda vectorial, debe instalarlo en el cuaderno. Use el código siguiente para instalar el paquete:

%pip install databricks-vectorsearch
dbutils.library.restartPython()

A continuación, use el siguiente comando para importar VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

Para obtener información sobre la autenticación, consulte Protección y autenticación de datos.

Consulta de un índice de búsqueda vectorial

Solo puede consultar el índice de búsqueda vectorial mediante el SDK de Python, la API REST o la función de INTELIGENCIA artificial /vector_search() SQL.

El tipo de consulta predeterminado es ann (vecino más cercano aproximado). Para más información sobre los distintos algoritmos de recuperación, consulte Algoritmos de recuperación.

• Para realizar una búsqueda híbrida de similitud de palabras clave, establezca el parámetro en query_typehybrid. Con la búsqueda híbrida, se incluyen todas las columnas de metadatos de texto y se devuelve un máximo de 200 resultados.
• Para usar el reranker en una consulta, consulte Uso del reranker en una consulta.

punto de conexión estándar del SDK de Python

Para más información, consulte la referencia del SDK de Python.

# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index using full-text search (Beta)
results4 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="FULL_TEXT"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.9] * 1024,
    columns=["id", "text"],
    num_results=2
    )

Endpoint de almacenamiento optimizado del SDK de Python

Para más información, consulte la referencia del SDK de Python.

La interfaz de filtro existente se ha vuelto a diseñar para los índices de vector de búsqueda optimizados para almacenamiento para adoptar una cadena de filtro más similar a SQL en lugar del diccionario de filtros que se usa en los puntos de conexión de vector de búsqueda estándar.

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

# similarity search with query vector
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
)

# similarity search with query vector and filter string
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    # this is a single filter string similar to SQL WHERE clause syntax
    filters="language = 'en' AND country = 'us'",
    num_results=2
)

REST API

Consulte la documentación de referencia de la API REST: POST /api/2.0/vector-search/indexes/{index_name}/query.

Para las aplicaciones de producción, Databricks recomienda utilizar credenciales de servicio en lugar de tokens de acceso personal. Además de mejorar la administración de seguridad y acceso, el uso de entidades de servicio puede mejorar el rendimiento hasta 100 msec por consulta.

En el ejemplo de código siguiente se muestra cómo consultar un índice mediante un principal de servicio.

export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...

# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint, then you need to have additional authorization details to invoke the serving endpoint
# export EMBEDDING_MODEL_SERVING_ENDPOINT_ID=...
# export AUTHORIZATION_DETAILS="$AUTHORIZATION_DETAILS"',{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/'"$EMBEDDING_MODEL_SERVING_ENDPOINT_ID"'","actions": ["query_inference_endpoint"]}'

# Generate OAuth token
export TOKEN=$(curl -X POST  --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')

# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')

# Query vector search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query vector search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

En el ejemplo de código siguiente se muestra cómo consultar un índice mediante un token de acceso personal (PAT).

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Query vector search index with `query_vector`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query vector search index with `query_text`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

SQL

Para usar esta función de IA, consulte vector_search función .

Paginación

Cuando una consulta solicita más de 1000 resultados, los resultados se devuelven automáticamente en páginas de hasta 1000. El número máximo de resultados que una sola consulta puede devolver en todas las páginas es de 10 000. Los puntos de conexión estándar y optimizados para almacenamiento admiten la paginación.

La paginación funciona con todos los tipos de consulta.

SDK de Python

El SDK de Python controla la paginación de forma transparente. Cuando se establece num_results en un valor mayor que 1000, el SDK recupera automáticamente todas las páginas y devuelve el conjunto de resultados completo. No se requiere código adicional.

# The SDK automatically paginates and returns all 5000 results
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=5000
)

REST API

Al usar la API REST directamente, debe gestionar la paginación manualmente. Si hay más resultados disponibles, la respuesta incluye un next_page_token campo. Para recuperar la siguiente página de resultados, pase este token al endpoint de la página siguiente en la consulta.

Consulte la documentación de referencia de la API REST: POST /api/2.0/vector-search/indexes/{index_name}/query-next-page.

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Initial query - if num_results exceeds 1000, the response includes next_page_token
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query \
  --data '{"num_results": 5000, "query_text": "...", "columns": ["id", "text"]}'

# Use next_page_token from the response to get the next page
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" \
  --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query-next-page \
  --data '{"page_token": "<next_page_token from previous response>"}'

Siga llamando al punto de conexión de consulta siguiente con la next_page_token de cada respuesta hasta que el token esté vacío o ausente, lo que indica que se han devuelto todos los resultados.

Usar filtros en consultas

Una consulta puede definir filtros basados en cualquier columna de la tabla Delta. similarity_search devuelve solo las filas que coinciden con los filtros especificados.

En la tabla siguiente se enumeran los filtros admitidos.

Notas sobre el uso de LIKE

LIKE ejemplos de puntos de conexión estándar

{"column LIKE": "apple"}: coincide con las cadenas "manzana" y "pera de manzana", pero no coincide con "piña". Tenga en cuenta que no coincide con la "piña", aunque contiene una subcadena "manzana", busca una coincidencia exacta sobre tokens separados por espacios en blanco como en "manzana pear".

{"column NOT LIKE": "apple"} hace lo contrario. Coincide con "piña" y "pera", pero no con "manzana" ni "manzana pera".

LIKE ejemplos de puntos de conexión optimizados para almacenamiento

Ejemplos de código

punto de conexión estándar del SDK de Python

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title": ["Ares", "Athena"]},
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title OR id": ["Ares", "Athena"]},
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title NOT": "Hercules"},
    num_results=2
    )

Endpoint de almacenamiento optimizado del SDK de Python

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title IN ("Ares", "Athena")',
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title = "Ares" OR id = "Athena"',
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title != "Hercules"',
    num_results=2
    )

REST API

Vea POST /api/2.0/vector-search/indexes/{index_name}/query.

Uso del reranker en una consulta

El rendimiento del agente depende de recuperar la información más relevante de una consulta. La reevaluación es una técnica que mejora la calidad de recuperación mediante la evaluación de los documentos recuperados para identificar los que son más relevantes semánticamente. Databricks ha desarrollado un sistema de inteligencia artificial compuesto basado en investigación para identificar estos documentos. También puede especificar columnas que contengan metadatos que desee que use el reranker para contexto adicional, ya que evalúa la relevancia de cada documento.

El proceso de reranking incurre en una pequeña latencia, pero puede mejorar significativamente la calidad del proceso de recuperación y el rendimiento del agente. Databricks recomienda probar el reordenamiento para cualquier caso de uso del agente RAG.

Los ejemplos de esta sección muestran cómo usar el reranker de búsqueda vectorial. Cuando se usa el reranker, se establecen las columnas que se devuelven (columns) y las columnas de metadatos que se van a usar para el reranking (columns_to_rerank) por separado. num_results es el número final de resultados que se van a devolver. Esto no afecta el número de resultados utilizados para la reorganización.

El mensaje de depuración de la consulta incluye información sobre cuánto tiempo tomó el paso de reranking. Por ejemplo:

'debug_info': {'response_time': 1647.0, 'ann_time': 29.0, 'reranker_time': 1573.0}

Si se produce un error en la llamada del reranker, esa información se incluye en el mensaje de depuración:

'debug_info': {'response_time': 587.0, 'ann_time': 331.0, 'reranker_time': 246.0, 'warnings': [{'status_code': 'RERANKER_TEMPORARILY_UNAVAILABLE', 'message': 'The reranker is temporarily unavailable. Results returned have not been processed by the reranker. Please try again later for reranked results.'}]}

SDK de Python

# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-vectorsearch --force-reinstall
dbutils.library.restartPython()

from databricks.vector_search.reranker import DatabricksReranker

results = index.similarity_search(
    query_text = "How to create a Vector Search index",
    columns = ["id", "text", "parent_doc_summary", "date"],
    num_results = 10,
    query_type = "hybrid",
    reranker=DatabricksReranker(columns_to_rerank=["text", "parent_doc_summary", "other_column"])
    )

REST API

Para asegurarse de obtener información de latencia, establezca debug_level en al menos 1.

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 10, "query_text": "How to create a Vector Search index", "columns": ["id", "text", "parent_doc_summary", "date"], "reranker": {"model": "databricks_reranker",
             "parameters": {
               "columns_to_rerank":
                 ["text", "parent_doc_summary"]
              }
             },
"debug_level": 1}'

Búsquedas de puntos

Para realizar una búsqueda de puntos, use un filtro en cualquier columna de clave principal.

Algoritmos de recuperación

En esta sección se describen los distintos algoritmos de recuperación o tipos de consulta y cuándo se puede usar cada uno. Use el query_type parámetro para especificar el algoritmo de recuperación que se va a usar. Para comparar automáticamente el rendimiento de diferentes algoritmos para el índice, consulte Evaluación de la calidad de recuperación de búsqueda vectorial.

ANN (búsqueda vectorial)

La búsqueda de ANN convierte una consulta en una inserción de vectores y busca documentos cuyas incrustaciones son más similares. Esto es eficaz para comprender el significado. Por ejemplo, una consulta como "cómo corregir una canalización rota" coincide con documentos sobre la fontanería aunque no contengan esas palabras exactas.

• Cuando ANN funciona bien: las consultas son conceptuales, conversacionales o usan vocabulario diferente al de los documentos.
• Cuando ANN podría tener un rendimiento inferior: las consultas dependen de palabras clave exactas, nombres adecuados o terminología específica del dominio que las incrustaciones no pueden capturar con precisión.

Texto completo (búsqueda de palabras clave)

La búsqueda de texto completo coincide con documentos que contienen los términos de consulta. La búsqueda de texto completo tiene una alta precisión. Cuando los usuarios buscan nombres, códigos o términos técnicos específicos, la coincidencia de palabras clave busca aciertos exactos que la búsqueda de vectores podría perder.

• Cuando el texto completo funciona bien: las consultas contienen identificadores específicos, nombres de producto, códigos de error o terminología específica del dominio.
• Cuando el texto completo puede tener un rendimiento inferior: las consultas se frasean de forma diferente de los documentos o usan sinónimos y parafrasean.

Búsqueda híbrida

La búsqueda híbrida ejecuta búsquedas de ANN y de texto completo en paralelo y luego fusiona los resultados mediante Fusión de Rango Recíproca (RRF). Esto combina la comprensión semántica de la búsqueda vectorial con la precisión de la coincidencia de palabras clave.

• Cuando la búsqueda híbrida funciona bien: la carga de trabajo de consulta es una combinación de consultas conceptuales y intensivas en palabras clave. La estrategia híbrida es la más robusta de uso general.

Reranker

El reranker es un segundo pase opcional aplicado sobre cualquier estrategia. Después de la recuperación inicial, un modelo de codificador cruzado vuelve a evaluar cada resultado en el contexto de la consulta, lo que genera un orden de relevancia más preciso.

Normalmente, el reranker mejora la calidad en aproximadamente 10%, pero agrega latencia. Es adecuado para aplicaciones en las que la calidad importa más, como los chatbots RAG, pero quizás menos indicado para aplicaciones de búsqueda de baja latencia y alto rendimiento.