Criar pontos de extremidade e índices de pesquisa de vetor

Este artigo descreve como criar endpoints e índices de busca vetorial usando Vector Search.

Você pode criar e gerenciar componentes de pesquisa de vetor, como um ponto de extremidade de pesquisa vetor e índices de pesquisa de vetor, usando a interface do usuário, o SDK Python ou a API REST.

Por exemplo, notebooks que ilustram como criar e consultar endpoints de pesquisa por vetor, consulte os notebooks de exemplo de pesquisa por vetor. Para obter informações de referência, consulte a referência do SDK do Python.

Requirements

• Workspace habilitado para Catálogo do Unity.
• Computação sem servidor habilitada. Para obter instruções, consulte Conectar-se à computação sem servidor.
• Para pontos de extremidade padrão, a tabela de origem deve ter o Feed de Dados de Alterações habilitado. Consulte Use o feed de dados de alterações do Delta Lake no Azure Databricks.
• Para criar um índice de pesquisa de vetor, você deve ter CREATE TABLE privilégios no esquema de catálogo em que o índice será criado.
• Para consultar um índice que pertence a outro usuário, você deve ter privilégios adicionais. Veja como consultar um índice de pesquisa de vetor.

A permissão para criar e gerenciar terminais de busca vetorial é configurada usando listas de controle de acesso. Consulte ACLs do endpoint de pesquisa vetorial.

Installation

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

%pip install databricks-vectorsearch
dbutils.library.restartPython()

Em seguida, use o seguinte comando para importar VectorSearchClient:

from databricks.vector_search.client import VectorSearchClient

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

Criar um endpoint de pesquisa de vetor

Você pode criar um endpoint de pesquisa vetorial usando a interface do usuário do Databricks, o SDK do Python ou a API.

Criar um endpoint de pesquisa de vetor usando a interface de usuário

Siga estas etapas para criar um endpoint de pesquisa de vetor usando a interface.

1. Na barra lateral esquerda, clique em Computação.

2. Clique na guia Pesquisa de Vetor e clique em Criar ponto de extremidade.

   

3. O formulário Criar ponto de extremidade é aberto. Insira um nome para este endpoint.

   

4. No campo Tipo , selecione Padrão ou Otimizado para Armazenamento. Consulte Opções de ponto de extremidade.

5. (Opcional) Em configurações avançadas, selecione uma política de uso. Consulte as políticas de uso de pesquisa do Vector.

6. Clique em Confirmar.

Criar um endpoint de busca vetorial usando o SDK do Python

O exemplo a seguir usa a função do SDK create_endpoint() para criar um endpoint de pesquisa de vetor.

# The following line automatically generates a PAT Token for authentication
client = VectorSearchClient()

# The following line uses the service principal token for authentication
# client = VectorSearchClient(service_principal_client_id=<CLIENT_ID>,service_principal_client_secret=<CLIENT_SECRET>)

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD" # or "STORAGE_OPTIMIZED"
)

Criar um endpoint de busca vetorial usando a API REST

Consulte a documentação de referência da API REST: POST /api/2.0/vector-search/endpoints.

Criar um endpoint de busca vetorial usando Declarative Automation Bundles

Você pode definir um endpoint de busca vetorial como um recurso nos Declarative Automation Bundles para gerenciá-lo como código junto com seus jobs, pipelines e outros ativos do espaço de trabalho. Para obter uma visão geral dos pacotes, consulte o que são pacotes de automação declarativa?.

O exemplo a seguir define um ponto de extremidade de pesquisa de vetor padrão:

resources:
  vector_search_endpoints:
    my_vector_search_endpoint:
      name: my_vector_search_endpoint
      endpoint_type: STANDARD

Para obter a lista completa de campos com suporte, incluindo endpoint_type, budget_policy_ide min_qps, consulte permissionsvector_search_endpoint.

Criar um endpoint com QPS de destino para cargas de trabalho de alta taxa de transferência

Para cargas de trabalho de alta taxa de transferência, você pode criar um endpoint com QPS de destino. Esse recurso está disponível apenas para endpoints padrão.

