Pesquise e filtre com incorporações vetoriais

Esta página descreve as diferentes formas de consultar incorporações vetoriais. Para ver uma vista geral das pesquisas de similaridade ANN e KNN, consulte as pesquisas de vetores.

Pesquisa de vizinhos mais próximos aproximados (ANN)

Para realizar uma pesquisa ANN, use a função approx_distance numa cláusula SELECT e ORDER BY. Tem de usar uma cláusula LIMIT numa pesquisa de ANN. Também pode obter o valor da distância colocando approx_distance numa lista SELECT.

Use a seguinte sintaxe para consultas ANN:

# Ordering by distance
SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=l2_squared')
LIMIT 4;

# Selecting the distance value
SELECT
  approx_distance(
    embedding_name,
    string_to_vector('[1,2,3]'),
    'distance_measure=cosine,num_leaves_to_search=3')
    dist
FROM table
ORDER BY dist
LIMIT limit_value;

A função approx_distance usa as seguintes opções:

  • embedding: usa o nome da coluna de incorporação de vetores da tabela base.
  • string_to_vector ou vector_to_string: converte um vetor numa string e uma string num vetor para tornar o vetor legível por humanos.
  • distance_measure: especifique a medida de distância a usar para uma pesquisa de similaridade de vetores. Este valor tem de corresponder ao valor que definiu no parâmetro distance_measure quando criou o índice. Este parâmetro é obrigatório. Os valores possíveis para este parâmetro são:
    • COSINE
    • L2_SQUARED
    • DOT_PRODUCT
  • num_leaves_to_search: opcional. Especifica o número de folhas a analisar para uma pesquisa de similaridade de vetores ANN. Se não especificar o número de folhas, o Cloud SQL usa um valor gerado com base no tamanho da tabela, no número de folhas no índice de vetores e noutros fatores. Pode ver este valor no grupo information_schema.innodb_vector_indexes. Recomendamos que ajuste os parâmetros num_leaves_to_search para alcançar o melhor equilíbrio entre a qualidade da pesquisa e o desempenho para a sua carga de trabalho específica. Se for aumentado, afeta o desempenho, mas melhora a capacidade de memorização.

O exemplo seguinte mostra como usar approx_distance para encontrar as K linhas mais próximas usando a medida de distância l2_squared e ordenar os resultados por distância.

# Ordering by distance
SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'),
                         'distance_measure=l2_squared')
LIMIT 4;

# Selecting the distance value
SELECT
    approx_distance
        (embedding, string_to_vector('[1,2,3]'),
         'distance_measure=l2_squared') dist
FROM table
ORDER BY dist
LIMIT 4;

Filtre resultados de consultas approx_distance

Pode usar a função approx_distance com condições WHERE que filtram os resultados da consulta com um predicado não vetorial para realizar a filtragem posterior. A função approx_distance é avaliada antes de aplicar o filtro, o que significa que o número de resultados devolvidos é não determinístico.

Por exemplo, para a seguinte consulta:

SELECT id FROM products WHERE price < 100
ORDER BY approx_distance(embedding, @query_vector,'distance_measure=cosine')
LIMIT 11;

A função approx_distance devolve os 11 vizinhos mais próximos do vetor de consulta, independentemente do preço. Na filtragem posterior, os produtos com um preço< 100 são selecionados. É possível que todos os vizinhos mais próximos tenham um preço inferior a 100, pelo que existem 11 resultados para a consulta. Em alternativa, se nenhum dos vizinhos mais próximos tiver um preço inferior a 100, são devolvidas 0 linhas.

Se prevê que a condição WHERE do filtro é muito seletiva, uma pesquisa exata (KNN) é uma opção para ajudar a garantir que é devolvido um número suficiente de linhas.

Outra opção é usar a filtragem iterativa para analisar mais do índice de pesquisa de ANN.

Use a filtragem iterativa para aumentar os resultados da pesquisa de ANN

