Criar pontos de extremidade e índices de pesquisa de vetor

Este artigo descreve como criar endpoints e índices de busca vetorial usando a Busca Vetorial de IA Mosaico.

Você pode criar e gerenciar componentes de pesquisa em vetores, como um endpoint de pesquisa em vetores e índices de pesquisa em vetores, usando a interface do usuário, o SDK do 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. Confira Usar 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 ponto de extremidade da busca em vetores 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 Busca em Vetores e clique em Criar.

   

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 orçamento. Consulte a Busca Vetorial de IA do Mosaico: políticas orçamentárias.

6. Clique em Confirmar.

Criar um endpoint de pesquisa 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.

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

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.

   

   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.

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

   Colunas a serem sincronizadas: selecione as colunas a serem sincronizadas com o índice de vetor. 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 inserção ou a coluna de vetor de inserção são sempre sincronizadas.

   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 a tabela Delta contém inserções pré-computadas (Use a coluna de inserção existente).

   • Se você selecionou inserções de computação, selecione a coluna para a qual deseja que as inserções computadas e o modelo de inserção usem para a computaçã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-gte-large-en 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-gte-large-en) 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 a coluna de inserção existente, 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.

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

   Ponto de extremidade de pesquisa vetor: selecione o ponto de extremidade de pesquisa de vetor 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 disparado, você usa o SDK do 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: (Opcional)

   • Você pode aplicar uma política de orçamento ao índice. Consulte a Busca Vetorial de IA do Mosaico: políticas orçamentárias.

   • Se você selecionou inserções de computação, pode especificar um modelo de inserção separado para consultar o índice de pesquisa de vetor. 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 baixo para consultar o índice. 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. Para especificar um modelo diferente, clique em Escolher modelo de inserçã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 de Sincronização Delta com inserções computadas pelo 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 inserçã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 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.
)

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 Disparado, poderá iniciar a sincronização usando a IU, 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 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 direto ao vetor

Você pode usar o SDK do 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 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 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

Se o esquema de colunas existentes na tabela de origem for alterado, você deverá recompilar o índice. Se a tabela de write-back estiver habilitada, você também deverá recompilar o índice quando novas colunas forem adicionadas à tabela de origem. Se a tabela de write-back não estiver habilitada, novas colunas não exigirão a recriação do índice.

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.
3. Depois que o novo índice estiver pronto, alterne o tráfego para o novo índice.
4. Exclua o índice original.