Se usó la API de Cloud Translation para traducir esta página.

Implementa una aplicación de IA con agentes en GKE con el kit de desarrollo de agentes (ADK) y un LLM autohospedado

En este instructivo, se muestra cómo implementar y administrar aplicaciones de IA/ML basadas en agentes en contenedores con Google Kubernetes Engine (GKE). Si combinas el kit de desarrollo de agentes (ADK) de Google con un modelo de lenguaje grande (LLM) autoalojado, como Llama 3.1, que se entrega con vLLM, puedes poner en funcionamiento agentes de IA de manera eficiente y a gran escala, y mantener el control total de la pila de modelos. En este instructivo, se explica el proceso integral para llevar un agente basado en Python desde el desarrollo hasta la implementación en producción en un clúster de GKE Autopilot con aceleración de GPU.

Este instructivo está dirigido a ingenieros de aprendizaje automático (AA), desarrolladores y arquitectos de nube que estén interesados en usar las capacidades de organización de contenedores de Kubernetes para entregar aplicaciones de IA/AA basadas en agentes. Para obtener más información sobre los roles comunes y las tareas de ejemplo a los que hacemos referencia en el contenido de Google Cloud, consulta Roles de usuario y tareas comunes de GKE Enterprise.

Antes de comenzar, asegúrate de conocer la siguiente información:

Fondo

En esta sección, se describen las tecnologías clave que se usan en este instructivo.

Kit de desarrollo de agentes (ADK)

El Kit de desarrollo de agentes (ADK) es un framework flexible y modular para desarrollar y, luego, implementar agentes de IA. Si bien está optimizado para Gemini y el ecosistema de Google, el ADK no requiere que uses un modelo o una implementación específicos, y está diseñado para ser compatible con otros frameworks. El ADK se diseñó para que el desarrollo de agentes se asemeje más al desarrollo de software, de modo que los desarrolladores puedan crear, implementar y coordinar con mayor facilidad arquitecturas basadas en agentes que abarcan desde tareas básicas hasta flujos de trabajo complejos.

Para obtener más información, consulta la documentación del ADK.

Servicio de Kubernetes administrado por GKE

Google Cloud ofrece una variedad de servicios, incluido GKE, que es adecuado para implementar y administrar cargas de trabajo de IA/AA. GKE es un servicio administrado de Kubernetes que simplifica la implementación, el escalamiento y la administración de aplicaciones alojadas en contenedores. GKE proporciona la infraestructura necesaria, incluidos recursos escalables, procesamiento distribuido y redes eficientes, para satisfacer las demandas computacionales de los LLM.

Para obtener más información sobre los conceptos clave de Kubernetes, consulta Comienza a aprender sobre Kubernetes. Para obtener más información sobre GKE y cómo te ayuda a escalar, automatizar y administrar Kubernetes, consulta la descripción general de GKE.

vLLM

vLLM es un framework de entrega de LLM de código abierto altamente optimizado que puede aumentar la capacidad de procesamiento de entrega en GPUs, con funciones como las siguientes:

Implementación optimizada de transformadores con PagedAttention.
Agrupación en lotes continua para mejorar la capacidad de procesamiento general de la entrega
Paralelismo de tensor y entrega distribuida en varias GPUs

Para obtener más información, consulta la documentación de vLLM.

Prepare el entorno

En este instructivo, se usa Cloud Shell para administrar recursos alojados en Google Cloud. Cloud Shell viene preinstalado con el software que necesitas para este instructivo, incluidos kubectl, terraform y Google Cloud CLI.

Para configurar tu entorno con Cloud Shell, sigue estos pasos:

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 un panel de la consola. Google Cloud
Configura las variables de entorno predeterminadas:
```
gcloud config set project PROJECT_ID
export GOOGLE_CLOUD_REGION=REGION
export PROJECT_ID=PROJECT_ID
```
Reemplaza los siguientes valores:
- PROJECT_ID: El Google Cloud ID del proyecto.
- REGION: La Google Cloud región (por ejemplo, us-east4) para aprovisionar tu clúster de GKE, Artifact Registry y otros recursos regionales. Asegúrate de especificar una región que admita GPU L4 y tipos de máquinas G2. Para verificar la disponibilidad de regiones, consulta Regiones y zonas de GPU en la documentación de Compute Engine.

Clona el proyecto de ejemplo

Desde la terminal de Cloud Shell, clona el repositorio de código de muestra del instructivo:
```
git clone https://github.com/GoogleCloudPlatform/kubernetes-engine-samples.git
```

Navega hacia el directorio del instructivo:

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

Crea y configura recursos de Google Cloud

Para implementar tu agente, primero debes aprovisionar los recursos de Google Cloudnecesarios. Puedes crear el clúster de GKE y el repositorio de Artifact Registry con gcloud CLI o Terraform.

