Amazon
Web Services
Microsoft Azure
Google Cloud PlatformComo criar e consultar um índice Vector Search
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 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 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
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 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. 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 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.
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.
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, 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 |
|---|---|---|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
Verifica se o valor do campo corresponde a algum dos valores do filtro. O endereço key deve conter |
|
|
Corresponde a strings parciais. |
|
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. |
|
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.
