Encontrar vizinhos aproximados mais próximos (ANN) e embeddings de vetor de consulta

Nesta página, descrevemos como encontrar vizinhos mais próximos aproximados (ANN, na sigla em inglês) e consultar embeddings de vetor usando as funções de distância de ANN.

Quando um conjunto de dados é pequeno, é possível usar K-vizinhos mais próximos (KNN, na sigla em inglês) para encontrar os vetores k-vizinhos mais próximos exatos. No entanto, à medida que o conjunto de dados cresce, a latência e o custo de uma pesquisa KNN também aumentam. É possível usar o ANN para encontrar os k vizinhos mais próximos aproximados com latência e custo significativamente reduzidos.

Em uma pesquisa de ANN, os vetores retornados por k não são os verdadeiros vizinhos mais próximos de k, porque a pesquisa de ANN calcula distâncias aproximadas e pode não analisar todos os vetores no conjunto de dados. Às vezes, alguns vetores que não estão entre os k vizinhos mais próximos são retornados. Isso é conhecido como perda de recall. A perda de recall aceitável depende do caso de uso, mas, na maioria dos casos, perder um pouco de recall em troca de um melhor desempenho do banco de dados é uma compensação aceitável.

Para mais detalhes sobre as funções de distância aproximada compatíveis com o Spanner, consulte as seguintes páginas de referência para o dialeto do banco de dados:

Consultar embeddings de vetor

O Spanner acelera as pesquisas de vetores de vizinho mais próximo aproximado (ANN, na sigla em inglês) usando um índice vetorial. É possível usar um índice de vetor para consultar embeddings de vetor. Para consultar embeddings de vetor, primeiro é necessário criar um índice de vetor. Em seguida, use qualquer uma das três funções de distância aproximada para encontrar a ANN.

As restrições ao usar as funções de distância aproximada incluem:

  • A função de distância aproximada precisa calcular a distância entre uma coluna de embedding e uma expressão constante (por exemplo, um parâmetro ou um literal).
  • A saída da função de distância aproximada precisa ser usada em uma cláusula ORDER BY como a única chave de classificação, e um LIMIT precisa ser especificado após o ORDER BY.
  • A consulta precisa filtrar explicitamente as linhas que não estão indexadas. Na maioria dos casos, isso significa que a consulta precisa incluir uma cláusula WHERE <column_name> IS NOT NULL que corresponda à definição do índice vetorial, a menos que a coluna já esteja marcada como NOT NULL na definição da tabela.

Para uma lista detalhada de limitações, consulte a página de referência da função de distância aproximada.

Exemplos

Considere uma tabela Documents que tenha uma coluna DocEmbedding de embeddings de texto pré-computados da coluna de bytes DocContents e uma coluna NullableDocEmbedding preenchida de outras fontes que podem ser nulas. As duas colunas de embedding especificam um comprimento de vetor de 3, que é necessário para criar um índice de vetor para pesquisa de ANN.

GoogleSQL

CREATE TABLE Documents (
  UserId       INT64 NOT NULL,
  DocId        INT64 NOT NULL,
  Author       STRING(1024),
  DocContents  BYTES(MAX),
  DocEmbedding ARRAY<FLOAT32>(vector_length=>3) NOT NULL,
  NullableDocEmbedding ARRAY<FLOAT32>(vector_length=>3),
  WordCount    INT64
) PRIMARY KEY (UserId, DocId);

PostgreSQL

CREATE TABLE documents (
  user_id      bigint not null,
  doc_id       bigint not null,
  author       varchar(1024),
  doc_contents bytea,
  doc_embedding float4[] VECTOR LENGTH 3 not null,
  nullable_doc_embedding float4[] VECTOR LENGTH 3,
  word_count   bigint,
  PRIMARY KEY (user_id, doc_id)
);

Para pesquisar os 100 vetores mais próximos de [1.0, 2.0, 3.0], especifique uma das seguintes opções de pesquisa na função de distância aproximada:

  • num_leaves_to_search: o número de folhas a serem pesquisadas. O valor precisa ser um número inteiro positivo.
  • pct_leaves_to_search: a porcentagem de folhas a serem pesquisadas. O valor precisa ser um duplo entre 0.0 e 100.0 com um marcador decimal explícito (por exemplo, 10.0). Os índices de vetor criados antes de novembro de 2025 podem não oferecer suporte a essa opção de pesquisa.

Não é possível especificar as duas opções na mesma função de distância aproximada.

Opção 1. Usar a opção de pesquisa num_leaves_to_search

GoogleSQL

