Cette page a été traduite par l'API Cloud Translation.

Déployer une application d'IA agentive sur GKE avec l'Agent Development Kit (ADK) et un LLM auto-hébergé

Ce tutoriel explique comment déployer et gérer des applications d'IA/ML agentiques conteneurisées à l'aide de Google Kubernetes Engine (GKE). En combinant le Google Agent Development Kit (ADK) avec un grand modèle de langage (LLM) auto-hébergé comme Llama 3.1 fourni par vLLM, vous pouvez opérationnaliser les agents d'IA de manière efficace et à grande échelle tout en conservant un contrôle total sur la pile de modèles. Ce tutoriel vous guide tout au long du processus de développement et de déploiement en production d'un agent basé sur Python sur un cluster GKE Autopilot avec accélération GPU.

Ce tutoriel est destiné aux ingénieurs en machine learning (ML), aux développeurs et aux architectes cloud qui souhaitent utiliser les fonctionnalités d'orchestration de conteneurs Kubernetes pour diffuser des applications d'IA/ML agentiques. Pour en savoir plus sur les rôles courants et les exemples de tâches que nous citons dans le contenu Google Cloud, consultez Rôles utilisateur et tâches courantes de GKE Enterprise.

Avant de commencer, assurez-vous de connaître les points suivants :

Arrière-plan

Cette section décrit les principales technologies utilisées dans ce tutoriel.

Agent Development Kit (ADK)

Agent Development Kit (ADK) est un framework flexible et modulaire permettant de développer et de déployer des agents IA. Bien qu'il soit optimisé pour Gemini et l'écosystème Google, l'ADK ne vous oblige pas à utiliser un modèle ou un déploiement spécifique. Il est conçu pour être compatible avec d'autres frameworks. ADK a été conçu pour que le développement d'agents ressemble davantage au développement de logiciels. Il permet aux développeurs de créer, de déployer et d'orchestrer plus facilement des architectures agentives allant des tâches de base aux workflows complexes.

Pour en savoir plus, consultez la documentation de l'ADK.

Service Kubernetes géré par GKE

Google Cloud propose une gamme de services, y compris GKE, qui est bien adapté au déploiement et à la gestion des charges de travail d'IA/ML. GKE est un service Kubernetes géré qui simplifie le déploiement, le scaling et la gestion des applications conteneurisées. GKE fournit l'infrastructure nécessaire (y compris des ressources évolutives, le calcul distribué et une mise en réseau efficace) pour répondre aux besoins de calcul des LLM.

Pour en savoir plus sur les principaux concepts de Kubernetes, consultez Commencer à découvrir Kubernetes. Pour en savoir plus sur GKE et sur la façon dont il vous aide à faire évoluer, automatiser et gérer Kubernetes, consultez la présentation de GKE.

vLLM

vLLM est un framework de diffusion LLM Open Source hautement optimisé qui peut augmenter le débit de diffusion sur les GPU, avec des fonctionnalités telles que les suivantes :

Implémentation optimisée du transformateur avec PagedAttention.
Traitement par lots continu pour améliorer le débit global de diffusion.
Parallélisme Tensor et diffusion distribuée sur plusieurs GPU.

Pour en savoir plus, consultez la documentation vLLM.

Préparer l'environnement

Ce tutoriel utilise Cloud Shell pour gérer les ressources hébergées sur Google Cloud. Cloud Shell est préinstallé avec les logiciels dont vous avez besoin dans ce tutoriel, y compris kubectl, terraform et Google Cloud CLI.

Pour configurer votre environnement avec Cloud Shell, procédez comme suit :

Dans la console Google Cloud , lancez une session Cloud Shell et cliquez sur Activer Cloud Shell. Cette action lance une session dans un volet de console Google Cloud .
Définissez les variables d'environnement par défaut :
```
gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_REGION=REGION
export PROJECT_ID=PROJECT_ID
```
Remplacez les valeurs suivantes :
- PROJECT_ID : ID de votre projet Google Cloud .
- REGION : région Google Cloud (par exemple, us-east4) pour provisionner votre cluster GKE, Artifact Registry et d'autres ressources régionales. Veillez à spécifier une région compatible avec les GPU L4 et les instances de type de machine G2. Pour vérifier la disponibilité des régions, consultez la page Régions et zones pour les GPU de la documentation Compute Engine.

Cloner l'exemple de projet

À partir de votre terminal Cloud Shell, clonez le dépôt de l'exemple de code du tutoriel :
```
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
```

Accédez au répertoire du tutoriel :

cd kubernetes-engine-samples/ai-ml/adk-vllm

Créer et configurer des ressources Google Cloud

