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

Consultar um Índice de Pesquisa de AI

Esta página descreve como consultar um Índice de Pesquisa de IA, incluindo paginação, filtros e reclassificação.

Para Notebooks de exemplo que ilustram como criar e consultar endpoints e índices do AI Search, consulte Notebooks de exemplo do AI Search. Para obter informações de referência, consulte a referência do SDK do Python.

Databricks AI Search era anteriormente conhecida como Databricks Vector Search.

Instalação​

Para usar o SDK de AI Search, você deve instalá-lo em seu notebook. Use o seguinte código para instalar o pacote:

%pip install databricks-ai-search
dbutils.library.restartPython()

Em seguida, execute o seguinte comando para importar AISearchClient:

from databricks.ai_search.client import AISearchClient

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

Como consultar um índice de pesquisa de AI​

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

nota

Se o usuário que consulta o índice não for o proprietário do Índice de Pesquisa de AI, o usuário deve ter os seguintes privilégios de UC:

  • USE CATALOG no catálogo que contém o Índice de Pesquisa de IA.
  • USE SCHEMA no esquema que contém o índice de pesquisa de AI.
  • SELECIONE no Índice de Pesquisa de AI.

O tipo de query default é ann (busca aproximada de vizinhos mais próximos). Para 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. Por default, a pesquisa híbrida inclui todas as colunas de metadados de texto e retorna um máximo de 200 resultados.
  • Para usar o reclassificador em uma consulta, consulte Usar o reclassificador em uma consulta.
info

Beta

A pesquisa de texto completo está disponível como um recurso beta. Para realizar uma pesquisa de texto completo, defina o parâmetro query_type como FULL_TEXT. Com a pesquisa de texto completo, é possível recuperar até 200 resultados usando a correspondência de palavras-chave sem incorporações. Queries de texto completo são suportadas em endpoints padrão e otimizados para armazenamento. Em endpoints otimizados para armazenamento, é possível também criar um índice de pesquisa de texto completo dedicado sem incorporações. Consulte Criar um índice de pesquisa de texto completo (Beta). Para pesquisar colunas de texto selecionadas, classificar resultados ou retornar contagens agregadas para consultas de texto completo e híbridas, consulte Pesquisar colunas de texto selecionadas, classificar resultados e retornar agregações (Beta).

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

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 automaticamente retornados 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. Ambos os endpoints padrão e otimizados para armazenamento suportam paginação.

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

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

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

Utilize filtros em queries​

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

A tabela a seguir lista os filtros compatíveis.

nota

Para endpoints otimizados para armazenamento, os resultados são excessivamente buscados. Se num_results for definido como k, mais de k resultados serão buscados e o filtro será aplicado aos resultados buscados. É possível que nenhum resultado seja retornado mesmo que haja resultados no dataset que correspondam à condição de filtro, se a pontuação desses documentos não estiver entre os melhores.

Operador de filtro

Comportamento

Exemplos

NOT

Padrão : nega o filtro. A key deve terminar com “NOT”. Por exemplo, “color NOT” com valor “vermelho” corresponde a documentos em que a cor não é vermelha.

Armazenamento otimizado : Consulte != (sinal de bangeq) operador.

Standard : {"id NOT": 2} {“color NOT”: “red”}

Armazenamento otimizado : "id != 2" "color != 'red'"

<

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

Armazenamento otimizado : Consulte < (sinal de menor que) operador.

Standard : {"id <": 200}

Armazenamento otimizado : "id < 200"

<=

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

Armazenamento otimizado : Consulte <= (sinal de menor ou igual) operador.

Standard : {"id <=": 200}

Armazenamento otimizado : "id <= 200"

>

Padrão : verifica se o valor do campo é maior que o valor do filtro. A key deve terminar com \>. Por exemplo, price \> com valor 200 corresponde a documentos em que o preço é maior que 200.

Armazenamento otimizado : Consulte > > operador.

Standard : {"id >": 200}

Armazenamento otimizado : "id > 200"

>=

Padrão : verifica se o valor do campo é maior ou igual ao valor do filtro. A key deve terminar com \>=. Por exemplo, price \>= com valor 200 corresponde a documentos em que o preço é maior ou igual a 200.

Armazenamento otimizado : Consulte o operador de maior ou igual a >=.

Standard : {"id >=": 200}

Armazenamento otimizado : "id >= 200"

OR

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

Armazenamento otimizado : Veja or operador.

Standard : {"color1 OR color2": ["red", "blue"]}

