Lavorare con gli incorporamenti vettoriali

Questa pagina mostra come utilizzare Cloud SQL per PostgreSQL per eseguire le seguenti azioni:

  • Genera e memorizza embedding vettoriali in base a un modello.

  • Indicizza ed esegui query sugli incorporamenti utilizzando l'estensione pgvector.

Per ulteriori informazioni, consulta Creare applicazioni di IA generativa utilizzando Cloud SQL.

Cloud SQL ti consente di utilizzare un modello di incorporamento ospitato da Vertex AI per tradurre una stringa di testo in un embedding, ovvero la rappresentazione del modello della semantica del testo specificato che equivale a un vettore numerico.

Cloud SQL implementa gli incorporamenti come array di valori real. In questo modo, puoi utilizzare gli embedding generati come input per le funzioni di estensione pgvector.

Prima di iniziare

Alcuni requisiti variano a seconda che tu voglia utilizzare Cloud SQL per generare embedding o se devi solo lavorare con gli embedding archiviati nel tuo database da un'altra origine.

Limitazioni regionali

Per generare incorporamenti con Cloud SQL, l'istanza deve trovarsi in una regione dove generative AI foundational models are supported. I modelli Vertex AI che Cloud SQL può utilizzare per gli incorporamenti, text-embedding e textembedding-gecko si trovano in questa regione.

Estensioni di database obbligatorie

Per lavorare con gli incorporamenti, devi avere l'estensione google_ml_integration, versione 1.2 o successiva, installata sull'istanza Cloud SQL.

Facoltativamente, se vuoi archiviare questi incorporamenti e utilizzare funzioni e operatori vettoriali con gli incorporamenti, hai bisogno anche dell'estensione pgvector.

Cloud SQL dispone di entrambe le estensioni. Puoi installarli su qualsiasi database della tua istanza. Per maggiori informazioni per informazioni, consulta Configurare le estensioni PostgreSQL.

Configura l'accesso al modello

Prima di poter generare embedding da un'istanza Cloud SQL, devi configurare Cloud SQL in modo che funzioni con un modello di embedding del testo.

Per lavorare con il modello text-embedding o textembedding-gecko basato su cloud, devi integrare Cloud SQL con Vertex AI.

Concedi agli utenti del database l'accesso per generare incorporamenti

Concedi agli utenti del database l'autorizzazione per utilizzare la funzione embedding per eseguire previsioni:

  1. Connetti un client psql all'istanza principale, come descritto in Connettiti utilizzando un client psql.

  2. Al prompt dei comandi psql, connettiti al database e concedi le autorizzazioni:

    \c DB_NAME

GRANT EXECUTE ON FUNCTION embedding TO USER_NAME;

    Sostituisci quanto segue:

    • DB_NAME: il nome del database per cui stai concedendo le autorizzazioni

    • USER_NAME: il nome dell'utente a cui stai concedendo le autorizzazioni

Genera embedding

Cloud SQL offre una funzione che ti consente di tradurre un testo in un all'incorporamento vettoriale. Puoi quindi archiviare l'incorporamento nel tuo database come vettore e, facoltativamente, utilizzare le funzioni pgvector per eseguire query.

Generare un incorporamento

Per generare un embedding utilizzando Cloud SQL, utilizza la funzione embedding() fornita dall'estensione google_ml_integration:

SELECT embedding( 'MODEL_IDVERSION_TAG', 'TEXT');

