Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Adicione índices de Pesquisa de IA como recursos do Databricks Apps para habilitar a pesquisa semântica e a recuperação baseada em similaridade em seus aplicativos. Os índices do AI Search armazenam e consultam embeddings vetoriais de alta dimensão, viabilizando casos de uso como geração aumentada por recuperação (RAG), pesquisa semântica e sistemas de recomendação.
A Pesquisa de IA do Databricks era anteriormente conhecida como Pesquisa de Vetores do Databricks.
Requisitos de privilégio
Para acessar um índice de Pesquisa de IA, 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. Quando você adiciona o recurso de índice, Azure Databricks concede automaticamente esses privilégios à entidade de serviço do aplicativo.
Para que essa concessão automática seja bem-sucedida, um dos seguintes deve ser verdadeiro para cada privilégio:
-
Para
USE CATALOG: ou todos os usuários da conta têm o privilégioUSE CATALOGno catálogo ou você tem o privilégioMANAGEno catálogo. -
Para
USE SCHEMA: Ou todos os usuários da conta possuem o privilégioUSE SCHEMAno esquema, ou você possui o privilégioMANAGEno esquema. -
Para
SELECT: ou todos os usuários da conta têm o privilégioSELECTno índice; ou você tem o privilégioMANAGEno índice.
Se o índice usar um modelo de embedding gerenciado pela Databricks em um endpoint de throughput provisionado ou endpoint de serviço personalizado, também adicione esse endpoint como um recurso do aplicativo com permissão Pode consultar, além de qualquer endpoint de embedding de consulta separado (model_endpoint_name_for_query).
get_index() lê esses endpoints e falha sem acesso. Os pontos de extremidade das APIs de modelo básico pay-per-token, como databricks-gte-large-en, não precisam de um recurso de aplicativo, a menos que a conta restrinja modelos de base com permissões do Unity Catalog, quando a entidade de serviço precisa de EXECUTE no modelo. Veja Configurar uma entidade de serviço.
Para obter mais informações sobre como consultar índices de Pesquisa de IA com essas permissões, consulte Como consultar um índice de Pesquisa de IA.
Consulte Referência de privilégios do Unity Catalog.
Adicionar um recurso de índice de pesquisa de IA
Antes de adicionar um índice de Pesquisa de IA como um recurso, examine os pré-requisitos do recurso de aplicativo.
- Na seção Recursos do App ao criar um aplicativo, ou em Configurações>Recursos ao editar um aplicativo, clique em + Adicionar recurso>.
- Escolha um índice de pesquisa de IA entre os índices disponíveis em seu espaço de trabalho. O índice já deve existir no Catálogo do Unity.
- Selecione o nível de permissão do aplicativo:
- Pode selecionar: Concede a permissão do aplicativo para consultar o índice de Pesquisa de IA para pesquisas de similaridade. Corresponde ao privilégio SELECT.
- (Opcional) Especifique uma chave de recurso personalizada, que é como você faz referência ao índice na configuração do aplicativo. A chave padrão é
vector-search-index.
Observação
Os índices de Pesquisa de IA são tabelas do Catálogo do Unity com tipo TABLE_ONLINE_VECTOR_INDEX_REPLICA ou TABLE_ONLINE_VECTOR_INDEX_DIRECT. Ao selecionar um índice de Pesquisa de IA, você está selecionando uma tabela especialmente configurada que dá suporte a operações de pesquisa semântica.
Variáveis de ambiente
Quando você implanta um app com um recurso de índice do AI Search, o Azure 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:
env:
- name: VECTOR_SEARCH_INDEX
valueFrom: vector-search-index # Use your custom resource key if different
Usando o índice em seu aplicativo:
Consulte o índice com o databricks-ai-search SDK Python e as credenciais do principal de serviço do app. Quando o workspace atende aos requisitos da URL do índice, o SDK envia consultas para a URL do índice, que pode usar a capacidade extra de um endpoint com uma taxa alvo de consultas por segundo (QPS). Consultas enviadas com WorkspaceClient().vector_search_indexes.query_index utilizam a URL de consulta do workspace, que é limitada a algumas dezenas de QPS. Consultas enviadas com o token do usuário a partir da autorização do usuário também usam a URL da consulta do workspace, portanto envie tráfego de busca com o principal de serviço do aplicativo.
Adicione databricks-ai-search a versão 0.83 ou superior às dependências do seu aplicativo. Consulte Gerenciar dependências de um aplicativo do Databricks.
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 alcançar maior taxa de transferência, defina um QPS alvo em um endpoint padrão. A capacidade extra se aplica apenas após o scaling_info.state do endpoint ser SCALING_CHANGE_APPLIED. Alcançar esse estado pode levar de minutos a horas, então espere até atingir esse estado antes de fazer o teste de carga. Para acompanhar a mudança e seu tempo estimado de conclusão, consulte Acompanhar o progresso do escalonamento.
Para obter mais informações, consulte Usar variáveis de ambiente para acessar recursos.
Remova um recurso de índice de Pesquisa de IA
Quando você remove um recurso de índice da Pesquisa de IA de um aplicativo, a entidade de serviço do aplicativo perde acesso ao índice. O índice em si permanece inalterado e continua disponível para outros usuários e aplicativos que têm permissões apropriadas.
Práticas recomendadas
Considere o seguinte ao trabalhar com recursos de índice de pesquisa de IA:
- Verifique se a entidade de serviço do aplicativo tem acesso a fontes de dados subjacentes se o índice fizer referência a outras tabelas.
- Monitore o desempenho da consulta e ajuste a configuração de índice ou os modelos de inserção se os tempos de resposta forem prejudicados.
- Considere agendamentos de atualização de índice para manter as inserções sincronizadas com os dados de origem.
- Use métricas de similaridade apropriadas (cosseno, euclidiano, produto de ponto) com base em seu modelo de incorporação.
- Um endpoint pode estar online antes que seus índices estejam prontos para consulta. Para verificar um índice sem bloqueio, leia
readyedetailed_stateno campostatusqueindex.describe()retorna. Para esperar por um índice, chameindex.wait_until_ready(), que verifica o índice a cada 30 segundos e gera um erro se o índice ficar offline ou se o timeout passar.