gcloud

En esta sección, se proporcionan comandos de gcloud CLI para configurar tu clúster de GKE y Artifact Registry.

Crea un clúster de GKE: Puedes implementar tu aplicación agentiva alojada en contenedores en un clúster de GKE Autopilot o Standard. Usa un clúster de Autopilot para una experiencia de Kubernetes completamente administrada. Para elegir el modo de operación de GKE que mejor se adapte a tus cargas de trabajo, consulta Acerca de los modos de operación de GKE.
Autopilot
En Cloud Shell, ejecute el siguiente comando:
```
gcloud container clusters create-auto CLUSTER_NAME \
    --location=$GOOGLE_CLOUD_REGION
```
Reemplaza CLUSTER_NAME por el nombre de tu clúster de GKE.

Con Autopilot, GKE aprovisiona automáticamente nodos según las solicitudes de recursos de tu carga de trabajo. La GPU requerida para el LLM se solicita en el manifiesto deploy-llm.yaml con un nodeSelector.

Para agregar una solicitud de nodeSelector a la GPU de nvidia-l4, sigue estos pasos:
1. Abre kubernetes-engine-samples/ai-ml/adk-vllm/deploy-llm/deploy-llm.yaml en un editor.
2. Agrega el siguiente nodeSelector debajo de spec.template.spec:
  nodeSelector: cloud.google.com/gke-accelerator: nvidia-l4
Estándar
1. En Cloud Shell, ejecuta el siguiente comando para crear un clúster de Standard:
  gcloud container clusters create CLUSTER_NAME \ --location=$GOOGLE_CLOUD_REGION
  Reemplaza CLUSTER_NAME por el nombre de tu clúster de GKE.
2. Crea un grupo de nodos habilitado para GPU para tu clúster ejecutando el siguiente comando:
  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
  El archivo deploy-llm.yaml especifica una GPU nvidia-l4, que está disponible en la serie de máquinas G2. Para obtener más información sobre este tipo de máquina, consulta Tipos de máquinas con GPU en la documentación de Compute Engine.
Crea un repositorio de Artifact Registry: Crea un repositorio de Artifact Registry para almacenar y administrar de forma segura la imagen de contenedor de Docker de tu agente.
```
gcloud artifacts repositories create REPO_NAME \
    --repository-format=docker \
    --location=$GOOGLE_CLOUD_REGION
```
Reemplaza REPO_NAME por el nombre del repositorio de Artifact Registry que deseas usar (por ejemplo, adk-repo).
Obtén la URL del repositorio: Para verificar la ruta completa a tu repositorio, ejecuta este comando. Usarás este formato para etiquetar tu imagen de Docker cuando compiles la imagen del agente.
```
gcloud artifacts repositories describe REPO_NAME \
    --location $GOOGLE_CLOUD_REGION
```

Terraform

En esta sección, se describe cómo usar la configuración de Terraform incluida en el repositorio de ejemplo para aprovisionar tus recursos de Google Cloud automáticamente.

Navega al directorio de Terraform: El directorio \terraform contiene todos los archivos de configuración necesarios para crear el clúster de GKE y otros recursos requeridos.
```
cd terraform
```
Crea un archivo de variables de Terraform: Copia el archivo de variables de ejemplo proporcionado (example_vars.tfvars) para crear tu propio archivo vars.tfvars.
```
cp example_vars.tfvars vars.tfvars
```
Abre el archivo vars.tfvars en un editor y reemplaza los valores de marcador de posición por tu configuración específica. Como mínimo, debes reemplazar PROJECT_ID por el ID de tu proyecto Google Cloud y CLUSTER_NAME por el nombre de tu clúster de GKE.
Inicializa Terraform: Para descargar los complementos del proveedor necesarios para Google Cloud, ejecuta este comando.
```
terraform init
```
Revisa el plan de ejecución: Este comando muestra los cambios en la infraestructura que realizará Terraform.
```
terraform plan -var-file=vars.tfvars
```
Aplica la configuración: Para crear los recursos en tu proyecto de Google Cloud , ejecuta el plan de Terraform. Confirma con yes cuando se te solicite.
```
terraform apply -var-file=vars.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 IAM y las cuentas de servicio necesarios, incluida la federación de identidades para cargas de trabajo para GKE.

Si deseas obtener más información para usar Terraform, consulta Aprovisiona recursos de GKE con Terraform.

Configura `kubectl` para comunicarse con tu clúster

Para configurar kubectl para que se comunique con tu clúster, ejecuta el siguiente comando:

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

Reemplaza CLUSTER_NAME por el nombre de tu clúster de GKE.

Compila la imagen del agente

Después de crear la infraestructura con gcloud CLI o Terraform, sigue estos pasos para compilar tu aplicación del agente.

Otorga el rol de IAM requerido para Cloud Build: El servicio de Cloud Build requiere permisos para enviar la imagen del contenedor del agente a Artifact Registry. Otorga el rol de roles/artifactregistry.writer a la cuenta de servicio predeterminada de Compute Engine, que usa Cloud Build.
1. Construye el correo electrónico para la cuenta de servicio predeterminada de Compute Engine:
```
export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")
export COMPUTE_SA_EMAIL=${PROJECT_NUMBER}-compute@developer.gserviceaccount.com
```
2. Otorga el rol roles/artifactregistry.writer a la cuenta de servicio:
```
gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member=serviceAccount:${COMPUTE_SA_EMAIL} \
    --role=roles/artifactregistry.writer