Pour déployer votre agent, vous devez d'abord provisionner les ressources Google Cloudnécessaires. Vous pouvez créer le cluster GKE et le dépôt Artifact Registry à l'aide de gcloud CLI ou de Terraform.

gcloud

Cette section fournit des commandes gcloud CLI permettant de configurer votre cluster GKE et Artifact Registry.

Créez un cluster GKE : vous pouvez déployer votre application agentique conteneurisée dans un cluster GKE Autopilot ou Standard. Utilisez un cluster Autopilot pour une expérience Kubernetes entièrement gérée. Pour choisir le mode de fonctionnement GKE le mieux adapté à vos charges de travail, consultez À propos des modes de fonctionnement GKE.
Autopilot
Dans Cloud Shell, exécutez la commande suivante :
```
gcloud container clusters create-auto CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION
```
Remplacez CLUSTER_NAME par le nom de votre cluster GKE.

Avec Autopilot, GKE provisionne automatiquement les nœuds en fonction des demandes de ressources de votre charge de travail. Le GPU requis pour le LLM est demandé dans le fichier manifeste deploy-llm.yaml à l'aide d'un nodeSelector.

Pour ajouter une requête nodeSelector au GPU nvidia-l4, procédez comme suit :
1. Ouvrez kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml dans un éditeur.
2. Ajoutez le nodeSelector suivant sous spec.template.spec :
  nodeSelector: cloud.google.com/gke-accelerator: nvidia-l4
Standard
1. Dans Cloud Shell, créez un cluster Standard en exécutant la commande suivante :
  gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION
  Remplacez CLUSTER_NAME par le nom de votre cluster GKE.
2. Créez un pool de nœuds compatible avec les GPU pour votre cluster en exécutant la commande suivante :
  gcloud container node-pools create gpu-node-pool \ --cluster=CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION \ --machine-type=g2-standard-8 \ --accelerator=type=nvidia-l4,count=1 \ --enable-gvnic
  Le fichier deploy-llm.yaml spécifie un GPU nvidia-l4, qui est disponible dans la série de machines G2. Pour en savoir plus sur ce type de machine, consultez Types de machines GPU dans la documentation Compute Engine.
Créez un dépôt Artifact Registry : créez un dépôt Artifact Registry pour stocker et gérer de manière sécurisée l'image de conteneur Docker de votre agent.
```
gcloud artifacts repositories create REPO_NAME \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_REGION
```
Remplacez REPO_NAME par le nom du dépôt Artifact Registry que vous souhaitez utiliser (par exemple, adk-repo).
Obtenez l'URL du dépôt : pour vérifier le chemin d'accès complet à votre dépôt, exécutez cette commande. Vous utiliserez ce format pour taguer votre image Docker lorsque vous créerez l'image de l'agent.
```
gcloud artifacts repositories describe REPO_NAME \
    --location $GOOGLE_CLOUD_REGION
```

Terraform

Cette section explique comment utiliser la configuration Terraform incluse dans l'exemple de dépôt pour provisionner automatiquement vos ressources Google Cloud .

Accédez au répertoire Terraform : le répertoire \terraform contient tous les fichiers de configuration nécessaires pour créer le cluster GKE et les autres ressources requises.
```
cd terraform
```
Créez un fichier de variables Terraform : copiez l'exemple de fichier de variables fourni (example_vars.tfvars) pour créer votre propre fichier vars.tfvars.
```
cp example_vars.tfvars vars.tfvars
```
Ouvrez le fichier vars.tfvars dans un éditeur et remplacez les valeurs d'espace réservé par votre configuration spécifique. Vous devez au moins remplacer PROJECT_ID par l'ID de votre projet Google Cloud et CLUSTER_NAME par le nom de votre cluster GKE.
Initialiser Terraform : exécutez cette commande pour télécharger les plug-ins de fournisseur nécessaires pour Google Cloud.
```
terraform init
```
Examinez le plan d'exécution : cette commande affiche les modifications que Terraform apportera à l'infrastructure.
```
terraform plan -var-file=vars.tfvars
```
Appliquez la configuration : pour créer les ressources dans votre projet Google Cloud , exécutez le plan Terraform. Confirmez l'opération avec yes lorsque vous y êtes invité.
```
terraform apply -var-file=vars.tfvars
```

Après avoir exécuté ces commandes, Terraform provisionne votre cluster GKE et votre dépôt Artifact Registry, et configure les rôles et comptes de service IAM nécessaires, y compris Workload Identity Federation for GKE.

Pour en savoir plus sur l'utilisation de Terraform, consultez Provisionner des ressources GKE avec Terraform.

Configurer `kubectl` pour communiquer avec votre cluster

Pour configurer kubectl de manière à communiquer avec votre cluster, exécutez la commande suivante :