Para definir um QPS de destino, use o target_qps parâmetro. Consulte Como aumentar a taxa de transferência do endpoint com QPS alto.

client.create_endpoint(
    name="vector_search_endpoint_name",
    endpoint_type="STANDARD",
    target_qps=500,  # target QPS for high-throughput workloads
)

Para alterar o QPS alvo em um endpoint existente, use update_endpoint().

from databricks.vector_search.client import VectorSearchClient

client = VectorSearchClient()

# Set or update target QPS
response = client.update_endpoint(name="vector_search_endpoint_name", target_qps=500)

# Check scaling status
scaling_info = response.get("endpoint", {}).get("scaling_info", {})
print(f"State: {scaling_info.get('state')}")  # SCALING_CHANGE_IN_PROGRESS or SCALING_CHANGE_APPLIED

Depois de atualizar o QPS de destino, sincronize seus índices para aplicar a nova configuração.

(Opcional) Criar e configurar um ponto de extremidade para atender ao modelo de inserção

Se você optar por ter o Databricks comutando as incorporações, poderá usar um endpoint de APIs de Modelo Fundamental pré-configurado ou criar um endpoint de serviço de modelo para atender ao modelo de incorporação de sua escolha. Consulte APIs de Modelo de Base de pagamento por token ou Criar modelo de base que atende os pontos de extremidade para obter instruções. Para obter exemplos de notebooks, consulte exemplos de notebooks de pesquisa Vector.

Quando você configura um ponto de extremidade de inserção, o Databricks recomenda que você remova a seleção padrão de Escala para zero. Os pontos de extremidade de serviço pode levar alguns minutos para se aquecer, e a consulta inicial em um índice com um ponto de extremidade reduzido pode demorar.

Criar um índice de pesquisa de vetor

Você pode criar um índice de pesquisa de vetor usando a interface do usuário, o SDK do Python ou a API REST. A interface do usuário é a abordagem mais simples.

Há dois tipos de índices:

• O Índice de Sincronização Delta sincroniza automaticamente com uma Tabela Delta de origem, atualizando automaticamente e incrementalmente o índice conforme os dados subjacentes na Tabela Delta são alterados.
• Direct Vector Access Index dá suporte à leitura direta e à gravação de vetores e metadados. O usuário é responsável por atualizar essa tabela usando a API REST ou o SDK do Python. Esse tipo de índice não pode ser criado usando a interface do usuário. Você deve usar a API REST ou o SDK.

Os Índices de Sincronização Delta dão suporte aos seguintes modos de pesquisa:

• Pesquisa de vetor (ANN ou híbrida): requer colunas de inserção. Dá suporte a endpoints padrão e otimizados para armazenamento. Você também pode usar query_type="FULL_TEXT" para pesquisa de palavra-chave nesses índices.
• Índice de pesquisa de texto completo dedicado (Beta): Um Índice de Sincronização Delta criado sem colunas de inserção, para pesquisa somente de palavra-chave. Disponível somente em pontos de extremidade otimizados para armazenamento usando o modo de sincronização acionada. Consulte Criar um índice de pesquisa de texto completo.

Criar índice usando a interface do usuário

1. Na barra lateral esquerda, clique em Catálogo para abrir a interface do usuário do Catalog Explorer.

2. Navegue até a tabela Delta que você deseja usar.

3. Clique no botão Criar no canto superior direito e selecione Índice de busca em vetores no menu suspenso.

   