```
Compila y envía la imagen del contenedor del agente: Desde el directorio raíz del proyecto (adk/llama/vllm), compila tu imagen de Docker y envíala a Artifact Registry ejecutando estos comandos.
```
export IMAGE_URL="${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME/adk-agent:latest"
gcloud builds submit --tag $IMAGE_URL
```
Verifica que se haya enviado la imagen: Después de que se complete correctamente el proceso de compilación, verifica que la imagen de contenedor de tu agente se haya enviado a Artifact Registry. Para ello, enumera las imágenes de tu repositorio.
```
gcloud artifacts docker images list ${GOOGLE_CLOUD_REGION}-docker.pkg.dev/${PROJECT_ID}/REPO_NAME
```
Deberías ver un resultado que enumere la imagen que acabas de enviar y etiquetar como latest.

Implementa el modelo

Después de configurar tu clúster de GKE y compilar la imagen del agente, el siguiente paso es implementar el modelo Llama 3.1 alojado por tu cuenta en el clúster. Para ello, implementa un servidor de inferencia de vLLM preconfigurado que extrae el modelo de Hugging Face y lo entrega de forma interna dentro del clúster.

Crea un secreto de Kubernetes para las credenciales de Hugging Face: Para permitir que el clúster de GKE descargue el modelo Llama 3.1 restringido, debes proporcionar tu token de Hugging Face como un secreto de Kubernetes. El manifiesto deploy-llm.yaml está configurado para usar este secreto para la autenticación.
```
kubectl create secret generic hf-secret \
    --from-literal=hf-token-secret=HUGGING_FACE_TOKEN
