Installer et configurer la boîte à outils MCP pour les bases de données pour vos applications d'IA générative et agents sur AlloyDB

1. Présentation

MCP Toolbox for Databases est un serveur Open Source de Google qui facilite la création d'outils d'IA générative pour interagir avec les bases de données. Il vous permet de développer des outils plus facilement, plus rapidement et de manière plus sécurisée en gérant les complexités telles que le regroupement de connexions, l'authentification, etc. Il vous aide à créer des outils d'IA générative qui permettent à vos agents d'accéder aux données de votre base de données. La boîte à outils fournit les éléments suivants :

Développement simplifié : intégrez des outils à votre agent en moins de 10 lignes de code, réutilisez des outils entre plusieurs agents ou frameworks, et déployez plus facilement de nouvelles versions d'outils.

Meilleures performances : bonnes pratiques telles que le regroupement de connexions, l'authentification et plus encore.

Sécurité renforcée : authentification intégrée pour un accès plus sécurisé à vos données.

Observabilité de bout en bout : métriques et traçage prêts à l'emploi avec prise en charge intégrée d'OpenTelemetry.

Toolbox se situe entre le framework d'orchestration de votre application et votre base de données. Il fournit un plan de contrôle utilisé pour modifier, distribuer ou appeler des outils. Il simplifie la gestion de vos outils en vous offrant un emplacement centralisé pour les stocker et les mettre à jour. Vous pouvez ainsi partager des outils entre les agents et les applications, et les mettre à jour sans nécessairement redéployer votre application.

Ce que vous allez faire

Dans cet atelier, vous allez créer une application qui utilise un outil pour exécuter une requête de base de données (AlloyDB) simple pouvant être appelée depuis votre agent ou l'application d'IA générative. Pour cela, vous devrez

Installer MCP Toolbox for Databases
Configurer l'outil (conçu pour effectuer une tâche dans AlloyDB) sur le serveur Toolbox
Déployer MCP Toolbox for Databases sur Cloud Run
Tester l'outil avec son point de terminaison Cloud Run déployé
Créer la fonction Cloud Run pour appeler la boîte à outils

Conditions requises

Un navigateur tel que Chrome ou Firefox
Un projet Google Cloud avec facturation activée (voir les étapes de la section suivante).

2. Avant de commencer

Créer un projet

Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
Assurez-vous que la facturation est activée pour votre projet Cloud. Découvrez comment vérifier si la facturation est activée sur un projet.
Vous allez utiliser Cloud Shell, un environnement de ligne de commande exécuté dans Google Cloud. Cliquez sur "Activer Cloud Shell" en haut de la console Google Cloud.

Image du bouton "Activer Cloud Shell"

Une fois connecté à Cloud Shell, vérifiez si vous êtes déjà authentifié et si le projet est défini sur l'ID de projet approprié à l'aide de la commande suivante :

gcloud auth list

Exécutez la commande suivante dans Cloud Shell pour vérifier que la commande gcloud connaît votre projet.

gcloud config list project

Si votre projet n'est pas défini, utilisez la commande suivante pour le définir :

gcloud config set project <YOUR_PROJECT_ID>

Activez les API requises en exécutant les commandes suivantes une par une dans votre terminal Cloud Shell :

Il existe également une seule commande pour exécuter les opérations ci-dessous, mais si vous utilisez un compte d'essai, vous risquez de rencontrer des problèmes de quota en essayant de les activer de manière groupée. C'est pourquoi les commandes sont listées une par ligne.

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'alternative à la commande gcloud consiste à passer par la console en recherchant chaque produit ou en utilisant ce lien.

Si vous oubliez d'activer une API, vous pourrez toujours le faire au cours de l'implémentation.

Consultez la documentation pour connaître les commandes gcloud ainsi que leur utilisation.

3. Configuration de la base de données

Dans cet atelier, nous allons utiliser AlloyDB comme base de données pour stocker les données commerciales. Il utilise des clusters pour stocker toutes les ressources, telles que les bases de données et les journaux. Chaque cluster possède une instance principale qui fournit un point d'accès aux données. Les tables contiennent les données réelles.

Commençons par créer un cluster, une instance et une table AlloyDB dans lesquels l'ensemble de données e-commerce sera chargé.

Créer un cluster et une instance

Accédez à la page AlloyDB de la console Cloud.

Pour trouver la plupart des pages de la console Cloud, le plus simple est de les rechercher à l'aide de la barre de recherche de la console.

