Crea applicazioni di AI generativa utilizzando AlloyDB AI

Importante: per accedere agli URL elencati in questa pagina, devi connetterti a internet. Gli URL vengono forniti per l'accesso al di fuori dell'ambiente air-gap.

Questa sezione descrive come richiamare le previsioni ed eseguire query e indici di embedding utilizzando l'estensione pgvector. Queste funzioni di AI basate sul machine learning sono disponibili tramite AlloyDB AI, una suite di funzionalità di AlloyDB per PostgreSQL che ti consente di applicare la potenza semantica e predittiva dei modelli di machine learning (ML) ai tuoi dati.

Scopri di più su AlloyDB AI all'indirizzo https://cloud.google.com//alloydb/docs/ai.

Richiamare le previsioni

Per integrare Vertex AI con AlloyDB Omni ed eseguire previsioni sui modelli archiviati in Vertex AI, segui questi passaggi.

Prima di iniziare

1. Abilita le previsioni online di Vertex AI in GDC.

2. Crea un secret Kubernetes basato sulla chiave del account di servizio scaricata nei passaggi precedenti eseguendo questo comando. Assicurati di creare il secret Kubernetes nello stesso spazio dei nomi della risorsa DBCluster.

   kubectl create secret generic SECRET_NAME \
   --from-file=PATH_TO_SERVICE_ACCOUNT_KEY/private-key.json \
   -n NAMESPACE

   Sostituisci quanto segue:

   • SECRET_NAME: il nome del secret utilizzato quando crei un manifest DBCluster per consentire ad AlloyDB Omni di accedere alle funzionalità di Distributed Cloud AI. Ad esempio: vertex-ai-key-alloydb.

   • PATH_TO_SERVICE_ACCOUNT_KEY: il percorso della posizione in cui hai scaricato la chiave del account di servizio private-key.json.

   • NAMESPACE: lo spazio dei nomi del cluster di database.

3. Installa l'operatore AlloyDB Omni seguendo i passaggi elencati in Scegliere un tipo di motore del database e creare un cluster di database.

4. Crea un cluster di database con AlloyDB AI e imposta vertexAIKeyRef sul secret Kubernetes creato nei passaggi precedenti nel campo googleMLExtension del manifest DBCluster.

   apiVersion: v1
   kind: Secret
   metadata:
     name: db-pw-DBCLUSTER_NAME
     namespace: USER_PROJECT
   type: Opaque
   data:
     DBCLUSTER_NAME: "BASE64_PASSWORD"
   ---
   apiVersion: DBENGINE_NAME.dbadmin.gdc.goog/v1
   kind: DBCluster
   metadata:
     name: DBCLUSTER_NAME
     namespace: USER_PROJECT
   spec:
     primarySpec:
       adminUser:
         passwordRef:
           name: db-pw-DBCLUSTER_NAME
       features:
         googleMLExtension:
           config:
             vertexAIKeyRef: SECRET_NAME
       version: "DB_VERSION"
       resources:
         memory: DB_MEMORY
         cpu: DB_CPU
         disks:
         - name: DataDisk
           size: DB_DATA_DISK
   

   Sostituisci le seguenti variabili:

   • DBCLUSTER_NAME: il nome del cluster di database.
   • USER_PROJECT: il nome del progetto utente in cui verrà creato il cluster di database.
   • BASE64_PASSWORD: la codifica Base64 della password dell'amministratore del database.
   • DBENGINE_NAME: il nome del motore del database. Imposta su alloydbomni.
   • DB_VERSION: la versione del motore del database.
   • DB_MEMORY: la quantità di memoria allocata al cluster di database, ad esempio 5Gi.
   • DB_CPU: la quantità di CPU allocata al cluster di database, ad esempio 2.
   • DB_DATA_DISK: la quantità di spazio allocata al cluster di database, ad esempio 10 Gi.

   Applica il manifest.

   kubectl apply -f DB_CLUSTER_YAML

   Sostituisci quanto segue:

   • DB_CLUSTER_YAML: il nome di questo file manifest del cluster di database, ad esempio alloydb-omni-db-cluster.yaml.

5. Installa l'estensione google_ml_integration.

   CREATE EXTENSION google_ml_integration CASCADE;
   

Richiamare una previsione