```
Reemplaza HUGGING_FACE_TOKEN por tu token.
Ver el manifiesto: Desde el directorio raíz del proyecto (adk/llama/vllm), navega al directorio /deploy-llm que contiene el manifiesto de Deployment del modelo.
```
cd deploy-llm
```
Aplica el manifiesto: Ejecuta el siguiente comando para aplicar el manifiesto deploy-llm.yaml a tu clúster.
```
kubectl apply -f deploy-llm.yaml
```
El comando crea tres recursos de Kubernetes:
- Es una implementación que ejecuta el servidor de vLLM, configurado para usar el modelo meta-llama/Llama-3.1-8B-Instruct.
- Un Service llamado vllm-llama3-service que expone el servidor de vLLM en una dirección IP interna del clúster, lo que permite que el agente del ADK se comunique con él.
- Un ConfigMap que contiene una plantilla de chat de Jinja que requiere el modelo de Llama 3.1
Verifica la implementación del modelo: El servidor de vLLM extrae los archivos del modelo de Hugging Face. Este proceso puede tardar varios minutos. Puedes supervisar el estado del Pod para asegurarte de que esté listo.
1. Espera a que la Deployment esté disponible.
```
kubectl wait --for=condition=available --timeout=600s deployment/vllm-llama3-deployment
```
2. Consulta los registros del Pod en ejecución para confirmar que el servidor se inició correctamente.
```
export LLM_POD=$(kubectl get pods -l app=vllm-llama3 -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $LLM_POD
```
  La implementación estará lista cuando veas un resultado de registro similar al siguiente, que indica que se inició el servidor del LLM y que las rutas de la API están 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. Envía una solicitud directamente al servidor del modelo para confirmar que el LLM está listo. Para ello, abre una nueva terminal de Cloud Shell y ejecuta el siguiente comando para retransmitir vllm-llama3-service a tu máquina local:
```
kubectl port-forward service/vllm-llama3-service 8000:8000
```
4. En otra terminal, envía una solicitud de muestra al extremo de API del modelo con curl. Por ejemplo:
```
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 el comando devuelve una respuesta JSON exitosa, tu LLM está listo. Ahora puedes finalizar el proceso de reenvío de puertos. Para ello, vuelve a la ventana de la terminal y presiona Ctrl+C. Luego, continúa con la implementación del agente.

Implementa la aplicación del agente

El siguiente paso es implementar la aplicación del agente basada en el ADK.

Navega al directorio /deploy-agent: Desde el directorio raíz de tu proyecto (adk/llama/vllm), navega al directorio /deploy-agent que contiene el código fuente del agente y el manifiesto de implementación.
```
cd ../deploy-agent
```
Actualiza el manifiesto de implementación del agente:
1. El archivo de manifiesto deploy-agent.yaml de muestra contiene un marcador de posición para el ID de tu proyecto en la URL de la imagen de contenedor. Debes reemplazar el marcador de posición por el ID de tu proyecto Google Cloud .
```
image: us-central1-docker.pkg.dev/PROJECT_ID/adk-repo/adk-agent:latest
```
  Para realizar esta sustitución en el lugar, puedes ejecutar el siguiente comando:
```
sed -i "s/<PROJECT_ID>/$PROJECT_ID/g" deploy-agent.yaml
```
2. Asegúrate de que la ruta de readinessProbe esté establecida en / en lugar de /dev-ui. Para realizar esta sustitución en el lugar, puedes ejecutar el siguiente comando:
```
sed -i "s|path: /dev-ui/|path: /|g" deploy-agent.yaml
```
Aplica el manifiesto: Ejecuta el siguiente comando para aplicar el manifiesto deploy-agent.yaml a tu clúster.
```
kubectl apply -f deploy-agent.yaml
```
Con este comando, se crean dos recursos de Kubernetes:
- Una Deployment llamada adk-agent que ejecuta la imagen de contenedor del agente compilado de forma personalizada.
- Un servicio llamado adk-agent de tipo NodePort que expone la aplicación del agente para que se pueda acceder a ella con fines de prueba.
Verifica la implementación del agente: Comprueba el estado del Pod para asegurarte de que se ejecute correctamente.
1. Espera a que la Deployment esté disponible:
```
kubectl wait --for=condition=available --timeout=300s deployment/adk-agent
```
2. Observa los registros del Pod del agente en ejecución:
```
export AGENT_POD=$(kubectl get pods -l app=adk-agent -o jsonpath='{.items[0].metadata.name}')
kubectl logs -f $AGENT_POD
```

La implementación se realiza correctamente cuando ves un resultado de registro similar al siguiente, que indica que el servidor de Uvicorn está en ejecución y listo para aceptar solicitudes:

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

Prueba tu agente implementado

Después de implementar correctamente el servidor de vLLM y la aplicación del agente, puedes probar la funcionalidad de extremo a extremo interactuando con la IU web del agente.

Reenvía el servicio del agente a tu máquina local: El servicio adk-agent es de tipo NodePort, pero la forma más directa de acceder a él desde tu entorno de Cloud Shell es usar el comando kubectl port-forward. Ejecuta este comando para crear un túnel seguro hacia el Pod del agente.
```
kubectl port-forward $AGENT_POD 8001:8001
```
Accede a la IU web del agente: En Cloud Shell, haz clic en el botón Vista previa en la Web y selecciona Vista previa en el puerto 8001. Se abrirá una pestaña nueva del navegador que mostrará la interfaz de chat del agente.
Interactúa con el agente: Hazle una pregunta al agente que invoque su herramienta get_weather. Por ejemplo:
```
What's the weather like in Tokyo?
```
Primero, el agente llamará al LLM para comprender la intención e identificar la necesidad de usar la herramienta get_weather. Luego, ejecutará la herramienta con "Tokio" como parámetro. Por último, usará el resultado de la herramienta para generar una respuesta. Deberías ver una respuesta similar a la siguiente:
```
  The weather in Tokyo is 25°C and sunny.
```
(Opcional) Verifica la llamada a la herramienta en los registros: Puedes observar la interacción del agente con el LLM y la ejecución de la herramienta si ves los registros de los Pods respectivos.
1. Registros del Pod del agente: En una terminal nueva, visualiza los registros del Pod adk-agent. Verás la llamada a la herramienta y su resultado.
```
kubectl logs -f $AGENT_POD
```
  El resultado muestra que se llamó a la herramienta y que se procesó el resultado.
2. Registros del Pod del LLM: Visualiza los registros del Pod de vllm-llama3-deployment para ver la solicitud entrante del agente.
```
kubectl logs -f $LLM_POD
```
  En los registros, se muestra la instrucción completa que el agente envió al LLM, incluido el mensaje del sistema, tu búsqueda y la definición de la herramienta get_weather.

Cuando termines de realizar las pruebas, puedes finalizar el proceso de port-forward. Para ello, vuelve a la ventana de la terminal y presiona Ctrl+C.