Pode usar a filtragem iterativa quando os filtros seletivos da cláusula WHERE na sua consulta de pesquisa de ANN produzem menos resultados do que o número de resultados especificado na cláusula LIMIT.

Por exemplo, na consulta seguinte, quando ativa a filtragem iterativa, a consulta analisa mais o índice vetorial, menos o primeiro conjunto de resultados filtrados.

EXPLAIN FORMAT=TREE
SELECT * FROM t1 WHERE next_id BETWEEN 15 AND 100
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=l2_squared')
LIMIT 10;

EXPLAIN
-> Limit: 10 row(s)  (rows=10)
   -> Vector index loop with iterative filtering
      -> Vector index scan on t1
      -> Filter: (t1.next_id between 15 and 100)
         -> Single-row index lookup on t1 using PRIMARY (id=t1.id)

Busca mais vizinhos do índice de vetores de pesquisa iterativamente até atingir o máximo configurado (cloudsql_vector_iterative_filtering_max_neighbors). Todas as correspondências de filtros são contabilizadas para o limite de LIMIT e removidas das análises adicionais do índice de vetores.

Ative a filtragem iterativa

Por predefinição, a filtragem iterativa está desativada para todas as sessões e instâncias do Cloud SQL.

Para ativar a filtragem iterativa para uma sessão existente, use a seguinte declaração SQL.

SET SESSION cloudsql_vector_iterative_filtering=on;

Também pode ativar a filtragem iterativa globalmente para todas as sessões de cliente que se ligam à instância definindo a flag na instância. Para definir uma flag para uma instância, consulte o artigo Defina uma flag de base de dados.

Para mais informações sobre como definir variáveis do sistema ao nível da sessão ou global, consulte o artigo Usar variáveis do sistema na documentação do MySQL.

Ajuste a filtragem iterativa

Para controlar quantos vizinhos mais próximos são devolvidos para uma consulta de pesquisa ANN com a filtragem iterativa ativada, pode usar a variável de sistema global ou de sessão cloudsql_vector_iterative_filtering_max_neighbors. Pode usar esta configuração para aumentar o número de vizinhos mais próximos pedidos. No entanto, para evitar armazenar demasiados resultados na memória, o máximo para esta variável é 1000.

Para definir esta variável para uma sessão, use a seguinte declaração SQL:

SET cloudsql_vector_iterative_filtering_max_neighbors=600;

A predefinição é 500 e o número mínimo é 10.

Limitações

Seguem-se as limitações da utilização da filtragem iterativa:

  • Não é uma garantia: quando usa a filtragem iterativa, o Cloud SQL tenta encontrar o número de resultados especificado na cláusula LIMIT, mas não garante que o número seja encontrado. Isto pode acontecer se o número máximo de vizinhos (cloudsql_vector_iterative_filtering_max_neighbors) for atingido antes de a condição LIMIT ser satisfeita ou se não existirem linhas suficientes que correspondam ao filtro na tabela.

  • Consultas complexas: a filtragem iterativa só funciona quando os predicados de filtro são enviados para o caminho de acesso da tabela base. Não é suportado para filtros em cima de tabelas temporárias; por exemplo, tabelas que usam uma cláusula HAVING. Nas subconsultas, apenas são considerados os filtros na tabela base na própria subconsulta para a filtragem iterativa.

Verifique o estado de alternativa nas pesquisas de ANN

Existem determinados casos em que uma pesquisa ANN recorre a uma pesquisa KNN. Estes incluem o seguinte:

  • Não existe um índice vetorial na tabela base.
  • Existe um índice vetorial na tabela base, mas usa uma medida de distância diferente do parâmetro distance_measure nas opções de pesquisa approx_distance.
  • O índice vetorial está danificado ou invisível para a transação atual.
  • O valor LIMIT especificado é superior a 10 000.
  • Não foi especificado nenhum LIMIT.
  • A consulta atual envolve mais do que uma chamada approx_distance na mesma tabela base.
  • O otimizador calcula que é mais eficiente usar o KNN.

