Installer et configurer la boîte à outils pour vos applications d'IA générative et agentique sur AlloyDB

1. Présentation

La boîte à outils d'IA générative pour les bases de données 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 pool 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. Toolbox 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.

Amélioration des performances:bonnes pratiques telles que le regroupement de connexions, l'authentification, etc.

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.

La boîte à outils se trouve entre le framework d'orchestration de votre application et votre base de données. Elle fournit un plan de contrôle qui permet de modifier, de distribuer ou d'invoquer des outils. Il simplifie la gestion de vos outils en vous fournissant un emplacement centralisé pour les stocker et les mettre à jour. Vous pouvez ainsi les partager entre les agents et les applications, et les mettre à jour sans avoir à redéployer votre application.

Ce que vous allez faire

Dans cet atelier, vous allez créer une application qui utilise un outil pour effectuer une requête de base de données (AlloyDB) simple pouvant être appelée à partir de votre agent ou de l'application d'IA générative. Pour ce faire, vous devez :

1. Installer Toolbox
2. Configurer l'outil (conçu pour effectuer une tâche dans AlloyDB) sur le serveur Toolbox
3. Déployer Toolbox sur Cloud Run
4. Tester l'outil avec son point de terminaison Cloud Run déployé
5. 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 la section suivante).

2. Avant de commencer

Créer un projet

1. Dans la console Google Cloud, sur la page du sélecteur de projet, sélectionnez ou créez un projet Google Cloud.
2. 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.
3. 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.

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

gcloud auth list

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

gcloud config list project

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

gcloud config set project <YOUR_PROJECT_ID>

7. 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 commandes ci-dessous. Toutefois, si vous utilisez un compte d'essai, vous risquez de rencontrer des problèmes de quota si vous essayez de les activer de manière groupée. C'est pourquoi les commandes sont séparées les unes des autres sur une 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

Vous pouvez également accéder à la commande gcloud via la console en recherchant chaque produit ou en suivant ce lien.

Si une API est manquante, vous pouvez toujours l'activer 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 dispose d'une instance principale qui fournit un point d'accès aux données. Les tables contiennent les données réelles.

Créons un cluster, une instance et une table AlloyDB dans lesquels l'ensemble de données sur l'e-commerce sera chargé.

Créer un cluster et une instance

1. Accédez à la page AlloyDB dans Cloud Console.

Pour trouver facilement la plupart des pages de la console Cloud, recherchez-les à l'aide de la barre de recherche de la console.

2. Sélectionnez "CRÉER UN CLUSTER" sur cette page:

3. 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 au cas où vous cloneriez le code de l'application à partir du dépôt):

• cluster id: "vector-cluster"
• mot de passe: "alloydb"
• Compatible avec PostgreSQL 15
• Région: "us-central1"
• Mise en réseau: "default"

4. Lorsque vous sélectionnez le réseau par défaut, un écran semblable à celui ci-dessous s'affiche. Sélectionnez CONFIGURER LA CONNEXION.
   
5. Sélectionnez "Utiliser une plage d'adresses IP automatiquement allouée", puis cliquez sur "Continuer". Après avoir examiné les informations, sélectionnez "CRÉER UNE CONNEXION".
6. 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 illustré ci-dessous:

Assurez-vous de 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 une vue d'ensemble du 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 la création de votre instance soit terminée. Une fois la création 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 à l'aide du signe plus à droite de la dernière fenêtre.

Vous pouvez saisir des commandes pour AlloyDB dans les fenêtres d'éditeur, à l'aide des options "Run" (Exécuter), "Format" (Mettre en forme) et "Clear" (Effacer) si nécessaire.

Activer les extensions

Pour créer cette application, nous utiliserons 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 des fonctions que vous pouvez utiliser 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 suivantes:

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 cette commande SQL:

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

Une fois la commande ci-dessus exécutée, 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 "Explorer" jusqu'à ce que la table intitulée "vêtements" s'affiche. Sélectionnez les trois points (⋮) pour afficher l'option permettant d'interroger le tableau. Une instruction SELECT s'ouvre dans un nouvel onglet de l'éditeur.

Accorder l'autorisation

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

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Attribuer le rôle d'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

Les ordinateurs traitent beaucoup plus facilement les nombres que le 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 qu'il utilise, etc.

Par exemple, un emplacement en bord de mer peut être appelé "sur l'eau", "en bord de mer", "à pied de la mer", "sur la mer", "на берегу океана", etc. Ces termes semblent tous différents, mais leur signification sémantique (ou, en termes de machine learning, leurs représentations vectorielles continues) devrait être très proche.

Maintenant que les données et le contexte sont prêts, nous allons exécuter la requête SQL pour ajouter les représentations vectorielles continues 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'encapsulation 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'encapsulation de texte, comme textembedding-gecko.