Richiama una previsione online utilizzando un endpoint del modello Vertex AI eseguendo la seguente funzione SQL ml_predict_row():

  SELECT ml_predict_row('PREDICTION_ENDPOINT/PROJECT_NAMESPACE/ORGANIZATION/ZONE/DNS/DNS_SUFFIX', '{ "instances": [ INSTANCES ], "parameters":
  PARAMETERS');

Sostituisci quanto segue:

• PREDICTION_ENDPOINT: il nome completo dell'endpoint Vertex AI

• PROJECT_NAMESPACE: lo spazio dei nomi in cui viene eseguito il deployment dell'endpoint Vertex AI

• ORGANIZATION: il nome dell'organizzazione in cui viene eseguito il deployment dell'endpoint Vertex AI

• ZONE: la zona in cui viene eseguito il deployment dell'endpoint Vertex AI

• DNS: il DNS della tua organizzazione

• DNS_SUFFIX: il suffisso dell'oggetto DNS

• INSTANCES: gli input della chiamata di previsione, in formato JSON

• PARAMETERS: i parametri della chiamata di previsione, in formato JSON

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. AlloyDB fornisce ottimizzazioni per l'utilizzo di pgvector, che ti consentono di creare indici in grado di velocizzare determinate query che coinvolgono incorporamenti.

Scopri di più sull'utilizzo di AlloyDB come LLM e sulla generazione e l'archiviazione di incorporamenti vettoriali basati su un LLM all'indirizzo https://cloud.google.com/alloydb/docs/ai/work-with-embeddings#index.

Crea indici ed esegui query sui vettori utilizzando ScaNN

Questa sezione mostra come utilizzare gli embedding archiviati per generare indici ed eseguire query sugli embedding. Puoi creare indici ScaNN con AlloyDB.

Prima di iniziare

Prima di poter iniziare a creare indici, devi completare i seguenti prerequisiti.

• I vettori di incorporamento vengono aggiunti a una tabella nel tuo database AlloyDB.

• È installata la vectorversione dell'estensione 0.5.0 o successive basate su pgvector, estese da Google per AlloyDB.

  CREATE EXTENSION IF NOT EXISTS vector;
  

• Per generare gli indici ScaNN, installa l'estensione postgres_ann oltre all'estensione vector.

  CREATE EXTENSION IF NOT EXISTS postgres_ann;
  

Nota: l'estensione postgres_ann può essere utilizzata con database compatibili con PostgreSQL 14 e 15.

Crea un indice ScaNN

Puoi creare un ScaNNindice per le tabelle del database.

Nota: poiché i nomi degli indici sono condivisi nel database, crea un nome di indice univoco per ogni tabella del database.

AlloyDB postgres_ann, un'estensione PostgreSQL sviluppata da Google che implementa un indice dei vicini più vicini altamente efficiente basato sull'algoritmo ScaNN.

L'indice ScaNN è un indice di quantizzazione basato su albero per la ricerca approssimativa del vicino più prossimo. Offre un tempo di creazione dell'indice ridotto e un utilizzo di memoria minimo. Inoltre, fornisce QPS veloci in base al workload.

Nota :prima di creare un indice, assicurati di aggiungere i vettori di incorporamento a una tabella nel database Distributed Cloud. Se provi a generare un indice ScaNN su una tabella vuota o partizionata, potresti riscontrare alcuni problemi.

Indice ScaNN ad albero a due livelli

Per applicare un indice ad albero a due livelli utilizzando l'algoritmo ScaNN a una colonna contenente incorporamenti vettoriali archiviati, esegui la seguente query DDL:

CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE);

Sostituisci quanto segue:

• INDEX_NAME: il nome dell'indice che vuoi creare, ad esempio my-scann-index. I nomi degli indici sono condivisi nel database. Assicurati che ogni nome di indice sia univoco per ogni tabella del database.

• TABLE: la tabella a cui aggiungere 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: l2

  • Prodotto scalare: dot_product

  • Distanza coseno: cosine

• NUM_LEAVES_VALUE: il numero di partizioni da applicare a questo indice. Imposta un valore compreso tra 1 e 1048576.

Indice ScaNN ad albero a tre livelli

Per creare un indice ad albero a tre livelli utilizzando l'algoritmo ScaNN in una colonna contenente incorporamenti vettoriali archiviati, esegui la seguente query DDL:

CREATE INDEX INDEX_NAME ON TABLE
  USING scann (EMBEDDING_COLUMN DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = MAX_NUM_LEVELS);