4. Use os seletores na caixa de diálogo para configurar o índice.

   

   Estrutura de índice

   Nome: nome a ser usado para a tabela online no Catálogo do Unity. O nome requer um namespace de três níveis, <catalog>.<schema>.<name>. Somente caracteres alfanuméricos e sublinhados são permitidos.

   Tipo de índice: selecione Híbrido para dar suporte à pesquisa semântica (vetor) e à palavra-chave no mesmo índice. Selecione Texto Completo para pesquisa somente palavra-chave sem inserções. Consulte Criar um índice de pesquisa de texto completo (Beta) para obter requisitos de índice de texto completo.

   Chave primária: coluna a ser usada como chave primária.

   Embeddings

   Fonte de inserção: indique se você deseja que o Databricks compute inserções para uma coluna de texto na tabela Delta (inserções de computação) ou se sua tabela Delta contém inserções pré-computadas (Use inserções existentes).

   • Se você selecionou Calcular embeddings, selecione a coluna para a qual deseja calcular os embeddings. Um modelo de inserção gerenciado pelo Databricks é selecionado por padrão. Para usar um modelo diferente, expanda as configurações avançadas e escolha na lista suspensa do modelo de inserção . Há suporte apenas para colunas de texto.

     • Para aplicativos de produção que usam pontos de extremidade padrão, o Databricks recomenda usar o modelo fundamental databricks-qwen3-embedding-0-6b com provisionamento de taxa de transferência para o ponto de extremidade.

     • Para aplicativos de produção que usam pontos de extremidade otimizados para armazenamento com modelos hospedados pelo Databricks, use o nome do modelo diretamente (por exemplo, databricks-qwen3-embedding-0-6b) como o ponto de extremidade do modelo de incorporação. Os pontos de extremidade otimizados para armazenamento usam ai_query com inferência em lote no momento da ingestão, fornecendo alta taxa de transferência para o trabalho de incorporação. Se você preferir usar um ponto de extremidade de taxa de transferência provisionado para realizar consultas, especifique-o no campo model_endpoint_name_for_query ao criar o índice.

   • Se você selecionou Usar inserções existentes, selecione a coluna que contém as inserções pré-computadas e a dimensão de inserção. O formato da coluna de inserção pré-computada deve ser array[float]. Para pontos de extremidade otimizados para armazenamento, a dimensão da incorporação deve ser uniformemente divisível por 16.

   Salve inserções computadas: alterne essa configuração para salvar as inserções geradas em uma tabela do Catálogo do Unity. Para obter mais informações, consulte Salvar a tabela de inserção gerada.

   Recursos de computação

   Endpoint de pesquisa vetorial: Selecione o endpoint de pesquisa vetorial para armazenar o índice.

   Modo de sincronização: o contínuo mantém o índice em sincronia com segundos de latência. No entanto, ele tem um custo mais alto associado a ele, uma vez que um cluster de computação é provisionado para executar o pipeline de streaming de sincronização contínua.

   • Para os pontos de extremidade padrão, tanto Contínuos quanto Disparados executam atualizações incrementais, portanto, somente os dados que foram alterados desde a última sincronização são processados.
   • Para pontos finais otimizados para armazenamento, cada sincronização reconstrói parcialmente o índice. Para índices gerenciados em sincronizações subsequentes, todas as incorporações geradas em que a linha de origem não foi alterada são reutilizadas e não precisam ser recomputadas. Consulte Limitações de pontos de extremidade otimizados para armazenamento.

   Com o modo de sincronização "Triggered", você usa o SDK Python ou a API REST para iniciar a sincronização. Consulte "Atualizar um Índice de Sincronização Delta".

   Para pontos de extremidade otimizados para armazenamento, há suporte apenas para o modo de sincronização Disparado.

   Configurações avançadas

   

   A seção Configurações avançadas fica recolhida por padrão. A maioria dos usuários pode aceitar os padrões. Expanda-o para ajustar qualquer um dos seguintes:

   Modelo de inserção: substitua o modelo de inserção padrão. O modelo padrão hospedado pelo Databricks funciona para a maioria dos workspaces. Altere-o aqui se você precisar de outro ou se não tiver acesso ao padrão.

   Colunas para indexar: selecione as colunas a serem incluídas no índice. Se você deixar esse campo em branco, todas as colunas da tabela de origem serão indexadas. A chave primária e as colunas de inserção são sempre incluídas. Somente colunas indexadas podem ser retornadas nos resultados da pesquisa ou usadas como filtros.

   Política de uso: aplique uma política de uso para marcar os custos do índice para acompanhamento por equipe ou projeto. Consulte as políticas de uso de pesquisa do Vector.

   Usar um modelo de embeddings separado para consultas: se você selecionou Calcular embeddings, selecione esta opção para especificar um endpoint de serviço separado para o modelo de embeddings usado para consultar o índice. Isso pode ser útil se você precisar de um endpoint de alto throughput para ingestão, mas de um endpoint de menor latência para consultas. O modelo especificado no campo de modelo de inserção é sempre usado para ingestão e também é usado para consulta, a menos que você especifique um modelo diferente aqui.