gcloud container clusters get-credentials CLUSTER_NAME \
    --location=${GOOGLE_CLOUD_REGION}

Remplacez CLUSTER_NAME par le nom de votre cluster GKE.

Créer l'image de l'agent

Une fois l'infrastructure créée à l'aide de la gcloud CLI ou de Terraform, suivez ces étapes pour créer votre application d'agent.

Attribuez le rôle IAM requis pour Cloud Build : le service Cloud Build nécessite des autorisations pour transférer l'image de conteneur de l'agent vers Artifact Registry. Attribuez le rôle roles/artifactregistry.writer au compte de service Compute Engine par défaut, qui est utilisé par Cloud Build.
1. Créez l'adresse e-mail du compte de service Compute Engine par défaut :
```
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com
```
2. Attribuez le rôle roles/artifactregistry.writer au compte de service :
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer
```
Créez et transférez l'image de conteneur de l'agent : à partir du répertoire racine du projet (adk/llama/vllm), créez votre image Docker et transférez-la vers votre Artifact Registry en exécutant les commandes suivantes.
```
export IMAGE_URL="${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME/adk-agent:latest"
gcloud builds submit --tag $IMAGE_URL
```
Vérifiez que l'image a été transférée : une fois le processus de compilation terminé, vérifiez que l'image de conteneur de votre agent a été transférée vers Artifact Registry en listant les images de votre dépôt.
```
gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME
```
Un résultat doit s'afficher, listant l'image que vous venez de transférer et de taguer en tant que latest.

Déployer le modèle

Après avoir configuré votre cluster GKE et créé l'image de l'agent, l'étape suivante consiste à déployer le modèle Llama 3.1 auto-hébergé sur votre cluster. Pour ce faire, déployez un serveur d'inférence vLLM préconfiguré qui extrait le modèle de Hugging Face et le diffuse en interne dans le cluster.

Créez un secret Kubernetes pour les identifiants Hugging Face : pour permettre au cluster GKE de télécharger le modèle Llama 3.1 restreint, vous devez fournir votre jeton Hugging Face en tant que secret Kubernetes. Le fichier manifeste deploy-llm.yaml est configuré pour utiliser ce secret pour l'authentification.
```
kubectl create secret generic hf-secret \
    --from-literal=hf-token-secret=HUGGING_FACE_TOKEN
```
Remplacez HUGGING_FACE_TOKEN par votre jeton.
Afficher le fichier manifeste : à partir du répertoire racine de votre projet (adk/llama/vllm), accédez au répertoire /deploy-llm contenant le fichier manifeste du déploiement du modèle.
```
cd deploy-llm
```
Appliquez le fichier manifeste : exécutez la commande suivante pour appliquer le fichier manifeste deploy-llm.yaml à votre cluster.
```
kubectl apply -f deploy-llm.yaml
```
La commande crée trois ressources Kubernetes :
- Déploiement qui exécute le serveur vLLM, configuré pour utiliser le modèle meta-llama/Llama-3.1-8B-Instruct.
- Un service nommé vllm-llama3-service qui expose le serveur vLLM sur une adresse IP de cluster interne, ce qui permet à l'agent ADK de communiquer avec lui.
- Un fichier ConfigMap contenant un modèle de chat Jinja requis par le modèle Llama 3.1.
Vérifiez le déploiement du modèle : le serveur vLLM extrait les fichiers du modèle depuis Hugging Face. Ce processus peut prendre plusieurs minutes. Vous pouvez surveiller l'état du pod pour vous assurer qu'il est prêt.
1. Attendez que le déploiement soit disponible.
```
kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment
```
2. Affichez les journaux du pod en cours d'exécution pour confirmer que le serveur a bien démarré.
```
export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $LLM_POD
```
  Le déploiement est prêt lorsque vous voyez un résultat de journal semblable à ce qui suit, indiquant que le serveur LLM a démarré et que les routes d'API sont disponibles :
```
INFO 07-16 14:15:16 api_server.py:129] Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
```
3. Envoyez une requête directement au serveur de modèles pour confirmer que le LLM est prêt. Pour ce faire, ouvrez un nouveau terminal Cloud Shell et exécutez la commande suivante pour transférer le vllm-llama3-service vers votre ordinateur local :
```
kubectl port-forward service/vllm-llama3-service 8000:8000
```
4. Dans un autre terminal, envoyez une requête exemple au point de terminaison de l'API du modèle à l'aide de curl. Exemple :
```
curl -X POST http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta-llama/Llama-3.1-8B-Instruct",
    "prompt": "Hello!",
    "max_tokens": 10
  }'