Effettua le seguenti sostituzioni:

  • MODEL_ID: l'ID del modello su cui eseguire la query.

    Se utilizzi Vertex AI Model Garden, specifica text-embedding-004 o
    text-multilingual-embedding-002. Questi sono i modelli basati su cloud Cloud SQL può usare per gli incorporamenti di testo. Per ulteriori informazioni, consulta Embedding di testo.

  • VERSION_TAG (Facoltativo): il tag della versione del modello da query. Per le versioni di textembedding-gecko precedenti a text-embedding-004 o text-multilingual-embedding-002,Prepend the tag with@`.

    Se utilizzi uno dei modelli textembedding-gecko con Vertex AI, quindi specifica uno dei tag di versione elencate in Versioni modello.

  • TEXT: il testo da tradurre in un incorporamento vettoriale.

L'esempio seguente utilizza il modello text-embedding-004 per generare un embedding in base a una stringa letterale fornita:

SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

Memorizzare un'evidenziazione generata

Il valore restituito della funzione embedding() è un array di valori real. Per memorizzare questo valore in una tabella, aggiungi una colonna real[]:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN real[DIMENSIONS];

Effettua le seguenti sostituzioni:

  • TABLE: il nome della tabella

  • EMBEDDING_COLUMN: il nome della nuova colonna di incorporamento

  • DIMENSIONS: il numero di dimensioni che il modello Google Cloud.

    Se utilizzi uno dei modelli text-embedding o textembedding-gecko con Vertex AI, quindi specifica 768.

Se hai installato l'estensione pgvector, puoi memorizzare gli incorporamenti come valori vector:

ALTER TABLE TABLE ADD COLUMN EMBEDDING_COLUMN vector(DIMENSIONS);

Dopo aver creato una colonna per archiviare gli incorporamenti, puoi compilarla in base i valori già archiviati in un'altra colonna nella stessa tabella:

UPDATE TABLE SET EMBEDDING_COLUMN = embedding('MODEL_IDVERSION_TAG', SOURCE_TEXT_COLUMN);

Effettua le seguenti sostituzioni:

  • TABLE: il nome della tabella.

  • EMBEDDING_COLUMN: il nome della colonna di incorporamento.

  • MODEL_ID: l'ID del modello su cui eseguire la query.

    Se usi lo strumento Vertex AI Model Garden e specificare text-embedding-004 o
    text-multilingual-embedding-002. Questi sono i modelli basati su cloud Cloud SQL può usare per gli incorporamenti di testo. Per ulteriori informazioni, vedi Incorporamenti di testo.

  • VERSION_TAG (Facoltativo): il tag della versione del modello su cui eseguire la query. Per le versioni di textembedding-gecko precedenti a text-embedding-004 o text-multilingual-embedding-002,Prepend the tag with@`.

    Se utilizzi uno dei modelli textembedding-gecko con Vertex AI, specifica uno dei tag di versione elencati in Versioni del modello.

  • SOURCE_TEXT_COLUMN: il nome della colonna che memorizza il testo. Traduci questo testo in incorporamenti.

Il comando precedente funziona per le colonne di incorporamento real[] e vector. Se le tue è di tipo vector, quindi Cloud SQL trasmette in modo implicito il valore restituito di embedding() da un array real a un valore vector.

L'esempio seguente utilizza il modello text-embedding-004 per compilare il messages.message_vector con incorporamenti basati sui contenuti di messages.message colonna:

UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);

Esegui query e indicizza gli embedding utilizzando pgvector

L'estensione pgvector PostgreSQL ti consente di utilizzare operatori e funzioni specifici per i vettori quando archivi, indicizzi ed esegui query sugli incorporamenti di testo nel tuo database. Cloud SQL ha le proprie ottimizzazioni per lavorare con pgvector, che ti consentono di creare indici in grado di velocizzare le query che coinvolgono gli embedding.

Crea un indice del vicino più vicino

pgvector supporta la ricerca del vicino più prossimo approssimato tramite l'indicizzazione.

Per creare un indice basato su pgvector con hnsw come metodo di indice, usa l'esempio seguente:

CREATE INDEX ON TABLE
  USING hnsw (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

Effettua le seguenti sostituzioni:

  • TABLE: la tabella a cui stai aggiungendo l'indice.

  • EMBEDDING_COLUMN: una colonna che memorizza i dati vector.

  • DISTANCE_FUNCTION: la funzione di distanza da utilizzare con questo di Google. Scegli una delle opzioni seguenti:

    • Distanza L2: vector_l2_ops

    • Prodotto interno: vector_ip_ops

    • Distanza incosino: vector_cosine_ops

  • M (facoltativo): il numero massimo di connessioni con punti dati vicini in un grafico. Ti consigliamo un intervallo compreso tra 5 e 48 perché 16 è il valore predefinito per pgvector.

  • EF_CONSTRUCTION (facoltativo): la dimensione dell'elenco che contiene i candidati più vicini durante l'esplorazione del grafico durante la creazione dell'indice. Valori più elevati inducono l'algoritmo a prendere in considerazione più candidati, consentendo di creare un indice migliore. La dimensione predefinita è 64.

Per creare questo indice su una colonna di incorporamento che utilizza il tipo di dati real[] anziché vector, trasmetti la colonna nel tipo di dati vector:

CREATE INDEX ON TABLE
  USING hnsw ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)))' DISTANCE_FUNCTION)
  WITH (m = M, ef_construction = EF_CONSTRUCTION);