Revenez à l'onglet AlloyDB Studio et saisissez la DML suivante:

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

Examinez à nouveau le tableau toys pour voir quelques embeddings. N'oubliez pas de relancer l'instruction SELECT pour voir les modifications.

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

Le vecteur d'embeddings, qui ressemble à un tableau de nombres à virgule flottante, devrait être renvoyé pour la description du jouet, comme indiqué ci-dessous:

Remarque:Les projets Google Cloud nouvellement créés dans le niveau 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 recommandons d'utiliser une requête de filtrage pour l'ID, puis de sélectionner de manière sélective 1 à 5 enregistrements, etc., lors de la génération de l'encapsulation.

6. Effectuer une recherche vectorielle

Maintenant que le tableau, 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 demande:

"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,

1. Le texte de recherche de l'utilisateur est: "I want a white plush teddy bear toy with a floral pattern."
2. Nous le convertissons en représentations vectorielles continues 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, où nous avons appliqué la fonction d'encapsulation à tous les éléments du tableau.
3. "<=>" 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.
4. Nous convertissons le résultat de la méthode d'embedding en type de vecteur pour le rendre compatible avec les vecteurs stockés dans la base de données.
5. LIMIT 5 indique que nous souhaitons extraire cinq voisins les plus proches du texte de recherche.

Le résultat se présente comme suit:

Comme vous pouvez le constater 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 Toolbox

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.

1. Accédez à votre instance AlloyDB, cliquez sur MODIFIER, puis accédez à la page "Modifier l'instance principale".
2. Accédez à la section "Connectivité avec une adresse IP publique", cochez la case "Activer l'adresse IP publique", puis saisissez l'adresse IP de votre machine Cloud Shell.
3. Pour obtenir l'adresse IP de votre machine Cloud Shell, accédez au terminal Cloud Shell et saisissez ifconfig. Identifiez l'adresse IPv4 eth0 dans le résultat, puis remplacez les deux derniers chiffres par 0.0 avec une taille de masque de "/16". Par exemple, "XX.XX.0.0/16", où XX correspond à des chiffres.
4. Collez cette adresse IP dans le champ "Réseaux" de la section "Réseaux externes autorisés" de la page de modification de l'instance.

5. Cliquez sur "METTRE À JOUR L'INSTANCE" une fois que vous avez terminé.

Cette opération prend quelques minutes.

8. Installation de la boîte à outils

1. Vous pouvez créer un dossier de projet pour stocker les informations sur l'outil. Dans ce cas, comme nous travaillons sur des données de magasin de jouets, créons un dossier nommé "toystore" et y accédons. 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

2. Exécutez la commande ci-dessous pour télécharger et installer Toolbox 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

3. Activez l'éditeur Cloud Shell. Développez le dossier "toystore" nouvellement créé, 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 correctes.

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 ne faisons que trouver la correspondance la plus proche du texte de recherche de l'utilisateur (description du jouet personnalisé) et renvoyer son prix. Vous pouvez également le 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 la documentation.

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

./toolbox --tools_file "tools.yaml"

5. Si vous ouvrez le serveur en mode d'aperçu Web dans le cloud, vous devriez pouvoir voir le serveur Toolbox en cours d'exécution avec votre nouvel outil nommé get-toy-price..

9. Déploiement Cloud Run de la boîte à outils

Déployez-le sur Cloud Run pour pouvoir l'utiliser.

1. Suivez les instructions de cette page une par une jusqu'à atteindre la commande gcloud run deploy toolbox, qui se trouve dans le 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 est utilisée lorsque vous utilisez une méthode de réseau VPC.
2. Une fois le déploiement terminé, vous recevrez un point de terminaison Cloud Run déployé de votre serveur Toolbox. Testez-le avec une commande CURL.

Vous pouvez maintenant utiliser votre nouvel outil dans votre application agentique.

10. Associer votre application à Toolbox

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

1. Accédez à Google Colab et ouvrez un nouveau notebook.
2. Exécutez le code suivant dans votre 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)

3. Vous devriez obtenir le résultat suivant:

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

4. 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.
5. Pour ce faire, consultez les extraits de code.

11. Passez au cloud !

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

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

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

2. Vous pouvez la tester directement dans la console Cloud Functions en accédant à l'onglet "TESTING" (TEST) et en saisissant ce qui suit comme entrée de requête:

{

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

}

3. Cliquez sur "TESTER LA FONCTION" ou sur "Exécuter dans le terminal Cloud Shell", selon ce que vous choisissez d'utiliser. Le résultat devrait s'afficher sur la droite, sous le titre "Sortie":

12. Félicitations

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