Installazione e configurazione degli strumenti MCP per database per le applicazioni Gen AI e Agentiche su AlloyDB

1. Panoramica

MCP 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 più facilmente, rapidamente e in modo più sicuro gestendo le complessità come il raggruppamento delle connessioni, l'autenticazione e altro ancora. Ti aiuta a creare strumenti di AI generativa che consentono ai tuoi agenti di accedere ai dati nel tuo database. Toolbox fornisce:

Sviluppo semplificato:integra gli strumenti nel tuo agente con meno di 10 righe di codice, riutilizza gli strumenti tra più agenti o framework e implementa più facilmente nuove versioni degli strumenti.

Rendimento migliore: 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 tracciamento pronti all'uso con supporto integrato per OpenTelemetry.

Toolbox si trova tra il framework di orchestrazione dell'applicazione e il database, fornendo un control plane utilizzato per modificare, distribuire o richiamare gli strumenti. Semplifica la gestione degli strumenti fornendoti una posizione centralizzata per archiviarli e aggiornarli, consentendoti di condividerli tra agenti e applicazioni e di aggiornarli senza dover necessariamente rieseguire il deployment dell'applicazione.

Cosa creerai

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

1. Installa MCP Toolbox for Databases
2. Configura lo strumento (progettato per eseguire un'attività in AlloyDB) sul server Toolbox
3. Esegui il deployment di MCP Toolbox per database 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 casella degli strumenti

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 è abilitata per 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.

4. Una volta eseguita la connessione a Cloud Shell, verifica se l'autenticazione è già stata eseguita e se il progetto è impostato sull'ID progetto corretto utilizzando il seguente comando:

gcloud auth list

5. Esegui questo comando in Cloud Shell per verificare che il comando gcloud conosca il tuo progetto.

gcloud config list project

6. Se il progetto non è impostato, utilizza il seguente comando per impostarlo:

gcloud config set project <YOUR_PROJECT_ID>

7. Abilita le API richieste eseguendo i seguenti comandi uno alla volta nel terminale Cloud Shell:

Esiste anche un singolo comando per eseguire le operazioni riportate di seguito, ma se utilizzi un account di prova, potresti riscontrare problemi di quota durante il tentativo di abilitare queste operazioni collettivamente. Per questo motivo, 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 abilitarla 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 vendita al dettaglio. Utilizza i cluster per contenere tutte le risorse, come database e log. Ogni cluster ha un'istanza primaria 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. Vai alla 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.

2. Seleziona CREA CLUSTER da questa pagina:

3. Vedrai una schermata come quella riportata di seguito. Crea un cluster e un'istanza con i seguenti valori (assicurati che i valori corrispondano se cloni il codice dell'applicazione dal repository):

• cluster id: "vector-cluster"
• password: "alloydb"
• Compatibile con PostgreSQL 15
• Regione: "us-central1"
• Networking: "default"

4. Quando selezioni la rete predefinita, viene visualizzata una schermata come quella riportata di seguito. Seleziona CONFIGURA CONNESSIONE.
   
5. Da qui, seleziona "Utilizza un intervallo IP allocato automaticamente" e fai clic su Continua. Dopo aver esaminato le informazioni, seleziona CREA CONNESSIONE.
6. 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:

Assicurati di modificare l'ID istanza in "

vector-instance"

.

Tieni presente che la creazione del cluster richiederà circa 10 minuti. Una volta completata l'operazione, dovresti visualizzare una schermata che mostra la panoramica del cluster che hai 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:

Potrebbe essere necessario 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 a PostgreSQL:

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

Una volta eseguita l'autenticazione in AlloyDB Studio, i comandi SQL possono essere inseriti nell'editor. Puoi aggiungere più finestre dell'editor utilizzando il segno più a destra dell'ultima finestra.

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

Attivare le estensioni

Per creare questa app, utilizzeremo le estensioni pgvector e google_ml_integration. L'estensione pgvector consente di archiviare ed eseguire ricerche di vector embedding. L'estensione google_ml_integration fornisce funzioni che utilizzi per accedere agli endpoint di previsione 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;

Se vuoi controllare le estensioni abilitate sul 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 il comando precedente viene eseguito correttamente, 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ù tardi nel lab.

Copia le righe/le istruzioni di inserimento e incollale in una scheda dell'editor vuota, quindi seleziona ESEGUI.

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

Concedi autorizzazione

Esegui l'istruzione riportata di seguito 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 al service account AlloyDB

Vai al terminale Cloud Shell ed esegui 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 il testo. Un sistema di embedding converte il testo in una serie di numeri in virgola mobile, chiamati vector embedding, che devono rappresentare il testo, indipendentemente dalla formulazione, dalla lingua utilizzata e così via.