Sostituisci quanto segue:

• MAX_NUM_LEVELS: il numero massimo di livelli dell'albero di clustering K-means. Imposta 1(valore predefinito) per la quantizzazione basata su albero a due livelli e 2 per la quantizzazione basata su albero a tre livelli.

Dopo aver creato l'indice, puoi eseguire query di ricerca del vicino più prossimo che utilizzano l'indice seguendo le istruzioni riportate in Eseguire una query del vicino più prossimo con un testo specifico.

I parametri dell'indice devono essere impostati in modo da trovare il giusto equilibrio tra QPS e richiamo.

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 INDEX_NAME ON TABLE
  USING scann (CAST(EMBEDDING_COLUMN AS vector(DIMENSIONS)) DISTANCE_FUNCTION)
  WITH (num_leaves=NUM_LEAVES_VALUE, max_num_levels = MAX_NUM_LEVELS);

Sostituisci DIMENSIONS con la larghezza dimensionale della colonna di incorporamento.

Per visualizzare l'avanzamento dell'indicizzazione, utilizza la visualizzazione pg_stat_progress_create_index:

SELECT * FROM pg_stat_progress_create_index;

La colonna phase mostra lo stato attuale della creazione dell'indice e la fase building index: tree training scompare dopo la creazione dell'indice.

Esegui una query

Dopo aver archiviato e indicizzato gli incorporamenti nel database, puoi iniziare a eseguire query utilizzando la funzionalità di query pgvector. Non puoi eseguire query di ricerca collettive utilizzando l'estensione postgres_ann.

Per trovare i vicini semantici più vicini per un vettore di incorporamento, puoi eseguire la seguente query di esempio, in cui imposti la stessa funzione di distanza che hai utilizzato durante la creazione dell'indice.

  SELECT * FROM TABLE
    ORDER BY EMBEDDING_COLUMN DISTANCE_FUNCTION_QUERY ['EMBEDDING']
    LIMIT ROW_COUNT

Sostituisci quanto segue:

• TABLE: la tabella contenente l'incorporamento a cui confrontare il testo.

• INDEX_NAME: il nome dell'indice che vuoi utilizzare, ad esempio my-scann-index.

• EMBEDDING_COLUMN: la colonna contenente gli incorporamenti memorizzati.

• DISTANCE_FUNCTION_QUERY: la funzione di distanza da utilizzare con questa query. Scegli una delle seguenti opzioni in base alla funzione di distanza utilizzata durante la creazione dell'indice:

  • Distanza L2: <->

  • Prodotto interno: <#>

  • Distanza coseno: <=>

• EMBEDDING: il vettore di embedding di cui vuoi trovare i vicini semantici memorizzati più vicini.

• ROW_COUNT: il numero di righe da restituire.

  Specifica 1 se vuoi solo la corrispondenza migliore.

Puoi anche utilizzare la funzione embedding() per tradurre il testo in un vettore. Applica il vettore a uno degli operatori pgvectornearest-neighbor, <-> per la distanza L2, per trovare le righe del database con gli incorporamenti semanticamente più simili. Tieni presente che per utilizzare questa funzione devi prima registrare il modello Gecko di incorporamento del testo.

Poiché embedding() restituisce un array real, devi eseguire il cast esplicito della chiamata embedding() a vector per utilizzare questi valori con gli operatori pgvector.

  CREATE EXTENSION google_ml_integration;
  CREATE EXTENSION IF NOT EXISTS vector;

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

Sostituisci quanto segue:

• MODEL_ID: l'ID del modello da interrogare.

  Se utilizzi Vertex AI Model Garden, specifica textembedding-gecko@003 come ID modello. Questi sono i modelli basati su cloud che Distributed Cloud può utilizzare per gli incorporamenti di testo.

• (Facoltativo) VERSION_TAG: il tag della versione del modello per cui eseguire la query. Aggiungi il prefisso @ al tag.

  Se utilizzi uno dei modelli in inglese textembedding-gecko con Vertex AI, specifica uno dei tag di versione, ad esempio textembedding-gecko@003.

  Google consiglia vivamente di specificare sempre il tag della versione. Se non specifichi il tag della versione, AlloyDB utilizza sempre l'ultima versione del modello, il che potrebbe portare a risultati imprevisti.

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

Metriche dell'indice vettoriale