5. Quando terminar de configurar o índice, clique em Criar.

Criar índice usando o SDK do Python

O exemplo a seguir cria um Índice de Sincronização Delta com inserções computadas pelo Databricks. Para obter detalhes, consulte a referência Python SDK.

Este exemplo também mostra o parâmetro opcional model_endpoint_name_for_query, que especifica um ponto de extremidade de serviço de um modelo de incorporação separado a ser usado para consultar o índice.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_source_column="text",
  embedding_model_endpoint_name="e5-small-v2", # This model is used for ingestion, and is also used for querying unless model_endpoint_name_for_query is specified.
  model_endpoint_name_for_query="e5-mini-v2"   # Optional. If specified, used only for querying the index.
)

O exemplo a seguir cria um Índice de Sincronização Delta com inserções autogerenciadas.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="vector_search_demo_endpoint",
  source_table_name="vector_search_demo.vector_search.en_wiki",
  index_name="vector_search_demo.vector_search.en_wiki_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector"
)

Por padrão, todas as colunas da tabela de origem são sincronizadas com o índice. Para selecionar um subconjunto de colunas a serem sincronizadas, use columns_to_sync. A chave primária e as colunas de inserção são sempre incluídas no índice.

Para sincronizar apenas a chave primária e a coluna de inserção, especifique-as columns_to_sync conforme mostrado:

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["id", "text_vector"] # to sync only the primary key and the embedding column
)

Para sincronizar colunas adicionais, especifique-as conforme mostrado. Você não precisa incluir a chave primária e a coluna de inserção, pois elas são sempre sincronizadas.

index = client.create_delta_sync_index(
  ...
  columns_to_sync=["revisionId", "text"] # to sync the `revisionId` and `text` columns in addition to the primary key and embedding column.
)

Criar um índice de pesquisa de texto completo (Beta)

Um índice de pesquisa de texto completo habilita a pesquisa baseada em palavra-chave em colunas de texto sem a necessidade de inserções de vetor. Isso é útil quando você deseja pesquisar termos exatos, identificadores ou palavras-chave em vez de similaridade semântica.

Os índices de pesquisa de texto completo têm os seguintes requisitos:

• Deve usar um endpoint otimizado para armazenamento. Não há suporte para pontos de extremidade padrão.
• Deve usar o modo de sincronização gatilhado. Não há suporte para sincronização contínua.
• Não há suporte para os parâmetros embedding_source_column, embedding_vector_column e embedding_dimension.

O exemplo a seguir cria um índice de pesquisa de texto completo usando o SDK do Python.

client = VectorSearchClient()

index = client.create_delta_sync_index(
  endpoint_name="storage_optimized_endpoint",
  source_table_name="catalog.schema.source_table",
  index_name="catalog.schema.full_text_index",
  pipeline_type="TRIGGERED",
  primary_key="id",
  columns_to_sync=["id", "text", "metadata_column"],
  index_subtype="FULL_TEXT"
)

Depois de criar o índice, dispare uma sincronização para preenchê-lo:

index.sync()

Para consultar o índice de texto completo, use query_type="FULL_TEXT". Consulte Consultar um índice de pesquisa de vetor para obter detalhes.

results = index.similarity_search(
  query_text="search terms",
  columns=["id", "text"],
  num_results=10,
  query_type="FULL_TEXT"
)

O exemplo a seguir cria um Índice de Acesso de Vetor Direto.

client = VectorSearchClient()

index = client.create_direct_access_index(
  endpoint_name="storage_endpoint",
  index_name=f"{catalog_name}.{schema_name}.{index_name}",
  primary_key="id",
  embedding_dimension=1024,
  embedding_vector_column="text_vector",
  schema={
    "id": "int",
    "field2": "string",
    "field3": "float",
    "text_vector": "array<float>"}
)

Criar índice usando a API REST

Consulte a documentação de referência da API REST: POST /api/2.0/vector-search/indexes.

