Consultar um índice de pesquisa vetorial

Este artigo descreve como consultar um índice de pesquisa vetorial, incluindo como usar filtros e reclassificação.

Para exemplos de cadernos que ilustram como criar e consultar endpoints e índices de pesquisa vetorial, veja cadernos de exemplo de pesquisa vetorial. Para obter informações de referência, consulte a referência do SDK do Python.

Installation

Para usar o SDK de pesquisa vetorial, você deve instalá-lo em seu bloco de anotações. Use o seguinte código para instalar o pacote:

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

Em seguida, use o seguinte comando para importar VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

Para informações sobre autenticação, consulte Proteção e autenticação de dados.

Como consultar um índice de pesquisa vetorial

Só pode consultar o índice de pesquisa vetorial usando o SDK Python, a API REST ou a função SQL vector_search() AI.

O tipo de consulta padrão é ann (vizinho mais próximo aproximado). Para executar uma pesquisa híbrida de semelhança de palavras-chave, defina o parâmetro query_type como hybrid. Com a pesquisa híbrida, todas as colunas de metadados de texto são incluídas e um máximo de 200 resultados são retornados.

Para usar o reranker em uma consulta, consulte Usar o reranker em uma consulta.

Endpoint padrão do SDK Python

Para obter detalhes, consulte a referência do SDK do 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
    )

Ponto de extremidade otimizado para armazenamento do Python SDK

Para obter detalhes, consulte a referência do SDK do Python.

A interface de filtro existente foi redesenhada para índices de pesquisa vetorial otimizados para armazenamento para adotar uma cadeia de caracteres de filtro mais semelhante ao SQL em vez do dicionário de filtros usado em pontos de extremidade de pesquisa vetorial padrão.

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
)

API REST

Consulte a documentação de referência da API REST: POST /api/2.0/vector-search/indexes/{index_name}/query.

Para aplicativos de produção, o Databricks recomenda o uso de entidades de serviço em vez de tokens de acesso pessoal. Além de melhorar a segurança e o gerenciamento de acesso, a utilização de entidades de serviço pode melhorar o desempenho em até 100 ms por consulta.

O exemplo de código a seguir ilustra como consultar um índice usando um principal de serviço.

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}'

O exemplo de código a seguir ilustra como consultar um índice usando um token de acesso pessoal (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 esse função de IA, consulte vector_search função.

Usar filtros em consultas

Uma consulta pode definir filtros com base em qualquer coluna na tabela Delta. similarity_search retorna apenas linhas que correspondem aos filtros especificados.

A tabela a seguir lista os filtros suportados.

Consulte os seguintes exemplos de código:

Endpoint padrão do SDK 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
    )

Ponto de extremidade otimizado para armazenamento do Python SDK

# 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
    )

API REST

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

GOSTAR

LIKE exemplos

{"column LIKE": "apple"}: corresponde às strings "maçã" e "pera maçã", mas não corresponde a "ananás" ou "pera". Note que ele não corresponde a "abacaxi", embora contenha uma substring "apple" --- ele procura uma correspondência exata sobre tokens separados de espaço em branco, como em "apple pear".

{"column NOT LIKE": "apple"} faz o contrário. Corresponde a "ananás" e "pera", mas não corresponde a "maçã" ou "pera maçã".

Usar o reclassificador em uma consulta

O desempenho do agente depende da recuperação das informações mais relevantes para uma consulta. A reclassificação é uma técnica que melhora a qualidade da recuperação, avaliando os documentos recuperados para identificar os que são semanticamente mais relevantes. A Databricks desenvolveu um sistema de IA composto baseado em pesquisa para identificar esses documentos. Você também pode especificar colunas contendo metadados que deseja que o reclassificador use para contexto adicional à medida que avalia a relevância de cada documento.

A reclassificação incorre em um pequeno atraso de latência, mas pode melhorar significativamente a qualidade da recuperação e o desempenho do agente. A Databricks recomenda experimentar a reclassificação para qualquer caso de uso do agente RAG.

Os exemplos nesta seção mostram como usar o reclassificador de pesquisa vetorial. Ao usar o reclassificador, você define as colunas para retornar (columns) e as colunas de metadados para usar para reclassificar (columns_to_rerank) separadamente. num_results é o número final de resultados a retornar. Isso não afeta o número de resultados usados para reclassificação.

A mensagem de depuração de consulta inclui informações sobre quanto tempo levou a etapa de reclassificação. Por exemplo:

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

Se a chamada do reranker falhar, essas informações serão incluídas na mensagem de depuração:

'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.'}]}

Python SDK

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

API REST

Para garantir que você obtenha informações de latência, defina debug_level como pelo 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}'

Consultas de pontos

Para fazer uma pesquisa por ponto, use um filtro em qualquer coluna de chave primária.