Consultar um índice de pesquisa de vetor

Este artigo descreve como consultar um índice de busca vetorial, incluindo como usar filtros e reordenação.

Por exemplo, notebooks que ilustram como criar e consultar endpoints e índices de pesquisa vetorial, consulte notebooks de exemplo de pesquisa vetorial. Para obter informações de referência, consulte a referência do SDK do Python.

Installation

Para usar o SDK de pesquisa de vetor, você deve instalá-lo em seu notebook. Use 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

Para obter informações sobre autenticação, consulte Proteção de dados e autenticação.

Como consultar um índice de pesquisa de vetor

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

O tipo de consulta padrão é ann (vizinho mais próximo aproximado). Para executar uma pesquisa de similaridade de palavra-chave híbrida, defina o parâmetro query_type como hybrid. Com a pesquisa 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 reranker em uma consulta.

Ponto de extremidade padrão do SDK do Python

Para obter detalhes, consulte a referência do SDK do 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
    )

Ponto de extremidade de armazenamento otimizado do SDK do Python

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

A interface de filtro existente foi recriada para que os índices de pesquisa de vetor com otimização de armazenamento adotem uma cadeia de caracteres de filtro mais semelhante a SQL em vez do dicionário de filtro usado nos pontos de extremidade de pesquisa de vetor padrão.

client = VectorSearchClient()
index = client.get_index(index_name="vector_search_demo.vector_search.en_wiki_index")

# similarity search with query vector
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    num_results=2
)

# similarity search with query vector and filter string
results = index.similarity_search(
    query_vector=[0.2, 0.33, 0.19, 0.52],
    columns=["id", "text"],
    # this is a single filter string similar to SQL WHERE clause syntax
    filters="language = 'en' AND country = 'us'",
    num_results=2
)

API REST

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

Para aplicativos de produção, o Databricks recomenda usar entidades de serviço em vez de tokens de acesso pessoal. Além de aprimorar a segurança e o gerenciamento de acesso, o uso de entidades de serviço pode aprimorar o desempenho em até 100 milissegundos por consulta.

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, 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}'

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

SQL

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

Usar filtros em consultas

Uma consulta pode definir filtros com base em qualquer coluna na tabela Delta. similarity_search retorna apenas linhas que correspondem aos filtros especificados.

A tabela a seguir lista os filtros com suporte.

Veja os seguintes exemplos de código:

Ponto de extremidade padrão do SDK do 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
    )

Ponto de extremidade de armazenamento otimizado do SDK do Python

# Match rows where `title` exactly matches `Athena` or `Ares`
results = index.similarity_search(
    query_text="Greek myths",
    columns=["id", "text"],
    filters='title IN ("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 = "Ares" OR id = "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 != "Hercules"',
    num_results=2
    )

API REST

Consulte a documentação em POST /api/2.0/vector-search/indexes/{index_name}/query.

CURTIR

LIKE Exemplos

{"column LIKE": "apple"}: corresponde às cadeias de caracteres "maçã" e "maçã pera", mas não corresponde a "abacaxi" ou "pera". Observe que ele não corresponde a "abacaxi", mesmo que contenha a substring "maçã" --- procura por uma correspondência exata nos tokens separados por espaço em branco, como em "maçã pera".

{"column NOT LIKE": "apple"} faz o oposto. Ele corresponde a "abacaxi" e "pera", mas não corresponde a "maçã" ou "maçã pera".

Usar o reranker em uma consulta

O desempenho do agente depende da recuperação das informações mais relevantes para uma consulta. O reclassificador é uma técnica que melhora a qualidade da recuperação avaliando os documentos recuperados para identificar os que são semanticamente mais relevantes. O Databricks desenvolveu um sistema de IA composto baseado em pesquisa para identificar esses documentos. Você também pode especificar colunas contendo metadados que deseja que o reclassificador use para contexto adicional, pois avalia a relevância de cada documento.

O reclassificador incorre em um pequeno atraso de latência, mas pode melhorar significativamente a qualidade de recuperação e o desempenho do agente. O Databricks recomenda testar o reclassificador para qualquer caso de uso do agente RAG.

Os exemplos nesta seção mostram como usar o reclassificador de pesquisa de vetor. Ao usar o reranker, defina as colunas para retornar (columns) e as colunas de metadados a serem usadas para o reclassificador (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 o reclassificado.

A mensagem de depuração de consulta inclui informações sobre quanto tempo a etapa de reclassificador levou. Por exemplo:

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

Se a chamada de reclassificador falhar, essas informações serão incluídas na mensagem de depuração:

'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.'}]}

SDK do 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()

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

API REST

Para garantir que você obtenha informações de latência, defina debug_level como pelo menos 1.

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

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": 10, "query_text": "How to create a Vector Search index", "columns": ["id", "text", "parent_doc_summary", "date"], "reranker": {"model": "databricks_reranker",
             "parameters": {
               "columns_to_rerank":
                 ["text", "parent_doc_summary"]
              }
             },
"debug_level": 1}'

Pesquisas de ponto

Para fazer uma pesquisa de ponto, use um filtro em qualquer coluna de chave primária.