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.

O senhor pode criar e gerenciar componentes de pesquisa vetorial, 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 .
sem servidor compute ativado. Para obter instruções, consulte Conectar-se à computação sem servidor.
A tabela de origem deve ter a opção Alterar feed de dados ativada. Para obter instruções, consulte Usar o feed de dados de alteração do Delta Lake no Databricks.
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 vetorial endpoint.
Se o senhor quiser usar o access tokens pessoal (não recomendado para cargas de trabalho de produção), verifique se o access tokens pessoal está ativado. Para usar tokens de entidade de serviço, passe-os explicitamente usando as chamadas 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.

Na barra lateral esquerda, clique em compute.
Clique na Vector Search tab e clique em Criar.
O formulário Criar endpoint é aberto. Insira um nome para esse terminal.
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 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 = 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 a documentação de referência REST API : 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 Databricks compute os embeddings, poderá usar um Foundation Model pré-configurado APIs endpoint ou criar um modelo de serviço endpoint para servir o modelo de embedding de sua escolha. Consulte Pay-per-tokens Foundation Model APIs ou Create generative IA servindo modelo endpoint para obter instruções. 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

Na barra lateral esquerda, clique em Catalog para abrir a interface do usuário do Catalog Explorer.
Navegue até a tabela Delta que o senhor deseja usar.
Clique no botão Create (Criar ) no canto superior direito e selecione Vector search index (Índice de pesquisa de vetor ) no menu suspenso.
Use os seletores na caixa de diálogo para configurar o í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 a pesquisa vetorial endpoint que o senhor deseja usar.

Colunas a serem sincronizadas: selecione as colunas a serem sincronizadas 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 key primária e a coluna de origem de incorporação ou a coluna de vetor de incorporação estão sempre sincronizadas.

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. O formato da coluna de incorporação pré-computada deve ser array[float].
Sync compute embeddings: Alterne essa configuração para salvar os embeddings gerados em uma tabela Unity Catalog. Para obter mais informações, consulte Salvar tabela de incorporação gerada.

Modo de sincronização: contínuo mantém o índice sincronizado 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. Tanto para Contínua quanto para Acionada, a atualização é incremental — somente os dados que foram alterados desde a última sincronização são processados.

No modo de sincronização acionada, o senhor usa o Python SDK ou o REST API para iniciar a sincronização. Consulte Atualizar um índice Delta Sync.
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 Delta Sync Index com embeddings autogerenciáveis. Esse exemplo também mostra o uso do parâmetro opcional columns_to_sync para selecionar somente um subconjunto de colunas a serem usadas no í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_dimension=1024,
  embedding_vector_column="text_vector"
)

Em default, todas as colunas da tabela de origem são sincronizadas com o índice. Para sincronizar somente um subconjunto de colunas, use columns_to_sync. As colunas primárias key e de incorporação são sempre incluídas no índice.

Para sincronizar apenas o key primário e a coluna de incorporação, o senhor deve especificá-los 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. O senhor não precisa incluir o key primário e a coluna de incorporação, pois eles são sempre sincronizados.

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 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": "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 incorporação gerada

Se o Databricks gerar as incorporações, o senhor poderá salvar as incorporações geradas em uma tabela no Unity Catalog. Essa tabela é criada no mesmo esquema que o índice vetorial e é vinculada a partir da página do índice vetorial.

O nome da tabela é o nome do índice de pesquisa de vetores, acrescido de _writeback_table. O nome não é editável.

O senhor pode acessar e consultar a tabela como qualquer outra tabela no Unity Catalog. No entanto, o senhor não deve descartar 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 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, use o Python SDK ou o REST API para iniciar a sincronização.

index.sync()

Consulte a documentação de referência da 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 documentação de referência da API REST: POST /api/2.0/vector-search/indexes.

O exemplo de código a seguir ilustra como atualizar um índice usando um access token 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": [...]}'

O exemplo de código a seguir ilustra como atualizar um índice usando uma entidade 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": [...]}'

Consultar um ponto de extremidade de pesquisa vetorial

O senhor só pode consultar a pesquisa vetorial endpoint usando a função Python SDK, REST API ou SQL vector_search() IA.

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.

Para executar uma pesquisa híbrida de similaridade de palavras-chave, defina o parâmetro query_type como hybrid. O valor de default é ann (vizinho mais próximo aproximado).

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

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

# Delta Sync Index with pre-calculated embeddings
results2 = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
    )

Consulte a documentação de referência da API REST: POST /api/2.0/vector-search/indexes/{index_name}/query.

O exemplo de código a seguir ilustra como consultar um índice usando um access token pessoal (PAT).

export TOKEN=...
export INDEX_NAME=...
export WORKSPACE_URL=https://...

# Query Vector Search index with `query_vector`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query Vector Search index with `query_text`
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url $WORKSPACE_URL/api/2.0/vector-search/indexes/$INDEX_NAME/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

O exemplo de código a seguir ilustra como consultar um índice usando uma entidade 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": "ReadVectorIndex"}'
# If you are using an route_optimized embedding model endpoint (TODO: link), then you need to have additional authorization details to invoke the serving endpoint
# export EMBEDDING_MODEL_SERVING_ENDPOINT_ID=...
# export AUTHORIZATION_DETAILS="$AUTHORIZATION_DETAILS"',{"type":"workspace_permission","object_type":"serving-endpoints","object_path":"/serving-endpoints/'"$EMBEDDING_MODEL_SERVING_ENDPOINT_ID"'","actions": ["query_inference_endpoint"]}'

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

# Query Vector Search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_vector": [...], "columns": [...], "debug_level": 1}'

# Query Vector Search index.
curl -X GET -H 'Content-Type: application/json' -H "Authorization: Bearer $TOKEN" --url https://$INDEX_URL/query --data '{"num_results": 3, "query_text": "...", "columns": [...], "debug_level": 1}'

Importante

A função vector_search() IA está em visualização pública.

Para usar essa função de IA, consulte a função vector_search.

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, “preço <” com valor 200 corresponde a documentos em que o preço é menor que 200.	`{"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 200 corresponde a documentos em que o preço é menor ou igual a 200.	`{"id <=": 200}`
`>`	Verifica se o valor do campo é maior que o valor do filtro. O endereço key deve terminar com " >". Por exemplo, “preço >” com valor 200 corresponde a documentos em que o preço é maior que 200.	`{"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 200 corresponde a documentos em que o preço é maior ou igual a 200.	`{"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
    )

Consulte POST /api/2.0/vector-search/indexes/{{index_name}/query.

Notebook de Exemplo

Os exemplos desta seção demonstram o uso do Python SDK de pesquisa vetorial.

Exemplos de LangChain

Consulte Como usar LangChain com Mosaic AI Vector Search para usar Mosaic AI Vector Search como uma integração com o pacote LangChain.

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

Pesquisa vetorial com o site Python SDK Notebook

Abra o bloco de anotações em outra guia

Exemplos Notebook para chamar um modelo de embeddings

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