Informazioni su questo codelab
1. Panoramica
MCP Toolbox for Databases è un server open source di Google che semplifica la creazione di strumenti di IA generativa per l'interazione 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 nel tuo agente in meno di 10 righe di codice, riutilizza gli strumenti tra più agenti o framework ed esegui più facilmente il deployment di nuove versioni degli strumenti.
Prestazioni migliori: best practice come pooling di connessioni, autenticazione e altro ancora.
Sicurezza avanzata:autenticazione integrata per un accesso più sicuro ai dati.
Osservabilità end-to-end: metriche e tracciamento pronti all'uso con supporto integrato per 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 in cui 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 dal tuo agente o dall'applicazione di IA generativa. A questo scopo
- Installa gli strumenti MCP per i database
- Configurare lo strumento (progettato per eseguire un'attività in AlloyDB) sul server degli strumenti
- Esegui il deployment degli strumenti MCP per i database su Cloud Run
- Testa lo strumento con il relativo endpoint Cloud Run di cui è stato eseguito il deployment
- Crea la funzione Cloud Run per richiamare gli Strumenti
Requisiti
2. Prima di iniziare
Crea un progetto
- Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
- Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come controllare se la fatturazione è abilitata per un progetto.
- Utilizzerai Cloud Shell, un ambiente a riga di comando in esecuzione su Google Cloud. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
- Dopo aver eseguito la connessione a Cloud Shell, controlla se hai già eseguito l'autenticazione e se il progetto è impostato sull'ID progetto corretto utilizzando il comando seguente:
gcloud auth list
- Esegui il seguente comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.
gcloud config list project
- Se il progetto non è impostato, utilizza il seguente comando per impostarlo:
gcloud config set project <YOUR_PROJECT_ID>
- Abilita le API richieste eseguendo i comandi seguenti uno alla volta nel terminale Cloud Shell:
Esiste anche un unico comando per eseguire il comando riportato di seguito, ma se sei un utente con account di prova, potresti riscontrare problemi di quota durante l'attivazione collettiva. Ecco perché i comandi vengono selezionati 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 ogni 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 contenere i dati di retail. 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 contengono 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
- Naviga nella pagina AlloyDB nella console Cloud.
Un modo semplice per trovare la maggior parte delle pagine nella console Cloud è cercarle utilizzando la barra di ricerca della console.
- Seleziona CREA CLUSTER da quella pagina:
- Verrà 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 tu stia clonando il codice dell'applicazione dal repository:
- ID cluster: "
vector-cluster" - password: "
alloydb" - Compatibile con PostgreSQL 15
- Regione: "
us-central1" - Networking: "
default"
- Quando selezioni la rete predefinita, viene visualizzata una schermata come quella riportata di seguito. Seleziona CONFIGURA CONNESSIONE.
- Da qui, seleziona "Utilizza un intervallo IP allocato automaticamente" e Continua. Dopo aver esaminato le informazioni, seleziona CREA CONNESSIONE.
- Dopo aver configurato la rete, puoi continuare a creare il cluster. Fai clic su CREA CLUSTER per completare la configurazione del cluster come mostrato di seguito:
Assicurati di modificare l'ID istanza in "
vector-instance"
.
Tieni presente che la creazione del cluster richiederà circa 10 minuti. Una volta riuscito, dovresti vedere una schermata che mostra la panoramica del cluster appena creato.
4. Importazione dati
A questo punto devi aggiungere una tabella con i dati relativi al datastore. Passa ad AlloyDB, seleziona il cluster principale e poi AlloyDB Studio:
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"
Una volta completata l'autenticazione in AlloyDB Studio, puoi inserire i comandi SQL nell'editor. Puoi aggiungere più finestre dell'Editor utilizzando il segno più a destra dell'ultima finestra.
Puoi inserire comandi per AlloyDB nelle finestre dell'editor, utilizzando le opzioni Esegui, Formato e Cancella in base alle tue esigenze.
Attiva le estensioni
Per creare questa app, utilizzeremo le estensioni pgvector e google_ml_integration. L'estensione pgvector ti consente di archiviare e cercare incorporamenti vettoriali. L'estensione google_ml_integration fornisce le funzioni che puoi utilizzare per accedere agli endpoint di previsione di Vertex AI per ottenere 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;
Per verificare le estensioni abilitate nel 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)) ;
Una volta eseguita correttamente il comando precedente, dovresti essere in grado di visualizzare la tabella nel database.
Importa i dati
Per questo lab, abbiamo i dati di test su 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 istruzioni di riga/insert da lì, quindi incollale in una scheda dell'editor vuota e seleziona ESEGUI.
Per vedere i contenuti della tabella, espandi la sezione Explorer fino a quando non vedi la tabella denominata "Apparels". Seleziona il triplo (⋮) per vedere l'opzione per eseguire query sulla tabella. Un'istruzione SELECT verrà aperta in una nuova scheda Editor.
Concedi autorizzazione
Esegui la seguente istruzione per concedere i diritti di esecuzione sulla funzione embedding all'utente postgres:
GRANT EXECUTE ON FUNCTION embedding TO postgres;
Concedi il RUOLO utente Vertex AI all'account di servizio AlloyDB
Vai al terminale Cloud Shell e fornisci questo 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 incorporamenti per il contesto
Per i computer è molto più facile elaborare i numeri che elaborare il testo. Un sistema di incorporamento converte il testo in una serie di numeri in virgola mobile, chiamati incorporamenti vettoriali, che dovrebbero rappresentare il testo, indipendentemente dalla loro formulazione, dal linguaggio utilizzato e così via.
Ad esempio, una località balneare potrebbe essere chiamata "sull'acqua", "spiaggia", "passeggia dalla tua stanza all'oceano", "sur la mer", "Mancano solo alla corrente", e così via. Questi termini sono tutti diversi, ma il loro significato semantico o, nella terminologia di machine learning, deve essere molto vicino.
Ora che i dati e il contesto sono pronti, eseguiamo l'SQL per aggiungere gli incorporamenti della descrizione del prodotto alla tabella nel campo embedding. Puoi utilizzare diversi modelli di incorporamento. Stiamo utilizzando text-embedding-005 di Vertex AI. Assicurati di utilizzare lo stesso modello di incorporamento in tutto il progetto.
Nota: se utilizzi un vecchio progetto Google Cloud, potresti dover continuare a utilizzare le versioni precedenti del modello di incorporamento 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);
Osserva di nuovo la tabella toys per vedere alcuni incorporamenti. Assicurati di eseguire di nuovo l'istruzione SELECT per vedere le modifiche.
SELECT id, name, description, price, quantity, image_url, text_embeddings FROM toys;
Per la descrizione del giocattolo, come mostrato di seguito, dovrebbe essere restituito il vettore degli incorporamenti, simile a un array di elementi mobili:
Nota:i progetti Google Cloud appena creati con il livello senza costi potrebbero riscontrare problemi di quota in relazione al numero di richieste di incorporamento consentite al secondo ai modelli di incorporamento. Ti suggeriamo di utilizzare una query di filtro per l'ID, quindi di scegliere selettivamente 1-5 record e così via, generando al contempo l'incorporamento.
6. Esegui la ricerca vettoriale
Ora che tabella, dati e incorporamenti sono pronti, eseguiamo la ricerca vettoriale in tempo reale per il testo della 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 errore eseguendo la query seguente:
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;
Diamo un'occhiata a questa query in dettaglio:
In questa query,
- Il testo di ricerca dell'utente è: "
I want a white plush teddy bear toy with a floral pattern." - Lo stiamo convertendo in incorporamenti nel metodo
embedding()utilizzando il modello:text-embedding-005. Questo passaggio dovrebbe risultare familiare dopo l'ultimo, in cui abbiamo applicato la funzione di incorporamento a tutti gli elementi della tabella. - "
<=>" rappresenta l'utilizzo del metodo di distanza COSINE SIMILARITY. Tutte le misure di somiglianza sono disponibili nella documentazione di pgvector. - Stiamo convertendo il risultato del metodo di incorporamento in tipo vettoriale per renderlo compatibile con i vettori memorizzati nel database.
- LIMITE 5 indica che vogliamo estrarre i 5 vicini più prossimi per il testo di ricerca.
Il risultato ha questo aspetto:
Come puoi notare nei risultati, le corrispondenze sono molto simili al testo di ricerca. Prova a modificare il testo per vedere come cambiano i risultati.
7. Preparazione di AlloyDB per l'interazione con gli strumenti
In preparazione per la configurazione di Toolbox, abilitiamo la connettività con IP pubblico nella nostra istanza AlloyDB in modo che il nuovo strumento possa accedere al database.
- Vai all'istanza AlloyDB, fai clic su MODIFICA e accedi alla pagina Modifica istanza principale.
- Vai alla sezione Connettività con IP pubblico, seleziona la casella di controllo Abilita IP pubblico e inserisci l'indirizzo IP della tua macchina Cloud Shell.
- Per ottenere il tuo IP della tua macchina Cloud Shell, vai al terminale Cloud Shell e inserisci ifconfig. Dal risultato identificare l'indirizzo eth0 inet e sostituire le ultime 2 cifre con 0,0 con una dimensione di maschera '/16'. Ad esempio, sarebbe "XX.XX.0.0/16", dove XX sono numeri.
- Incolla questo IP nella casella di testo "Reti" delle reti esterne autorizzate della pagina di modifica dell'istanza.
- Al termine, fai clic su AGGIORNA ISTANZA.
Il completamento dell'operazione richiede alcuni minuti.
8. Strumenti MCP per l'installazione dei database
- Puoi creare una cartella di progetto in cui archiviare i dettagli dello strumento. In questo caso, dato che stiamo lavorando sui dati dei negozi di giocattoli, creiamo una cartella denominata "negozio giocattoli" e andiamo al suo interno. Vai al Terminale Cloud Shell e assicurati che il tuo progetto sia selezionato e visualizzato nel prompt del terminale. Esegui il comando seguente dal terminale Cloud Shell:
mkdir toystore
cd toystore
- Esegui il comando seguente per scaricare e installare gli strumenti nella tua 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
- Passa all'editor di Cloud Shell. Espandi la cartella "toystore" appena creata e crea un nuovo file denominato tool.yaml. Copia i seguenti contenuti. Sostituisci YOUR_PROJECT_ID e controlla che tutti gli altri dettagli della connessione siano accurati.
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, individuiamo semplicemente la corrispondenza più simile al testo di ricerca dell'utente (descrizione del giocattolo personalizzato) e restituiamo il relativo prezzo. Puoi anche modificarlo per trovare il prezzo medio dei primi 5 giocattoli più simili tra loro:
select avg(price) from ( SELECT price FROM giocattoli ORDER BY text_embeddings <=> CAST(embedding("text-embedding-005", $1) AS vector(768)) LIMIT 5 ) come prezzo;
Hai terminato la definizione dello strumento.
Per ulteriori dettagli sulla configurazione ditools.yaml, consulta questa documentazione.
- Passa al terminale Cloud Shell e inserisci il comando seguente per avviare il server degli strumenti con la configurazione degli strumenti:
./toolbox --tools_file "tools.yaml"
- Se apri il server in modalità di anteprima web sul cloud, dovresti essere in grado di vedere il server degli Strumenti in esecuzione con il nuovo strumento denominato
get-toy-price.
9. Deployment di Cloud Run degli strumenti MCP per i database
Eseguiamo il deployment in Cloud Run in modo da poter mettere in pratica questo strumento.
- Segui le istruzioni in questa pagina una alla volta fino a raggiungere il comando
gcloud run deploy toolboxche si trova nel terzo punto nella sezione "Deploy to Cloud Run". Devi avere la prima opzione e non la seconda quando utilizzi un metodo di rete VPC. - Una volta eseguito il deployment, riceverai un endpoint di Cloud Run di cui è stato eseguito il deployment del tuo server degli Strumenti. Testalo con un comando CURL.
Suggerimenti:
Segui attentamente le istruzioni nella pagina e non perdere l'occasione.
È tutto pronto per utilizzare lo strumento appena implementato nella tua applicazione agente.
10. Collega la tua app con gli strumenti MCP per i database
In questa parte creeremo una piccola applicazione per testare il tuo strumento al fine di interagire con le esigenze dell'applicazione e recuperare la risposta.
- Passa a Google Colab e apri un nuovo blocco note.
- Esegui il codice seguente nel blocco note
!pip install toolbox-core
from toolbox_core import ToolboxClient
# Replace with your Toolbox service's URL
toolbox = ToolboxClient("https://toolbox-*****-uc.a.run.app")
# This tool can be passed to your application!
tool = toolbox.load_tool("get-toy-price")
# If there are multiple tools
# These tools can be passed to your application!
# tools = await client.load_toolset("<<toolset_name>>")
# Invoke the tool with a search text to pass as the parameter
result = tool.invoke({"description": "white plush toy"})
# Print result
print(result)
- Il risultato dovrebbe essere simile al seguente:
Questo è lo strumento richiamato esplicitamente in un'applicazione Python che utilizza il toolkit toolbox-langchain.
- 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. - A questo scopo, consulta gli snippet di codice.
11. Portalo su Cloud!!!
Aggreghiamo questo snippet di codice Python in una funzione Cloud Run per renderlo serverless.
- Copia il codice sorgente dalla cartella del repository di codice per scaricarlo in Cloud Functions.
- Vai alla console Cloud Run Functions e fai clic su CREA FUNZIONE.
- Mantienilo non autenticato per l'applicazione demo e seleziona il runtime Python 3.11 nella pagina successiva.
- Copia i file
main.pyerequirements.txtdal repository di origine condiviso nel passaggio 1 e incolla i rispettivi file. - Sostituisci l'URL del server nel file main.py con l'URL del server.
- Esegui il deployment della funzione e avrai un endpoint REST per lo strumento di previsione dei prezzi a cui accedere nell'applicazione web Toystore.
- Il tuo endpoint dovrebbe avere l'aspetto seguente:
https://us-central1-*****.cloudfunctions.net/toolbox-toys
- Puoi testarlo direttamente nella console Cloud Functions accedendo alla scheda TEST e inserendo quanto segue come input della richiesta:
{
"search": "White plush toy"
}
- Fai clic su TESTA LA FUNZIONE o esegui nel terminale Cloud Shell qualsiasi cosa scegli di utilizzare. Dovresti vedere il risultato a destra sotto il titolo "Output":
12. Complimenti
Complimenti! Hai creato con successo uno strumento robusto e modulare che può interagire tra database, piattaforme e framework di orchestrazione dell'IA generativa per aiutarti a creare la tua applicazione agente.