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

Como criar e consultar um índice de pesquisa vetorial

Este artigo descreve como criar e consultar um índice 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.

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

Autenticação​

Consulte Proteção de dados e autenticação.

Crie 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 os exemplosNotebook para chamar um modelo de embeddings.

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, Databricks recomenda o uso do modelo de fundação databricks-gte-large-en com um endpoint de serviço de Taxa de transferência de provisionamento.
    • 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
    }
])

Consultar um endpoint de pesquisa vetorial​

Você só pode consultar o endpoint de pesquisa vetorial usando o SDK Python, a API REST ou a função SQL vector_search() AI.

nota

Se o usuário que consulta 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 busca vetorial.
  • USE SCHEMA no esquema que contém o índice de pesquisa vetorial.
  • Selecione no índice de pesquisa vetorial.

O tipo de consulta default é ann (vizinho mais próximo aproximado). Para realizar uma pesquisa híbrida de similaridade de palavras-chave, defina o parâmetro query_type como hybrid. Na busca híbrida, todas as colunas de metadados de texto são incluídas e um máximo de 200 resultados são retornados.

Para usar o reclassificador em uma consulta, consulte Usar o reclassificador em uma consulta.

info

Beta

A busca por texto completo está disponível como recurso beta. Para realizar uma pesquisa de texto completo, defina o parâmetro query_type como FULL_TEXT. Com a pesquisa de texto completo, você pode recuperar até 200 resultados com base na correspondência de palavras-chave sem usar incorporações vetoriais.

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

Python
# Delta Sync Index with embeddings computed by Databricks
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2
    )

# Delta Sync Index using hybrid search, with embeddings computed by Databricks
results3 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="hybrid"
    )

# Delta Sync Index using full-text search (Beta)
results4 = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "field2"],
    num_results=2,
    query_type="FULL_TEXT"
    )

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.9] * 1024,
    columns=["id", "text"],
    num_results=2
    )

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

A tabela a seguir lista os filtros suportados.

Operador de filtro

Comportamento

Exemplos

NOT

Padrão : Anula o filtro. A key deve terminar com “NOT”. Por exemplo, “cor NÃO” com o valor “vermelho” corresponde a documentos onde a cor não é vermelha.

Otimizado para armazenamento : Consulte o operador!= (sinal bangeq).

Padrão : {"id NOT": 2} {“color NOT”: “red”}

Otimizado para armazenamento : "id != 2" "color != 'red'"

<

Padrão : verifica se o valor do campo é menor que o valor do filtro. O endereço key deve terminar com " <". Por exemplo, “price <” com valor 200 corresponde a documentos em que o preço é menor que 200.

Otimizado para armazenamento : Consulte o operador< (sinal lt).

Padrão : {"id <": 200}

Otimizado para armazenamento : "id < 200"

<=

Padrão : Verifica se o valor do campo é menor ou igual ao valor do filtro. A key deve terminar com “<=”. Por exemplo, “preço <=” com valor 200 corresponde a documentos onde o preço é menor ou igual a 200.

Otimizado para armazenamento : Consulte o operador<= (sinal de igualdade).

Padrão : {"id <=": 200}

Otimizado para armazenamento : "id <= 200"

>

Padrão : Verifica se o valor do campo é maior que o valor do filtro. A key deve terminar com “ >”. Por exemplo, “preço >” com valor 200 corresponde a documentos onde o preço é superior a 200.

Otimizado para armazenamento : Consulte o operador> (sinal gt).

Padrão : {"id >": 200}

Otimizado para armazenamento : "id > 200"

>=

Padrão : Verifica se o valor do campo é maior ou igual ao valor do filtro. A key deve terminar com “>=”. Por exemplo, “preço >=” com o valor 200 corresponde a documentos onde o preço é maior ou igual a 200.

Otimizado para armazenamento : Consulte o operador>= (gt sinal de igualdade).

Padrão : {"id >=": 200}

Otimizado para armazenamento : "id >= 200"

OR

Padrão : Verifica se o valor do campo corresponde a algum dos valores de filtro. A key deve conter OR para separar várias subchaves. Por exemplo, color1 OR color2 com valor ["red", "blue"] corresponde a documentos onde color1 é red ou color2 é blue.

Otimizado para armazenamento : Consulte o operadoror.

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

Otimizado para armazenamento : "color1 = 'red' OR color2 = 'blue'"

LIKE

Padrão : Corresponde tokens separados por espaços em branco em uma string. Veja os exemplos de código abaixo.

Otimizado para armazenamento : Consulte o operadorlike.

Padrão : {"column LIKE": "hello"}

Otimizado para armazenamento : "column LIKE 'hello'"