Sostituisci DIMENSIONS con la larghezza dimensionale della colonna di incorporamento.

La sezione successiva mostra un esempio di questo tipo di indice.

Eseguire una query per il vicino più prossimo con un determinato testo

Dopo aver archiviato e indicizzato gli embedding nel database, hai a disposizione l'intera gamma di funzionalità di query di pgvector.

Per trovare i termini semantici più vicini a un testo, utilizza la funzione embedding() per tradurre il testo in un vettore. Nella stessa query, applica questo vettore all'operatore pgvector vicino più prossimo, <->, per trovare le righe del database con gli incorporamenti semanticamente più simili.

Poiché embedding() restituisce un array real, devi trasmettere la chiamata embedding() a vector per utilizzare questi valori con gli operatori pgvector.

  SELECT RESULT_COLUMNS FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Effettua le seguenti sostituzioni:

  • RESULT_COLUMNS: le colonne da visualizzare semanticamente righe simili.

  • TABLE: la tabella contenente l'embedding con cui confronti il testo.

  • EMBEDDING_COLUMN: la colonna contenente gli incorporamenti archiviati.

  • MODEL_ID: l'ID del modello su cui eseguire la query.

    Se utilizzi Vertex AI Model Garden, specifica text-embedding-004 o
    text-embedding-multilingual-002. Questi sono i modelli basati su cloud che Cloud SQL può utilizzare per gli embedding di testo. Per ulteriori informazioni, vedi Incorporamenti di testo.

  • VERSION_TAG (Facoltativo): il tag della versione del modello da query. Anteponi al tag @.

    Se utilizzi uno dei modelli textembedding-gecko con Vertex AI, quindi specifica uno dei tag di versione elencate in Versioni modello.

  • TEXT: il testo che vuoi, in modo che tu possa trovare il contenuto vicini semantici.

  • ROW_COUNT: il numero di righe da restituire. Se vuoi solo la singola corrispondenza migliore, specifica 1 come valore per questo parametro.

Per eseguire questa query con una colonna di incorporamento archiviata che utilizza il tipo di dati real[] anziché vector, trasmetti la colonna nel tipo di dati vector:

  SELECT RESULT_COLUMNS::vector FROM TABLE
    ORDER BY EMBEDDING_COLUMN
    <-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
    LIMIT ROW_COUNT

Utilizza i tag della versione del modello per evitare errori

Google consiglia vivamente di utilizzare sempre una versione stabile del modello di embedding scelto. Per la maggior parte dei modelli, ciò significa impostare un tag della versione in modo esplicito.

Chiamare la funzione embedding() senza specificare il tag versione di il modello è sintatticamente valido, ma è anche soggetto a errori.

Se ometti il tag della versione quando utilizzi un modello in Vertex AI Model Garden, Vertex AI utilizza la versione più recente del modello. Potrebbe non essere l'ultima versione stabile. Per maggiori informazioni informazioni sulle versioni disponibili dei modelli Vertex AI, consulta Versioni del modello.

Una determinata versione del modello Vertex AI restituisce sempre la stessa rispostaembedding() a un determinato input di testo. Se non specifichi le versioni del modello nelle chiamate a embedding(), una nuova versione del modello pubblicata può cambiare bruscamente il vettore restituito per un determinato input. Questo può causare errori o altri comportamenti imprevisti nelle applicazioni.

Per evitare questi problemi, specifica sempre la versione del modello.

Passaggi successivi