Como criar e consultar um índice de pesquisa de vetor

Este artigo descreve como criar e consultar um índice de busca em vetores usando o Mosaic AI Vector Search.

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

Requisitos

• Workspace do Unity Catalog habilitado.
• Computação sem servidor habilitada. Para obter instruções, consulte Conectar-se à computação sem servidor.
• A origem table deve ter o recurso Change Data Feed habilitado. Para obter instruções, consulte Usar o feed de alterações de dados do Delta Lake no Azure Databricks.
• Para criar um índice de pesquisa de vetor, você deve ter privilégios de CREATE TABLE no catalogschemawhere onde o índice será criado.
• Para consultar um índice que pertence a outro usuário, você deve ter privilégios adicionais. Confira Consultar um ponto de extremidade da Busca em Vetores.
• Se quiser usar tokens de acesso pessoal (não recomendados para cargas de trabalho de produção), verifique se os Tokens de acesso pessoal estão habilitados. Para, alternativamente, usar um token de entidade de serviço, repasse-o explicitamente usando o SDK ou chamadas à API.

A permissão para criar e gerenciar terminais de busca vetorial é configurada usando listas de controle de acesso. Consulte ACLs de ponto de extremidade de busca em vetores.

Instalação

Para usar o SDK de pesquisa de vetor, você deve instalá-lo em seu notebook. Use o seguinte código:

%pip install databricks-vectorsearch

dbutils.library.restartPython()

from databricks.vector_search.client import VectorSearchClient

Criar um endpoint de pesquisa de vetor

Você pode criar um ponto de extremidade da busca em vetores usando a interface do usuário do Databricks, o SDK do Python ou a API.

Criar um endpoint de pesquisa de vetor usando a interface de usuário

Siga estas etapas para criar um endpoint de pesquisa de vetor usando a interface.

1. Na barra lateral esquerda, clique em Computação.

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

   

3. O formulário Criar ponto de extremidade é aberto. Insira um nome para esse ponto de extremidade.

4. Clique em Confirmar.

Criar um endpoint de pesquisa vetorial usando o SDK do Python

O exemplo a seguir usa a função do SDK create_endpoint() para criar um endpoint de pesquisa de vetor.

# 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 busca vetorial usando a API REST

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

(Opcional) Criar e configurar um ponto de extremidade para atender ao modelo de inserção

Se você optar por ter o Databricks comutando as incorporações, poderá usar um endpoint de APIs de Modelo Fundamental pré-configurado ou criar um endpoint de serviço de modelo para atender ao modelo de incorporação de sua escolha. Veja APIs do modelo básico de pagamento por token ou Criar modelo de IA generativa que atende pontos de extremidade para obter instruções. Para obter exemplos de notebooks, confira Exemplos de notebook para chamar um modelo de inserções.

Quando você configura um ponto de extremidade de incorporação, o Databricks recomenda que você remove a seleção padrão de Escalar para zero. Os pontos de extremidade de serviço pode levar alguns minutos para se aquecer, e a consulta inicial em um índice com um ponto de extremidade reduzido pode demorar.

Criar um índice de pesquisa de vetor

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

Há dois tipos de índices:

• Delta Sync Index sincroniza automaticamente com um Delta Tablede origem, atualizando automaticamente e incrementalmente o índice à medida que os dados subjacentes no Delta Table são alterados.
• Direct Vector Access Index dá suporte à leitura direta e à gravação de vetores e metadados. O usuário é responsável por atualizar esse table usando a API REST ou o SDK do Python. Esse tipo de índice não pode ser criado usando a interface do usuário. Você deve usar a API REST ou o SDK.

Criar índice usando a interface do usuário

1. Na barra lateral esquerda, clique em Catalog para abrir a UI do Explorer Catalog.

2. Navegue até a table Delta que você deseja usar.

