Questa pagina mostra come utilizzare Cloud SQL per PostgreSQL per eseguire le seguenti azioni:
Genera e memorizza embedding vettoriali in base a un modello.
Esegui l'indicizzazione e le query sugli embedding utilizzando l'estensione
pgvector
.
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 significato semantico del testo dato da parte del modello come vettore numerico.
Cloud SQL implementa gli embedding 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 embedding Vertex AI con Cloud SQL, l'istanza deve trovarsi in una regione in cui generative AI foundational models are supported
.
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 embedding, installa l'estensione google_ml_integration
nell'istanza Cloud SQL. Per i modelli Vertex AI, installa la versione 1.2
o successiva. Per i modelli personalizzati o di terze parti, installa la versione 1.4.2
o successive.
Se vuoi memorizzare questi embedding e utilizzarli con funzioni e operatori vettoriali, devi disporre anche dell'estensione pgvector
.
Cloud SQL dispone di entrambe le estensioni. Puoi installarli su qualsiasi database della tua istanza. Per maggiori informazioni, consulta Configurare le estensioni PostgreSQL.
Configurare 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 utilizzare 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 embedding
Concedi agli utenti del database l'autorizzazione per utilizzare la funzione embedding
per eseguire le previsioni:
Connetti un client
psql
all'istanza principale, come descritto in Eseguire la connessione utilizzando 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
Genera embedding
Cloud SQL fornisce una funzione che consente di tradurre il testo in un embedding vettoriale. Puoi quindi archiviare l'embedding nel database come dati vettoriali e, facoltativamente, utilizzare le funzioni pgvector
per eseguire query.
Generare un'evidenziazione
Per generare un embedding utilizzando Cloud SQL, utilizza la funzione embedding()
fornita dall'estensione google_ml_integration
:
SELECT embedding( 'MODEL_IDVERSION_TAG', 'TEXT');
Apporta le seguenti sostituzioni:
MODEL_ID: l'ID del modello su cui eseguire la query.
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 embedding di testo. Per ulteriori informazioni, consulta Embedding di testo.VERSION_TAG (Facoltativo): il tag della versione del modello su cui eseguire la query. 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.TEXT: il testo da tradurre in un embedding 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 dalla 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];
Apporta le seguenti sostituzioni:
TABLE: il nome della tabella
EMBEDDING_COLUMN: il nome della nuova colonna di embedding
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 embedding, puoi completarla 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);
Apporta le seguenti sostituzioni:
TABLE: il nome della tabella.
EMBEDDING_COLUMN: il nome della colonna di embedding.
MODEL_ID: l'ID del modello su cui eseguire la query.
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 embedding di testo. Per ulteriori informazioni, consulta Embedding di testo.VERSION_TAG (Facoltativo): il tag della versione del modello su cui eseguire la query. 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. Traducete questo testo in embedding.
Il comando precedente funziona sia per le colonne di incorporamento real[]
sia per quelle vector
. Se la colonna di incorporamento è di tipo vector
, Cloud SQL esegue il casting del valore restituito di embedding()
da un array real
a un valore vector
in modo implicito.
L'esempio seguente utilizza il modello text-embedding-004
per compilare la colonna messages.message_vector
con gli embedding in base ai contenuti della colonna messages.message
:
UPDATE messages SET message_vector = embedding( 'text-embedding-004', message);
Esegui query e indici di 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 approssimativo tramite l'indicizzazione.
Per creare un indice basato su pgvector
con hnsw
come metodo di indicizzazione, utilizza il seguente esempio:
CREATE INDEX ON TABLE
USING hnsw (EMBEDDING_COLUMN DISTANCE_FUNCTION)
WITH (m = M, ef_construction = EF_CONSTRUCTION);
Apporta 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 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 in una colonna di incorporamento che utilizza il tipo di dati real[]
instead of vector
, esegui il casting 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 di ricerca del vicino più prossimo con un testo specificato
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 eseguire il casting 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
Apporta le seguenti sostituzioni:
RESULT_COLUMNS: le colonne da visualizzare dalle righe semanticamente simili.
TABLE: la tabella contenente l'embedding con cui confronti il testo.
EMBEDDING_COLUMN: la colonna contenente gli embedding archiviati.
MODEL_ID: l'ID del modello su cui eseguire la query.
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 embedding di testo. Per ulteriori informazioni, consulta Embedding 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 del modello.TEXT: il testo che ti interessa per trovare i vicini semantici memorizzati 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[]
instead of vector
, esegui il casting 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 delle versioni 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.
La chiamata alla funzione embedding()
senza specificare il tag della versione del
modello è valida dal punto di vista sintattico, 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. Potrebbe non essere l'ultima versione stabile. Per ulteriori informazioni sulle versioni dei modelli Vertex AI disponibili, consulta Versioni dei modelli.
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ò modificare bruscamente il vettore restituito per un determinato input. Ciò può causare errori o altri comportamenti imprevisti nelle applicazioni.
Per evitare questi problemi, specifica sempre la versione del modello.