Nenhum operador de filtro especificado

Padrão : O filtro verifica se há uma correspondência exata. Se forem especificados vários valores, qualquer um deles será considerado válido.

Otimizado para armazenamento : Consulte o operador= (sinal de igualdade) e o predicadoin.

Padrão : {"id": 200} {"id": [200, 300]}

Otimizado para armazenamento : "id = 200" "id IN (200, 300)"

to_timestamp (somente endpoint otimizado para armazenamento)

Otimizado para armazenamento : Filtre por data e hora. Consulte a funçãoto_timestamp

Otimizado para armazenamento : "date > TO_TIMESTAMP('1995-01-01')"

Veja os exemplos de código a seguir:

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

Use o reclassificador em uma consulta​

info

Visualização

Este recurso está em Pré-visualização Pública.

O desempenho do agente depende da recuperação da informação mais relevante para uma consulta. A reclassificação é uma técnica que melhora a qualidade da recuperação de dados, avaliando os documentos recuperados para identificar aqueles que são semanticamente mais relevantes. Databricks desenvolveu um sistema AI composto, baseado em pesquisa, para identificar esses documentos. Você também pode especificar colunas contendo metadados que deseja que o reclassificador utilize para obter contexto adicional ao avaliar a relevância de cada documento.

A reclassificação acarreta um pequeno atraso de latência, mas pode melhorar significativamente a qualidade da recuperação e o desempenho do agente. A Databricks recomenda experimentar a reclassificação para qualquer caso de uso de agente RAG.

Os exemplos nesta seção mostram como usar o reclassificador de busca vetorial. Ao usar o reclassificador, você define as colunas a serem retornadas (columns) e as colunas de metadados a serem usadas para reclassificação (columns_to_rerank) separadamente. num_results é o número final de resultados a serem retornados. Isso não afeta o número de resultados usados para a reclassificação.

A mensagem de depuração da consulta inclui informações sobre quanto tempo demorou a reclassificação do passo. Por exemplo:

Bash
'debug_info': {'response_time': 1647.0, 'ann_time': 29.0, 'reranker_time': 1573.0}

Se a chamada do reclassificador falhar, essa informação será incluída na mensagem de depuração:

Bash
'debug_info': {'response_time': 587.0, 'ann_time': 331.0, 'reranker_time': 246.0, 'warnings': [{'status_code': 'RERANKER_TEMPORARILY_UNAVAILABLE', 'message': 'The reranker is temporarily unavailable. Results returned have not been processed by the reranker. Please try again later for reranked results.'}]}
nota

A ordem em que as colunas são listadas em columns_to_rerank é importante. O cálculo de reclassificação considera as colunas na ordem em que estão listadas e leva em conta apenas os primeiros 2000 caracteres encontrados.

Python
# Install the most recent version.
# Databricks SDK version 0.57 or above is required to use the reranker.
%pip install databricks-vectorsearch --force-reinstall
dbutils.library.restartPython()
Python
from databricks.vector_search.reranker import DatabricksReranker

results = index.similarity_search(
    query_text = "How to create a Vector Search index",
    columns = ["id", "text", "parent_doc_summary", "date"],
    num_results = 10,
    query_type = "hybrid",
    reranker=DatabricksReranker(columns_to_rerank=["text", "parent_doc_summary", "other_column"])
    )

Exemplo de caderno​

Os exemplos nesta seção demonstram o uso do SDK Python de busca vetorial. Para obter informações de referência, consulte a referênciaPython SDK.

Exemplos de LangChain​

Consulte Como usar LangChain com Mosaic AI Vector Search para obter informações sobre como usar Mosaic AI Vector Search na integração com o pacote LangChain .

O seguinte Notebook mostra como converter os resultados da sua pesquisa de similaridade em documentos LangChain .

Pesquisa vetorial com o Notebook SDK Python

Open notebook in new tab

ExemplosNotebook para chamar um modelo de embeddings​

O seguinte Notebook demonstra como configurar um endpoint Mosaic AI Model Serving para geração de embeddings.

Invoque um modelo de embeddings OpenAI usando o Notebook Mosaic AI Model Serving

Open notebook in new tab

Chame um modelo de embeddings GTE usando o Notebook Mosaic AI Model Serving

Open notebook in new tab

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

Open notebook in new tab

Utilize a Pesquisa Vetorial com tokens OAuth​

O seguinte Notebook mostra como chamar um endpoint de pesquisa vetorial usando o SDK de pesquisa vetorial ou HTTP com novos tokens OAuth .

Use a Pesquisa Vetorial com um Notebook de Tokens OAuth

Open notebook in new tab