SELECT DocId
FROM Documents
WHERE WordCount > 1000
ORDER BY APPROX_EUCLIDEAN_DISTANCE(
  ARRAY<FLOAT32>[1.0, 2.0, 3.0], DocEmbedding,
  options => JSON '{"num_leaves_to_search": 10}')
LIMIT 100

PostgreSQL

SELECT doc_id
FROM documents
WHERE word_count > 1000
ORDER BY spanner.approx_euclidean_distance(
  ARRAY[1.0, 2.0, 3.0]::float4[], doc_embedding,
  options=>jsonb'{"num_leaves_to_search": 10}'
)
LIMIT 100;

Opção 2. Usar a opção de pesquisa pct_leaves_to_search

GoogleSQL

SELECT DocId
FROM Documents
WHERE WordCount > 1000
ORDER BY APPROX_EUCLIDEAN_DISTANCE(
  ARRAY<FLOAT32>[1.0, 2.0, 3.0], DocEmbedding,
  options => JSON '{"pct_leaves_to_search": 10.0}')
LIMIT 100

PostgreSQL

SELECT doc_id
FROM documents
WHERE word_count > 1000
ORDER BY spanner.approx_euclidean_distance(
  ARRAY[1.0, 2.0, 3.0]::float4[], doc_embedding,
  options=>jsonb'{"pct_leaves_to_search": 10.0}'
)
LIMIT 100;

Para pesquisar os 100 vetores mais próximos de um embedding gerado por uma expressão SQL, use o padrão a seguir. Neste exemplo, a consulta está encontrando os documentos mais semelhantes ao embedding de UserId = 1 e DocId = 1:

GoogleSQL

WITH emb AS (
  SELECT DocEmbedding AS value
  FROM Documents
  WHERE UserId = 1 AND DocId = 1
  LIMIT 1
)
SELECT DocId
FROM Documents, emb
ORDER BY APPROX_EUCLIDEAN_DISTANCE(
  emb.value, DocEmbedding,
  options => JSON '{"num_leaves_to_search": 10}')
LIMIT 100

PostgreSQL

SELECT documents.doc_id
FROM
  documents,
  (
    SELECT doc_embedding AS value
    FROM documents
    WHERE user_id = 1 AND doc_id = 1
    LIMIT 1
  ) vector
WHERE documents.doc_embedding IS NOT NULL
ORDER BY spanner.APPROX_EUCLIDEAN_DISTANCE(documents.doc_embedding,
         vector.value, options=>'{"num_leaves_to_search": 10}'::jsonb)
LIMIT 100

Se a coluna de embedding for anulável:

GoogleSQL

SELECT DocId
FROM Documents
WHERE NullableDocEmbedding IS NOT NULL AND WordCount > 1000
ORDER BY APPROX_EUCLIDEAN_DISTANCE(
  ARRAY<FLOAT32>[1.0, 2.0, 3.0], NullableDocEmbedding,
  options => JSON '{"num_leaves_to_search": 10}')
LIMIT 100

PostgreSQL

SELECT doc_id
FROM documents
WHERE nullable_doc_embedding IS NOT NULL AND word_count > 1000
ORDER BY spanner.approx_euclidean_distance(
  ARRAY[1.0, 2.0, 3.0]::float4[], nullable_doc_embedding,
  options=>jsonb'{"num_leaves_to_search": 10}'
)
LIMIT 100;

Adicionar a distância aos resultados da consulta

Nos exemplos anteriores, a distância de ANN é usada para ordenar os resultados da consulta, mas não é exibida neles. Para adicionar a distância aos resultados, coloque a função de distância na cláusula SELECT e use um alias para ela. Em seguida, use esse alias como a única chave de ordenação na cláusula ORDER BY.

Exemplos

GoogleSQL

SELECT DocId,
  APPROX_EUCLIDEAN_DISTANCE(
    ARRAY<FLOAT32>[1.0, 2.0, 3.0], NullableDocEmbedding,
    options => JSON '{"num_leaves_to_search": 10}') AS distance
FROM Documents
WHERE NullableDocEmbedding IS NOT NULL AND WordCount > 1000
ORDER BY distance
LIMIT 100

PostgreSQL

SELECT doc_id,
  spanner.approx_euclidean_distance(
    ARRAY[1.0, 2.0, 3.0]::float4[], nullable_doc_embedding,
    options=>jsonb'{"num_leaves_to_search": 10}'
  ) AS distance
FROM documents
WHERE nullable_doc_embedding IS NOT NULL AND word_count > 1000
ORDER BY distance
LIMIT 100;

A seguir