Como criar e consultar um índice Vector Search

Visualização

Esse recurso está em Prévia Pública.

Este artigo descreve como criar e query um índice de pesquisa vetorial usando Databricks Vector Search.

O senhor pode criar e gerenciar componentes do Vector Search, como um endpoint de pesquisa vetorial e índices de pesquisa vetorial, usando a interface do usuário, o Python SDK ou a API REST.

Requisitos

  • Unity Catalog habilitado workspace para .

  • serverless compute habilitado.

  • A tabela de origem deve ter o Change Data Feed ativado.

  • Para criar um índice, o senhor deve ter privilégios CREATE TABLE no(s) esquema(s) do catálogo para criar índices. Para consultar um índice que pertence a outro usuário, o senhor deve ter privilégios adicionais. Consulte Consultar uma pesquisa de vetor endpoint.

  • Se você quiser usar o token de acesso pessoal (não recomendado para cargas de trabalho de produção), verifique se o token de acesso pessoal está habilitado. Para usar tokens de entidade de serviço, passe-os explicitamente usando chamadas de SDK ou API.

Para usar o SDK, o senhor deve instalá-lo em seu site Notebook. Use o seguinte código:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Criar um ponto de extremidade de pesquisa vetorial

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

Criar um ponto de extremidade de pesquisa vetorial usando a interface do usuário

Siga estes passos para criar um endpoint de pesquisa vetorial usando a UI.

  1. Na barra lateral esquerda, clique em compute.

  2. Clique na Vector Search tab e clique em Criar.

    Criar formulário de endpoint
  3. O formulário Criar endpoint é aberto. Insira um nome para esse terminal.

  4. Clique em Confirmar.

Criar um endpoint de pesquisa vetorial usando o Python SDK

O exemplo a seguir usa a função create_endpoint() do SDK para criar um endpoint do Vector Search.

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

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

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

Criar um endpoint de pesquisa vetorial usando a API REST

Consulte POST /api/2.0/vector-search/endpoint.

(Opcional) Crie e configure um ponto de extremidade para servir o modelo de incorporação

Se o senhor optar por ter o Databricks compute os embeddings, deverá configurar um modelo de serviço endpoint para servir o modelo de embedding. Para obter instruções, consulte Criar endpoint de modelo de serviço de fundação. Para obter um exemplo do Notebook, consulte Notebook examples for calling an embeddings model.

Ao configurar uma incorporação endpoint, a Databricks recomenda que o senhor remova a seleção default de escala para zero. Os endpoints de atendimento podem levar alguns minutos para aquecer, e a consulta inicial em um índice com um endpoint reduzido pode ter um tempo limite.

Observação

A inicialização do índice de pesquisa de vetores pode demorar um pouco se a incorporação endpoint não estiver configurada adequadamente para o dataset. O senhor só deve usar o endpoint da CPU para pequenos conjuntos de dados e testes. Para conjuntos de dados maiores, use uma GPU endpoint para obter o desempenho ideal.

Crie um índice de pesquisa vetorial

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

Há dois tipos de índices:

  • O Delta Sync Index é sincronizado 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 oferece suporte à leitura e gravação direta de vetores e metadados. O usuário é responsável por atualizar essa tabela usando a API REST ou o Python SDK. Esse tipo de índice não pode ser criado usando a interface do usuário. O senhor deve usar a API REST ou o SDK.

Criar índice usando a UI

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

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

  3. No menu kebab no canto superior direito, selecione Create vector search index (Criar índice de pesquisa vetorial).

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

    criar diálogo de índice

    Name (Nome): Nome a ser usado para a tabela on-line 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.

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

    endpoint: Selecione o endpoint do modelo de serviço que o senhor deseja usar.

    Fonte de incorporação: Indique se o senhor deseja que o Databricks compute embeddings para uma coluna de texto na tabela Delta (compute embeddings) ou se a tabela Delta contém embeddings pré-computados(Use existing embedding column).

    • Se o senhor selecionou compute embeddings, selecione a coluna para a qual deseja que os embeddings sejam computados e o endpoint que está servindo o modelo de embedding. Somente colunas de texto são suportadas.

      • Se o senhor 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.

    Modo de sincronização: Contínuo mantém o índice em sincronia com segundos de latência. No entanto, ele tem um custo mais alto associado, pois um compute cluster é o provisionamento para executar a transmissão de sincronização contínua pipeline. O acion amento é mais econômico, mas deve ser iniciado manualmente usando o site API. Tanto para o Continuous quanto para o Triggered, a atualização é incremental - somente os dados que foram alterados desde a última sincronização são processados.

  5. Quando o senhor tiver terminado de configurar o índice, clique em Create (Criar).

Criar índice usando o Python SDK

O exemplo a seguir cria um índice Delta Sync com embeddings computados pela Databricks.

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

