Pular para o conteúdo principal
Última atualização em

Criar ponto de extremidade e índices de pesquisa vetorial

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

Você pode criar e gerenciar componentes de busca vetorial, como um endpoint de busca vetorial e índices de busca vetorial, usando a interface do usuário, o SDK Python ou a API REST.

Por exemplo, veja o Notebook de exemplo de pesquisa vetorial, que ilustra como criar e consultar um endpoint de pesquisa vetorial. Para obter informações de referência, consulte a referênciaPython SDK.

Requisitos​

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

Instalação​

Para usar o SDK de busca vetorial, você precisa instalá-lo em seu Notebook. Utilize 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 endpointde pesquisa vetorial​

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

Crie um endpoint de pesquisa vetorial usando a interface do usuário.​

Siga estes passos para criar um endpoint de pesquisa vetorial usando a interface do usuário.

  1. Na barra lateral esquerda, clique em calcular .

  2. Clique na tab Pesquisa Vetorial e clique em Criar .

    Criar formulário endpoint

  3. O formulário Criar endpoint será aberto. Insira um nome para este endpoint.

    Criar caixa de diálogo endpoint de pesquisa vetorial.

  4. No campo Tipo , selecione Padrão ou Otimizado para armazenamento . Consulte as opções de endpoint.

  5. (Opcional) Em Configurações avançadas , selecione uma política orçamentária. Consulte Mosaic AI Vector Search: Políticas orçamentárias.

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

Python
# 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"
)

Crie um endpoint de busca vetorial usando a API REST.​

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

(Opcional) Crie e configure um endpoint para disponibilizar o modelo de incorporação.​

Se você optar por que Databricks compute os embeddings, poderá usar um endpoint APIs do Foundation Model pré-configurado ou criar um endpoint de modelo de serviço para disponibilizar o modelo de embedding de sua escolha. Consulte APIsdo modelo Foundation Pay-per-tokens ou o endpoint Criar modelo Foundation para obter instruções. Por exemplo, consulte o exemplo de pesquisa vetorial no Notebook.

Ao configurar um endpoint de incorporação, Databricks recomenda que você remova a seleção default de escala para zero . O servidor pode levar alguns minutos para aquecer e a consulta inicial em um índice com um endpoint reduzido pode expirar.

nota

A inicialização do índice de busca vetorial pode expirar se o endpoint de incorporação não estiver configurado adequadamente para o dataset. Você só deve usar o endpoint da CPU para conjuntos de dados pequenos e para testes. Para conjuntos de dados maiores, utilize um endpoint de GPU para obter o melhor desempenho.

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:

  • O Delta Sync Index sincroniza-se automaticamente com uma tabela Delta de origem, atualizando o índice de forma automática e incremental à medida que os dados subjacentes na tabela Delta são alterados.
  • O Direct Vector Access Index suporta leitura e gravação direta de vetores e metadados. O usuário é responsável por atualizar esta tabela usando a API REST ou o SDK do Python. Este tipo de índice não pode ser criado usando a interface do usuário. Você deve usar a API REST ou o SDK.
nota

