Consultar um índice de pesquisa de vetor

Esta página descreve como consultar um índice de pesquisa de vetor, incluindo paginação, filtros e reclassimento.

Por exemplo, notebooks que ilustram como criar e consultar endpoints e índices de pesquisa vetorial, consulte notebooks 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 de vetor, você deve instalá-lo em seu notebook. 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 obter informações sobre autenticação, consulte Proteção de dados e autenticação.

Como consultar um índice de pesquisa de vetor

Você só pode consultar o índice de pesquisa de vetor usando o SDK do Python, a API REST ou a função de IA do SQL vector_search().

O tipo de consulta padrão é ann (vizinho mais próximo aproximado). Para executar uma pesquisa de similaridade de palavra-chave híbrida, 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, veja Usar o reranker em uma consulta.

Endpoint padrão do SDK Python

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

# 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 armazenamento otimizado do SDK Python

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

A interface de filtro existente foi recriada para que os índices de pesquisa de vetor com otimização de armazenamento adotem uma cadeia de caracteres de filtro mais semelhante a SQL em vez do dicionário de filtro usado nos pontos de extremidade de pesquisa de vetor 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 usar entidades de serviço em vez de tokens de acesso pessoal. Além de aprimorar a segurança e o gerenciamento de acesso, o uso de entidades de serviço pode aprimorar o desempenho em até 100 milissegundos 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 PAT (token de acesso pessoal).

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 essa função de IA, consulte vector_search função.

Paginação

Quando uma consulta solicita mais de 1.000 resultados, os resultados são retornados automaticamente em páginas de até 1.000. O número máximo de resultados que uma única consulta pode retornar em todas as páginas é 10.000. Os endpoints padrão e otimizados para armazenamento são compatíveis com paginação.

A paginação funciona com todos os tipos de consulta.

SDK do Python

O SDK do Python manipula a paginação de forma transparente. Quando você define num_results um valor maior que 1.000, o SDK recupera automaticamente todas as páginas e retorna o conjunto de resultados completo. Nenhum código adicional é necessário.

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

API REST

Ao usar a API REST diretamente, você deve manipular a paginação manualmente. Se houver mais resultados disponíveis, a resposta incluirá um next_page_token campo. Para recuperar a próxima página de resultados, passe esse token para o ponto de extremidade da próxima página de consulta.

Consulte a documentação de referência da 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>"}'

Continue chamando o endpoint query-next-page com o next_page_token de cada resposta até que o token esteja vazio ou ausente, o que indica que todos os resultados foram retornados.

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 com suporte.

Anotações sobre o uso de LIKE

LIKE exemplos de pontos de extremidade padrão

{"column LIKE": "apple"}: corresponde às cadeias de caracteres "maçã" e "pera de maçã", mas não corresponde a "abacaxi". Observe que ele não corresponde a "abacaxi" mesmo que contenha uma subcadeia de caracteres "apple" – ele procura uma correspondência exata sobre tokens separados de espaço em branco, como em "pera de maçã".

{"column NOT LIKE": "apple"} faz o oposto. Ele corresponde a "abacaxi" e "pera", mas não corresponde a "maçã" ou "maçã pera".

LIKE exemplos de endpoints otimizados para armazenamento

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
    )

Endpoint 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 a documentação em POST /api/2.0/vector-search/indexes/{index_name}/query.

Usar o reranker em uma consulta

O desempenho do agente depende da recuperação das informações mais relevantes para uma consulta. O reclassificador é uma técnica que melhora a qualidade da recuperação avaliando os documentos recuperados para identificar os que são semanticamente mais relevantes. O 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, pois avalia a relevância de cada documento.

O reordenamento incorre em um pequeno atraso de latência, mas pode melhorar significativamente a qualidade na recuperação e o desempenho do agente. Databricks recomenda testar a reordenação para qualquer caso de uso do agente RAG.

Os exemplos nesta seção mostram como usar o reclassificador de pesquisa de vetor. Ao usar o reranker, defina as colunas para retornar (columns) e as colunas de metadados a serem usadas para o reclassificador (columns_to_rerank) separadamente. num_results é o número final de resultados a serem retornados. Isso não afeta o número de resultados usados para a reclassificação.

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

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

Se a chamada de reclassificador 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.'}]}

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

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

Pesquisas de ponto

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