Criar endpoints e índices de pesquisa vetorial

Este artigo descreve como criar endpoints e índices de pesquisa vetorial usando a Mosaic AI Vector Search.

Pode criar e gerir componentes de pesquisa vetorial, como um endpoint de pesquisa vetorial e índices de pesquisa vetorial, usando a interface, o SDK Python ou a API REST.

Por exemplo, cadernos que ilustram como criar e consultar endpoints de pesquisa vetorial, veja cadernos de exemplo de pesquisa vetorial. Para informações de referência, consulte a referência do SDK Python.

Requerimentos

• Espaço de trabalho com o Catálogo Unity ativado.
• 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 Change Data Feed habilitado. Veja Use o feed de dados de alterações do Delta Lake no Azure Databricks.
• Para criar um índice de pesquisa vetorial, você deve ter privilégios de CREATE TABLE no esquema de catálogo onde 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 vetorial.

A permissão para criar e gerir terminais de pesquisa vetorial é configurada usando listas de controlo de acesso. Consulte as ACLs do ponto de extremidade de pesquisa vetorial.

Installation

Para usar o SDK de pesquisa vetorial, você deve instalá-lo em seu bloco de anotações. 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 informações sobre autenticação, consulte Proteção e autenticação de dados.

Criar um endereço de pesquisa vetorial

Pode criar um endpoint de pesquisa vetorial usando a interface do Databricks, o SDK Python ou a API.

Criar um endpoint de pesquisa vetorial usando a interface gráfica do utilizador

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

1. Na barra lateral esquerda, clique em Compute.

2. Clique na aba Pesquisa Vetorial e clique em Criar endpoint.

   

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

   

4. No campo Tipo, selecione Padrão ou Armazenamento otimizado. Consulte Opções de ponto final.

5. (Opcional) Em Configurações avançadas, selecione uma política de orçamento. Ver políticas orçamentais de pesquisa vetorial.

6. Clique em Confirmar.

Crie um endpoint de pesquisa vetorial usando o SDK Python

O exemplo a seguir usa a função create_endpoint() SDK para criar um ponto de extremidade de pesquisa vetorial.

# 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 pesquisa 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 com um objetivo mínimo de QPS para cargas de trabalho de alto rendimento

Para cargas de trabalho de alto rendimento, pode criar um endpoint com uma meta mínima de QPS. Esta funcionalidade está disponível apenas para endpoints padrão.

Para definir um alvo mínimo de QPS, use o min_qps parâmetro. Veja Aumentar a taxa de transferência do endpoint com alto QPS (Beta).

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

Para alterar o QPS mínimo num endpoint existente, use update_endpoint().

from databricks.vector_search.client import VectorSearchClient, MIN_QPS_RESET_TO_DEFAULT

client = VectorSearchClient()