Sur cette page, sélectionnez CRÉER UN CLUSTER :

Un écran semblable à celui ci-dessous s'affiche. Créez un cluster et une instance avec les valeurs suivantes (assurez-vous que les valeurs correspondent si vous clonez le code de l'application à partir du dépôt) :

ID du cluster : "vector-cluster"
password: "alloydb"
Compatible avec PostgreSQL 15
Région : "us-central1"
Mise en réseau : "default"

Lorsque vous sélectionnez le réseau par défaut, un écran semblable à celui ci-dessous s'affiche. Sélectionnez CONFIGURER LA CONNEXION.
Sélectionnez ensuite "Utiliser une plage d'adresses IP automatiquement allouée", puis cliquez sur "Continuer". Après avoir vérifié les informations, sélectionnez CRÉER UNE CONNEXION.
Une fois votre réseau configuré, vous pouvez continuer à créer votre cluster. Cliquez sur CRÉER UN CLUSTER pour terminer la configuration du cluster, comme indiqué ci-dessous :

Veillez à remplacer l'ID d'instance par "

vector-instance"

Notez que la création du cluster prendra environ 10 minutes. Une fois l'opération terminée, un écran présentant le cluster que vous venez de créer devrait s'afficher.

4. Ingestion de données

Il est maintenant temps d'ajouter un tableau contenant les données sur le magasin. Accédez à AlloyDB, sélectionnez le cluster principal, puis AlloyDB Studio :

Vous devrez peut-être attendre que votre instance soit créée. Une fois l'opération terminée, connectez-vous à AlloyDB à l'aide des identifiants que vous avez créés lors de la création du cluster. Utilisez les données suivantes pour vous authentifier auprès de PostgreSQL :

Nom d'utilisateur : "postgres"
Base de données : "postgres"
Mot de passe : "alloydb"

Une fois que vous vous êtes authentifié dans AlloyDB Studio, vous pouvez saisir des commandes SQL dans l'éditeur. Vous pouvez ajouter plusieurs fenêtres de l'éditeur en cliquant sur le signe plus à droite de la dernière fenêtre.

Vous pouvez saisir des commandes pour AlloyDB dans les fenêtres de l'éditeur, en utilisant les options "Exécuter", "Mettre en forme" et "Effacer" selon vos besoins.

Activer les extensions

Pour créer cette application, nous allons utiliser les extensions pgvector et google_ml_integration. L'extension pgvector vous permet de stocker et de rechercher des embeddings vectoriels. L'extension google_ml_integration fournit les fonctions que vous utilisez pour accéder aux points de terminaison de prédiction Vertex AI afin d'obtenir des prédictions en SQL. Activez ces extensions en exécutant les LDD suivants :

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

Si vous souhaitez vérifier les extensions qui ont été activées dans votre base de données, exécutez la commande SQL suivante :

select extname, extversion from pg_extension;

Créer une table

Créez une table à l'aide de l'instruction LDD ci-dessous :

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

Si la commande ci-dessus s'exécute correctement, vous devriez pouvoir afficher le tableau dans la base de données.

Ingérer des données

Pour cet atelier, nous disposons de données de test d'environ 72 enregistrements dans ce fichier SQL. Il contient les champs id, name, description, quantity, price, image_url. Les autres champs seront remplis plus tard dans l'atelier.

Copiez les lignes/instructions d'insertion à partir de là, puis collez-les dans un onglet d'éditeur vide et sélectionnez "Exécuter".

Pour afficher le contenu de la table, développez la section "Explorateur" jusqu'à ce que la table "apparels" s'affiche. Sélectionnez le tricolon (⋮) pour afficher l'option permettant d'interroger la table. Une instruction SELECT s'ouvre dans un nouvel onglet de l'éditeur.

Accorder l'autorisation

Exécutez l'instruction ci-dessous pour accorder les droits d'exécution sur la fonction embedding à l'utilisateur postgres :

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Attribuer le RÔLE Utilisateur Vertex AI au compte de service AlloyDB

Accédez au terminal Cloud Shell et exécutez la commande suivante :

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. Créer des embeddings pour le contexte

Il est beaucoup plus facile pour les ordinateurs de traiter des nombres que du texte. Un système d'embedding convertit le texte en une série de nombres à virgule flottante, appelés embeddings vectoriels, qui doivent représenter le texte, quelle que soit sa formulation, la langue utilisée, etc.

