Pular para o conteúdo principal
Última atualização em

Consultar um índice de pesquisa vetorial

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

Por exemplo, veja o Notebook de exemplo de pesquisa vetorial e como consultar endpoints e índices de pesquisa vetorial. Para obter informações de referência, consulte a referênciaPython SDK.

Instalação​

Para usar o SDK de busca vetorial, você precisa instalá-lo em seu Notebook. Utilize 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 vetorial​

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

nota

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

  • USE CATALOG no catálogo que contém o índice de busca vetorial.
  • USE SCHEMA no esquema que contém o índice de pesquisa vetorial.
  • Selecione no índice de pesquisa vetorial.

O tipo de consulta default é ann (vizinho mais próximo aproximado). Para obter detalhes sobre os diferentes algoritmos de recuperação, consulte Algoritmos de recuperação.

  • Para realizar uma pesquisa híbrida de similaridade de palavras-chave, defina o parâmetro query_type como hybrid. Na busca 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 reclassificador em uma consulta.
info

Beta

A busca por texto completo está disponível como recurso beta. Para realizar 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 incorporações vetoriais. Consultas de texto completo são suportadas tanto no endpoint padrão quanto no endpoint otimizado para armazenamento. Em um endpoint otimizado para armazenamento, você também pode criar um índice de pesquisa de texto completo dedicado, sem incorporações. Consulte Criar um índice de pesquisa de texto completo (Beta).

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

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
    )

Paginação​

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

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

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

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

Use filtros nas consultas​

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

A tabela a seguir lista os filtros suportados.

nota

Para endpoints otimizados para armazenamento, os resultados são buscados em excesso. Se você definir num_results para k, mais de k resultados serão obtidos e o filtro será aplicado aos resultados obtidos. É possível que nenhum resultado seja retornado mesmo que existam resultados no dataset que correspondam à condição do filtro, caso a pontuação desses documentos não esteja entre as melhores.

Operador de filtro

Comportamento

Exemplos

NOT

Padrão : Anula o filtro. A key deve terminar com “NOT”. Por exemplo, “cor NÃO” com o valor “vermelho” corresponde a documentos onde a cor não é vermelha.

Otimizado para armazenamento : Consulte o operador!= (sinal bangeq).

Padrão : {"id NOT": 2} {“color NOT”: “red”}

Otimizado para armazenamento : "id != 2" "color != 'red'"

<

Padrão : verifica se o valor do campo é menor que o valor do filtro. O endereço key deve terminar com " <". Por exemplo, “price <” com valor 200 corresponde a documentos em que o preço é menor que 200.

Otimizado para armazenamento : Consulte o operador< (sinal lt).

Padrão : {"id <": 200}

Otimizado para armazenamento : "id < 200"

<=

Padrão : Verifica se o valor do campo é menor ou igual ao valor do filtro. A key deve terminar com “<=”. Por exemplo, “preço <=” com valor 200 corresponde a documentos onde o preço é menor ou igual a 200.

Otimizado para armazenamento : Consulte o operador<= (sinal de igualdade).

Padrão : {"id <=": 200}

Otimizado para armazenamento : "id <= 200"

>

Padrão : Verifica se o valor do campo é maior que o valor do filtro. A key deve terminar com “ >”. Por exemplo, “preço >” com valor 200 corresponde a documentos onde o preço é superior a 200.

Otimizado para armazenamento : Consulte o operador> (sinal gt).

Padrão : {"id >": 200}

Otimizado para armazenamento : "id > 200"

>=

Padrão : Verifica se o valor do campo é maior ou igual ao valor do filtro. A key deve terminar com “>=”. Por exemplo, “preço >=” com o valor 200 corresponde a documentos onde o preço é maior ou igual a 200.

Otimizado para armazenamento : Consulte o operador>= (gt sinal de igualdade).

Padrão : {"id >=": 200}

Otimizado para armazenamento : "id >= 200"

OR

Padrão : Verifica se o valor do campo corresponde a algum dos valores de filtro. A key deve conter OR para separar várias subchaves. Por exemplo, color1 OR color2 com valor ["red", "blue"] corresponde a documentos onde color1 é red ou color2 é blue.

Otimizado para armazenamento : Consulte o operadoror.

Padrão : {"color1 OR color2": ["red", "blue"]}

Otimizado para armazenamento : "color1 = 'red' OR color2 = 'blue'"

LIKE

Padrão : Corresponde tokens separados por espaços em branco em uma string.

Otimizado para armazenamento : Consulte o operadorlike.

Consulte as notas sobre o uso de LIKE.

Nenhum operador de filtro especificado

Padrão : O filtro verifica se há uma correspondência exata. Se forem especificados vários valores, qualquer um deles será considerado válido.

Otimizado para armazenamento : Consulte o operador= (sinal de igualdade) e o predicadoin.

Padrão : {"id": 200} {"id": [200, 300]}

Otimizado para armazenamento : "id = 200" "id IN (200, 300)"

to_timestamp (somente endpoint otimizado para armazenamento)

Otimizado para armazenamento : Filtre por data e hora. Consulte a funçãoto_timestamp

Otimizado para armazenamento : "date > TO_TIMESTAMP('1995-01-01')"

Notas sobre o uso de LIKE​

LIKE exemplos para endpoint padrão

{"column LIKE": "apple"}: corresponde às strings "apple" e "apple pear", mas não corresponde a "pineapple". Note que não corresponde a "abacaxi", mesmo que contenha uma substring "maçã" – procura uma correspondência exata em tokens separados por espaços em branco, como em "maçã e pera".

{"column NOT LIKE": "apple"} faz o oposto. A palavra "abacaxi" e "pera" correspondem, mas não a "maçã" ou "pera-maçã".