```
  Si la commande renvoie une réponse JSON indiquant que l'opération a réussi, votre LLM est prêt. Vous pouvez maintenant mettre fin au processus de transfert de port en revenant à la fenêtre de terminal et en appuyant sur Ctrl+C, puis déployer l'agent.

Déployer l'application de l'agent

L'étape suivante consiste à déployer l'application d'agent basée sur ADK.

Accédez au répertoire /deploy-agent : depuis le répertoire racine de votre projet (adk/llama/vllm), accédez au répertoire /deploy-agent qui contient le code source et le fichier manifeste de déploiement de l'agent.
```
cd ../deploy-agent
```
Mettez à jour le fichier manifeste de déploiement de l'agent :
1. L'exemple de fichier manifeste deploy-agent.yaml contient un espace réservé pour l'ID de votre projet dans l'URL de l'image de conteneur. Vous devez remplacer l'espace réservé par l'ID de votre projet Google Cloud .
```
image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest
```
  Pour effectuer cette substitution sur place, vous pouvez exécuter la commande suivante :
```
sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml
```
2. Assurez-vous que le chemin d'accès readinessProbe est défini sur / au lieu de /dev-ui. Pour effectuer cette substitution sur place, vous pouvez exécuter la commande suivante :
```
sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml
```
Appliquez le fichier manifeste : exécutez la commande suivante pour appliquer le fichier manifeste deploy-agent.yaml à votre cluster.
```
kubectl apply -f deploy-agent.yaml
```
Cette commande crée deux ressources Kubernetes :
- Un déploiement nommé adk-agent qui exécute votre image de conteneur d'agent personnalisé.
- Un service nommé adk-agent de type NodePort qui expose l'application d'agent afin qu'elle puisse être accessible pour les tests.
Vérifiez le déploiement de l'agent : vérifiez l'état du pod pour vous assurer qu'il s'exécute correctement.
1. Attendez que le déploiement soit disponible :
```
kubectl wait --for=condition=available --timeout=300s deployment/adk-agent
```
2. Affichez les journaux du pod de l'agent en cours d'exécution :
```
export AGENT_POD=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $AGENT_POD
```

Le déploiement est réussi lorsque vous voyez un résultat de journalisation semblable à ce qui suit, indiquant que le serveur Uvicorn est en cours d'exécution et prêt à accepter les requêtes :

INFO:     Uvicorn running on http://0.0.0.0:8001 (Press CTRL+C to quit)

Tester votre agent déployé

Une fois le serveur vLLM et l'application d'agent déployés, vous pouvez tester la fonctionnalité de bout en bout en interagissant avec l'interface utilisateur Web de l'agent.

Transférez le service de l'agent vers votre machine locale : le service adk-agent est de type NodePort, mais le moyen le plus direct d'y accéder depuis votre environnement Cloud Shell consiste à utiliser la commande kubectl port-forward. Créez un tunnel sécurisé vers le pod de l'agent en exécutant cette commande.
```
kubectl port-forward $AGENT_POD 8001:8001
```
Accédez à l'interface utilisateur Web de l'agent : dans Cloud Shell, cliquez sur le bouton Aperçu Web et sélectionnez Prévisualiser sur le port 8001. Un nouvel onglet de navigateur s'ouvre et affiche l'interface de chat de l'agent.
Interagissez avec l'agent : posez-lui une question qui invoquera son outil get_weather. Exemple :
```
What's the weather like in Tokyo?
```
L'agent appellera d'abord le LLM pour comprendre l'intention et identifier la nécessité d'utiliser l'outil get_weather. Il exécutera ensuite l'outil avec "Tokyo" comme paramètre. Enfin, il utilisera le résultat de l'outil pour générer une réponse. Un résultat semblable à celui-ci doit s'afficher :
```
  The weather in Tokyo is 25°C and sunny.
```
(Facultatif) Vérifiez l'appel d'outil dans les journaux : vous pouvez observer l'interaction de l'agent avec le LLM et l'exécution de l'outil en consultant les journaux des pods respectifs.
1. Journaux du pod de l'agent : dans un nouveau terminal, affichez les journaux du pod adk-agent. L'appel d'outil et son résultat s'affichent.
```
kubectl logs -f $AGENT_POD
```
  Le résultat montre que l'outil est appelé et que le résultat est traité.
2. Journaux du pod LLM : affichez les journaux du pod vllm-llama3-deployment pour voir la requête entrante de l'agent.
```
kubectl logs -f $LLM_POD
```
  Les journaux affichent l'intégralité de la requête envoyée par l'agent au LLM, y compris le message système, votre requête et la définition de l'outil get_weather.

Une fois les tests terminés, vous pouvez mettre fin au processus port-forward en revenant à sa fenêtre de terminal et en appuyant sur Ctrl+C.