Par exemple, un emplacement en bord de mer peut être appelé "au bord de l'eau", "en bord de plage", "à quelques pas de l'océan", "sur la mer", "на берегу океана", etc. Ces termes sont tous différents, mais leur signification sémantique ou, en termes de machine learning, leurs embeddings devraient être très proches les uns des autres.

Maintenant que les données et le contexte sont prêts, nous allons exécuter le code SQL pour ajouter les embeddings de la description du produit à la table dans le champ embedding. Vous pouvez utiliser différents modèles d'embedding. Nous utilisons text-embedding-005 de Vertex AI. Veillez à utiliser le même modèle d'embedding tout au long du projet.

Remarque : Si vous utilisez un ancien projet Google Cloud, vous devrez peut-être continuer à utiliser d'anciennes versions du modèle d'embedding de texte, comme textembedding-gecko.

Revenez à l'onglet AlloyDB Studio et saisissez le code LMD suivant :

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

Consultez à nouveau le tableau toys pour voir quelques embeddings. N'oubliez pas de réexécuter l'instruction SELECT pour voir les modifications.

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

Le vecteur d'embedding, qui ressemble à un tableau de valeurs flottantes, devrait être renvoyé pour la description du jouet, comme indiqué ci-dessous :

Remarque : Les projets Google Cloud nouvellement créés avec le forfait sans frais peuvent rencontrer des problèmes de quota concernant le nombre de requêtes d'embedding autorisées par seconde pour les modèles d'embedding. Nous vous suggérons d'utiliser une requête de filtre pour l'ID, puis de sélectionner de manière sélective un à cinq enregistrements, et ainsi de suite, lors de la génération de l'embedding.

6. Effectuer une recherche vectorielle

Maintenant que la table, les données et les embeddings sont prêts, effectuons la recherche vectorielle en temps réel pour le texte de recherche de l'utilisateur.

Supposons que l'utilisateur pose la question suivante :

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

Pour trouver des correspondances, exécutez la requête ci-dessous :

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;

Examinons cette requête en détail :

Dans cette requête,

Le texte de recherche de l'utilisateur est : "I want a white plush teddy bear toy with a floral pattern."
Nous le convertissons en embeddings dans la méthode embedding() à l'aide du modèle text-embedding-005. Cette étape devrait vous sembler familière après la dernière étape, où nous avons appliqué la fonction d'embedding à tous les éléments du tableau.
"<=>" représente l'utilisation de la méthode de distance COSINE SIMILARITY. Vous trouverez toutes les mesures de similarité disponibles dans la documentation de pgvector.
Nous convertissons le résultat de la méthode d'embedding en type vectoriel pour le rendre compatible avec les vecteurs stockés dans la base de données.
LIMIT 5 indique que nous souhaitons extraire les cinq voisins les plus proches du texte de recherche.

Le résultat ressemble à ceci :

Comme vous pouvez le voir dans vos résultats, les correspondances sont assez proches du texte de recherche. Essayez de modifier le texte pour voir comment les résultats changent.

7. Préparer AlloyDB pour l'interaction avec la boîte à outils

Avant de configurer Toolbox, activons la connectivité IP publique dans notre instance AlloyDB afin que le nouvel outil puisse accéder à la base de données.

Accédez à votre instance AlloyDB, cliquez sur "Modifier" et accédez à la page "Modifier l'instance principale".
Accédez à la section "Connectivité à l'adresse IP publique", cochez la case "Activer l'adresse IP publique", puis saisissez l'adresse IP de votre machine Cloud Shell.
Pour obtenir l'adresse IP de votre machine Cloud Shell, accédez au terminal Cloud Shell et saisissez "ifconfig". Dans le résultat, identifiez l'adresse inet eth0 et remplacez les deux derniers chiffres par 0.0 avec une taille de masque "/16". Par exemple, il ressemblerait à "XX.XX.0.0/16", où XX sont des nombres.
Collez cette adresse IP dans la zone de texte "Réseaux" de la page de modification de l'instance, sous "Réseaux externes autorisés".

Une fois l'opération terminée, cliquez sur "UPDATE INSTANCE" (METTRE À JOUR L'INSTANCE).

Cette opération prend quelques minutes.

8. Installation de MCP Toolbox for Databases

Vous pouvez créer un dossier de projet pour stocker les détails de l'outil. Dans ce cas, comme nous travaillons sur des données de magasin de jouets, créons un dossier nommé "toystore" et accédons-y. Accédez au terminal Cloud Shell et assurez-vous que votre projet est sélectionné et affiché dans l'invite du terminal. Exécutez la commande ci-dessous à partir de votre terminal Cloud Shell :

