Questa pagina descrive come generare e archiviare i vector embedding in base a un modello.
Per ulteriori informazioni, consulta Creare applicazioni di AI generativa utilizzando Cloud SQL.
Cloud SQL ti consente di utilizzare un modello di embedding ospitato da Vertex AI per tradurre una stringa di testo in un embedding, ovvero la rappresentazione del modello del significato semantico del testo dato come vettore numerico.
Cloud SQL implementa gli incorporamenti come array di valori real
. 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 che tu debba solo lavorare con incorporamenti archiviati nel tuo database da un'altra origine.
Limitazioni regionali
Per generare embedding Vertex AI con Cloud SQL, la tua
istanza deve trovarsi in una regione in cui
sono supportati i modelli di base di AI generativa.
I modelli Vertex AI che Cloud SQL può utilizzare per gli embedding, text-embedding
e textembedding-gecko
, si trovano in quella regione.
Estensioni del database richieste
Per lavorare con gli incorporamenti, installa l'estensione
google_ml_integration
sull'istanza Cloud SQL. Per i modelli Vertex AI, installa
la versione 1.2
o successive. Per i modelli personalizzati o di terze parti, installa la versione
1.4.2
o successive.
Se vuoi archiviare questi embedding e utilizzare funzioni e
operatori vettoriali con gli embedding, devi anche installare
l'estensione pgvector
.
Cloud SQL dispone di entrambe le estensioni. Puoi installarli su qualsiasi database dell'istanza. Per maggiori informazioni, vedi Configurare le estensioni PostgreSQL.
Configurare l'accesso al modello
Prima di poter generare incorporamenti da un'istanza Cloud SQL, devi configurare Cloud SQL in modo che funzioni con un modello di incorporamento di testo.
Per lavorare con il modello basato sul cloud text-embedding
o textembedding-gecko
,
devi integrare Cloud SQL con Vertex AI.
Concedere agli utenti del database l'accesso per generare incorporamenti
Concedi l'autorizzazione agli utenti del database per utilizzare la funzione embedding
per eseguire le previsioni:
Connetti un client
psql
all'istanza primaria, come descritto in Connessione tramite un client psql.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
Generare incorporamenti
Cloud SQL fornisce una funzione che consente di tradurre il testo in un
incorporamento vettoriale. Puoi quindi archiviare l'embedding nel database come dati vettoriali 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 da interrogare.
Se utilizzi Vertex AI Model Garden, specifica
text-embedding-004
otext-multilingual-embedding-002
. Questi sono i modelli basati su cloud che Cloud SQL può utilizzare per gli incorporamenti di testo. Per maggiori informazioni, consulta Incorporamenti di testo.VERSION_TAG (facoltativo): il tag della versione del modello da interrogare. Per le versioni di
textembedding-gecko
precedenti atext-embedding-004
otext-multilingual-embedding-002
, anteponi al tag@
.Se utilizzi uno dei modelli
textembedding-gecko
con Vertex AI, specifica uno dei tag di versione elencati in Versioni del modello.TEXT: il testo da tradurre in un embedding vettoriale.
L'esempio seguente utilizza il modello text-embedding-004
per generare un
incorporamento basato su una stringa letterale fornita:
SELECT embedding( 'text-embedding-004', 'Cloud SQL is a managed, cloud-hosted SQL database service.');
Memorizzare un incorporamento generato
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 supportate dal modello.
Se utilizzi uno dei modelli
text-embedding
otextembedding-gecko
con Vertex AI, specifica768
.
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 ai valori già archiviati in un'altra colonna della 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 da interrogare.
Se utilizzi Vertex AI Model Garden, specifica
text-embedding-004
otext-multilingual-embedding-002
. Questi sono i modelli basati su cloud che Cloud SQL può utilizzare per gli incorporamenti di testo. Per maggiori informazioni, consulta Incorporamenti di testo.VERSION_TAG (Facoltativo): il tag della versione del modello da interrogare. Per le versioni di
textembedding-gecko
precedenti atext-embedding-004
otext-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 sia per le colonne di incorporamento real[]
che per quelle vector
. Se
la colonna di incorporamento è di tipo vector
, Cloud SQL esegue il cast
del valore restituito di embedding()
da un array real
a un valore vector
in modo implicito.
Il seguente esempio utilizza il modello text-embedding-004
per compilare la
colonna messages.message_vector
con incorporamenti basati sui contenuti della
colonna messages.message
:
UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);
Query e indici di embedding utilizzando pgvector
L'estensione PostgreSQL pgvector
ti consente di utilizzare operatori e funzioni specifici per i vettori quando archivi, indicizzi ed esegui query sugli incorporamenti di testo nel database.
Cloud SQL ha ottimizzazioni proprie per l'utilizzo di pgvector
, che ti consentono di creare indici in grado di velocizzare le query che coinvolgono gli incorporamenti.
Crea un indice dei vicini più prossimi
pgvector
supporta le ricerche approssimative del vicino più prossimo (ANN) tramite
indicizzazione.
Per creare un indice HNSW
, utilizza la funzione hnsw
, come mostrato nell'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 indice. Scegli una delle opzioni seguenti:
Distanza L2:
vector_l2_ops
Prodotto interno:
vector_ip_ops
Distanza coseno:
vector_cosine_ops
M (facoltativo): il numero massimo di connessioni con punti dati vicini in un grafico. Ti consigliamo un intervallo da 5 a 48. Il valore predefinito è 16.
EF_CONSTRUCTION (facoltativo): le dimensioni dell'elenco che contiene i candidati più vicini durante l'attraversamento del grafico durante la creazione dell'indice. Valori più alti portano l'algoritmo a considerare più candidati, consentendo di creare un indice migliore. La dimensione predefinita è 64.
Per creare questo indice in una colonna di incorporamento che utilizza il tipo di dati real[]
anziché vector
, esegui il cast della 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.
Esegui una query per il vicino più prossimo con il testo specificato
Dopo aver archiviato e indicizzato gli incorporamenti nel database, è disponibile l'intera gamma di
funzionalità di query
pgvector
.
Per trovare i vicini 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 per trovare il vicino più prossimo pgvector
, <->
, per trovare
le righe del database con gli incorporamenti semanticamente più simili.
Poiché embedding()
restituisce un array real
, devi eseguire il cast della 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 dalle righe semanticamente simili.
TABLE: la tabella contenente l'incorporamento a cui viene confrontato il testo.
EMBEDDING_COLUMN: la colonna contenente gli embedding archiviati.
MODEL_ID: l'ID del modello da interrogare.
Se utilizzi Vertex AI Model Garden, specifica
text-embedding-004
otext-embedding-multilingual-002
. Questi sono i modelli basati su cloud che Cloud SQL può utilizzare per gli incorporamenti di testo. Per maggiori informazioni, consulta Incorporamenti di testo.VERSION_TAG (Facoltativo): il tag della versione del modello da interrogare. Aggiungi il prefisso
@
al tag.Se utilizzi uno dei modelli
textembedding-gecko
con Vertex AI, specifica uno dei tag di versione elencati in Versioni del modello.TEXT: il testo che vuoi per trovare i vicini semantici memorizzati più vicini.
ROW_COUNT: il numero di righe da restituire. Se vuoi solo la migliore corrispondenza singola, specifica
1
come valore per questo parametro.
Per eseguire questa query con una colonna di incorporamento memorizzata che utilizza il tipo di dati real[]
anziché vector
, esegui il cast della colonna nel tipo di dati vector
:
SELECT RESULT_COLUMNS FROM TABLE
ORDER BY EMBEDDING_COLUMN::vector
<-> embedding('MODEL_IDVERSION_TAG', 'TEXT')::vector
LIMIT ROW_COUNT
Utilizzare i tag della versione del modello per evitare errori
Cloud SQL consiglia vivamente di utilizzare sempre una versione stabile del modello di incorporamento scelto. Per la maggior parte dei modelli, ciò significa impostare un tag di versione in modo esplicito.
Chiamare la funzione embedding()
senza specificare il tag di versione del modello è valido dal punto di vista sintattico, ma può essere 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 ulteriori informazioni sulle versioni del modello Vertex AI disponibili, 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 la versione del modello nelle chiamate di incorporamento, è possibile che una versione del modello appena pubblicata possa modificare bruscamente il vettore restituito per un determinato input. Ciò può
causare errori o altri comportamenti imprevisti nelle applicazioni.
Passaggi successivi
- Crea applicazioni di AI generativa utilizzando Cloud SQL
- Integra Cloud SQL con Vertex AI
- Richiamare le previsioni online dalle istanze Cloud SQL
- Comprendere un esempio di flusso di lavoro di incorporamento
- Crea applicazioni basate su LLM utilizzando LangChain
- Gestire i dati utilizzando Cloud SQL Studio
- Scrivere SQL con l'assistenza di Gemini