Adicione um recurso de índice de pesquisa vetorial a um aplicativo Databricks.

Adicione índices de pesquisa vetorial como recursos Databricks Apps para habilitar a pesquisa semântica e a recuperação baseada em similaridade em seus aplicativos. Os índices de busca vetorial armazenam e consultam representações vetoriais de alta dimensão, possibilitando casos de uso como geração aumentada por recuperação (RAG), busca semântica e sistemas de recomendação.

Requisitos de privilégio

Para acessar um índice de pesquisa vetorial, 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, o Databricks concede automaticamente esses 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.

Para obter mais informações sobre como consultar índices de pesquisa vetorial com essas permissões, consulte Como consultar um índice de pesquisa vetorial.

Consulte PrivilégiosUnity Catalog e objetos protegíveis.

Adicionar um recurso de índice de pesquisa vetorial

Antes de adicionar um índice de pesquisa vetorial como um recurso, revise os pré-requisitos do recurso do aplicativo.

1. Ao criar ou editar um aplicativo, navegue até Configurar o passo.

2. Na seção Recurso do aplicativo , clique em + Adicionar recurso .

3. Selecione o índice de pesquisa vetorial como tipo de recurso.

4. Escolha um índice de pesquisa vetorial dentre os índices disponíveis em seu workspace. O índice já deve existir no Unity Catalog.

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

   • É possível selecionar: Concede permissão ao aplicativo para consultar o índice de pesquisa vetorial em buscas por similaridade. Corresponde ao privilégio SELECT.

6. (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

Os índices de pesquisa vetorial são tabelas Unity Catalog com tipo TABLE_ONLINE_VECTOR_INDEX_REPLICA ou TABLE_ONLINE_VECTOR_INDEX_DIRECT. Ao selecionar um índice de pesquisa vetorial, você está selecionando uma tabela especialmente configurada que oferece suporte a operações de pesquisa semântica.

variável de ambiente

Quando você implanta um aplicativo com um recurso de índice de pesquisa vetorial, Databricks expõe o nome completo de três níveis por meio de variável 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:

Python

import os
from databricks.sdk import WorkspaceClient

# Access the vector search index name
index_name = os.getenv("VECTOR_SEARCH_INDEX")

# Initialize workspace client
w = WorkspaceClient()

# Query the vector search index
results = w.vector_search_indexes.query_index(
    index_name=index_name,
    query_text="What is machine learning?",
    num_results=10
)

# Process results
for result in results.manifest.columns:
    print(f"Result: {result}")

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

Remover um recurso de índice de pesquisa vetorial

Ao remover um recurso de índice de pesquisa vetorial de um aplicativo, a entidade de serviço do aplicativo perde o acesso ao índice. O índice em si permanece inalterado e continua disponível para outros usuários e aplicativos que possuam as permissões adequadas.

Melhores práticas

Considere o seguinte ao trabalhar com o recurso de índice de pesquisa vetorial:

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