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, vedi Creare applicazioni di AI 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
. Questo
consente di utilizzare le metriche
incorporamenti come input per le funzioni di estensione di pgvector
.
Prima di iniziare
Alcuni requisiti variano a seconda che si voglia utilizzare a Cloud SQL per generare incorporamenti o se devi solo lavorare con gli incorporamenti archiviati nel 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 ha entrambe le estensioni. Puoi installarle 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 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 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 a utilizzare embedding
per eseguire previsioni:
Connetti un client
psql
all'istanza principale, come descritto in Connettiti 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 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 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.
Genera un incorporamento
Per generare un incorporamento mediante Cloud SQL, utilizza embedding()
funzione 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 usi lo strumento Vertex AI Model Garden e specificare
text-embedding-004
otext-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 da 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, 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 incorporamento in base a una stringa letterale fornita:
SELECT embedding( 'text-embedding-004', '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 che il modello Google Cloud.
Se utilizzi uno dei modelli
text-embedding
otextembedding-gecko
con Vertex AI, quindi specifica768
.
Facoltativamente, se hai installato l'estensione pgvector
, puoi:
Archivia 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
otext-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 da 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, quindi specifica uno dei tag di versione elencate in Versioni modello.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 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 incorporamenti utilizzando pgvector
L'estensione PostgreSQL pgvector
ti consente di utilizzare funzioni e operatori specifici del vettore
quando archivi, indicizzi ed esegui query sul testo
incorporamenti nel tuo database. Cloud SQL ha le proprie ottimizzazioni
per lavorare con pgvector
, consentendoti 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 quantizzazione scalare
caratteristica che puoi specificare quando crei un indice. Quando abiliti questa funzione, il valore scalare
la quantizzazione può accelerare le query che hanno dimensioni
vettori di rete. 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
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. Scegli 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 database, l'intera gamma
pgvector
query
funzionalità
a tua disposizione.
Per trovare i vicini semantici più vicini a una porzione di testo, usa
la funzione embedding()
per tradurre il testo in un vettore. Nella stessa query,
applica questo vettore all'operatore del vicino più prossimo pgvector
, <->
, 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 semanticamente righe simili.
TABLE: la tabella contenente l'incorporamento con cui confronti i testo.
EMBEDDING_COLUMN: la colonna contenente gli incorporamenti archiviati.
MODEL_ID: l'ID del modello su cui eseguire la query.
Se usi lo strumento Vertex AI Model Garden e specificare
text-embedding-004
otext-embedding-multilingual-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 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 di incorporamento scelto. Per la maggior parte dei modelli, significa impostare in modo esplicito un tag di versione.
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, poi Vertex AI utilizza la versione più recente del modello. Questa versione 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 lo stesso
Risposta embedding()
a un determinato input di testo. Se non specifichi il modello
versioni successive nelle tue chiamate a embedding()
, poi un nuovo modello pubblicato
può modificare 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.