3. Clique no botão Criar no canto superior direito e em selectíndice de busca em vetores no menu suspenso.

   

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

   

   Nome: Nome a ser usado para a table 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.

   chave primária: Column para usar como chave primária.

   Ponto de extremidade: Select o ponto de extremidade de busca em vetores que você deseja usar.

   Columns sync : Select as columns para sync com o índice de vetor. Se você deixar esse campo em branco, todas as columns da table de origem serão sincronizadas com o índice. A chave primária column e a fonte de incorporação column ou vetor de incorporação column estão sempre sincronizados.

   Fonte de incorporação: indique se você deseja que o Databricks compute incorporações para uma coluna de column na table Delta (Computar incorporações) ou se a sua table Delta contém incorporações pré-computadas (Usar a column de incorporação existente).

   • Se você selecionou Computar incorporações, select a column para a qual deseja que as incorporações sejam computadas e o ponto de extremidade que está servindo o modelo de incorporação. Há suporte apenas para columns de texto.
   • Se você selecionou Usar column de incorporação existente, select a column que contém as incorporações pré-computadas e a dimensão de incorporação. O formato da column de incorporação pré-computada deve ser array[float].

   Sync incorporações computadas: ative essa configuração para salvar as incorporações geradas em uma table do Unity Catalog. Para obter mais informações, consulte Salvar table de incorporação gerada.

   Modo de Sync: o modo contínuo mantém o índice sync com uma latência de segundos. No entanto, ele tem um custo mais elevado, pois um cluster de computação é provisionado para executar o pipeline de streaming contínuo sync. Para os modos Contínuo e Por disparado, a update é incremental — apenas os dados que foram alterados desde a última sync são processados.

   No modo de sync Por disparo, use o SDK do Python ou a API REST para iniciar a sync. Consulte Update um Índice de Sync Delta.

5. Quando terminar de configurar o índice, clique em Criar.

Criar índice usando o SDK do Python

O exemplo a seguir cria um Índice de Sync Delta com inserções computadas pelo 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 Índice de Sync Delta com inserções autogerenciadas. Este exemplo também mostra o uso do parâmetro opcional columns_to_sync para select apenas um subconjunto de columns 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"
)

Por padrão, todas as columns da table de origem são sincronizadas com o índice. Para sync apenas um subconjunto de columns, use columns_to_sync. As columns de chave primária e de incorporação são sempre incluídas no índice.

Para sync apenas as column de chave primária e de incorporação, especifique-as 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 sync columns adicionais, especifique-as conforme mostrado. Você não precisa incluir as column de chave primária e de incorporação, pois elas são sempre sincronizadas.

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 de Vetor Direto.

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 table de incorporação gerada

Se o Databricks gerar as incorporações, você poderá salvar as incorporações geradas em uma table no Unity Catalog. Essa table é criada no mesmo schema que o índice de vetor e é vinculada à página do índice de vetor.

O nome do table é o nome do índice de pesquisa de vetor, acrescentado por _writeback_table. O nome não é editável.

Você pode acessar e consultar o table como qualquer outro table no Unity Catalog. No entanto, você não deve remover ou modificar a table, pois ela não se destina a ser atualizada manualmente. A table é excluída automaticamente se o índice for excluído.

Update um índice de pesquisa de vetor

Update um Índice de Sync Delta

Os índices criados com o modo de sync contínua são automaticamente update quando a table de origem é alterada. Se você estiver usando o modo de sync Por disparo, use o SDK do Python ou a API REST para iniciar a sync.

Python SDK

index.sync()

REST API

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

Update um Índice de Acesso Direto a Vetores

Você pode usar o SDK do Python ou a API REST para insert, update ou excluir dados de um Índice de Acesso Direto a Vetores.

Python SDK

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

REST API

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 update um índice usando um PAT (token de acesso pessoal).

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 update 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 busca em vetores

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

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

Python SDK

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

REST API

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 PAT (token de acesso pessoal).

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 um principal 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}'

SQL

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

Usar filtros em consultas

Uma consulta pode definir filtros com base em qualquer column no delta table. similarity_search retorna apenas linhas que correspondem aos filtros especificados. Há suporte para os seguintes filtros:

Veja os seguintes exemplos de código:

Python SDK

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

REST API

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

Notebooks de exemplo

Os exemplos nesta seção demonstram o uso do SDK do Python de pesquisa de vetores.

Exemplos de LangChain

Confira Como usar o LangChain com o Mosaic AI Vector Search para usar o Mosaic AI Vector Search integrado com pacotes LangChain.

O bloco de anotações a seguir mostra como converter os resultados da pesquisa de similaridade em documentos LangChain.

Busca em vetores com o notebook do SDK do Python

Get notebook

Exemplos de notebook para chamar um modelo de incorporações

Os blocos de anotações a seguir demonstram como configurar um ponto de extremidade do Mosaic AI Model Serving para geração de embeddings.

Chame um modelo de embeddings OpenAI usando o notebook Mosaic AI Model Serving

Get notebook

Chamar um modelo de inserções GTE usando o notebook do Mosaic AI Model Serving

Get notebook

Registrar e servir um notebook de código aberto do modelo de incorporação

Get notebook