# Set or update minimum QPS
response = client.update_endpoint(name="vector_search_endpoint_name", min_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

# Remove high QPS configuration and return to default
client.update_endpoint(name="vector_search_endpoint_name", min_qps=MIN_QPS_RESET_TO_DEFAULT)

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

(Opcional) Criar e configurar um endpoint para servir o modelo de embed

Se você optar por fazer com que o Databricks calcule as incorporações, poderá usar um ponto de extremidade de APIs de Modelo de Base pré-configurado ou criar um ponto de extremidade de serviço de modelo para atender ao modelo de incorporação de sua escolha. Consulte APIs do modelo de base de pagamento por token ou Criar modelo de base servindo pontos de extremidade para obter instruções. Para cadernos de exemplo, veja cadernos de exemplo de pesquisa vetorial.

Quando configuras um ponto de extremidade de integração, a Databricks recomenda que removas a seleção predefinida de Escala para zero. Os pontos de extremidade de serviço podem levar alguns minutos para ficar operacionais, e a consulta inicial em um índice com um ponto de extremidade reduzido pode expirar o tempo limite.

Criar um índice de pesquisa vetorial

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

Existem dois tipos de índices:

• do Índice de Sincronização Delta sincroniza automaticamente com uma Tabela Delta de origem, atualizando automática e incrementalmente o índice à medida que os dados subjacentes na Tabela Delta mudam.
• Direct Vetor Access Index suporta leitura e gravação diretas de vetores e metadados. O utilizador é responsável por atualizar esta tabela usando a API REST ou o SDK 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 Delta Sync suportam os seguintes modos de pesquisa:

• Pesquisa vetorial (ANN ou híbrida): Requer incorporação de colunas. Suporta endpoints padrão e otimizados para armazenamento. Também pode usar query_type="FULL_TEXT" para pesquisa por palavras-chave nestes índices.
• Índice dedicado de pesquisa em texto completo (Beta): Um Índice Delta Sync criado sem quaisquer colunas de embedding, para pesquisa apenas por palavras-chave. Disponível apenas em endpoints otimizados para armazenamento que utilizam o modo de sincronização desencadeado. Veja Criar um índice de pesquisa em 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 pesquisa vetorial no menu suspenso.

   

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

   

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

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

   Colunas a sincronizar: Selecione as colunas a sincronizar com o índice vetorial. Se você deixar esse campo em branco, todas as colunas da tabela de origem serão sincronizadas com o índice. A coluna de chave primária e a coluna de origem de incorporação ou a coluna de vetor de incorporação são sempre sincronizadas.

   Incorporação de fontes: Indique se deseja que o Databricks calcule incorporações para uma coluna de texto na tabela Delta (Compute embeddings), ou se sua tabela Delta contém incorporações pré-computadas (Use a coluna de incorporação existente).

   • Se você selecionou Incorporações de computação, selecione a coluna para a qual deseja que as incorporações sejam computadas e o modelo de incorporação a ser usado para a computação. Apenas colunas de texto são suportadas.

     • Para aplicações de produção que utilizam endpoints padrão, a Databricks recomenda usar o modelo fundamental databricks-gte-large-en com um endpoint de serviço de throughput predefinido.

     • Para aplicações de produção que usam endpoints otimizados para armazenamento com modelos alojados em Databricks, use o nome do modelo diretamente (por exemplo, databricks-gte-large-en) como endpoint de modelo de incorporação. Os endpoints otimizados para armazenamento utilizam ai_query com inferência em lote no momento da ingestão, proporcionando um alto rendimento para o trabalho de embedding. Se preferir usar um endpoint de throughput provisionado para consultas, especifique-o no campo model_endpoint_name_for_query quando criar o índice.

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

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

   Ponto de extremidade de pesquisa vetorial: selecione o ponto de extremidade de pesquisa vetorial para armazenar o índice.

   modo de sincronização: Contínuo mantém o índice sincronizado com latência de segundos. 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 endpoints padrão, Contínuo e Acionado executam atualizações incrementais, portanto, apenas os dados alterados desde a última sincronização são processados.
   • Para endpoints otimizados para armazenamento, cada ação de sincronização recria 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 recalculadas. Consulte Limitações de endpoints otimizados para armazenamento.

   Com o modo de sincronização Triggered, utiliza-se o SDK Python ou a API REST para iniciar a sincronização. Veja Atualize um índice de sincronização delta.

   Para endpoints otimizados para armazenamento, apenas o modo de sincronização acionado é suportado.

   Definições Avançadas: (Opcional)

   • Pode aplicar uma política orçamental ao índice. Ver políticas orçamentais de pesquisa vetorial.

   • Se selecionou Compute embeddings, pode especificar um modelo de embedding separado para consultar o seu índice de pesquisa vetorial. Isso pode ser útil se precisar de um ponto de extremidade com alta taxa de transferência para ingestão, mas com latência mais baixa para consultar o índice. O modelo especificado no campo Modelo de incorporação é sempre usado para ingestão e também é usado para consulta, a menos que você especifique um modelo diferente aqui. Para especificar um modelo diferente, clique em Escolher modelo de incorporação separado para consultar o índice e selecione um modelo no menu suspenso.

     

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

Criar índice usando o SDK Python

O exemplo a seguir cria um índice Delta Sync com incorporações computadas por Databricks. Para mais detalhes, consulte a referência do SDK Python.

Este exemplo também mostra o parâmetro opcional model_endpoint_name_for_query, que especifica um ponto de extremidade separado para o modelo de incorporação a ser utilizado 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 incorporaçõ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 sincronizar, use columns_to_sync. A chave primária e as colunas de incorporação são sempre incluídas no índice.

Para sincronizar apenas a chave primária e a coluna de incorporação, você deve especificá-las em 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. Não é necessário incluir a chave primária e a coluna de incorporação, pois elas estã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.
)

Crie um índice de pesquisa em texto completo (Beta)

Um índice de pesquisa em texto completo permite pesquisa baseada em palavras-chave nas colunas de texto sem necessidade de embeddings vetoriais. Isto é útil quando se quer procurar termos exatos, identificadores ou palavras-chave em vez de similaridade semântica.

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

• Deve usar um endpoint otimizado para armazenamento . Pontos de extremidade padrão não são suportados.
• Tem de usar o modo de sincronização desencadeado . A sincronização contínua não é suportada.
• Os parâmetros embedding_source_column, embedding_vector_columne embedding_dimension não são suportados.

O exemplo seguinte cria um índice de pesquisa em texto completo usando o SDK 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, acione uma sincronização para o preencher:

index.sync()

Para consultar o índice do texto completo, use query_type="FULL_TEXT". Consulte um índice de pesquisa vetorial para mais 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 Direct Vetor Access Index.

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 tabela de incorporação gerada

Se o Databricks gerar as incorporações, você poderá salvar as incorporações geradas em uma tabela no Unity Catalog. Esta tabela é criada no mesmo esquema que o índice vetorial e é vinculada a partir da página de índice vetorial.

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

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

Atualizar um índice de pesquisa vetorial

Atualizar um Índice Delta Sync

Os índices criados com modo de sincronização de contínua são atualizados automaticamente quando a tabela Delta de origem é alterada. Se estiveres a usar o modo de sincronização Triggered, podes iniciar a sincronização usando a interface, o SDK Python ou a API REST.

Interface do usuário do Databricks

1. No Gerenciador de Catálogos, navegue até o índice de pesquisa vetorial.

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

   .

Python SDK

Para mais detalhes, consulte a referência do SDK Python.

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 vetorial direto

Pode usar o SDK Python ou a API REST para inserir, atualizar ou eliminar dados de um Índice de Acesso Vetorial Direto.

Python SDK

Para mais detalhes, consulte a referência do SDK Python.

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 o uso de entidades de serviço em vez de tokens de acesso pessoal. O desempenho pode ser melhorado em até 100 mseg 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 token de acesso pessoal (PAT).

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 indisponibilidade

Alterações de esquema na tabela de origem não são suportadas a menos que reconstrua o índice. Isto inclui modificar colunas existentes e adicionar novas colunas. O esquema do índice é fixo no momento da criação, por isso quaisquer alterações no esquema requerem a criação de um novo índice para ter efeito.

Siga estes passos para reconstruir e implementar o índice sem tempo de inatividade:

1. Realiza a alteração do esquema na tua tabela de código-fonte.
2. Crie um novo índice usando o esquema atualizado.
3. Depois de o novo índice estar pronto, mude o tráfego para o novo índice.
4. Apaga o índice original.