Questa sezione elenca le metriche relative agli indici vettoriali generati in AlloyDB. Puoi visualizzare queste metriche utilizzando la visualizzazione pg_stat_ann_indexes disponibile quando installi l'postgres_annestensione.

Metriche di usabilità

Le metriche di usabilità includono metriche che ti aiutano a comprendere lo stato di utilizzo dell'indice con metriche quali la configurazione dell'indice e il numero di scansioni dell'indice.

Nome metrica	Tipo di dati	Descrizione
relid	OID	Identificatore univoco della tabella che contiene l'indice vettoriale.
indexrelid	OID	Identificatore univoco dell'indice vettoriale.
schemaname	NAME	Nome dello schema a cui appartiene l'indice.
relname	NAME	Nome della tabella contenente l'indice.
indexrelname	NAME	Nome dell'indice.
indextype	NAME	Tipo di indice. Questo valore è sempre impostato su postgres_ann.
indexconfig	TEXT[]	Configurazione, ad esempio conteggio delle foglie e quantizzatore, definita per l'indice al momento della creazione.
indexsize	TEXT	Dimensioni dell'indice.
indexscan	BIGINT	Numero di scansioni dell'indice avviate sull'indice.

Metriche di ottimizzazione

Le metriche di ottimizzazione forniscono informazioni sull'ottimizzazione corrente dell'indice, consentendoti di applicare i suggerimenti per migliorare le prestazioni delle query.

Nome metrica	Tipo di dati	Descrizione
insertcount	BIGINT	Numero di operazioni di inserimento nell'indice. Questa metrica include anche un numero qualsiasi di righe esistenti prima della creazione dell'indice.
updatecount	BIGINT	Numero di operazioni di aggiornamento sull'indice. Questa metrica non tiene conto di eventuali aggiornamenti HOT.
deletecount	BIGINT	Numero di operazioni di eliminazione sull'indice.
distribution	JSONB	Distribuzioni dei vettori in tutte le partizioni dell'indice. I seguenti campi mostrano la distribuzione: maximum (INT8): Numero massimo di vettori in tutte le partizioni. minimum (INT8): Numero minimo di vettori in tutte le partizioni. average (FLOAT) : numero medio di vettori in tutte le partizioni. outliers (INT8[]): I valori anomali principali in tutte le partizioni. Questo valore mostra i 20 valori anomali principali. Nota:a causa delle caratteristiche intrinseche dell'algoritmo di clustering K-means, ci sarà sempre un certo grado di varianza nella distribuzione dei vettori tra le partizioni, anche quando l'indice viene creato inizialmente.

Suggerimento di ottimizzazione basato sulle metriche

Mutazione

Le metriche insertcount, updatecount e deletecount mostrano insieme le modifiche o le mutazioni nel vettore per l'indice.

L'indice viene creato con un numero specifico di vettori e partizioni. Quando vengono eseguite operazioni come inserimento, aggiornamento o eliminazione sull'indice vettoriale, queste influiscono solo sul set iniziale di partizioni in cui risiedono i vettori. Di conseguenza, il numero di vettori in ogni partizione varia nel tempo, il che potrebbe influire sul richiamo, sulle QPS o su entrambi.

Se nel tempo riscontri problemi di lentezza o precisione, ad esempio QPS basso o scarso richiamo, nelle query di ricerca ANN, valuta la possibilità di esaminare queste metriche. Un numero elevato di mutazioni rispetto al numero totale di vettori potrebbe indicare la necessità di reindicizzazione.

Distribuzione

La metrica distribution mostra le distribuzioni dei vettori in tutte le partizioni.

Quando crei un indice, questo viene creato con un numero specifico di vettori e partizioni fisse. Il processo di partizionamento e la successiva distribuzione avvengono in base a questa considerazione. Se vengono aggiunti altri vettori, questi vengono partizionati tra le partizioni esistenti, il che comporta una distribuzione diversa rispetto a quella al momento della creazione dell'indice. Poiché la distribuzione finale non considera tutti i vettori contemporaneamente, il richiamo, le QPS o entrambi potrebbero essere interessati.

Se noti un calo graduale del rendimento delle query di ricerca ANN, ad esempio tempi di risposta più lenti o una riduzione dell'accuratezza dei risultati (misurata in QPS o richiamo), valuta la possibilità di controllare questa metrica e di eseguire nuovamente l'indicizzazione.