Armazenamento otimizado : "color1 = 'red' OR color2 = 'blue'"

LIKE

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

Armazenamento otimizado : Veja like operador.

Consulte Notas sobre o uso de LIKE.

Nenhum operador de filtro especificado

Padrão : verifica se há correspondência exata. Se vários valores forem especificados, corresponde a qualquer um dos valores.

Armazenamento otimizado : Consulte o = operador (sinal de igualdade) e o in predicado.

Standard : {"id": 200} {"id": [200, 300]}

Armazenamento otimizado : "id = 200" "id IN (200, 300)"

to_timestamp (Somente para endpoints otimizados para armazenamento)

Armazenamento otimizado : filtrar em um timestamp. Consulte funçãoto_timestamp

Armazenamento otimizado : "date > TO_TIMESTAMP('1995-01-01')"

Notas sobre o uso de LIKE​

LIKE exemplos para endpoints padrão

{"column LIKE": "apple"}: corresponde às strings "apple" e "apple pear", mas não corresponde a "pineapple". Observe que não corresponde a "abacaxi", mesmo contendo uma substring "apple" — ele busca uma correspondência exata sobre tokens separados por espaços em branco, como em "apple pear".

{"column NOT LIKE": "apple"} faz o oposto. Corresponde a "pineapple" e "pear", mas não corresponde a "apple" ou "apple pear".

LIKE exemplos para endpoints otimizados para armazenamento

Formato

Correspondências

"column LIKE 'apple'"

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

"column LIKE 'apple%'"

Retorna linhas onde um prefixo corresponde a apple, como applepie.

"column LIKE '%apple'"

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

"column LIKE '%apple%'"

Retorna linhas que contêm 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={&quot;title&quot;: [&quot;Ares&quot;, &quot;Athena&quot;]},
    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={&quot;title OR id&quot;: [&quot;Ares&quot;, &quot;Athena&quot;]},
    num_results=2
    )

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

Pesquisar colunas de texto selecionadas, ordenar resultados e retornar agregações (Beta)​

info

Beta

As opções para pesquisar colunas de texto selecionadas, classificar e retornar agregações fazem parte da **Pesquisa Vetorial: Pesquisa de Texto Completo** beta. Para usar query_columns, sort_columns ou facets, ative o Pré-lançamento público do Vector Search: Pesquisa de Texto Completo . Entre em contato com sua equipe de contas ou consulte Gerenciar pré-visualizações do Databricks para habilitar pré-visualizações.

Use estas opções para pesquisar campos de texto selecionados, aplicar uma ordem de resultados explícita ou retornar agregações para resultados correspondentes.

Estas opções são compatíveis com queries em texto completo e híbridas. Não são compatíveis para queries de rede neurais artificiais (ANN).

Pesquisar colunas de texto selecionadas

Use query_columns para pesquisar somente as colunas de texto especificadas. Caso seja omitido, a consulta pesquisa todas as colunas de texto.

Python
query_columns=["title", "text"]

Ordenar resultados

Use sort_columns para ordenar os resultados pelos valores das colunas em vez da ordem de relevância default. Entradas usam o formato "<column> ASC" ou "<column> DESC".

Python
sort_columns=["rating DESC", "publication_year DESC"]

Retornar agregações

Use facets para retornar contagens agregadas para resultados correspondentes.

Facetas de valor contam resultados correspondentes por valores distintos em uma coluna, como idioma ou categoria. TOP limita a quantidade de valores retornados, e o padrão é 10 se omitido.

Python
facets=["language TOP 5"]

Resposta de exemplo:

JSON
{
  "facet_result": {
    "facet_array": [
      ["language", "en", 28],
      ["language", "el", 14]
    ]
  }
}

Buckets numéricos contam resultados correspondentes que se enquadram em intervalos numéricos especificados, como anos de publicação ou preços. Os limites do bucket são inclusivos.

Python
facets=["publication_year BUCKETS [[1900,1949],[1950,1999],[2000,2025]]"]

Resposta de exemplo:

JSON
{
  "facet_result": {
    "facet_array": [
      ["publication_year", "[1900,1949]", 8],
      ["publication_year", "[1950,1999]", 14],
      ["publication_year", "[2000,2025]", 20]
    ]
  }
}

Para consultas de texto completo, o AI Search calcula agregações sobre todos os resultados que correspondem à consulta e aos filtros, não apenas as linhas retornadas na resposta. Para consultas híbridas, o AI Search aplica classificação e agregações ao conjunto limitado de candidatos que a pesquisa híbrida produz, e não a cada linha do índice.

