Pular para o conteúdo principal

Adicionar um recurso de Índice de Pesquisa de AI a um aplicativo Databricks

Adicionar Índices de Pesquisa de AI como recursos do Databricks Apps para habilitar a busca semântica e a recuperação baseada em similaridade em seus aplicativos. Os índices de AI Search armazenam e consultam incorporações vetoriais de alta dimensionalidade, possibilitando casos de uso como geração aumentada de recuperação (RAG), busca semântica e sistemas de recomendação.

Databricks AI Search era anteriormente conhecida como Databricks Vector Search.

Requisitos de privilégio​

Para acessar um índice do AI Search, a entidade de serviço do aplicativo deve ter o privilégio USE CATALOG no catálogo pai, o privilégio USE SCHEMA no esquema pai e o privilégio SELECT no índice. Ao adicionar o recurso de índice, a Databricks concede automaticamente estes privilégios à entidade de serviço do aplicativo.

Para que essa concessão automática seja bem-sucedida, uma das seguintes condições deve ser verdadeira para cada privilégio:

  • Para USE CATALOG: Ou todos os usuários account têm o privilégio USE CATALOG no catálogo, ou você tem o privilégio MANAGE no catálogo.
  • Para USE SCHEMA: Ou todos os usuários account têm o privilégio USE SCHEMA no esquema, ou você tem o privilégio MANAGE no esquema.
  • Para SELECT: Ou todos os usuários account têm o privilégio SELECT no índice, ou você tem o privilégio MANAGE no índice.

Se o índice usa um modelo de embedding gerenciado pelo Databricks em um Endpoint de serviço personalizado ou de throughput provisionada, também adicione esse Endpoint como um recurso de aplicativo com permissão de Pode query , além de qualquer Endpoint de embedding de query separado (model_endpoint_name_for_query). get_index() lê esses Endpoint e falha sem acesso. Endpoint de APIs do Foundation Model pagas por token, como databricks-gte-large-en, não precisam de um recurso de aplicativo, a menos que sua account restrinja modelos de base com permissões do Unity Catalog, caso em que o Service Principal precisa de EXECUTE no modelo. Consulte Configurar uma Service Principal.

Para mais informações sobre como consultar índices de Pesquisa de AI com essas permissões, consulte Como consultar um Índice de Pesquisa de AI.

Consulte a referência de privilégiosUnity Catalog.

Adicionar um recurso de Índice de Pesquisa de AI​

Antes de adicionar um Índice de Pesquisa de AI como um recurso, revise os pré-requisitos de recursos do aplicativo.

  1. Na seção Recursos do aplicativo ao criar um aplicativo ou em Configurações > Recursos ao editar um aplicativo, clique em + Adicionar recurso > Índice de pesquisa vetorial .

  2. Escolha o Índice de Pesquisa de AI dentre os índices disponíveis em seu workspace. O índice já deve existir no Unity Catalog.

  3. Selecione o nível de permissão para seu aplicativo:

    • Pode selecionar: Concede à aplicação permissão para consultar o Índice de Pesquisa de IA para pesquisas de similaridade. Corresponde ao privilégio SELECT.
  4. (Opcional) Especifique uma key de recurso personalizada, que é como você referencia o índice na configuração do seu aplicativo. A key default é vector-search-index.

nota

Índices de pesquisa de AI são tabelas do Unity Catalog com o tipo TABLE_ONLINE_VECTOR_INDEX_REPLICA ou TABLE_ONLINE_VECTOR_INDEX_DIRECT. Ao selecionar um Índice de Pesquisa de IA, seleciona-se uma tabela especialmente configurada que dá suporte a operações de pesquisa semântica.

variável de ambiente​

Quando você implanta um aplicativo com um recurso de índice de pesquisa de AI, o Databricks expõe o nome completo de três níveis por meio de variáveis de ambiente que você pode referenciar usando o campo valueFrom.

Configuração de exemplo:

YAML
env:
- name: VECTOR_SEARCH_INDEX
valueFrom: vector-search-index # Use your custom resource key if different

Utilizando o índice em sua aplicação:

Faça query do índice com o databricks-ai-search Python SDK e as credenciais do service principal do aplicativo. Quando o workspace atende aos requisitos de URL de índice, o SDK envia queries para a URL de índice, que pode usar a capacidade extra de um endpoint com uma target queries per second (QPS). As queries enviadas com WorkspaceClient().vector_search_indexes.query_index usam a URL de query do workspace, que é limitada a algumas dezenas de QPS. As queries enviadas com o token do usuário da autorização de usuário também usam a URL de query do workspace; portanto, envie tráfego de pesquisa com o service principal do aplicativo.

Adicione a versão 0.83 ou acima de databricks-ai-search às dependências do seu app. Consulte Gerenciar dependências de um app do Databricks.

Python
import os
from databricks.ai_search.client import AISearchClient

# DATABRICKS_HOST can be set without a scheme, and the SDK requires one.
host = os.environ["DATABRICKS_HOST"]
if not host.startswith(("https://", "http://")):
host = f"https://{host}"

# Pass the app's service principal credentials so queries use the index URL.
client = AISearchClient(
workspace_url=host,
service_principal_client_id=os.environ["DATABRICKS_CLIENT_ID"],
service_principal_client_secret=os.environ["DATABRICKS_CLIENT_SECRET"],
)

# Create the index object when the app starts and reuse it for every query.
index = client.get_index(index_name=os.environ["VECTOR_SEARCH_INDEX"])

results = index.similarity_search(
query_text="What is machine learning?", # Or pass query_vector for self-managed embeddings.
columns=["id", "text"],
num_results=10,
)

# Each row lists values in the same order as the manifest columns.
column_names = [column["name"] for column in results["manifest"]["columns"]]
for row in results["result"]["data_array"]:
print(dict(zip(column_names, row)))

Substitua columns pelas colunas do seu índice. Para atingir maior throughput, defina um QPS de destino em um endpoint padrão. A capacidade extra só se aplica após o scaling_info.state do endpoint ser SCALING_CHANGE_APPLIED. Atingir esse estado pode levar de minutos a horas, por isso aguarde antes de realizar o teste de carga. Para rastrear a alteração e seu tempo estimado de conclusão, consulte Rastrear o progresso do dimensionamento.

Para mais informações, veja Usar variável de ambiente para acessar recurso.

Remover um recurso de Índice de Pesquisa de AI​

Ao remover um recurso de índice do AI Search de um aplicativo, a entidade de serviço do aplicativo perde o acesso ao índice. O próprio índice permanece inalterado e continua disponível para outros usuários e aplicativos que tenham as permissões apropriadas.

Melhores práticas​

Considere o seguinte ao trabalhar com recursos do Índice de Pesquisa de IA:

  • Certifique-se de que a entidade de serviço do aplicativo tenha acesso à fonte de dados subjacente se o índice fizer referência a outras tabelas.
  • Monitore o desempenho das consultas e ajuste a configuração do índice ou os modelos de incorporação caso os tempos de resposta se degradem.
  • Considere um programa refresh de índice para manter os embeddings sincronizados com os dados de origem.
  • Utilize métricas de similaridade apropriadas (cosseno, euclidiana, produto escalar) com base no seu modelo de incorporação.
  • Um endpoint pode estar online antes que seus índices estejam prontos para query. Para verificar um índice sem bloquear, leia ready e detailed_state no campo status que index.describe() retorna. Para aguardar um índice, chame index.wait_until_ready(), que faz polling a cada 30 segundos e gera um erro se o índice ficar offline ou se o tempo limite passar.