Cercare e filtrare con gli embedding vettoriali

Questa pagina descrive i diversi modi in cui puoi eseguire query sui vector embedding. Per una panoramica delle ricerche di somiglianza ANN e KNN, consulta Vector Search.

Prima di iniziare

Attiva il flag di database cloudsql_vector sulla tua istanza Cloud SQL.

Per le istanze che utilizzano Cloud SQL per MySQL 9.7 o versioni successive, anche se non è necessario attivare cloudsql_vector per creare e archiviare vector embedding, devi attivare il flag di database cloudsql_vector nell'istanza Cloud SQL per creare indici vettoriali ed eseguire ricerche ANN sui dati vettoriali.

Cerca i vicini più prossimi approssimati (ANN)

Per eseguire una ricerca ANN, utilizza la funzione approx_distance in una clausola SELECT e ORDER BY. Devi utilizzare una clausola LIMIT in una ricerca ANN. Puoi anche ottenere il valore della distanza inserendo approx_distance in un elenco SELECT.

Utilizza la seguente sintassi per le query 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;

La funzione approx_distance utilizza le seguenti opzioni:

  • embedding: utilizza il nome della colonna di vector embedding della tabella di base.
  • string_to_vector o vector_to_string: converte un vettore in una stringa e una stringa in un vettore per renderlo leggibile.
  • distance_measure: specifica la misura della distanza da utilizzare per una ricerca di somiglianza vettoriale. Questo valore deve corrispondere a quello impostato nel parametro distance_measure durante la creazione dell'indice. Questo parametro è obbligatorio. I valori possibili per questo parametro sono:
    • COSINE
    • L2_SQUARED
    • DOT_PRODUCT
  • num_leaves_to_search: facoltativo. Specifica il numero di nodi foglia da analizzare per una ricerca di somiglianza vettoriale ANN. Se non specifichi il numero di foglie, Cloud SQL utilizza un valore generato in base alle dimensioni della tabella, al numero di foglie nell'indice vettoriale e ad altri fattori. Puoi visualizzare questo valore in information_schema.innodb_vector_indexes. Ti consigliamo di ottimizzare num_leaves_to_search per ottenere il miglior equilibrio tra qualità e prestazioni di ricerca per il tuo workload specifico. Se aumentato, influisce sulle prestazioni, ma migliora il richiamo.

L'esempio seguente mostra come utilizzare approx_distance per trovare le K righe più vicine utilizzando la misura di distanza l2_squared e ordinare i risultati in base alla distanza.

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

Filtra i risultati delle query approx_distance

Puoi utilizzare la funzione approx_distance con le condizioni WHERE che filtrano i risultati delle query con un predicato non vettoriale per eseguire il post-filtraggio. La funzione approx_distance viene valutata prima di applicare il filtro, il che significa che il numero di risultati restituiti non è deterministico.

Ad esempio, per la seguente query:

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

La funzione approx_distance restituisce gli 11 vicini più prossimi al vettore di query, indipendentemente dal prezzo. Nel filtro post, vengono selezionati i prodotti con un prezzo < 100. È possibile che tutti gli elementi più prossimi abbiano un prezzo < 100, quindi la query restituisce 11 risultati. In alternativa, se nessuno dei vicini più prossimi ha un prezzo < 100, non vengono restituite righe.

Se prevedi che il filtro nella condizione WHERE sia molto selettivo, una ricerca esatta (KNN) è un'opzione che ti aiuta a garantire che venga restituito un numero sufficiente di righe.

Un'altra opzione è utilizzare il filtro iterativo per eseguire la scansione di una parte maggiore dell'indice della Ricerca ANN.

Utilizza il filtro iterativo per aumentare i risultati di ricerca ANN

Puoi utilizzare il filtro iterativo quando i filtri selettivi della clausola WHERE nella query di ricerca ANN producono meno risultati rispetto al numero di risultati specificato nella clausola LIMIT.

Ad esempio, nella seguente query, quando attivi il filtro iterativo, la query analizza una parte maggiore dell'indice vettoriale meno il primo insieme di risultati filtrati.

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)

Recuperi più vicini dall'indice vettoriale di ricerca in modo iterativo fino a raggiungere il numero massimo configurato (cloudsql_vector_iterative_filtering_max_neighbors). Tutte le corrispondenze dei filtri vengono conteggiate ai fini del LIMIT e rimosse dalle scansioni aggiuntive dell'indice vettoriale.

Attiva il filtro iterativo

Per impostazione predefinita, il filtro iterativo è disattivato per tutte le sessioni e le istanze Cloud SQL.

Per attivare il filtro iterativo per una sessione esistente, utilizza la seguente istruzione SQL.

SET SESSION cloudsql_vector_iterative_filtering=on;

Puoi anche attivare il filtro iterativo a livello globale per tutte le sessioni client che si connettono all'istanza impostando il flag sull'istanza. Per impostare un flag per un'istanza, consulta Imposta un flag di database.

Per saperne di più sull'impostazione delle variabili di sistema a livello di sessione o globale, consulta Utilizzo delle variabili di sistema nella documentazione di MySQL.

Ottimizza il filtro iterativo