LIKE exemplos de endpoints otimizados para armazenamento

Formato

Partidas

"column LIKE 'apple'"

Equivalente ao operador = . Retorna apenas correspondências exatas.

"column LIKE 'apple%'"

Retorna linhas onde um prefixo corresponde apple, como applepie.

"column LIKE '%apple'"

Retorna linhas onde um sufixo corresponde a apple, como pineapple.

"column LIKE '%apple%'"

Retorna linhas que possuem uma substring que corresponde a apple, como pineapplecake.

Exemplos de código​

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
    )

Use o reclassificador em uma consulta​

O desempenho do agente depende da recuperação da informação mais relevante para uma consulta. A reclassificação é uma técnica que melhora a qualidade da recuperação de dados, avaliando os documentos recuperados para identificar aqueles que são semanticamente mais relevantes. Databricks desenvolveu um sistema AI composto, baseado em pesquisa, para identificar esses documentos. Você também pode especificar colunas contendo metadados que deseja que o reclassificador utilize para obter contexto adicional ao avaliar a relevância de cada documento.

A reclassificação acarreta 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 de agente RAG.

Os exemplos nesta seção mostram como usar o reclassificador de busca vetorial. Ao usar o reclassificador, você define as colunas a serem retornadas (columns) e as colunas de metadados a serem usadas para reclassificação (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 da consulta inclui informações sobre quanto tempo demorou a reclassificação do passo. Por exemplo:

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

Se a chamada do reclassificador falhar, essa informação será incluída na mensagem de depuração:

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

A ordem em que as colunas são listadas em columns_to_rerank é importante. O cálculo de reclassificação considera as colunas na ordem em que estão listadas e leva em conta apenas os primeiros 2000 caracteres encontrados.

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()
Python
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"])
    )

Pesquisas de ponto​

Para realizar uma pesquisa pontual, utilize um filtro em qualquer coluna key primária.

Algoritmos de recuperação​

Esta seção descreve os diferentes algoritmos de recuperação ou tipos de consulta e quando cada um pode ser usado. Use o parâmetro query_type para especificar o algoritmo de recuperação a ser usado. Para comparar automaticamente o desempenho de diferentes algoritmos para o seu índice, consulte Avaliar a qualidade da recuperação da pesquisa vetorial.

Estratégia

Como funciona

Melhor para

rede neurais artificiais (ANN) (vizinho mais próximo aproximado)

Realiza buscas usando vetores de incorporação para encontrar documentos semanticamente semelhantes.

Consultas conceituais e semânticas onde o significado importa mais do que a formulação exata.

Texto completo

Pesquisa por palavra-chave que corresponde a termos exatos.

Consultas com termos específicos, nomes próprios, IDs de produtos ou jargão técnico.

Híbrido

Combina resultados de rede neurais artificiais (ANN) e texto completo usando Reciprocal Rank Fusion (RRF).

Recuperação de propósito geral. O ponto de partida recomendado para a maioria dos casos de uso.

Híbrido + reclassificador

A execução da busca híbrida é seguida pela reclassificação dos resultados com um modelo de recodificação cruzada.

Maior precisão quando a latência permite (aproximadamente 1,5s adicionais por consulta).

rede neurais artificiais (ANN) (pesquisa vetorial)​

A pesquisa de rede neurais artificiais (RNA) converte uma consulta em uma incorporação vetorial e encontra documentos cujos embeddings são mais semelhantes. Isso é eficaz para compreender o significado . Por exemplo, uma consulta como "como consertar um cano quebrado" encontra resultados sobre encanamento, mesmo que eles não contenham exatamente essas palavras.

  • Quando as redes neurais artificiais (RNA) têm um bom desempenho : as consultas são conceituais, conversacionais ou usam vocabulário diferente dos documentos.
  • Quando as redes neurais artificiais (RNA) podem apresentar desempenho inferior : As consultas dependem de palavras-chave exatas, nomes próprios ou terminologia específica do domínio que os embeddings podem não capturar com precisão.

Texto completo (busca por palavra-chave)​

A pesquisa de texto completo encontra documentos que contêm os termos da pesquisa. A busca por texto completo possui alta precisão. Quando os usuários pesquisam por nomes, códigos ou termos técnicos específicos, a correspondência de palavras-chave encontra resultados exatos que a pesquisa vetorial poderia não encontrar.

  • Quando o texto completo apresenta bom desempenho : As consultas contêm identificadores específicos, nomes de produtos, códigos de erro ou terminologia específica do domínio.
  • Quando a consulta de texto completo pode ter um desempenho inferior : As consultas são formuladas de maneira diferente dos documentos ou usam sinônimos e paráfrases.

Busca híbrida​

Execução de pesquisa híbrida tanto em redes neurais artificiais (ANN) quanto em texto completo em paralelo e, em seguida, mesclar os resultados usando Reciprocal Rank Fusion (RRF). Isso combina a compreensão semântica da busca vetorial com a precisão da correspondência de palavras-chave.

  • Quando a pesquisa híbrida apresenta bom desempenho : A carga de trabalho de consultas é uma mistura de consultas conceituais e consultas com muitas palavras-chave. A estratégia híbrida é a mais robusta para uso geral.

Reclassificador​

O reclassificador é uma segunda etapa opcional aplicada sobre qualquer estratégia. Após a recuperação inicial, um modelo de codificação cruzada reavalia cada resultado no contexto da consulta, produzindo uma ordenação de relevância mais precisa.

O reclassificador normalmente melhora a qualidade em cerca de 10%, mas aumenta a latência. É adequado para aplicações onde a qualidade é fundamental, como chatbots RAG, mas potencialmente menos adequado para aplicações de busca de alta taxa de transferência e baixa latência.

Nesta página