Salvar a tabela de inserção gerada

Se o Databricks gerar as inserções, você poderá salvar as inserções geradas em uma tabela no Catálogo do Unity. Essa tabela é criada no mesmo esquema que o índice de vetor e é vinculada na página de índice de vetor.

O nome da tabela é o nome do índice de pesquisa de vetor, acrescentado por _writeback_table. O nome não é editável.

Você pode acessar e consultar a tabela como qualquer outra tabela no Catálogo do Unity. No entanto, você não deve remover ou modificar a tabela, pois ela não se destina a ser atualizada manualmente. A tabela será excluída automaticamente se o índice for excluído.

Atualizar um índice de pesquisa de vetor

Atualizar um índice de sincronização delta

Os índices criados com o modo de sincronização contínua são atualizados automaticamente quando a tabela Delta de origem é alterada. Se você estiver usando o modo de sincronização Triggered, poderá iniciar a sincronização usando a interface do usuário, o SDK do Python ou a API REST.

Interface do usuário do Databricks

1. No Catalog Explorer, navegue até o índice de pesquisa de vetor.

2. Na guia Visão Geral , na seção Ingestão de Dados , clique em Sincronizar agora.

   .

SDK do Python

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

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

index.sync()

API REST

Consulte a documentação de referência da API REST: POST /api/2.0/vector-search/indexes/{index_name}/sync.

Atualizar um índice de acesso direto ao vetor

Você pode usar o SDK Python ou a API REST para inserir, atualizar ou excluir dados de um índice de acesso de vetor direto.

SDK do Python

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

index.upsert([
    {
        "id": 1,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.0] * 1024
    },
    {
        "id": 2,
        "field2": "value2",
        "field3": 3.0,
        "text_vector": [1.1] * 1024
    }
])

API REST

Consulte a documentação de referência da API REST: POST /api/2.0/vector-search/indexes.

Para aplicativos de produção, o Databricks recomenda usar entidades de serviço em vez de tokens de acesso pessoal. O desempenho pode ser melhorado em até 100 msec por consulta.

O exemplo de código a seguir ilustra como atualizar um índice usando um principal de serviço.

export SP_CLIENT_ID=...
export SP_CLIENT_SECRET=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...
export WORKSPACE_ID=...

# Set authorization details to generate OAuth token
export AUTHORIZATION_DETAILS='{"type":"unity_catalog_permission","securable_type":"table","securable_object_name":"'"$INDEX_NAME"'","operation": "WriteVectorIndex"}'

# Generate OAuth token
export TOKEN=$(curl -X POST --url $WORKSPACE_URL/oidc/v1/token -u "$SP_CLIENT_ID:$SP_CLIENT_SECRET" --data 'grant_type=client_credentials' --data 'scope=all-apis' --data-urlencode 'authorization_details=['"$AUTHORIZATION_DETAILS"']' | jq .access_token | tr -d '"')

# Get index URL
export INDEX_URL=$(curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME | jq -r '.status.index_url' | tr -d '"')

# Upsert data into vector search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/upsert-data --data '{"inputs_json": "[...]"}'

# Delete data from vector search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/delete-data --data '{"primary_keys": [...]}'

O exemplo de código a seguir ilustra como atualizar um índice usando um PAT (token de acesso pessoal).

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Upsert data into vector search index.
curl -X POST -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/upsert-data --data '{"inputs_json": "..."}'

# Delete data from vector search index
curl -X DELETE -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/delete-data --data '{"primary_keys": [...]}'

Como fazer alterações de esquema sem tempo de inatividade

Não há suporte para alterações de esquema na tabela de origem, a menos que você recompile o índice. Isso inclui a modificação de colunas existentes e a adição de novas colunas. O esquema de índice é corrigido no momento da criação, portanto, todas as alterações de esquema exigem a criação de um novo índice para entrar em vigor.

Siga estas etapas para recompilar e implantar o índice sem tempo de inatividade:

1. Execute a alteração do esquema na tabela de origem.
2. Crie um novo índice usando o esquema atualizado.
3. Depois que o novo índice estiver pronto, alterne o tráfego para o novo índice.
4. Exclua o índice original.