Criar endpoints e índices de pesquisa vetorial

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

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

Por exemplo, cadernos que ilustram como criar e consultar endpoints de pesquisa vetorial, veja cadernos de exemplo de pesquisa vetorial. Para obter informações de referência, consulte a referência do SDK do 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. Consulte o feed de alterações de dados 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

Você pode criar um endpoint de pesquisa vetorial usando a interface do utilizador do Databricks, o SDK do 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 no separador Pesquisa vetorial e clique em Criar .

   

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. Consulte Mosaic AI Vetor Search: Políticas orçamentais.

6. Clique em Confirmar.

Criar um ponto de extremidade de pesquisa vetorial usando o Python SDK

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.

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

Observação

A inicialização do índice de pesquisa vetorial pode atingir o tempo limite se o ponto de extremidade de incorporação não estiver configurado adequadamente para o conjunto de dados. Você só deve usar terminais de CPU para pequenos conjuntos de dados e testes. Para conjuntos de dados maiores, use um endpoint GPU para obter o desempenho ideal.

Criar um índice de pesquisa vetorial

Você pode criar um índice de pesquisa vetorial usando a interface do usuário, o SDK do 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 usuário é responsável por atualizar esta tabela usando a API REST ou o Python SDK. Esse tipo de índice não pode ser criado usando a interface do usuário. Você deve usar a API REST ou o SDK.

Observação

O nome da coluna _id está reservado. Se a tabela de origem tiver uma coluna chamada _id, renomeie-a antes de criar um índice de pesquisa vetorial.

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 o SDK do Python ou a API REST para iniciar a sincronização. Consulte Atualizar 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. Consulte Mosaic AI Vetor Search: Políticas orçamentais.

   • Se selecionou Compute embeddings, pode especificar um modelo de embedding separado para consultar o seu índice de pesquisa vetorial. Isso pode ser útil se você precisar de um ponto de extremidade de alta taxa de transferência para ingestão, mas um ponto de extremidade de 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 do Python

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

Este exemplo também mostra o parâmetro model_endpoint_name_for_queryopcional , que especifica um modelo de incorporação separado que serve o ponto de extremidade 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 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.
)

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 você estiver usando o modo de sincronização acionado , 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 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 obter detalhes, consulte a referência do SDK do 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

Você pode usar o SDK do Python ou a API REST para inserir, atualizar ou excluir dados de um Direct Vetor Access Index.

Python SDK

Para obter detalhes, consulte a referência do SDK do 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

Se o esquema das colunas existentes na tabela de origem mudar, terá de reconstruir o índice. Se a tabela de writeback estiver ativada, é necessário também reconstruir o índice sempre que novas colunas forem adicionadas à tabela de origem. Se a tabela de writeback não estiver ativada, as novas colunas não requerem reconstruir o índice.

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.
3. Depois de o novo índice estar pronto, mude o tráfego para o novo índice.
4. Apaga o índice original.