mkdir toystore

cd toystore

Exécutez la commande ci-dessous pour télécharger et installer la boîte à outils dans votre nouveau dossier :

# 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

Basculez vers l'éditeur Cloud Shell. Développez le dossier "toystore" que vous venez de créer, puis créez un fichier nommé tools.yaml. Copiez le contenu ci-dessous. Remplacez YOUR_PROJECT_ID et vérifiez que toutes les autres informations de connexion sont exactes.

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;

Dans cet outil, nous recherchons simplement la correspondance la plus proche du texte de recherche de l'utilisateur (description du jouet personnalisé) et nous renvoyons son prix. Vous pouvez également la modifier pour trouver le prix moyen des cinq jouets les plus proches :

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 définition de l'outil est terminée.

Pour en savoir plus sur la configuration de votre fichier tools.yaml, consultez cette documentation.

Basculez vers le terminal Cloud Shell et saisissez la commande suivante pour démarrer le serveur de la boîte à outils avec la configuration de vos outils :

./toolbox --tools_file "tools.yaml"

Si vous ouvrez le serveur en mode Aperçu sur le Web dans le cloud, vous devriez voir le serveur de la boîte à outils en cours d'exécution avec votre nouvel outil nommé get-toy-price..

9. Déploiement Cloud Run de MCP Toolbox for Databases

Déployons-la sur Cloud Run pour que vous puissiez utiliser cet outil.

Suivez les instructions de cette page une par une jusqu'à atteindre la commande gcloud run deploy toolbox qui se trouve au troisième point de la section "Déployer sur Cloud Run". Vous avez besoin de la première option, et non de la seconde qui s'applique lorsque vous utilisez une méthode de réseau VPC.
Une fois le déploiement réussi, vous recevrez un point de terminaison Cloud Run de votre serveur Toolbox. Testez-le avec une commande CURL.

Conseils :

Suivez attentivement les instructions sur la page et ne les manquez pas.

Vous pouvez maintenant utiliser votre nouvel outil déployé dans votre application agentique.

10. Connecter votre application à MCP Toolbox for Databases

Dans cette partie, nous allons créer une petite application pour tester votre outil afin d'interagir avec les besoins de l'application et récupérer une réponse.

Accédez à Google Colab et ouvrez un notebook.
Exécutez les commandes suivantes dans votre 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)

Vous devriez obtenir un résultat semblable à celui-ci :

Il s'agit de l'outil appelé explicitement dans une application Python qui utilise le kit d'outils : toolbox-langchain.

Si vous souhaitez utiliser cet outil et l'associer à un agent dans une application intégrée à LangGraph, vous pouvez le faire facilement avec la boîte à outils langgraph.
Pour cela, reportez-vous aux extraits de code.

11. Transférez-le dans le cloud !!!

Encapsulons cet extrait de code Python dans une fonction Cloud Run pour le rendre sans serveur.

Copiez la source du dossier du dépôt de code pour l'envoyer à Cloud Functions.
Accédez à la console Cloud Run Functions, puis cliquez sur "CRÉER UNE FONCTION".
Laissez-le non authentifié pour l'application de démonstration et sélectionnez l'environnement d'exécution Python 3.11 sur la page suivante.
Copiez les fichiers main.py et requirements.txt à partir du dépôt source partagé à l'étape 1, puis collez-les dans les fichiers correspondants.
Remplacez l'URL du serveur dans main.py par la vôtre.
Déployez la fonction et vous obtiendrez un point de terminaison REST pour que l'outil de prédiction des prix soit accessible dans l'application Web de la boutique de jouets.
Votre point de terminaison devrait se présenter comme suit :

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

Vous pouvez le tester directement dans la console Cloud Functions en accédant à l'onglet "TEST" et en saisissant les éléments suivants comme entrée de requête :

{

           "search": "White plush toy"

}

Cliquez sur "TESTER LA FONCTION" ou exécutez la fonction dans le terminal Cloud Shell, selon votre choix. Le résultat devrait s'afficher à droite, sous le titre "Output" (Sortie) :

12. Félicitations

Félicitations ! Vous avez créé un outil robuste et véritablement modulaire qui peut interagir avec des bases de données, des plates-formes et des frameworks d'orchestration de l'IA générative pour vous aider à créer votre application agentive.