Todos estes casos enviam um aviso ao cliente a indicar que foi feita uma pesquisa exata e o motivo.

Use o seguinte comando no cliente mysql para ver o estado de alternativa:

SHOW global status LIKE '%cloudsql_vector_knn_fallback%';

Se quiser usar a ANN e esta estiver a recorrer à KNN, a consulta pode ser executada mais lentamente. Deve encontrar o motivo pelo qual está a usar a alternativa e avaliar se deve fazer alterações para que seja usada a ANN.

Exemplo: crie um índice vetorial e execute uma consulta ANN

O exemplo seguinte explica os passos para criar um índice vetorial e executar uma consulta ANN no Cloud SQL.

  1. Gere incorporações vetoriais. Pode criar incorporações vetoriais manualmente ou usar uma API de incorporação de texto à sua escolha. Para ver um exemplo que usa o Vertex AI, consulte o artigo Gere incorporações vetoriais com base nos dados das linhas.

  2. Crie uma tabela no Cloud SQL que contenha uma coluna de incorporação de vetores com três dimensões.

    CREATE TABLE books(
id INTEGER PRIMARY KEY AUTO_INCREMENT, title VARCHAR(60), embedding VECTOR(3) USING VARBINARY);

  3. Inserir uma incorporação de vetor na coluna.

    INSERT INTO books VALUES ((1, 'book title', string_to_vector('[1,2,3]')));

  4. Confirme as alterações.

    commit;

  5. Crie o índice vetorial com a função L2_squared para medir a distância.

    CREATE
  VECTOR INDEX vectorIndex
ON dbname.books(embeddings)
USING SCANN QUANTIZER = SQ8 DISTANCE_MEASURE = l2_squared;

  6. Use a seguinte sintaxe para fazer uma pesquisa de ANN com um LIMIT de 4 resultados da pesquisa:

    SELECT title
FROM books
ORDER BY approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=l2_squared')
LIMIT 4;

SELECT approx_distance(embedding, string_to_vector('[1,2,3]'), 'distance_measure=cosine') dist
FROM books
ORDER BY dist
LIMIT 4;

Pesquisa dos K vizinhos mais próximos (KNN)

Para realizar uma pesquisa de K-vizinhos mais próximos, use a função vector_distance com uma opção de medida de distância e uma função de conversão de vetores (string_to_vector ou vector_to_string) numa declaração SELECT. Use a seguinte sintaxe:

SELECT vector_distance(string_to_vector('[1,2,3]'),
                      string_to_vector('[1,2,3]'),
                      'Distance_Measure=dot_product');

Substitua os valores [1,2,3] pelos valores de incorporação dos seus dados.

O exemplo seguinte mostra como usar esta consulta com a função cosine_distance e a função de conversão de vetores string_to_vector.

SELECT id,cosine_distance(embedding, string_to_vector('[1,2,3]')) dist
FROM books
ORDER BY distance
LIMIT 10;

Obtenha a distância de cosseno numa consulta KNN

Use a função Cloud SQL cosine_distance para calcular a distância usando o cosseno.

SELECT cosine_distance(embedding, string_to_vector('[3,1,2]')) AS distance FROM books WHERE id = 10;

Obtenha a distância do produto escalar num pedido KNN

Use a função dot_product do Cloud SQL para calcular a distância através do produto escalar.

SELECT dot_product(embedding, string_to_vector('[3,1,2]')) AS distance FROM books WHERE id = 10;

Obtenha a distância ao quadrado L2 numa consulta KNN

Use a função Cloud SQL l2_squared_distance para calcular a distância usando L2 ao quadrado.

SELECT
  l2_squared_distance(embedding, string_to_vector('[3,1,2]'))
    AS distance
FROM books
WHERE id = 10;

O que se segue?