Ce guide 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 Vertex AI en tant que fournisseur de grands modèles de langage (LLM), vous pouvez opérationnaliser les agents d'IA de manière efficace et à grande échelle. Ce guide vous explique de bout en bout comment passer du développement au déploiement en production sur GKE d'un agent basé sur FastAPI et optimisé par Gemini 2.0 Flash.
Ce guide s'adresse 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 dans le contenu Google Cloud , consultez Rôles utilisateur et tâches courantes de l'utilisateur dans GKE Enterprise.
Avant de commencer, assurez-vous de connaître les points suivants :
Arrière-plan
Ce guide combine plusieurs technologies Google pour créer une plate-forme évolutive pour l'IA agentique. GKE fournit l'orchestration de conteneurs pour l'agent, qui est créé à l'aide de l'ADK. En utilisant l'API Vertex AI pour l'inférence LLM, le cluster GKE ne nécessite pas de matériel GPU spécialisé, car l'inférence est gérée par l'infrastructure gérée de Google.
Google 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 est indépendant du modèle et du déploiement, et est conçu pour être compatible avec d'autres frameworks.
Pour en savoir plus, consultez la documentation de l'ADK.
Service Kubernetes géré par GKE
GKE est un service Kubernetes géré permettant de déployer, de faire évoluer et de gérer 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.
Vertex AI
Vertex AI est la plate-forme de ML unifiée de Google Cloud, qui permet aux développeurs de créer, de déployer et de faire évoluer des modèles d'IA/de ML. Pour les applications d'IA agentiques sur GKE, Vertex AI fournit des outils et services essentiels, y compris l'accès à des LLM tels que Gemini 2.0 Flash, une infrastructure gérée pour l'entraînement et l'inférence, ainsi que des fonctionnalités MLOps pour une gestion efficace du cycle de vie.
Lorsque vous utilisez des LLM via l'API Vertex AI, l'inférence de modèle se produit sur l'infrastructure gérée de Google, ce qui réduit le besoin de quotas de GPU ou de TPU spécifiques dans votre cluster GKE.
Pour en savoir plus sur Vertex AI pour les applications d'IA agentique, consultez la documentation Vertex AI.
Gemini 2.0 Flash
Gemini 2.0 Flash offre des fonctionnalités de nouvelle génération et des capacités améliorées conçues pour les charges de travail agentiques, y compris une vitesse supérieure, l'utilisation d'outils intégrés, la génération multimodale et une fenêtre de contexte d'un million de jetons. Gemini 2.0 Flash améliore le modèle Flash précédent et offre une qualité supérieure à des vitesses similaires.
Pour obtenir des informations techniques sur Gemini 2.0 Flash (comme les benchmarks de performances, des informations sur nos ensembles de données d'entraînement, nos efforts en matière de durabilité, l'utilisation prévue et les limites, ainsi que notre approche de l'éthique et de la sécurité), consultez la fiche du modèle Gemini 2.0 Flash.
Objectifs
Cette page vous explique comment :
- Configurez votre environnement Google Cloud .
- Créez une image de conteneur pour votre agent.
- Déployez l'agent sur un cluster GKE.
- Testez l'agent déployé.
Coûts
Ce guide utilise les composants facturables suivants de Google Cloud :
Consultez les tarifs de chaque service pour comprendre les coûts potentiels.
Avant de commencer
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the required APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the required APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
Make sure that you have the following role or roles on the project: roles/container.admin, roles/iam.serviceAccountAdmin, roles/artifactregistry.admin, roles/cloudbuild.builds.editor, roles/resourcemanager.projectIamAdmin
Check for the roles
-
In the Google Cloud console, go to the IAM page.
Go to IAM - Select the project.
-
In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.
- For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.
Grant the roles
-
In the Google Cloud console, go to the IAM page.
Accéder à IAM - Sélectionnez le projet.
- Cliquez sur Accorder l'accès.
-
Dans le champ Nouveaux comptes principaux, saisissez votre identifiant utilisateur. Il s'agit généralement de l'adresse e-mail d'un compte Google.
- Dans la liste Sélectionner un rôle, sélectionnez un rôle.
- Pour attribuer des rôles supplémentaires, cliquez sur Ajouter un autre rôle et ajoutez tous les rôles supplémentaires.
- Cliquez sur Enregistrer.
- Dans la console Google Cloud , lancez une session Cloud Shell et cliquez sur
Activer Cloud Shell. Une session s'ouvre dans le volet inférieur de la console Google Cloud .
Définissez les variables d'environnement par défaut :
gcloud config set project PROJECT_ID export GOOGLE_CLOUD_LOCATION=REGION export PROJECT_ID=PROJECT_ID export GOOGLE_CLOUD_PROJECT=$PROJECT_ID export WORKLOAD_POOL=$PROJECT_ID.svc.id.goog export PROJECT_NUMBER=$(gcloud projects describe --format json $PROJECT_ID | jq -r ".projectNumber")
Remplacez les valeurs suivantes :
- PROJECT_ID : ID de votre projet Google Cloud .
- REGION : région Google Cloud (par exemple,
us-central1
) pour provisionner votre cluster GKE, Artifact Registry et d'autres ressources régionales.
À 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-vertex
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 Choisir un mode de fonctionnement GKE.
Autopilot
Dans Cloud Shell, exécutez la commande suivante :
gcloud container clusters create-auto CLUSTER_NAME \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Remplacez CLUSTER_NAME par le nom de votre cluster GKE Autopilot.
Standard
Dans Cloud Shell, exécutez la commande suivante :
gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID \ --release-channel=stable \ --num-nodes=1 \ --machine-type=e2-medium \ --workload-pool=$PROJECT_ID.svc.id.goog
Remplacez CLUSTER_NAME par le nom de votre cluster standard.
Créez un dépôt Artifact Registry pour votre conteneur Docker : 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. Ce registre privé permet de s'assurer que votre application est prête à être déployée sur GKE et s'intègre à Cloud Build.
gcloud artifacts repositories create adk-repo \ --repository-format=docker \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Obtenez l'URL du dépôt : exécutez cette commande pour vérifier le chemin d'accès complet à votre dépôt. Vous utiliserez ce format de chemin pour taguer votre image Docker à l'étape suivante.
gcloud artifacts repositories describe adk-repo \ --location $GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Attribuez les rôles IAM requis au compte de service Compute Engine par défaut : par défaut, le compte de service Compute Engine par défaut n'est pas autorisé à envoyer des images à Artifact Registry, ni à afficher des objets dans Cloud Storage ou des journaux. Attribuez les rôles nécessaires pour ces opérations.
ROLES_TO_ASSIGN=( "roles/artifactregistry.writer" "roles/storage.objectViewer" "roles/logging.viewer" ) for ROLE in "${ROLES_TO_ASSIGN[@]}"; do gcloud projects add-iam-policy-binding "${PROJECT_ID}" \ --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \ --role="${ROLE}" done
Créez et transférez l'image de conteneur de l'agent : exécutez cette commande pour créer votre image Docker et la transférer vers votre Artifact Registry. Assurez-vous que votre fichier Dockerfile et le code de votre application se trouvent dans le répertoire
/app
.export IMAGE_URL="${GOOGLE_CLOUD_LOCATION}-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest" gcloud builds submit \ --tag "$IMAGE_URL" \ --project="$PROJECT_ID" \ app
Vérifiez que l'image a été transférée :
gcloud artifacts docker images list \ $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$PROJECT_ID/adk-repo/adk-agent \ --project=$PROJECT_ID
Initialisez Terraform : accédez au répertoire
terraform
et initialisez Terraform.terraform init
Examinez le plan d'exécution : cette commande affiche les modifications que Terraform apportera à l'infrastructure.
terraform plan -var-file=default_env.tfvars
Appliquez la configuration : exécutez le plan Terraform pour créer les ressources dans votre projet Google Cloud . Confirmez l'opération avec
yes
lorsque vous y êtes invité.terraform apply -var-file=default_env.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 pour GKE.
Créez un compte de service pour accéder à Vertex AI :
gcloud iam service-accounts create vertex-sa \ --project=$PROJECT_ID
Attribuez le rôle
aiplatform.user
au compte de service. Cela permet au compte de service d'interagir avec Vertex AI.gcloud projects add-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/aiplatform.user"
Créez un compte de service Kubernetes dans votre cluster. Veillez à suivre les instructions de la section Configurer
kubectl
pour communiquer avec votre cluster avant d'exécuter cette commande.kubectl create serviceaccount vertex-sa
Annotez le KSA pour l'associer à votre compte de service :
kubectl annotate serviceaccount vertex-sa \ iam.gke.io/gcp-service-account=vertex-sa@$PROJECT_ID.iam.gserviceaccount.com
Accordez à votre compte de service les autorisations nécessaires pour agir en tant qu'utilisateur de la fédération d'identité de charge de travail pour GKE pour le compte de service Kubernetes :
gcloud iam service-accounts add-iam-policy-binding vertex-sa@$PROJECT_ID.iam.gserviceaccount.com \ --role roles/iam.workloadIdentityUser \ --member "serviceAccount:$PROJECT_ID.svc.id.goog[default/vertex-sa]"
- Comprendre la structure de l'application d'agent : le répertoire
/app
contient les fichiers principaux de votre application d'agent :main.py
: point d'entrée de l'application FastAPI, responsable de l'exposition de l'API de l'agent.agent.py
: contient la logique de l'agent ADK, qui définit la façon dont il utilise Vertex AI et gère les requêtes.__init__.py
: initialise le package Python.requirements.txt
: liste toutes les dépendances Python de votre agent.Dockerfile
: définit la manière dont votre application est empaquetée dans une image Docker.
Créez le fichier manifeste de déploiement de l'agent : dans le répertoire
tutorials-and-examples/adk/vertex
, créez le fichier manifeste suivant et nommez-leagent-deployment.yaml
:apiVersion: apps/v1 kind: Deployment metadata: name: adk-agent-deployment labels: app: adk-agent spec: replicas: 1 selector: matchLabels: app: adk-agent template: metadata: labels: app: adk-agent spec: serviceAccountName: vertex-sa containers: - name: adk-agent image: IMAGE_URL ports: - containerPort: 8000 env: - name: GOOGLE_CLOUD_PROJECT_ID value: PROJECT_ID - name: GOOGLE_CLOUD_LOCATION value: REGION - name: GOOGLE_GENAI_USE_VERTEXAI value: "1" - name: PORT value: "8000" resources: requests: memory: "512Mi" cpu: "500m" limits: memory: "1Gi" cpu: "1"
Remplacez les valeurs suivantes :
- IMAGE_URL : URL complète de l'image Docker que vous avez transférée vers Artifact Registry (par exemple,
us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest
). Vous pouvez obtenir cette valeur à partir du résultat de la commandegcloud artifacts docker images list
dans la section précédente. Vous pouvez également exécuter une commande comme la suivante :sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yaml
. - PROJECT_ID : ID de votre projet Google Cloud .
- REGION : Google Cloud région dans laquelle votre cluster GKE est provisionné.
- IMAGE_URL : URL complète de l'image Docker que vous avez transférée vers Artifact Registry (par exemple,
Appliquez le fichier manifeste de déploiement :
kubectl apply -f agent-deployment.yaml
Cette commande crée le déploiement et les pods associés pour votre application d'agent dans le cluster GKE.
Exposer l'agent : vous pouvez utiliser ces méthodes pour exposer votre agent et le rendre accessible.
- Pour accéder à votre agent depuis l'extérieur du cluster, créez un service Kubernetes.
Pour une API Web, un service de type
LoadBalancer
est courant. Pour le développement et les tests en local, utilisez la commande
kubectl port-forward
pour accéder directement à votre agent.
LoadBalancer
Créez le fichier manifeste suivant et enregistrez-le sous le nom
agent-service.yaml
:apiVersion: v1 kind: Service metadata: name: adk-agent-service spec: selector: app: adk-agent type: LoadBalancer # Creates an external IP address for access ports: - protocol: TCP port: 80 targetPort: 8000 # Matches the containerPort exposed in the Deployment
Appliquez le fichier manifeste :
kubectl apply -f agent-service.yaml
Le provisionnement de l'adresse IP externe peut prendre quelques minutes.
Vérifiez que l'adresse IP est provisionnée :
kubectl get service adk-agent-service
Recherchez la valeur
EXTERNAL-IP
dans le résultat. Une fois la valeur disponible, utilisez cette adresse IP pour interagir avec votre agent déployé.
port-forward
Si vous utilisez principalement
port-forward
, envisagez d'utiliser un type de serviceClusterIP
au lieu deLoadBalancer
, car le serviceClusterIP
est interne et consomme moins de ressources.POD_NAME=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}') kubectl port-forward $POD_NAME 8000:8000
Cette commande bloque votre terminal, mais elle transfère le trafic de
localhost:8000
sur votre machine vers l'agent exécuté dans le cluster GKE.- Pour accéder à votre agent depuis l'extérieur du cluster, créez un service Kubernetes.
Pour une API Web, un service de type
Identifiez le point de terminaison de l'agent : selon la façon dont vous avez choisi d'exposer votre agent dans la section précédente, identifiez son point de terminaison accessible :
LoadBalancer
Récupérez l'adresse IP externe :
kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
Stockez l'adresse IP externe dans une variable d'environnement pour faciliter son utilisation :
export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
L'URL de base de votre agent est
http://${AGENT_IP}
.
port-forward
Assurez-vous que votre commande
kubectl port-forward
s'exécute dans un terminal distinct. L'URL de base de votre agent esthttp://localhost:8000
.Tester l'API de l'agent : testez l'API de l'agent en envoyant une requête curl à son point de terminaison
/run
. L'agent s'attend à recevoir une charge utile JSON avec un champ de message. Remplacez AGENT_BASE_URL parhttp://${AGENT_IP}
(pour LoadBalancer) ouhttp://localhost:8000
(pour le transfert de port).Créer une session Cela prépare l'agent pour une nouvelle conversation.
# The user ID and session ID are arbitrary. # The appName must match the agent's Python package directory name (in this case, "capital-agent"). curl -X POST AGENT_BASE_URL/apps/capital-agent/users/user-123/sessions/session-123
Vous pouvez lister les applications disponibles à l'aide de la commande suivante :
curl -X GET AGENT_BASE_URL/list-apps
Envoyez une requête à l'agent en utilisant les détails de la session de l'étape précédente.
curl -X POST AGENT_BASE_URL/run \ -H "Content-Type: application/json" \ -d '{ "appName": "capital-agent", "userId": "user-123", "sessionId": "session-123", "newMessage": { "role": "user", "parts": [{ "text": "Hello, agent! What can you do for me?" }] } }'
Vous devriez recevoir une réponse JSON de votre agent, indiquant qu'il traite correctement les requêtes et interagit avec le modèle Gemini via Vertex AI. La réponse contient la réponse générée par l'agent en fonction de votre message.
Accédez à l'interface utilisateur Web de l'agent (le cas échéant) : si votre agent inclut une interface utilisateur Web, accédez-y en accédant à votre AGENT_BASE_URL dans un navigateur Web. L'ADK inclut généralement une interface utilisateur Web de base pour l'interaction et le débogage. Par exemple, si vous avez exposé votre agent via un équilibreur de charge et que son
EXTERNAL-IP
est34.123.45.67
, accédez àhttp://34.123.45.67
dans votre navigateur.Dans votre terminal Cloud Shell, accédez au répertoire
tutorials-and-examples/adk/vertex/
:cd tutorials-and-examples/adk/vertex/
Exécutez cette commande pour supprimer toutes les ressources définies dans vos fichiers de configuration Terraform.
cd terraform terraform destroy
- Découvrez comment configurer l'autoscaler horizontal de pods (HPA) pour ajuster automatiquement les ressources de votre agent à la demande.
- Découvrez comment configurer Identity-Aware Proxy (IAP) pour vos applications Web exécutées surGoogle Cloud, en fournissant une autorisation centralisée pour l'accès à l'interface utilisateur de votre agent.
- Découvrez comment utiliser Cloud Logging et Cloud Monitoring pour obtenir des informations sur les performances et l'état de votre agent dans votre cluster GKE.
- Explorez les exemples expérimentaux dans GKE AI Labs qui peuvent vous aider à utiliser GKE pour accélérer vos initiatives d'IA agentique.
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
etGoogle Cloud CLI
.Pour configurer votre environnement avec Cloud Shell, procédez comme suit :
Cloner l'exemple de projet
Créer et configurer des ressources Google Cloud
Pour déployer votre agent sur GKE, provisionnez les ressourcesGoogle Cloud nécessaires. Vous pouvez déployer l'agent à l'aide de gcloud CLI pour une exécution directe en ligne de commande ou de Terraform pour l'infrastructure en tant que code.
gcloud
Cette section fournit des commandes de l'interface de ligne de commande gcloud pour configurer votre cluster GKE, Artifact Registry et Workload Identity Federation for GKE afin de les intégrer de manière fluide à Vertex AI. Assurez-vous d'avoir défini les variables d'environnement comme décrit dans Préparer l'environnement.
Terraform
Cette section explique comment utiliser Terraform pour provisionner vos ressources Google Cloud. Le dépôt d'exemple que vous avez cloné inclut les fichiers de configuration Terraform nécessaires.
Pour en savoir plus sur l'utilisation de Terraform, consultez la page Compatibilité de Terraform avec GKE.
Configurer
kubectl
pour communiquer avec votre clusterSi vous n'avez pas configuré
kubectl
pour communiquer avec votre cluster, exécutez la commande suivante :gcloud container clusters get-credentials CLUSTER_NAME \ --location=${GOOGLE_CLOUD_LOCATION}
Remplacez CLUSTER_NAME par le nom de votre cluster GKE.
Configurer l'accès à la fédération d'identité de charge de travail pour GKE
Vous pouvez ignorer cette étape si vous utilisez Terraform. Ce processus associe un compte de service Kubernetes (KSA) à un compte de service IAM pour accorder de manière sécurisée à votre agent l'accès aux services Google Cloud .
Déployer et configurer l'application d'agent
Après avoir configuré vos ressources Google Cloud , préparez votre application d'agent pour le déploiement et configurez son environnement d'exécution sur GKE. Cela implique de définir le code de votre agent, de créer un Dockerfile pour le conteneuriser et d'écrire un fichier manifeste Kubernetes pour le déployer sur votre cluster.
Tester votre agent déployé
Maintenant que votre application d'agent est déployée et exposée, testez ses fonctionnalités.
Cette section explique comment identifier le point de terminaison de votre agent et tester son API.
Effectuer un nettoyage
Pour éviter que les ressources utilisées lors de ce tutoriel soient facturées sur votre compte Google Cloud, supprimez le projet contenant les ressources, ou conservez le projet et supprimez les ressources individuelles.
Supprimer les ressources déployées
Pour éviter que les ressources que vous avez créées dans ce guide soient facturées sur votre compte Google Cloud , exécutez les commandes suivantes :
gcloud
gcloud container clusters delete CLUSTER_NAME \ --location=${GOOGLE_CLOUD_LOCATION} \ --project=$PROJECT_ID gcloud projects remove-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/aiplatform.user" gcloud iam service-accounts delete vertex-sa@$PROJECT_ID.iam.gserviceaccount.com gcloud artifacts repositories delete adk-repo \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Remplacez CLUSTER_NAME par le nom de votre cluster GKE.
Terraform
Étapes suivantes
-