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

Consultar um Índice de Pesquisa de AI

Você pode consultar um índice de Pesquisa de IA com o SDK Python, a API REST ou a função SQL vector_search(). A Pesquisa de IA suporta tipos de consulta rede neurais artificiais (ANN), híbridos e de texto completo, juntamente com paginação, filtros e reclassificação para ajustar a qualidade da recuperaçã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

O usuário ou service principal que consulta o índice deve ter os seguintes privilégios do Unity Catalog:

  • 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.
  • SELECT no Índice de Pesquisa de AI. O proprietário do índice já tem este privilégio.

Para um índice que usa um modelo de incorporação gerenciado pelo Databricks, a identidade que chama também pode precisar de permissões em seus endpoints de servindo modelo de incorporação. Consulte Configurar uma Service Principal, que também abrange a configuração de uma Service Principal para queries de produção.

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, você pode recuperar até 10.000 resultados com base na correspondência de palavras-chave sem usar incorporações vetoriais. Queries de texto completo são suportadas em endpoints padrão e otimizados para armazenamento. Em endpoints otimizados 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 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 uma query de texto completo, manifest.total_hit_count relata o número de documentos correspondentes independentemente de num_results. Contagens de 10.000 ou menos são exatas. Para um conjunto de correspondência maior, o AI Search pode relatar um limite inferior.

O campo manifest.total_hit_count_lower_bound indica como interpretar a contagem. Um valor de false significa que total_hit_count é exato. Um valor de true significa que é um limite inferior.

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
    )

Obter um token OAuth de um notebook​

Em um Notebook em execução no compute do Databricks, você pode obter um token OAuth para consultar um índice sem um Service Principal. Para fazer isso, troque o token do notebook por um token OAuth no endpoint do workspace /oidc/v1/token usando o OAuth 2.0 Token Exchange (RFC 8693). Como no exemplo do Service Principal na tab da API REST, o token trocado tem authorization_details para o índice e você o usa com a URL do índice.

nota

: Essa troca funciona apenas a partir de um notebook no compute do Databricks no mesmo workspace. : Não é possível usá-lo com um access token pessoal que você cria nas configurações do usuário ou fora do compute do Databricks, como no seu laptop. : Fora do compute do Databricks, use a autorização OAuth user-to-machine (U2M) ou uma Service Principal com um token OAuth.

A solicitação de troca de tokens usa os seguintes campos:

  • grant_type: urn:ietf:params:oauth:grant-type:token-exchange.
  • subject_token: O token do notebook.
  • subject_token_type: urn:databricks:params:oauth:token-type:personal-access-token.
  • requested_token_type: urn:ietf:params:oauth:token-type:access_token.
  • scope: all-apis.
  • authorization_details: Uma matriz JSON que permite a operação ReadVectorIndex no índice. Adicione também uma entrada workspace_permission que permite query_inference_endpoint para cada endpoint de disponibilização de incorporação otimizado para rota. Use o ID do endpoint de disponibilização, não seu nome.

A identidade em execução do Notebook deve ter os privilégios do Unity Catalog listados em Como fazer query de um índice de Pesquisa de AI no índice e as permissões de Endpoint de serviço em Configurar um Service Principal.

O tokens trocado concede acesso ao índice como essa identidade. Não imprima, Logs ou compartilhe.

O exemplo a seguir é execução em um notebook. Ele lê o token do notebook do contexto do notebook.

Python
import json
import requests

WORKSPACE_URL = "https://<workspace-url>"
INDEX_NAME = "<catalog>.<schema>.<index>"
TIMEOUT_SECONDS = 30

AUTHORIZATION_DETAILS = [
    {
        "type": "unity_catalog_permission",
        "securable_type": "table",
        "securable_object_name": INDEX_NAME,
        "operation": "ReadVectorIndex",
    },
    # If the index uses a route-optimized embedding model serving endpoint, also allow querying it:
    # {
    #     "type": "workspace_permission",
    #     "object_type": "serving-endpoints",
    #     "object_path": "/serving-endpoints/<serving-endpoint-id>",
    #     "actions": ["query_inference_endpoint"],
    # },
]

def get_oauth_token():
    # Read the notebook token on each call so that a refresh uses a current token.
    notebook_token = dbutils.notebook.entry_point.getDbutils().notebook().getContext().apiToken().get()
    response = requests.post(
        f"{WORKSPACE_URL}/oidc/v1/token",
        data={
            "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
            "subject_token": notebook_token,
            "subject_token_type": "urn:databricks:params:oauth:token-type:personal-access-token",
            "requested_token_type": "urn:ietf:params:oauth:token-type:access_token",
            "scope": "all-apis",
            "authorization_details": json.dumps(AUTHORIZATION_DETAILS),
        },
        timeout=TIMEOUT_SECONDS,
    )
    if response.ok:
        return response.json()["access_token"]
    try:
        error = response.json().get("error")
    except ValueError:
        error = None
    # Report the status and OAuth error code, not the full response.
    raise RuntimeError(f"Token exchange failed: status {response.status_code}, error {error}")