Per controllare il numero di vicini più prossimi restituiti per una query di ricerca ANN con il filtro iterativo abilitato, puoi utilizzare la variabile di sistema di sessione o globale cloudsql_vector_iterative_filtering_max_neighbors. Puoi utilizzare questa configurazione per aumentare il numero di vicini più prossimi richiesti. Tuttavia, per evitare di archiviare troppi risultati in memoria, il valore massimo per questa variabile è 1000.

Per impostare questa variabile per una sessione, utilizza la seguente istruzione SQL:

SET cloudsql_vector_iterative_filtering_max_neighbors=600;

Il valore predefinito è 500 e il numero minimo è 10.

Limitazioni

Di seguito sono riportate le limitazioni relative all'utilizzo dei filtri iterativi:

  • Nessuna garanzia: quando utilizzi il filtro iterativo, Cloud SQL tenta di trovare il numero di risultati specificati nella clausola LIMIT, ma non garantisce che il numero venga trovato. Questo può accadere se il numero massimo di vicini (cloudsql_vector_iterative_filtering_max_neighbors) viene raggiunto prima che LIMIT venga soddisfatto o se nella tabella non sono presenti righe sufficienti che corrispondono al filtro.

  • Query complesse: il filtro iterativo funziona solo quando i predicati di filtro vengono applicati al percorso di accesso della tabella di base. Non è supportata per i filtri su tabelle temporanee, ad esempio tabelle che utilizzano una clausola HAVING. Nelle sottoquery, solo i filtri sulla tabella di base all'interno della sottoquery stessa vengono presi in considerazione per il filtro iterativo.

Controlla lo stato di riserva per le ricerche ANN

In alcuni casi, una ricerca ANN viene sostituita da una ricerca KNN. Sono inclusi i seguenti tipi:

  • Non esiste un indice vettoriale nella tabella di base.
  • Nella tabella di base è presente un indice vettoriale, ma utilizza una misura di distanza diversa dal parametro distance_measure nelle opzioni di ricerca approx_distance.
  • L'indice vettoriale è danneggiato o non è visibile alla transazione corrente.
  • Il valore LIMIT specificato è maggiore di 10.000.
  • Non è stato specificato alcun LIMIT.
  • La query corrente prevede più di una chiamata approx_distance sulla stessa tabella di base.
  • L'ottimizzatore calcola che è più efficiente utilizzare KNN.

In tutti questi casi, viene inviato un avviso al client che indica che è stata eseguita una ricerca esatta e il motivo.

Utilizza il seguente comando nel client mysql per visualizzare lo stato del fallback:

SHOW global status LIKE '%cloudsql_vector_knn_fallback%';

Se vuoi utilizzare ANN e viene eseguito il fallback a KNN, la query potrebbe essere eseguita più lentamente. Dovresti trovare il motivo del fallback e valutare se apportare modifiche in modo da utilizzare ANN.

Esempio: crea un indice vettoriale ed esegui una query ANN

La seguente procedura dettagliata di esempio fornisce i passaggi per creare un indice vettoriale ed eseguire una query ANN in Cloud SQL.

  1. Genera vector embedding. Puoi creare vector embedding manualmente o utilizzare un'API di text embedding di tua scelta. Per un esempio che utilizza Vertex AI, consulta Genera vector embedding in base ai dati delle righe.
  2. Crea una tabella in Cloud SQL che contenga una colonna di vector embedding con tre dimensioni.

    CREATE TABLE books(
    id INTEGER PRIMARY KEY AUTO_INCREMENT, title VARCHAR(60), embedding VECTOR(3) USING VARBINARY);
    
  3. Inserisci un vector embedding nella colonna.

    INSERT INTO books VALUES ((1, 'book title', string_to_vector('[1,2,3]')));
    
  4. Esegui il commit delle modifiche.

    commit;
    
  5. Crea l'indice vettoriale utilizzando la funzione L2_squared per misurare la distanza.

    CREATE
      VECTOR INDEX vectorIndex
    ON dbname.books(embeddings)
    USING SCANN QUANTIZER = SQ8 DISTANCE_MEASURE = l2_squared;
    
  6. Utilizza la seguente sintassi per eseguire una ricerca ANN con un LIMIT di 4 risultati di ricerca:

    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;
    

Cerca i vicini più prossimi (KNN)

Per eseguire una ricerca dei k-nearest neighbor, utilizza la funzione vector_distance con un'opzione di misurazione della distanza e una funzione di conversione vettoriale (string_to_vector o vector_to_string) in un'istruzione SELECT. Utilizza la seguente sintassi:

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

Sostituisci i valori [1,2,3] con i valori di embedding dei tuoi dati.

L'esempio seguente mostra come utilizzare questa query con la funzione cosine_distance e la funzione di conversione vettoriale string_to_vector.

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

Ottieni la distanza coseno in una query KNN

Utilizza la funzione cosine_distance di Cloud SQL per calcolare la distanza utilizzando il coseno.

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

Ottieni la distanza prodotto scalare in una query KNN

Utilizza la funzione dot_product di Cloud SQL per calcolare la distanza utilizzando il prodotto scalare.

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

Ottieni la distanza al quadrato L2 in una query KNN

Utilizza la funzione l2_squared_distance di Cloud SQL per calcolare la distanza utilizzando L2 al quadrato.

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

Passaggi successivi