Installazione e configurazione di Toolbox per le tue applicazioni di IA generativa e agenti su AlloyDB

1. Panoramica

Gen AI Toolbox for Databases è un server open source di Google che semplifica la creazione di strumenti di AI generativa per interagire con i database. Ti consente di sviluppare strumenti in modo più semplice, rapido e sicuro gestendo complessità come il pooling delle connessioni, l'autenticazione e altro ancora. Ti aiuta a creare strumenti di IA generativa che consentono ai tuoi agenti di accedere ai dati nel tuo database. Toolbox fornisce:

Sviluppo semplificato:integra gli strumenti nell'agente in meno di 10 righe di codice, riutilizza gli strumenti tra più agenti o framework e esegui più facilmente il deployment di nuove versioni degli strumenti.

Migliore rendimento:best practice come il pooling delle connessioni, l'autenticazione e altro ancora.

Maggiore sicurezza:autenticazione integrata per un accesso più sicuro ai tuoi dati.

Osservabilità end-to-end:metriche e monitoraggio out-of-the-box con il supporto integrato di OpenTelemetry.

Toolbox si trova tra il framework di orchestrazione dell'applicazione e il database e fornisce un piano di controllo utilizzato per modificare, distribuire o richiamare gli strumenti. Semplifica la gestione degli strumenti fornendoti un luogo centralizzato per archiviarli e aggiornarli, consentendoti di condividerli tra agenti e applicazioni e di aggiornarli senza necessariamente eseguire nuovamente il deployment dell'applicazione.

Cosa creerai

Nell'ambito di questo lab, creerai un'applicazione che utilizza uno strumento per eseguire una semplice query sul database (AlloyDB) che può essere richiamata dall'agente o dall'applicazione di IA generativa. A questo scopo, dovrai

  1. Installare Toolbox
  2. Configura lo strumento (disponibile per eseguire un'attività in AlloyDB) sul server Toolbox
  3. Esegui il deployment di Toolbox su Cloud Run
  4. Testare lo strumento con l'endpoint Cloud Run di cui è stato eseguito il deployment
  5. Crea la funzione Cloud Run per richiamare la cassetta degli attrezzi

Requisiti

  • Un browser, ad esempio Chrome o Firefox
  • Un progetto Google Cloud con la fatturazione abilitata (passaggi nella sezione successiva).

2. Prima di iniziare

Crea un progetto

  1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
  2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è attivata in un progetto.
  3. Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione in Google Cloud. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.

Immagine del pulsante Attiva Cloud Shell

  1. Una volta connesso a Cloud Shell, controlla se hai già eseguito l'autenticazione e se il progetto è impostato sull'ID progetto corretto utilizzando il seguente comando:
gcloud auth list
  1. Esegui il seguente comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.
gcloud config list project
  1. Se il progetto non è impostato, utilizza il seguente comando per impostarlo:
gcloud config set project <YOUR_PROJECT_ID>
  1. Abilita le API richieste eseguendo uno alla volta i seguenti comandi nel terminale Cloud Shell:

Esiste anche un singolo comando per eseguire quanto segue, ma se sei un utente con un account di prova, potresti riscontrare problemi di quota durante l'attivazione collettiva. Per questo motivo, i comandi vengono evidenziati uno per riga.

gcloud services enable alloydb.googleapis.com
gcloud services enable compute.googleapis.com 
gcloud services enable cloudresourcemanager.googleapis.com 
gcloud services enable servicenetworking.googleapis.com 
gcloud services enable run.googleapis.com 
gcloud services enable cloudbuild.googleapis.com 
gcloud services enable cloudfunctions.googleapis.com 
gcloud services enable aiplatform.googleapis.com

L'alternativa al comando gcloud è tramite la console cercando ciascun prodotto o utilizzando questo link.

Se manca un'API, puoi sempre attivarla durante l'implementazione.

Consulta la documentazione per i comandi e l'utilizzo di gcloud.

3. Configurazione del database

In questo lab utilizzeremo AlloyDB come database per memorizzare i dati di vendita al dettaglio. Utilizza i cluster per contenere tutte le risorse, come database e log. Ogni cluster ha un'istanza principale che fornisce un punto di accesso ai dati. Le tabelle conterranno i dati effettivi.

Creiamo un cluster, un'istanza e una tabella AlloyDB in cui verrà caricato il set di dati di e-commerce.

Crea un cluster e un'istanza

  1. Esplora la pagina AlloyDB nella console Cloud.

Un modo semplice per trovare la maggior parte delle pagine in Cloud Console è cercarle utilizzando la barra di ricerca della console.

  1. Seleziona CREA CLUSTER da questa pagina:

f76ff480c8c889aa.png

  1. Viene visualizzata una schermata come quella riportata di seguito. Crea un cluster e un'istanza con i seguenti valori (assicurati che i valori corrispondano nel caso in cui stia clonando il codice dell'applicazione dal repository):
  • cluster id: "vector-cluster"
  • password: "alloydb"
  • Compatibile con PostgreSQL 15
  • Regione: "us-central1"
  • Networking: "default"