headers = {"Authorization": f"Bearer {get_oauth_token()}"}

# Get the index URL, then query the index
index_response = requests.get(
    f"{WORKSPACE_URL}/api/2.0/vector-search/indexes/{INDEX_NAME}", headers=headers, timeout=TIMEOUT_SECONDS
)
index_response.raise_for_status()
index_url = index_response.json()["status"]["index_url"]

query_response = requests.post(
    f"https://{index_url}/query",
    headers=headers,
    json={"num_results": 3, "query_text": "...", "columns": ["id", "text"]},
    timeout=TIMEOUT_SECONDS,
)
query_response.raise_for_status()
results = query_response.json()

O tokens trocado tem vida curta, normalmente uma hora. O campo expires_in da resposta do token fornece sua vida útil em segundos. Para refresh o token, repita a troca antes que o token expire.

nota

Para aplicações de produção, o Databricks recomenda uma Service Principal com um token OAuth em vez de um token trocado de um Notebook.

Log de payloads de query (Beta)​

O log do payload da query grava solicitações e respostas da query da Pesquisa de AI na tabela do sistema system.telemetry.otel_logs para monitoramento e análise de qualidade de recuperação. Está disponível para índices em Endpoint padrão e Endpoint otimizados para armazenamento. Quando você cria um índice no Explorador de Catálogo com a visualização AI Search Quality Mode habilitada, o registro de carga útil de query está ativado por default.

Para usar o registro de payload da query, seu workspace deve estar habilitado para o Unity Catalog e inscrito na versão beta do AI Search Quality Mode na página Visualizações . Para alterar a configuração, você deve ter USE CATALOG no catálogo do índice, USE SCHEMA em seu esquema e MODIFY no índice.

Na página de índice no Catalog Explorer, use o Registro de payload de query na barra lateral direita para ativar ou desativar o registro.

Para ativar ou desativar o registro de payload de query com o Python SDK, use update_index_payload_logging(). Os índices criados com o SDK têm o registro de payload de query desativado, a menos que você passe payload_logging_enabled=True ao criar o índice.

Python
from databricks.ai_search.client import AISearchClient

client = AISearchClient()
client.update_index_payload_logging(
    index_name="catalog.schema.index_name",
    payload_logging_enabled=True,
)

Defina payload_logging_enabled=False para desativar o registro.

Por default, apenas administradores de account que também são administradores de metastore podem ler logs de payload de query. Para conceder acesso a outro usuário, consulte Conceder acesso às tabelas do sistema.

A seguinte query retorna logs de carga útil de Pesquisa de AI para um índice:

SQL
SELECT time, attributes, body
FROM system.telemetry.otel_logs
WHERE service_name = 'ai-search'
  AND attributes:['index_id']::STRING = '<index-id>'
ORDER BY time DESC;

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 query pode definir filtros com base em qualquer coluna indexada 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')"

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 de 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.

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={"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
    )

Filtrar campos estruturados e valores de mapa​

Filtrar um campo estruturado primitivo usando um caminho separado por pontos. Filtrar um valor de mapa primitivo usando notação de colchetes para a chave do mapa.

Os exemplos a seguir filtram o campo age na struct profile e a chave voltage no mapa attrs:

Python
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"profile.age": 18, "attrs['voltage']": 9},
    num_results=10
)

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 versão beta do Vector Search: Pesquisa de texto completo . Para usar query_columns, sort_columns ou facets, habilite Vector Search: Pesquisa de texto completo em Prévias . Entre em contato com sua equipe de conta ou consulte Gerenciar prévias do Databricks para habilitar prévias.

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 reclassificador de pesquisa de AI é um serviço designado do Databricks que usa Databricks Geos para gerenciar a residência de dados. Clientes fora dos EUA, UE, Austrália e Nova Zelândia podem precisar habilitar o processamento cross-Geo 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': 693.0, 'ann_time': 29.0, 'reranker_time': 619.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"])
    )

Queries somente de filtro e pesquisas pontuais​

Uma query apenas de filtro retorna linhas que correspondem a um filtro sem realizar recuperação vetorial ou por palavra-chave. Omita query_text, query_vector e query_type e especifique filters. Consultas apenas de filtro suportam qualquer coluna indexada e filtrável em endpoints padrão e otimizados para armazenamento.

Os exemplos a seguir retornam linhas onde status é active:

Python
results = index.similarity_search(
    columns=["id", "status"],
    filters={"status": "active"},
    num_results=100
)

Os limites de num_results e de paginação se aplicam a consultas apenas de filtro. Para uma pesquisa de ponto, filtre em uma 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 (geralmente menos de 1 segundo adicional por consulta).

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 (geralmente menos de 1 segundo adicional 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