En esta guía se muestra cómo desplegar y gestionar aplicaciones de IA/ML con agentes en contenedores mediante Google Kubernetes Engine (GKE). Si combinas el kit de desarrollo de agentes de Google (ADK) con Vertex AI como proveedor de modelos de lenguaje extenso (LLM), puedes poner en marcha agentes de IA de forma eficiente y a gran escala. En esta guía se describe todo el proceso para llevar un agente basado en FastAPI y con la tecnología de Gemini 2.0 Flash desde el desarrollo hasta el despliegue en producción en GKE.
Esta guía está dirigida a ingenieros de aprendizaje automático, desarrolladores y arquitectos de Cloud interesados en usar las funciones de orquestación de contenedores de Kubernetes para servir aplicaciones de IA o aprendizaje automático basadas en agentes. Para obtener más información sobre los roles y las tareas habituales en el contenido de Google Cloud , consulta Roles y tareas habituales de los usuarios de GKE Enterprise.
Antes de empezar, asegúrate de que conoces lo siguiente:
Fondo
En esta guía se combinan varias tecnologías de Google para crear una plataforma escalable para la IA basada en agentes. GKE proporciona la orquestación de contenedores del agente, que se crea con el ADK. Al usar la API Vertex AI para la inferencia de LLMs, el clúster de GKE no requiere hardware de GPU especializado, ya que la inferencia se gestiona mediante la infraestructura gestionada de Google.
Google Agent Development Kit (ADK)
Agent Development Kit (ADK) es un framework flexible y modular para desarrollar e implementar agentes de IA. Aunque está optimizado para Gemini y el ecosistema de Google, el ADK es independiente del modelo y de la implementación, y se ha diseñado para que sea compatible con otros frameworks.
Para obtener más información, consulta la documentación del ADK.
Servicio de Kubernetes gestionado de GKE
GKE es un servicio de Kubernetes gestionado que permite desplegar, escalar y gestionar aplicaciones en contenedores. GKE proporciona la infraestructura necesaria, incluidos recursos escalables, computación distribuida y redes eficientes, para gestionar las demandas computacionales de los LLMs.
Para obtener más información sobre los conceptos clave de Kubernetes, consulta Empezar a aprender sobre Kubernetes. Para obtener más información sobre GKE y cómo te ayuda a escalar, automatizar y gestionar Kubernetes, consulta la descripción general de GKE.
Vertex AI
Vertex AI es la plataforma de aprendizaje automático unificada de Google Cloud, que permite a los desarrolladores crear, desplegar y escalar modelos de IA y aprendizaje automático. Para las aplicaciones de IA basadas en agentes en GKE, Vertex AI proporciona herramientas y servicios esenciales, como acceso a LLMs como Gemini 2.0 Flash, infraestructura gestionada para el entrenamiento y la inferencia, y funciones de MLOps para una gestión eficiente del ciclo de vida.
Cuando se consumen LLMs a través de la API de Vertex AI, la inferencia de modelos se produce en la infraestructura gestionada de Google, lo que reduce la necesidad de cuotas específicas de GPU o TPU en tu clúster de GKE.
Para obtener más información sobre Vertex AI para aplicaciones de IA basadas en agentes, consulta la documentación de Vertex AI.
Gemini 2.0 Flash
Gemini 2.0 Flash ofrece funciones de última generación y capacidades mejoradas diseñadas para cargas de trabajo de agentes, como mayor velocidad, uso de herramientas integrado, generación multimodal y una ventana de contexto de 1 millón de tokens. Gemini 2.0 Flash mejora el modelo Flash anterior y ofrece una calidad superior a velocidades similares.
Para obtener información técnica sobre Gemini 2.0 Flash (como los puntos de referencia de rendimiento, información sobre nuestros conjuntos de datos de entrenamiento, esfuerzos en materia de sostenibilidad, uso previsto y limitaciones, y nuestro enfoque de la ética y la seguridad), consulta la tarjeta de modelo de Gemini 2.0 Flash.
Objetivos
En esta guía se explica cómo hacer lo siguiente:
- Configura tu Google Cloud entorno.
- Crea una imagen de contenedor para tu agente.
- Despliega el agente en un clúster de GKE.
- Prueba el agente desplegado.
Costes
En esta guía se usan los siguientes componentes facturables de Google Cloud:
Consulta los precios de cada servicio para conocer los posibles costes.
Antes de empezar
- 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.
Ir a IAM - Selecciona el proyecto.
- Haz clic en Conceder acceso.
-
En el campo Nuevos principales, introduce tu identificador de usuario. Normalmente, se trata de la dirección de correo de una cuenta de Google.
- En la lista Selecciona un rol, elige un rol.
- Para conceder más roles, haz clic en Añadir otro rol y añade cada rol adicional.
- Haz clic en Guardar.
- En la Google Cloud consola
, inicia una sesión de Cloud Shell y haz clic en Activar Cloud Shell. Esta acción inicia una sesión en el panel inferior de la consola Google Cloud .
Define las variables de entorno predeterminadas:
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")
Sustituye los siguientes valores:
- PROJECT_ID: tu Google Cloud ID de proyecto.
- REGION: la Google Cloud región (por ejemplo,
us-central1
) en la que se aprovisionarán el clúster de GKE, Artifact Registry y otros recursos regionales.
En el terminal de Cloud Shell, clona el repositorio de código de ejemplo del tutorial:
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
Ve al directorio del tutorial:
cd kubernetes-engine-samples/ai-ml/adk-vertex
Crea un clúster de GKE: puedes desplegar tu aplicación basada en agentes en contenedores en un clúster Autopilot o Estándar de GKE. Usa un clúster de Autopilot para disfrutar de una experiencia de Kubernetes totalmente gestionada. Para elegir el modo de funcionamiento de GKE que mejor se adapte a tus cargas de trabajo, consulta Elegir un modo de funcionamiento de GKE.
Autopilot
En Cloud Shell, ejecuta el siguiente comando:
gcloud container clusters create-auto CLUSTER_NAME \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Sustituye CLUSTER_NAME por el nombre de tu clúster de Autopilot de GKE.
Estándar
En Cloud Shell, ejecuta el siguiente comando:
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
Sustituye CLUSTER_NAME por el nombre de tu clúster estándar.
Crea un repositorio de Artifact Registry para tu contenedor Docker: crea un repositorio de Artifact Registry para almacenar y gestionar de forma segura la imagen de contenedor Docker de tu agente. Este registro privado ayuda a que tu aplicación esté disponible para desplegarse en GKE y se integra con Cloud Build.
gcloud artifacts repositories create adk-repo \ --repository-format=docker \ --location=$GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Obtener la URL del repositorio: ejecuta este comando para verificar la ruta completa a tu repositorio. Usarás este formato de ruta para etiquetar tu imagen de Docker en el siguiente paso.
gcloud artifacts repositories describe adk-repo \ --location $GOOGLE_CLOUD_LOCATION \ --project=$PROJECT_ID
Concede a la cuenta de servicio predeterminada de Compute Engine los roles de gestión de identidades y accesos necesarios: de forma predeterminada, la cuenta de servicio predeterminada de Compute Engine no tiene permisos para enviar imágenes a Artifact Registry ni para ver objetos en Cloud Storage o registros. Concede los roles necesarios para estas operaciones.
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
Crea y envía la imagen del contenedor del agente: ejecuta este comando para crear tu imagen de Docker y enviarla a Artifact Registry. Asegúrate de que el archivo Dockerfile y el código de la aplicación estén en el directorio
/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
Verifica que la imagen se haya enviado:
gcloud artifacts docker images list \ $GOOGLE_CLOUD_LOCATION-docker.pkg.dev/$PROJECT_ID/adk-repo/adk-agent \ --project=$PROJECT_ID
Inicializa Terraform: ve al directorio
terraform
e inicializa Terraform.terraform init
Revisa el plan de ejecución: este comando muestra los cambios que Terraform hará en la infraestructura.
terraform plan -var-file=default_env.tfvars
Aplica la configuración: ejecuta el plan de Terraform para crear los recursos en tu Google Cloud proyecto. Confirma la acción con
yes
cuando se te solicite.terraform apply -var-file=default_env.tfvars
Después de ejecutar estos comandos, Terraform aprovisiona tu clúster de GKE y tu repositorio de Artifact Registry, y configura los roles de gestión de identidades y accesos y las cuentas de servicio necesarios, incluida la federación de identidades de carga de trabajo para GKE.
Crea una cuenta de servicio para acceder a Vertex AI:
gcloud iam service-accounts create vertex-sa \ --project=$PROJECT_ID
Asigna el rol
aiplatform.user
a la cuenta de servicio. De esta forma, la cuenta de servicio puede interactuar con Vertex AI.gcloud projects add-iam-policy-binding $PROJECT_ID \ --member "serviceAccount:vertex-sa@$PROJECT_ID.iam.gserviceaccount.com" \ --role "roles/aiplatform.user"
Crea un KSA en tu clúster. Antes de ejecutar este comando, asegúrate de seguir las instrucciones que se indican en Configurar
kubectl
para que se comunique con tu clúster.kubectl create serviceaccount vertex-sa
Anota el KSA para vincularlo a tu cuenta de servicio:
kubectl annotate serviceaccount vertex-sa \ iam.gke.io/gcp-service-account=vertex-sa@$PROJECT_ID.iam.gserviceaccount.com
Concede permisos a tu cuenta de servicio para que actúe como usuario de Workload Identity Federation para GKE de la KSA:
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]"
- Conocer la estructura de la aplicación del agente: el directorio
/app
contiene los archivos principales de la aplicación del agente:main.py
: punto de entrada de la aplicación FastAPI, responsable de exponer la API del agente.agent.py
: contiene la lógica del agente del ADK, que define cómo usa Vertex AI y gestiona las solicitudes.__init__.py
: inicializa el paquete de Python.requirements.txt
: muestra todas las dependencias de Python de tu agente.Dockerfile
: define cómo se empaqueta tu aplicación en una imagen de Docker.
Crea el manifiesto de implementación del agente: en el directorio
tutorials-and-examples/adk/vertex
, crea el siguiente manifiesto como un archivo llamadoagent-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"
Sustituye los siguientes valores:
- IMAGE_URL: la URL completa de la imagen de Docker que has subido a Artifact Registry (por ejemplo,
us-central1-docker.pkg.dev/${PROJECT_ID}/adk-repo/adk-agent:latest
). Puedes obtener este valor del resultado del comandogcloud artifacts docker images list
de la sección anterior. También puedes ejecutar un comando como el siguiente:sed -i "s|image: IMAGE_URL|image: $IMAGE_URL|" agent-deployment.yaml
. - PROJECT_ID: tu ID de proyecto Google Cloud .
- REGION: la Google Cloud región en la que se aprovisiona el clúster de GKE.
- IMAGE_URL: la URL completa de la imagen de Docker que has subido a Artifact Registry (por ejemplo,
Aplica el manifiesto de implementación:
kubectl apply -f agent-deployment.yaml
Este comando crea el Deployment y los pods asociados de tu aplicación de agente en el clúster de GKE.
Exponer el agente: puedes usar estos métodos para exponer tu agente y permitir el acceso.
- Para acceder a tu agente desde fuera del clúster, crea un servicio de Kubernetes.
En el caso de las APIs web, es habitual que se trate de un servicio de tipo
LoadBalancer
. Para el desarrollo y las pruebas locales, usa el comando
kubectl port-forward
para acceder directamente a tu agente.
LoadBalancer
Crea el siguiente manifiesto como un archivo llamado
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
Aplica el archivo de manifiesto:
kubectl apply -f agent-service.yaml
La dirección IP externa puede tardar unos minutos en aprovisionarse.
Verifica que la dirección IP esté aprovisionada:
kubectl get service adk-agent-service
Busca el valor
EXTERNAL-IP
en el resultado. Una vez que el valor esté disponible, usa esta dirección IP para interactuar con el agente implementado.
port-forward
Si usas principalmente
port-forward
, te recomendamos que utilices un tipo de servicioClusterIP
en lugar deLoadBalancer
, ya que el servicioClusterIP
es interno y consume menos recursos.POD_NAME=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}') kubectl port-forward $POD_NAME 8000:8000
Este comando bloquea tu terminal, pero reenvía el tráfico de
localhost:8000
en tu máquina al agente que se ejecuta en el clúster de GKE.- Para acceder a tu agente desde fuera del clúster, crea un servicio de Kubernetes.
En el caso de las APIs web, es habitual que se trate de un servicio de tipo
Identifica el endpoint del agente: en función de cómo hayas decidido exponer tu agente en la sección anterior, identifica su endpoint accesible:
LoadBalancer
Recupera la dirección IP externa:
kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}'
Almacena la dirección IP externa en una variable de entorno para que sea más fácil de usar:
export AGENT_IP=$(kubectl get service adk-agent-service -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
La URL base de tu agente es
http://${AGENT_IP}
.
port-forward
Asegúrate de que el comando
kubectl port-forward
se ejecuta en un terminal independiente. La URL base de tu agente eshttp://localhost:8000
.Prueba la API del agente: prueba la API del agente haciendo una solicitud curl a su endpoint
/run
. El agente espera una carga útil JSON con un campo de mensaje. Sustituye AGENT_BASE_URL porhttp://${AGENT_IP}
(para LoadBalancer) ohttp://localhost:8000
(para reenvío de puertos).Crea una sesión. De esta forma, el agente se prepara para una nueva conversación.
# 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
Puedes consultar las aplicaciones disponibles con el siguiente comando:
curl -X GET AGENT_BASE_URL/list-apps
Envía una consulta al agente usando los detalles de la sesión del paso anterior.
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?" }] } }'
Deberías recibir una respuesta JSON de tu agente que indique que procesa las solicitudes correctamente e interactúa con el modelo de Gemini a través de Vertex AI. La respuesta contiene la réplica generada por el agente basada en tu mensaje.
Accede a la interfaz web del agente (si procede): si tu agente incluye una interfaz de usuario basada en la Web, accede a ella desplazándote hasta tu AGENT_BASE_URL en un navegador web. El ADK suele incluir una interfaz de usuario web básica para la interacción y la depuración. Por ejemplo, si has expuesto tu agente a través de un LoadBalancer y su
EXTERNAL-IP
es34.123.45.67
, ve ahttp://34.123.45.67
en tu navegador.En el terminal de Cloud Shell, ve al directorio
tutorials-and-examples/adk/vertex/
:cd tutorials-and-examples/adk/vertex/
Ejecuta este comando para quitar todos los recursos definidos en tus archivos de configuración de Terraform.
cd terraform terraform destroy
- Consulta cómo configurar Horizontal Pod Autoscaler (HPA) para ajustar automáticamente los recursos de tu agente en función de la demanda.
- Consulta cómo configurar Identity-Aware Proxy (IAP) para tus aplicaciones web que se ejecutan enGoogle Cloud, lo que proporciona una autorización centralizada para acceder a la interfaz de usuario de tu agente.
- Consulta cómo usar Cloud Logging y Cloud Monitoring para obtener información valiosa sobre el rendimiento y el estado de tu agente en el clúster de GKE.
- Descubre ejemplos experimentales en GKE AI Labs que pueden ayudarte a usar GKE para acelerar tus iniciativas de IA basada en agentes.
Preparar el entorno
En este tutorial se usa Cloud Shell para gestionar los recursos alojados en Google Cloud. Cloud Shell viene preinstalado con el software que necesitas para este tutorial, como
kubectl
,terraform
yGoogle Cloud CLI
.Para configurar tu entorno con Cloud Shell, sigue estos pasos:
Clonar el proyecto de ejemplo
Crear y configurar Google Cloud recursos
Para implementar tu agente en GKE, aprovisiona los recursos deGoogle Cloud necesarios. Puedes desplegar el agente mediante la CLI de gcloud para ejecutar comandos directamente o con Terraform para usar la infraestructura como código.
gcloud
En esta sección se proporcionan comandos de la CLI de gcloud para configurar el clúster de GKE, Artifact Registry y Workload Identity Federation for GKE para que se integren perfectamente con Vertex AI. Asegúrate de haber definido las variables de entorno tal como se describe en Preparar el entorno.
Terraform
En esta sección se describe cómo usar Terraform para aprovisionar tus recursos de Google Cloud. El repositorio de ejemplo que has clonado incluye los archivos de configuración de Terraform necesarios.
Para obtener más información sobre el uso de Terraform, consulta Compatibilidad de Terraform con GKE.
Configurar
kubectl
para que se comunique con tu clústerSi no has configurado
kubectl
para que se comunique con tu clúster, ejecuta el siguiente comando:gcloud container clusters get-credentials CLUSTER_NAME \ --location=${GOOGLE_CLOUD_LOCATION}
Sustituye CLUSTER_NAME por el nombre de tu clúster de GKE.
Configurar Workload Identity Federation para acceder a GKE
Puedes saltarte este paso si usas Terraform. Este proceso vincula una cuenta de servicio de Kubernetes (KSA) a una cuenta de servicio de gestión de identidades y accesos (IAM) para conceder de forma segura a tu agente acceso a los servicios de Google Cloud .
Desplegar y configurar la aplicación del agente
Después de configurar tus Google Cloud recursos, prepara tu aplicación de agente para la implementación y configura su tiempo de ejecución en GKE. Para ello, debes definir el código de tu agente, crear un Dockerfile para empaquetarlo en un contenedor y escribir un manifiesto de Kubernetes para desplegarlo en tu clúster.
Probar el agente desplegado
Ahora que tu aplicación de agente se ha implementado y expuesto, prueba su funcionalidad.
En esta sección se describe cómo identificar el endpoint de tu agente y probar la API del agente.
Limpieza
Para evitar que los recursos utilizados en este tutorial se cobren en tu cuenta de Google Cloud, elimina el proyecto que contiene los recursos o conserva el proyecto y elimina los recursos.
Eliminar los recursos desplegados
Para evitar que se apliquen cargos en tu cuenta de Google Cloud por los recursos que has creado en esta guía, ejecuta los siguientes comandos:
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
Sustituye CLUSTER_NAME por el nombre de tu clúster de GKE.
Terraform
Siguientes pasos
-