538dba58908162fb.png

  1. Quando selezioni la rete predefinita, viene visualizzata una schermata come quella riportata di seguito. Seleziona CONFIGURA CONNESSIONE.
    7939bbb6802a91bf.png
  2. Da qui, seleziona "Utilizza un intervallo IP allocato automaticamente" e Continua. Dopo aver esaminato le informazioni, seleziona CREA CONNESSIONE. 768ff5210e79676f.png
  3. Una volta configurata la rete, puoi continuare a creare il cluster. Fai clic su CREA CLUSTER per completare la configurazione del cluster come mostrato di seguito:

e06623e55195e16e.png

Assicurati di modificare l'ID istanza in "

vector-instance"

.

Tieni presente che la creazione del cluster richiede circa 10 minuti. Al termine dell'operazione, dovresti visualizzare una schermata che mostra la panoramica del cluster appena creato.

4. Importazione dati

Ora è il momento di aggiungere una tabella con i dati del negozio. Vai ad AlloyDB, seleziona il cluster principale e poi AlloyDB Studio:

847e35f1bf8a8bd8.png

Potresti dover attendere il completamento della creazione dell'istanza. Al termine, accedi ad AlloyDB utilizzando le credenziali che hai creato durante la creazione del cluster. Utilizza i seguenti dati per l'autenticazione in PostgreSQL:

  • Nome utente : "postgres"
  • Database : "postgres"
  • Password : "alloydb"

Dopo aver eseguito l'autenticazione in AlloyDB Studio, puoi inserire i comandi SQL nell'editor. Puoi aggiungere più finestre di Editor utilizzando il segno Più a destra dell'ultima finestra.

91a86d9469d499c4.png

Puoi inserire comandi per AlloyDB nelle finestre dell'editor, utilizzando le opzioni Esegui, Formatta e Cancella in base alle esigenze.

Attivare le estensioni

Per creare questa app, utilizzeremo le estensioni pgvector e google_ml_integration. L'estensione pgvector ti consente di archiviare e cercare gli incorporamenti vettoriali. L'estensione google_ml_integration fornisce le funzioni che utilizzi per accedere agli endpoint di previsione di Vertex AI per ottenere le previsioni in SQL. Attiva queste estensioni eseguendo i seguenti DDL:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;

Se vuoi controllare le estensioni che sono state attivate nel tuo database, esegui questo comando SQL:

select extname, extversion from pg_extension;

Creare una tabella

Crea una tabella utilizzando l'istruzione DDL riportata di seguito:

CREATE TABLE toys ( id VARCHAR(25), name VARCHAR(25), description VARCHAR(20000), quantity INT, price FLOAT, image_url VARCHAR(200), text_embeddings vector(768)) ;

Se l'esecuzione del comando precedente è andata a buon fine, dovresti essere in grado di visualizzare la tabella nel database.