O exemplo a seguir cria um Direct Vector Access Index.


client = VectorSearchClient()

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

Criar índice usando a API REST

Consulte POST /api/2.0/vector-search/indexes.

Atualizar um índice de pesquisa vetorial

Atualizar um índice Delta Sync

Os índices criados com o modo de sincronização contínua são atualizados automaticamente quando a tabela Delta de origem é alterada. Se estiver usando o modo de sincronização acionada, o senhor pode usar o Python SDK ou a API REST para iniciar a sincronização.

index.sync()

Consulte a API REST (POST /api/2.0/vector-search/indexes/{index_name}/sync).

Atualizar um índice Direct Vector Access

O senhor pode usar o Python SDK ou a API REST para inserir, atualizar ou excluir dados de um Direct Vector Access Index.

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

Consulte a API REST (POST /api/2.0/vector-search/indexes).

Consultar um endpoint Vector Search

O senhor só pode consultar o endpoint do Vector Search usando o Python SDK ou a API REST.

Observação

Se o usuário que estiver consultando o endpoint não for o proprietário do índice de pesquisa vetorial, ele deverá ter os seguintes privilégios de UC:

  • USE CATALOG no catálogo que contém o índice de pesquisa vetorial.

  • USE SCHEMA no esquema que contém o índice de pesquisa vetorial.

  • SELECT no índice de pesquisa de vetores.

results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    num_results=2
    )

results

Usar filtros nas consultas

Uma consulta pode definir filtros com base em qualquer coluna da tabela Delta. similarity_search retorna apenas as linhas que correspondem aos filtros especificados. Os seguintes filtros são suportados:

Operador de filtro

Comportamento

Exemplos

NOT

Nega o filtro. O endereço key deve terminar com "NOT". Por exemplo, "color NOT" com o valor "red" corresponde a documentos em que a cor não é vermelha.

{"id NOT": 2} {“color NOT”: “red”}

<

Verifica se o valor do campo é menor que o valor do filtro. O endereço key deve terminar com " <". Por exemplo, "price <" com valor 100 corresponde a documentos em que o preço é menor que 100.

{"id <": 200}

<=

Verifica se o valor do campo é menor ou igual ao valor do filtro. O endereço key deve terminar com " <=". Por exemplo, "price <=" com valor 100 corresponde a documentos em que o preço é menor ou igual a 100.

{"id <=": 200}

>

Verifica se o valor do campo é maior que o valor do filtro. O endereço key deve terminar com " >". Por exemplo, "price >" com valor 100 corresponde a documentos em que o preço é maior que 100.

{"id >": 200}

>=

Verifica se o valor do campo é maior ou igual ao valor do filtro. O endereço key deve terminar com " >=". Por exemplo, "price >=" com valor 100 corresponde a documentos em que o preço é maior ou igual a 100.

{"id >=": 200}

OR

Verifica se o valor do campo corresponde a algum dos valores do filtro. O endereço key deve conter OR para separar várias subchaves. Por exemplo, color1 OR color2 com valor ["red", "blue"] corresponde a documentos em que color1 é red ou color2 é blue.

{"color1 OR color2": ["red", "blue"]}

LIKE

Corresponde a strings parciais.

{"column LIKE": "hello"}

Nenhum operador de filtro especificado

O filtro verifica se há uma correspondência exata. Se vários valores forem especificados, ele corresponde a qualquer um dos valores.

{"id": 200} {"id": [200, 300]}

Veja os exemplos de código a seguir:

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title": ["Ares", "Athena"]}
    num_results=2
    )

# Match rows where `title` or `id` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title OR id": ["Ares", "Athena"]}
    num_results=2
    )

# Match only rows where `title` is not `Hercules`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters={"title NOT": "Hercules"}
    num_results=2
    )

Notebook de Exemplo

Os exemplos nesta seção demonstram o uso do Vector Search Python SDK.

Exemplos de LangChain

Consulte Como usar o LangChain com o Databricks Vector Search para usar o Databricks Vector Search como na integração com o pacote LangChain.

O Notebook a seguir mostra como converter os resultados da pesquisa de similaridade em documentos LangChain.

Vector Search com o Python SDK Notebook

Abra o bloco de anotações em outra guia

Exemplos Notebook para chamar um modelo de embeddings

O Notebook a seguir demonstra como configurar um endpoint de modelo instalado do Databricks para geração de embeddings.

Chame um modelo de embeddings OpenAI usando Databricks instalado modelo Notebook

Abra o bloco de anotações em outra guia

Chame um modelo de embeddings BGE usando Databricks instalado modelo Notebook

Abra o bloco de anotações em outra guia

registrar e servir um modelo de incorporação OSS Notebook

Abra o bloco de anotações em outra guia