O nome da coluna _id está reservado. Se a sua 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 Explorador de Catálogo.

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

  3. Clique no botão Criar no canto superior direito e selecione Índice de pesquisa vetorial no menu suspenso.

    Criar botão de índice

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

    criar diálogo de índice

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

    keyprimária : Coluna a ser usada como key primária.

    Colunas a sincronizar : (Compatível apenas com o endpoint padrão.) Selecione as colunas a serem sincronizadas com o índice do vetor. Se você deixar este campo em branco, todas as colunas da tabela de origem serão sincronizadas com o índice. A coluna key primária e a coluna da fonte de incorporação ou a coluna do vetor de incorporação estão sempre sincronizadas. Para endpoints otimizados para armazenamento, todas as colunas da tabela de origem são sempre sincronizadas.

    Fonte de incorporação : Indique se deseja que Databricks compute as incorporações para uma coluna de texto na tabela Delta ( calcular incorporações ) ou se a sua tabela Delta contém incorporações pré-calculadas ( Usar coluna de incorporação existente ).

    • Se você selecionou "calcular embeddings" , selecione a coluna para a qual deseja calcular os embeddings e o modelo de embedding a ser usado no cálculo. Somente colunas de texto são suportadas.

      • Para aplicações de produção que utilizam endpoints padrão, Databricks recomenda o uso do modelo de fundação databricks-gte-large-en com um provisionamento Taxa de transferência servindo endpoint.

      • Para aplicações de produção que utilizam endpoints otimizados para armazenamento com modelos hospedados Databricks , use o nome do modelo diretamente (por exemplo, databricks-gte-large-en) como endpoint do modelo de incorporação. Uso de endpoint otimizado para armazenamento ai_query com inferência de lotes no momento da ingestão, proporcionando alta taxa de transferência para o trabalho de incorporação. Se preferir usar um endpoint de provisionamento Taxa de transferência para consulta, especifique-o no campo model_endpoint_name_for_query ao criar o índice.

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

    Sincronizar embeddings de computação : Ative esta configuração para salvar os embeddings gerados em uma tabela Unity Catalog . Para obter mais informações, consulte Salvar tabela de incorporação gerada.

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

    Modo de sincronização : O modo contínuo mantém o índice sincronizado com uma latência de segundos. No entanto, isso acarreta um custo mais elevado, uma vez que um cluster compute é provisionado para a execução do pipeline de transmissão síncrona contínua.

    • Para o endpoint padrão, tanto o Contínuo quanto o Acionado realizam atualizações incrementais, portanto, apenas os dados que foram alterados desde a última sincronização são processados.
    • Para endpoints otimizados para armazenamento, cada sincronização reconstrói parcialmente o índice. Para gerenciar índices em sincronizações subsequentes, quaisquer embeddings gerados onde a linha de origem não foi alterada são reutilizados e não precisam ser recalculados. Consulte Limitações de endpoints otimizados para armazenamento.

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

    Para endpoints otimizados para armazenamento, somente o modo de sincronização acionado é compatível.

    Configurações avançadas : (Opcional) Se você selecionou "calcular embeddings" , pode especificar um modelo de embedding separado para consultar seu índice de pesquisa vetorial. Isso pode ser útil se você precisar de um endpoint com alta taxa de transferência para ingestão, mas um endpoint com menor latência para consultar o índice. O modelo especificado no campo Modelo de incorporação é sempre usado para ingestão e também 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.

    Adicionar endpoint de modelo local para consulta

  5. Após concluir a configuração do índice, clique em Criar .

Criar índice usando o SDK do Python​

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

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

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

Python
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 default, todas as colunas da tabela de origem são sincronizadas com o índice.

No endpoint padrão, você pode selecionar um subconjunto de colunas para sincronizar usando columns_to_sync. A key primária e as colunas de incorporação estão sempre incluídas no índice.

Para sincronizar apenas a key primária e a coluna de incorporação, você deve especificá-las em columns_to_sync conforme mostrado:

Python
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 key primária e a coluna de incorporação, pois elas estão sempre sincronizadas.

Python
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 Vetorial Direto.

Python

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 Databricks gerar os embeddings, você poderá salvá-los em uma tabela no Unity Catalog. Esta tabela foi criada no mesmo esquema do índice de vetores e está vinculada a partir da página do índice de vetores.

O nome da tabela é o nome do índice de pesquisa do vetor, seguido por _writeback_table. O nome não pode ser editado.

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

Atualizar um índice de pesquisa vetorial​

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 acionada , poderá iniciar a sincronização usando a interface do usuário, o SDK Python ou a API REST .

  1. No Explorador de Catálogo, navegue até o índice de pesquisa vetorial.

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

    Botão &quot;Sincronizar agora&quot; para sincronizar um índice de pesquisa vetorial do Catalog Explorer..

Atualizar um Índice de Acesso Direto a Vetores​

Você pode usar o SDK do Python ou a API REST para inserir, atualizar ou excluir dados de um Índice de Acesso Vetorial Direto.

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

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
    }
])