Para os campos de solicitação da API REST e o esquema de resposta, consulte POST /api/2.0/vector-search/indexes/{index_name}/query.

Usar 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 avaliando os documentos recuperados para identificar aqueles que são semanticamente mais relevantes. Databricks desenvolveu um sistema composto de AI baseado em pesquisa para identificar estes documentos. É possível também especificar colunas que contêm metadados para que o reranker os utilize como contexto adicional ao avaliar 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 o reranking para qualquer caso de uso de agente RAG.

O reranker de pesquisa de AI é um serviço designado da Databricks que usa Databricks Geos para gerenciar a residência de dados. Clientes fora dos EUA e da UE podem precisar habilitar o processamento entre regiões geográficas para usar o reclassificador.

Os exemplos nesta seção mostram como usar o reclassificador de Busca AI. Ao usar o reorganizador, as colunas a serem retornadas (columns) e as colunas de metadados a serem usadas para reorganização (columns_to_rerank) são definidas separadamente. num_results é o número final de resultados a serem retornados. Isso não afeta o número de resultados usados para reclassificação.

A mensagem de depuração da consulta inclui informação sobre quanto tempo o passo de reorganização demorou. Por exemplo:

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

Se a chamada do reordenador falhar, essa informação estará 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 utiliza as colunas na ordem em que estão listadas e considera apenas os primeiros 2.000 caracteres que encontra.

Python
# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-ai-search --force-reinstall
dbutils.library.restartPython()
Python
from databricks.ai_search.reranker import DatabricksReranker

results = index.similarity_search(
    query_text = "How to create an AI 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 pontuais​

Para fazer uma busca pontual, aplique um filtro em qualquer coluna de chave primária.

Algoritmos de recuperação​

Esta seção descreve os diferentes algoritmos de recuperação ou tipos de query e quando utilizar cada um. 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 Avalie a qualidade de recuperação da Pesquisa de IA.

Estratégia

Como funciona

Melhor para

ANN (vizinho mais próximo aproximado)

Pesquisas usando incorporações de vetor para encontrar documentos semanticamente semelhantes.

Consultas conceituais e semânticas onde o significado importa mais do que o texto exato.

Texto completo

Busca por palavras-chave com correspondência exata de termos

Consultas com termos específicos, nomes próprios, IDs de produtos ou jargões técnicos.

Híbrido

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

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

Híbrido + reclassificador

Executa pesquisa híbrida, e reclassifica os resultados com um modelo de reclassificação de codificador cruzado.

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

rede neurais artificiais (ANN) (Pesquisa vetorial)​

A busca por redes neurais artificiais (ANN) converte uma consulta em uma incorporação vetorial e encontra documentos cujas incorporações são mais semelhantes. Isto é eficaz para compreender o significado. Por exemplo, uma consulta como "como consertar um cano quebrado" corresponde a documentos sobre encanamento, mesmo que eles não contenham essas palavras exatas.

  • Quando a **rede neurais artificiais (ANN)** apresenta bom desempenho: as consultas são conceituais, conversacionais ou usam vocabulário diferente dos documentos.
  • Quando redes neurais artificiais (ANN) podem ter um desempenho insatisfatório : consultas dependem de palavras-chave exatas, substantivos próprios ou terminologia específica do domínio que as incorporações podem não capturar com precisão.

Pesquisa de texto completo (busca por palavra-chave)​

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

Use opções de consulta de texto completo ou híbridas para pesquisar colunas de texto selecionadas, classificar resultados ou retornar contagens agregadas. Consulte Pesquisar colunas de texto selecionadas, classificar resultados e retornar agregações (Beta).

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

Pesquisa híbrida​

A busca híbrida executa tanto pesquisas de rede neurais artificiais (ANN) quanto pesquisas de texto completo em paralelo, e então combina os resultados usando Reciprocal Rank Fusion (RRF). Isto combina a compreensão semântica da pesquisa vetorial com a precisão da correspondência de palavras-chave.

  • Quando a busca híbrida apresenta um bom desempenho: a carga de trabalho das queries é uma mistura de queries conceituais e com grande volume de palavras-chave. Híbrido é a estratégia de propósito geral mais robusta.

reclassificador​

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

O reorganizador normalmente melhora a qualidade em aproximadamente 10%, mas adiciona latência. É adequado para aplicativos onde a qualidade é mais importante, como chatbots RAG, mas potencialmente menos adequado para aplicativos de pesquisa de alta taxa de transferência e baixa latência.

Nesta página