Consultar um índice de pesquisa de vetor

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

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() .

Observação

Se o usuário que consulta o índice não for o proprietário do índice de pesquisa de vetor, o usuário deverá ter os seguintes privilégios de UC:

USE CATALOG no catálogo que contém o índice de busca em vetores.
USE SCHEMA no esquema que contém o índice de busca em vetores.
SELECT no índice de busca em vetores.

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 reclassificador em uma consulta, consulte Usar o reranker em uma consulta.

Importante

A pesquisa de texto completo está disponível como um recurso beta. Para executar uma pesquisa de texto completo, defina o parâmetro query_type como FULL_TEXT. Com a pesquisa de texto completo, você pode recuperar até 200 resultados com base na correspondência de palavras-chave sem usar inserções de vetor.

Ponto de extremidade padrão do SDK do 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 de armazenamento otimizado do SDK do Python

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

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

Importante

A função de IA vector_search() está em visualização pública.

Para usar essa 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 com suporte.

Operador de filtro	Comportamento	Exemplos
`NOT`	Padrão: nega o filtro. A chave deve terminar com "NOT". Por exemplo, "color NOT" com valor "vermelho" corresponde a documentos em que a cor não é vermelha. Otimizado para armazenamento: consulte `!=` Operador (sinal de bangeq).	Padrão: `{"id NOT": 2}{“color NOT”: “red”}` Otimização de Armazenamento: `"id != 2" "color != 'red'"`
`<`	Padrão: verifica se o valor do campo é menor que o valor do filtro. A chave deve terminar com " <". Por exemplo, "preço <" com o valor 200 corresponde a documentos em que o preço é menor que 200. Otimizado para armazenamento: consulte `<` Operador (sinal de menor que).	Padrão: `{"id <": 200}` Otimização de Armazenamento: `"id < 200"`
`<=`	Padrão: verifica se o valor do campo é menor ou igual ao valor do filtro. A chave deve terminar com " <=". Por exemplo, "price <=" com o valor 200 corresponde a documentos em que o preço é menor ou igual a 200. Otimizado para armazenamento: consulte `<=` Operador (sinal de menor ou igual).	Padrão: `{"id <=": 200}` Otimização de Armazenamento: `"id <= 200"`
`>`	Padrão: verifica se o valor do campo é maior que o valor do filtro. A chave deve terminar com " >". Por exemplo, "preço >" com o valor 200 corresponde a documentos em que o preço é maior que 200. Otimizado para armazenamento: consulte `>` Operador (sinal de maior que).	Padrão: `{"id >": 200}` Otimização de Armazenamento: `"id > 200"`
`>=`	Padrão: verifica se o valor do campo é maior ou igual ao valor do filtro. A chave deve terminar com " >=". Por exemplo, "price >=" com o valor 200 corresponde a documentos em que o preço é maior ou igual a 200. Otimizado para armazenamento: consulte `>=` Operador (sinal de maior ou igual).	Padrão: `{"id >=": 200}` Otimização de Armazenamento: `"id >= 200"`
`OR`	Padrão: verifica se o valor do campo corresponde a qualquer um dos valores de filtro. A chave deve conter `OR` para separar várias subchaves. Por exemplo, `color1 OR color2` com o valor `["red", "blue"]` corresponde a documentos em que `color1` é `red` ou `color2` é `blue`. Otimizado para armazenamento: consulte Operador`or`.	Padrão: `{"color1 OR color2": ["red", "blue"]}` Otimização de Armazenamento: `"color1 = 'red' OR color2 = 'blue'"`
`LIKE`	Padrão: corresponde a tokens separados por espaço em branco em uma cadeia de caracteres. Veja os exemplos de código abaixo. Otimizado para armazenamento: consulte Operador`like`.	Padrão: `{"column LIKE": "hello"}` Otimização de Armazenamento: `"column LIKE 'hello'"`
Nenhum operador de filtro especificado	Padrão: filtrar verificações para obter uma correspondência exata. Se vários valores forem especificados, ele corresponderá a qualquer um dos valores. Otimizado para armazenamento: consulte `=` Operador (sinal de igual) e `in` predicado.	Padrão: `{"id": 200}{"id": [200, 300]}` Otimizado para armazenamento: `"id = 200""id IN (200, 300)"`
`to_timestamp` (somente pontos de extremidade com otimizado para armazenamento)	Otimizado para armazenamento: filtrar por um carimbo de data/hora. Veja a função `to_timestamp`	Otimização de Armazenamento: `"date > TO_TIMESTAMP('1995-01-01')"`

Veja os seguintes exemplos de código:

Ponto de extremidade padrão do SDK do 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 de armazenamento otimizado do SDK do 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
    )

API REST

Consulte a documentação em POST /api/2.0/vector-search/indexes/{index_name}/query.

CURTIR

LIKE Exemplos

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

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

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 reclassificador incorre em um pequeno atraso de latência, mas pode melhorar significativamente a qualidade de recuperação e o desempenho do agente. O Databricks recomenda testar o reclassificador 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 o reclassificado.

A mensagem de depuração de consulta inclui informações sobre quanto tempo a etapa de reclassificador 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.'}]}

Observação

A ordem na columns_to_rerank qual as colunas estão listadas é importante. O cálculo de reclassificador usa as colunas na ordem em que estão listadas e considera apenas os primeiros 2.000 caracteres encontrados.

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.

Comentários

Esta página foi útil?

Last updated on 2025-12-08

Compartilhar via

Consultar um índice de pesquisa de vetor

Installation

Como consultar um índice de pesquisa de vetor

Ponto de extremidade padrão do SDK do Python

Ponto de extremidade de armazenamento otimizado do SDK do Python

API REST

SQL

Usar filtros em consultas

Ponto de extremidade padrão do SDK do Python

Ponto de extremidade de armazenamento otimizado do SDK do Python

API REST

CURTIR

Usar o reranker em uma consulta

SDK do Python

API REST

Pesquisas de ponto

Comentários

Recursos adicionais