Importa i dati

Per questo lab, abbiamo dati di test di circa 72 record in questo file SQL. Contiene i campi id, name, description, quantity, price, image_url. Gli altri campi verranno compilati più avanti nel lab.

Copia le righe/le istruzioni insert da lì, poi incollale in una scheda dell'editor vuota e seleziona ESEGUI.

Per visualizzare i contenuti della tabella, espandi la sezione Esplora fino a visualizzare la tabella denominata abbigliamento. Seleziona i tre puntini (⋮) per visualizzare l'opzione per eseguire una query sulla tabella. In una nuova scheda dell'editor si aprirà un'istruzione SELECT.

cfaa52b717f9aaed.png

Concedi autorizzazione

Esegui la seguente istruzione per concedere all'utente postgres i diritti di esecuzione sulla funzione embedding:

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Concedi il RUOLO Utente Vertex AI all'account di servizio AlloyDB

Vai al terminale Cloud Shell ed esegui il seguente comando:

PROJECT_ID=$(gcloud config get-value project)

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
--role="roles/aiplatform.user"

5. Crea gli incorporamenti per il contesto

Per i computer è molto più facile elaborare numeri che testo. Un sistema di embedding converte il testo in una serie di numeri in virgola mobile, chiamati vector embedding, che dovrebbero rappresentare il testo, indipendentemente dalla formulazione, dalla lingua utilizzata e così via.

Ad esempio, una località sul mare potrebbe essere chiamata "on the water", "beachfront", "walk from your room to the ocean", "sur la mer", "на берегу океана" e così via. Questi termini sembrano tutti diversi, ma il loro significato semantico o, nella terminologia del machine learning, i relativi embedding dovrebbero essere molto vicini tra loro.

Ora che i dati e il contesto sono pronti, eseguiremo il codice SQL per aggiungere gli embedding della descrizione del prodotto alla tabella nel campo embedding. Esistono diversi modelli di embedding che puoi utilizzare. Utilizziamo text-embedding-005 di Vertex AI. Assicurati di utilizzare lo stesso modello di embedding in tutto il progetto.

Nota: se utilizzi un vecchio progetto Google Cloud, potresti dover continuare a utilizzare versioni precedenti del modello di embedding del testo, come textembedding-gecko.

Torna alla scheda AlloyDB Studio e digita il seguente DML:

UPDATE toys set text_embeddings = embedding( 'text-embedding-005', description);

Esamina di nuovo la tabella toys per vedere alcuni embedding. Assicurati di eseguire di nuovo l'istruzione SELECT per visualizzare le modifiche.

SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;

Dovrebbe restituire il vettore di embedding, che ha la forma di un array di valori float, per la descrizione del giocattolo, come mostrato di seguito:

7d32f7cd7204e1f3.png

Nota:i progetti Google Cloud appena creati nel livello senza costi potrebbero riscontrare problemi di quota per quanto riguarda il numero di richieste di incorporamento consentite al secondo per i modelli di incorporamento. Ti consigliamo di utilizzare una query di filtro per l'ID e di scegliere in modo selettivo 1-5 record e così via durante la generazione dell'embedding.

6. Eseguire la ricerca vettoriale

Ora che la tabella, i dati e gli embedding sono pronti, eseguiamo la ricerca di vettori in tempo reale per il testo di ricerca dell'utente.

Supponiamo che l'utente chieda:

"I want a white plush teddy bear toy with a floral pattern."

Puoi trovare corrispondenze per questo eseguendo la query riportata di seguito:

select * from toys
ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', 'I want a white plush teddy bear toy with a floral pattern') as vector(768))
LIMIT 5;

Esaminiamo questa query in dettaglio:

In questa query,

  1. Il testo di ricerca dell'utente è: "I want a white plush teddy bear toy with a floral pattern."
  2. Lo stiamo convertendo in embedding nel metodo embedding() utilizzando il modello: text-embedding-005. Questo passaggio dovrebbe essere simile all'ultimo, in cui abbiamo applicato la funzione di incorporamento a tutti gli elementi della tabella.
  3. "<=>" indica l'utilizzo del metodo di distanza COSINE SIMILARITY. Puoi trovare tutte le misure di somiglianza disponibili nella documentazione di pgvector.
  4. Stiamo convertendo il risultato del metodo di embedding in tipo di vettore per renderlo compatibile con i vettori archiviati nel database.
  5. LIMIT 5 indica che vogliamo estrarre 5 vicini più prossimi per il testo di ricerca.

Il risultato sarà simile al seguente:

fa7f0fc3a4c68804.png

Come puoi notare nei risultati, le corrispondenze sono molto simili al testo di ricerca. Prova a cambiare il testo per vedere come cambiano i risultati.

7. Preparare AlloyDB per l'interazione con la cassetta degli attrezzi

In preparazione alla configurazione di Toolbox, abilitiamo la connettività IP pubblico nella nostra istanza AlloyDB in modo che il nuovo strumento possa accedere al database.

  1. Vai all'istanza AlloyDB, fai clic su MODIFICA e vai alla pagina Modifica istanza principale.
  2. Vai alla sezione Connettività IP pubblico, seleziona la casella di controllo Abilita IP pubblico e inserisci l'indirizzo IP della tua macchina Cloud Shell.
  3. Per ottenere l'IP della tua macchina Cloud Shell, vai al terminale Cloud Shell e inserisci ifconfig. Dal risultato, identifica l'indirizzo inet eth0 e sostituisci le ultime 2 cifre con 0.0 con una dimensione della maschera "/16". Ad esempio, avrà il seguente aspetto: "XX.XX.0.0/16", dove XX sono numeri.
  4. Incolla questo IP nella casella di testo "Reti" delle reti esterne autorizzate della pagina di modifica dell'istanza.

5f6e60e8dec2cea1.png

  1. Al termine, fai clic su AGGIorna istanza.

Il completamento dell'operazione richiede alcuni minuti.

8. Installazione della cassetta degli attrezzi

  1. Puoi creare una cartella del progetto per archiviare i dettagli dello strumento. In questo caso, poiché stiamo lavorando con i dati del negozio di giocattoli, creiamo una cartella denominata "negozio di giocattoli" ed entriamo al suo interno. Vai a Cloud Shell Terminal e assicurati che il progetto sia selezionato e visualizzato nel prompt del terminale. Esegui il comando seguente dal terminale Cloud Shell:
mkdir toystore

cd toystore
  1. Esegui il comando seguente per scaricare e installare Toolbox nella nuova cartella:
# see releases page for other versions
export VERSION=0.1.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
  1. Passa all'editor di Cloud Shell. Espandi la cartella "negozio di giocattoli" appena creata e crea un nuovo file denominato tools.yaml. Copia i contenuti di seguito. Sostituisci YOUR_PROJECT_ID e controlla se tutti gli altri dettagli di connessione sono corretti.
sources:
    alloydb-toys:
        kind: "alloydb-postgres"
        project: "YOUR_PROJECT_ID"
        region: "us-central1"
        cluster: "vector-cluster"
        instance: "vector-instance"
        database: "postgres"
        user: "postgres"
        password: "alloydb"

tools:
  get-toy-price:
    kind: postgres-sql
    source: alloydb-toys
    description: Get the price of a toy based on a description.
    parameters:
      - name: description
        type: string
        description: A description of the toy to search for.
    statement: |
      SELECT price FROM toys
      ORDER BY text_embeddings <=> CAST(embedding('text-embedding-005', $1) AS vector(768))
      LIMIT 1;

In questo strumento, cerchiamo semplicemente la corrispondenza più simile al testo di ricerca dell'utente (descrizione del giocattolo personalizzato) e ne restituiamo il prezzo. Puoi anche modificarlo per trovare il prezzo medio dei 5 giocattoli più corrispondenti:

select avg(price) from ( SELECT price FROM toys ORDER BY text_embeddings <=> CAST(embedding(‘text-embedding-005', $1) AS vector(768)) LIMIT 5 ) as price;

La definizione dello strumento è completata.

Per ulteriori dettagli sulla configurazione di tools.yaml, consulta questa documentazione.

  1. Passa al terminale Cloud Shell e inserisci il seguente comando per avviare il server della cassetta degli attrezzi con la configurazione degli strumenti:
./toolbox --tools_file "tools.yaml"
  1. Ora, se apri il server in una modalità di anteprima web sul cloud, dovresti riuscire a vedere il server Toolbox in esecuzione con il nuovo strumento denominato get-toy-price.

9. Deployment di Toolbox in Cloud Run

Eseguiamo il deployment su Cloud Run in modo che tu possa utilizzare questo strumento.

  1. Segui le istruzioni riportate in questa pagina una alla volta fino a raggiungere il comando gcloud run deploy toolbox nel terzo punto della sezione "Esegui il deployment in Cloud Run". Devi utilizzare la prima opzione e non la seconda, che è pensata per quando utilizzi un metodo di rete VPC.
  2. Una volta completato il deployment, riceverai un endpoint di Cloud Run di cui è stato eseguito il deployment del server Toolbox. Testa con un comando CURL.

Ora puoi utilizzare lo strumento appena disegnato nella tua applicazione di agenzia.

10. Collegare l'app a Toolbox

In questa parte, creeremo una piccola applicazione per testare lo strumento in modo che interagisca con le esigenze dell'applicazione e ne recuperi la risposta.

  1. Vai a Google Colab e apri un nuovo blocco note.
  2. Esegui quanto segue nel tuo notebook
pip install toolbox-langchain
from toolbox_langchain import ToolboxClient

# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
tool = toolbox.load_tool("get-toy-price")

# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})

# Print result
print(result)
  1. Dovresti ottenere il seguente risultato:

5074f209a86c4f15.png

Questo è lo strumento invocato esplicitamente in un'applicazione Python che utilizza il toolkit toolbox-langchain.

  1. Se vuoi utilizzare questo strumento e associarlo a un agente all'interno di un'applicazione integrata di LangGraph, puoi farlo facilmente con il toolkit langgraph.
  2. Per questo, consulta gli snippet di codice.

11. Passa al cloud.

Inglobiamo questo snippet di codice Python in una funzione Cloud Run per renderlo serverless.

  1. Copia il codice sorgente dalla cartella del repository del codice per importarlo in Cloud Functions.
  2. Vai alla console Cloud Run Functions e fai clic su CREA FUNZIONE.
  3. Mantieni l'autenticazione non attiva per l'applicazione di dimostrazione e seleziona il runtime di Python 3.11 nella pagina successiva.
  4. Copia i file main.py e requirements.txt dal repository di origine condiviso nel passaggio 1 e incollali nei rispettivi file.
  5. Esegui il deployment della funzione e avrai un endpoint REST per lo strumento di previsione dei prezzi a cui accedere nell'applicazione web del negozio di giocattoli.
  6. L'endpoint dovrebbe avere il seguente aspetto:

https://us-central1-*****.cloudfunctions.net/toolbox-toys

  1. Puoi testarlo direttamente nella console Cloud Functions andando alla scheda TESTING e inserendo quanto segue come input della richiesta:

{

               "`search`"`:` "`White plush toy`"

}

  1. Fai clic su TESTA LA FUNZIONE o esegui nel terminale Cloud Shell ciò che scegli di utilizzare. Dovresti vedere il risultato a destra sotto il titolo "Output":

d7ba57cf5e5ca553.png

12. Complimenti

Complimenti! Hai creato uno strumento solido e veramente modulare che può interagire con database, piattaforme e framework di orchestrazione dell'IA generativa per aiutarti a creare la tua applicazione agente.