Ad esempio, una località balneare potrebbe essere chiamata "sull'acqua", "fronte spiaggia", "a pochi passi dalla camera all'oceano", "sur la mer", "на берегу океана" e così via. Questi termini sembrano diversi, ma il loro significato semantico o, in termini di machine learning, i loro incorporamenti dovrebbero essere molto simili tra loro.

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

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

Torna alla scheda AlloyDB Studio e digita il seguente DML:

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

Dai un'occhiata di nuovo alla tabella toys per vedere alcuni incorporamenti. 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 incorporamento, che appare come un array di numeri in virgola mobile, per la descrizione del giocattolo, come mostrato di seguito:

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 ai modelli di incorporamento. Ti suggeriamo di utilizzare una query di filtro per l'ID e poi di scegliere in modo selettivo 1-5 record e così via, durante la generazione dell'incorporamento.

6. Esegui la ricerca vettoriale

Ora che la tabella, i dati e gli embedding sono pronti, eseguiamo la ricerca vettoriale 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 le corrispondenze 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;

Analizziamo questa query nel 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 incorporamenti nel metodo embedding() utilizzando il modello: text-embedding-005. Questo passaggio dovrebbe sembrarti familiare dopo l'ultimo, in cui abbiamo applicato la funzione di incorporamento a tutti gli elementi della tabella.
3. "<=>" rappresenta l'utilizzo del metodo di distanza COSINE SIMILARITY. Puoi trovare tutte le misure di similarità disponibili nella documentazione di pgvector.
4. Stiamo convertendo il risultato del metodo di embedding in tipo vettoriale per renderlo compatibile con i vettori archiviati nel database.
5. LIMIT 5 indica che vogliamo estrarre i 5 vicini più prossimi per il testo di ricerca.

Il risultato è simile al seguente:

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 Toolbox

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 due cifre con 0.0 con una dimensione della maschera "/16". Ad esempio, "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.

5. Al termine, fai clic su AGGIORNA ISTANZA.

Il completamento dell'operazione richiede alcuni minuti.

8. Installazione di MCP Toolbox for Databases

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

mkdir toystore

cd toystore

2. Esegui il comando riportato di seguito 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

3. Passa all'editor di Cloud Shell. Espandi la cartella appena creata "toystore" e crea un nuovo file chiamato tools.yaml. Copia i contenuti riportati di seguito. Sostituisci YOUR_PROJECT_ID e controlla che tutti gli altri dettagli della connessione siano 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, troviamo solo la corrispondenza più vicina al testo di ricerca dell'utente (descrizione del giocattolo personalizzato) e restituiamo il relativo prezzo. Puoi anche modificarla per trovare il prezzo medio dei 5 giocattoli più simili:

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 è completa.

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

4. Passa al terminale Cloud Shell e inserisci il comando seguente per avviare il server della casella degli strumenti con la configurazione degli strumenti:

./toolbox --tools_file "tools.yaml"

5. Ora, se apri il server in modalità di anteprima web sul cloud, dovresti essere in grado di vedere il server Toolbox in esecuzione con il nuovo strumento denominato get-toy-price..

9. Deployment di Cloud Run di MCP Toolbox per database

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, che si trova al terzo punto della sezione "Esegui il deployment in Cloud Run". Devi scegliere la prima opzione e non la seconda, che è per quando utilizzi un metodo di rete VPC.
2. Una volta eseguito il deployment, riceverai un endpoint di Cloud Run del server Toolbox. Testalo con un comando CURL.

Suggerimenti:

Segui attentamente le istruzioni riportate nella pagina e non perderti nulla.

Ora puoi utilizzare lo strumento appena implementato nella tua applicazione con agenti.

10. Connetti la tua app a MCP Toolbox for Databases

In questa parte, creeremo una piccola applicazione per testare lo strumento per interagire con le esigenze dell'applicazione e recuperare la risposta.

1. Vai a Google Colab e apri un nuovo notebook.
2. Esegui questo codice nel notebook

!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)

3. Dovresti ottenere un risultato simile a questo:

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

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

11. Portalo sul cloud.

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

1. Copia l'origine dalla cartella del repository di codice per trasferirla a Cloud Functions.
2. Vai alla console Cloud Run Functions e fai clic su CREA FUNZIONE.
3. Mantienila non autenticata per l'applicazione demo 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. Sostituisci l'URL del server in main.py con il tuo URL.
6. Esegui il deployment della funzione e avrai un endpoint REST per accedere allo strumento di previsione dei prezzi nell'applicazione web del negozio di giocattoli.
7. Il tuo endpoint dovrebbe avere il seguente aspetto:

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

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

{

           "search": "White plush toy"

}

3. 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":

12. Complimenti

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