Lavorare con gli incorporamenti vettoriali

MySQL   |  PostgreSQL   |  SQL Server

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

• Genera e archivia incorporamenti vettoriali in base a un modello.

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

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

Cloud SQL consente di utilizzare un modello di incorporamento ospitato da Vertex AI per tradurre una stringa di testo in un incorporamento, che è la rappresentazione del modello del significato semantico del testo specificato come vettore numerico.

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

Prima di iniziare

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

Limitazioni regionali

Per generare incorporamenti con Cloud SQL, l'istanza deve risiedere in una regione in cui generative AI foundational models are supported. Il modello Vertex AI che Cloud SQL può utilizzare per gli incorporamenti, textembedding-gecko, si trova in quella regione.

Nota: questa limitazione non impedisce alle istanze Cloud SQL di integrarsi con Vertex AI, indipendentemente da dove si trovano.

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 ha entrambe le estensioni. Puoi installarle su qualsiasi database nella tua istanza. Per ulteriori informazioni, consulta Configurare le estensioni PostgreSQL.

Nota: fai riferimento a pgvector come vector nei comandi SQL, incluso il comando CREATE EXTENSION necessario per installare le estensioni. Per saperne di più, consulta la guida introduttiva.

Configura l'accesso al modello

Prima di poter generare incorporamenti da un'istanza Cloud SQL, devi configurare Cloud SQL in modo che utilizzi un modello di incorporamento del testo.

Per lavorare con il modello textembeddings-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 a utilizzare la funzione embedding per eseguire previsioni:

1. Connetti un client psql all'istanza principale, come descritto in Connettersi 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 il quale stai concedendo le autorizzazioni

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

Genera incorporamenti

Cloud SQL offre una funzione che consente di tradurre il testo in un incorporamento vettoriale. Puoi quindi archiviare l'incorporamento nel tuo database come dati vettoriali e, facoltativamente, utilizzare le funzioni pgvector per eseguire query su quest'ultimo.

Genera un incorporamento

Per generare un incorporamento mediante 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 textembedding-gecko o
  textembedding-gecko-multilingual. Questi sono i modelli basati su cloud che Cloud SQL può usare per gli incorporamenti di testo. Per maggiori informazioni, consulta Incorporamenti di testo.

• VERSION_TAG (facoltativo): il tag della versione del modello su cui eseguire la query. Anteponi @ al tag.

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

  Google consiglia vivamente di specificare il tag di versione.

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

L'esempio seguente utilizza la versione 001 del modello textembedding-gecko per generare un incorporamento in base a una stringa letterale fornita:

SELECT embedding( 'textembedding-gecko@001', 'Cloud SQL is a managed, cloud-hosted SQL database service.');

Archivia un incorporamento generato

Il valore restituito della funzione embedding() è un array di valori real. Per archiviare 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 supportate dal modello.

  Se utilizzi uno dei modelli textembedding-gecko con Vertex AI, specifica 768.

Facoltativamente, se hai installato l'estensione pgvector, puoi archiviare 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 ai 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 utilizzi Vertex AI Model Garden, specifica textembedding-gecko o
  textembedding-gecko-multilingual. Questi sono i modelli basati su cloud che Cloud SQL può usare per gli incorporamenti di testo. Per maggiori informazioni, consulta Incorporamenti di testo.

• VERSION_TAG (facoltativo): il tag della versione del modello su cui eseguire la query. Anteponi @ al tag.

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

  Google consiglia vivamente di specificare il tag di versione. Se non lo fai, rischi di ottenere risultati inaspettati.

• SOURCE_TEXT_COLUMN: il nome della colonna in cui è memorizzato il testo. Traduci questo testo in incorporamenti.

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

L'esempio seguente utilizza la versione 001 del modello textembedding-gecko per completare la colonna messages.message_vector con gli incorporamenti in base ai contenuti della colonna messages.message:

UPDATE messages SET message_vector = embedding( 'textembedding-gecko@001', message);

Esegui query e indicizza gli incorporamenti utilizzando pgvector

L'estensione PostgreSQL pgvector ti consente di utilizzare funzioni e operatori specifici del vettore quando archivi, indicizzi ed esegui query su incorporamenti di testo nel tuo database. Cloud SQL ha le proprie ottimizzazioni per l'utilizzo di pgvector, che ti consentono di creare indici che possono accelerare le query che coinvolgono gli incorporamenti.

Crea un indice di vicino più prossimo ottimizzato

pgvector supporta la ricerca del vicino più prossimo approssimato tramite l'indicizzazione. Cloud SQL aggiunge a questo supporto una funzionalità di quantizzazione scalare che puoi specificare quando crei un indice. Quando abiliti questa funzionalità, la quantizzazione scalare può accelerare le query con vettori dimensionali più grandi. Inoltre, questa funzione consente di archiviare vettori con un massimo di 8000 dimensioni.

Per abilitare la quantizzazione scalare su un indice basato su pgvector, specifica ivf come metodo di indice e SQ8 come quantizzatore:

CREATE INDEX ON TABLE
  USING ivf (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT, quantizer = 'SQ8');

Effettua le seguenti sostituzioni:

• TABLE: la tabella a cui aggiungi l'indice.

• EMBEDDING_COLUMN: una colonna che memorizza i dati di vector.

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

  • Distanza L2: vector_l2_ops

  • Prodotto interno: vector_ip_ops

  • Distanza incosino: vector_cosine_ops

• LIST_COUNT: il numero di elenchi da utilizzare con questo indice.

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 ivf ((CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)))'}} DISTANCE_FUNCTION)
  WITH (lists = LIST_COUNT, quantizer = 'SQ8');

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 incorporamenti nel tuo database, avrai a disposizione l'intera gamma di funzionalità di query pgvector.

Per trovare i vicini semantici più vicini a una porzione di testo, utilizza la funzione embedding() per tradurre il testo in un vettore. Nella stessa query, applica questo vettore all'operatore pgvector vicino al vicino più prossimo, <->, per trovare le righe di database con gli incorporamenti semanticamente 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 da righe semanticamente simili.

• TABLE: la tabella contenente l'incorporamento 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 textembedding-gecko o
  textembedding-gecko-multilingual. Questi sono i modelli basati su cloud che Cloud SQL può usare per gli incorporamenti di testo. Per maggiori informazioni, consulta Incorporamenti di testo.

• VERSION_TAG (facoltativo): il tag della versione del modello su cui eseguire la query. Anteponi @ al tag.

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

  Google consiglia vivamente di specificare il tag di versione. Se non lo fai, rischi di ottenere risultati inaspettati.

• TEXT: il testo che vuoi che ti consenta di trovare i vicini semantici archiviati più vicini.

• 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

Attenzione: per evitare risultati incoerenti dalla funzione embedding(), specifica sempre un modello di incorporamenti stabile, incluso un tag di versione.

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

Chiamare la funzione embedding() senza specificare il tag di versione del modello è sintatticamente valida, ma è anche soggetta 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. Questa versione potrebbe non essere l'ultima versione stabile. Per ulteriori informazioni sulle versioni disponibili dei modelli Vertex AI, consulta Versioni del modello.

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

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

Passaggi successivi

• Crea applicazioni di AI generativa utilizzando Cloud SQL

• Integra Cloud SQL con Vertex AI

• Richiamare previsioni online da istanze Cloud SQL

• Comprendere un esempio di flusso di lavoro di incorporamento

• Creare applicazioni basate su LLM utilizzando LangChain

• Gestire i dati con Cloud SQL Studio

• Scrivi codice SQL con l'assistenza di Gemini