1. Introducción
Los modelos de lenguaje grandes (LLM) están cambiando la forma en que creamos aplicaciones inteligentes. Sin embargo, preparar estos modelos potentes para su uso en el mundo real puede ser complicado. Necesitan mucha potencia de procesamiento, especialmente tarjetas gráficas (GPU), y formas inteligentes de controlar muchas solicitudes a la vez. Además, quieres mantener bajos los costos y que tu aplicación funcione sin problemas ni demoras.
En este codelab, se te mostrará cómo abordar estos desafíos. Usaremos dos herramientas clave:
- vLLM: Piensa en esto como un motor superrápido para LLMs. Esto hace que tus modelos se ejecuten de manera mucho más eficiente, ya que procesan más solicitudes a la vez y reducen el uso de memoria.
- Google Cloud Run: Esta es la plataforma sin servidores de Google. Es fantástico para implementar aplicaciones, ya que se encarga de todo el ajuste de escala por ti, desde cero usuarios hasta miles, y viceversa. Lo mejor de todo es que Cloud Run ahora admite GPUs, que son esenciales para alojar LLMs.
En conjunto, vLLM y Cloud Run ofrecen una forma potente, flexible y rentable de entregar tus LLMs. En esta guía, implementarás un modelo abierto y lo pondrás a disposición como una API web estándar.
Qué aprenderás**:**
- Cómo elegir el tamaño y la variante del modelo adecuados para la entrega
- Cómo configurar vLLM para que entregue extremos de API compatibles con OpenAI
- Cómo contenerizar el servidor de vLLM con Docker
- Cómo enviar tu imagen de contenedor a Google Artifact Registry
- Cómo implementar el contenedor en Cloud Run con aceleración por GPU
- Cómo probar el modelo implementado
Requisitos**:**
- Un navegador, como Chrome, para acceder a la consola de Google Cloud
- Una conexión a Internet confiable
- Un proyecto de Google Cloud con la facturación habilitada
- Un token de acceso de Hugging Face (crea uno aquí si aún no lo tienes)
- Conocimientos básicos sobre Python, Docker y la interfaz de línea de comandos
- Una mente curiosa y ganas de aprender
2. Antes de comenzar
Configura el proyecto de Google Cloud
Este codelab requiere un proyecto de Google Cloud con una cuenta de facturación activa.
- Para las sesiones dirigidas por un instructor: Si estás en un aula, el instructor te proporcionará la información necesaria sobre el proyecto y la facturación. Sigue las instrucciones del instructor para completar la configuración.
- Para estudiantes independientes: Si lo haces por tu cuenta, deberás configurar un proyecto nuevo y activar una cuenta de facturación de prueba. Sigue los pasos que se indican a continuación para comenzar.
- Presiona (Ctrl + Mayúsculas + N o Cmd + Mayúsculas + N) para abrir una ventana de incógnito.
- Ve a este portal de canje desde la ventana de incógnito.
- Accede y obtén una cuenta de facturación de prueba con tu cuenta personal de Gmail
- Sigue las instrucciones de esta presentación para completar la configuración.
Configura Cloud Shell
Ahora, configuremos Cloud Shell, una práctica interfaz de línea de comandos directamente en la consola de Google Cloud.
Iniciar Cloud Shell
En la esquina superior derecha de la consola de Google Cloud, verás un ícono que parece una terminal (>_). Haz clic en él para activar Cloud Shell.
Autorizar acceso
Si se te solicita, haz clic en Autorizar para otorgarle a Cloud Shell los permisos necesarios para interactuar con tu proyecto de Google Cloud.
Verificar el ID del proyecto
Observa el Project ID en tu terminal. Se escribirá en amarillo, como se muestra en la siguiente imagen. Asegúrate de que sea el mismo ID que registraste cuando creaste el proyecto.
Si el Project ID se refleja correctamente en la terminal, continúa con el paso Habilita las APIs necesarias.
ID del proyecto correcto (si es necesario)
Si el Project ID es incorrecto o no aparece, usa este comando para corregirlo. Asegúrate de reemplazar el texto your-project-id por tu Project ID correcto antes de ejecutar el comando.
gcloud config set project your-project-id
Habilita las APIs necesarias
Para usar los servicios de Google Cloud, como Cloud Run, primero debes activar sus respectivas APIs para tu proyecto. Ejecuta los siguientes comandos en Cloud Shell para habilitar los servicios necesarios para este codelab:
gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com
3. Cómo elegir el modelo adecuado
Puedes encontrar muchos modelos abiertos en sitios web como Hugging Face Hub y Kaggle. Cuando quieras usar uno de estos modelos en un servicio como Google Cloud Run, debes elegir uno que se ajuste a los recursos que tienes (es decir, una GPU NVIDIA L4).
Más allá del tamaño, recuerda considerar lo que el modelo puede hacer. No todos los modelos son iguales; cada uno tiene sus propias ventajas y desventajas. Por ejemplo, algunos modelos pueden procesar diferentes tipos de entrada (como imágenes y texto, lo que se conoce como capacidades multimodales), mientras que otros pueden recordar y procesar más información a la vez (lo que significa que tienen ventanas de contexto más grandes). A menudo, los modelos más grandes tendrán capacidades más avanzadas, como la llamada a funciones y el pensamiento.
También es importante verificar si la herramienta de entrega (vLLM en este caso) admite el modelo que deseas. Puedes consultar todos los modelos compatibles con vLLM aquí.
Ahora, exploremos Gemma 3, la familia más reciente de modelos de lenguaje grandes (LLM) disponibles de forma abierta de Google. Gemma 3 viene en cuatro escalas diferentes según su complejidad, medida en parámetros: 1,000 millones, 4,000 millones, 12,000 millones y 27,000 millones.
Para cada uno de estos tamaños, encontrarás dos tipos principales:
- Una versión base (entrenada previamente): Este es el modelo fundamental que aprendió de una gran cantidad de datos.
- Una versión ajustada según las instrucciones: Esta versión se perfeccionó aún más para comprender y seguir mejor instrucciones o comandos específicos.
Los modelos más grandes (4,000 millones, 12,000 millones y 27,000 millones de parámetros) son multimodales, lo que significa que pueden comprender y trabajar con imágenes y texto. Sin embargo, la variante más pequeña, con 1,000 millones de parámetros, se enfoca únicamente en el texto.
En este codelab, usaremos 1,000 millones de variantes de Gemma 3: gemma-3-1b-it. Usar un modelo más pequeño también te ayuda a aprender a trabajar con recursos limitados, lo que es importante para mantener bajos los costos y asegurarte de que tu app se ejecute sin problemas en la nube.
4. Variables de entorno y Secrets
Crea un archivo de entorno
Antes de continuar, es una buena práctica tener en un solo lugar todos los parámetros de configuración que usarás a lo largo de este codelab. Para comenzar, abre tu terminal y sigue estos pasos:
- Crea una carpeta nueva para este proyecto.
- Navega a la carpeta recién creada.
- Crea un archivo .env vacío dentro de esta carpeta (este archivo contendrá más adelante tus variables de entorno).
Este es el comando para realizar esos pasos:
mkdir vllm-gemma3
cd vllm-gemma3
touch .env
A continuación, copia las variables que se indican a continuación y pégalas en el archivo.env que acabas de crear. Recuerda reemplazar los valores de marcador de posición (your_project_id y your_region) por la información específica de tu proyecto. Por ejemplo, PROJECT_ID=unique-ai-project y REGION=us-central1.
PROJECT_ID=your_project_id
REGION=your_region
MODEL_PROVIDER=google
MODEL_VARIANT=gemma-3-1b-it
MODEL_NAME=${MODEL_PROVIDER}/${MODEL_VARIANT}
AR_REPO_NAME=vllm-gemma3-repo
SERVICE_NAME=${MODEL_VARIANT}-service
IMAGE_NAME=${REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/${SERVICE_NAME}
SERVICE_ACC_NAME=${SERVICE_NAME}-sa
SERVICE_ACC_EMAIL=${SERVICE_ACC_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
Una vez que se edita y guarda el archivo.env, escribe este comando para cargar esas variables de entorno en la sesión de la terminal:
source .env
Puedes probar si las variables se cargaron correctamente o no haciendo eco de una de ellas. Por ejemplo:
echo $SERVICE_NAME
Si obtienes el mismo valor que asignaste en el archivo.env, las variables se cargaron correctamente.
Almacena un secreto en Secret Manager
Para cualquier dato sensible, incluidos los códigos de acceso, las credenciales y las contraseñas, se recomienda utilizar un administrador de secretos.
Antes de usar los modelos de Gemma 3, primero debes confirmar que aceptas los Términos y Condiciones, ya que están restringidos. Visita la tarjeta del modelo de Gamma3 en Hugging Face Hub y acepta los Términos y Condiciones.
Una vez que tengas el token de acceso de Hugging Face, ve a la página de Secret Manager y crea un secreto siguiendo estas instrucciones.
- Ve a Google Cloud Console
- Selecciona el proyecto en la barra desplegable de la esquina superior izquierda.
- Busca Secret Manager en la barra de búsqueda y haz clic en esa opción cuando aparezca.
Cuando estés en la página de Secret Manager, haz lo siguiente:
- Haz clic en el botón + Crear secreto.
- Completa la siguiente información:
- Nombre: HF_TOKEN
- Valor del secreto: <tu_token_de_acceso_a_hf>
- Cuando termines, haz clic en el botón Crear secreto.
Ahora deberías tener el token de acceso de Hugging Face como un secreto en Secret Manager de Google Cloud.
Para probar tu acceso al secreto, ejecuta el siguiente comando en la terminal, que lo recuperará de Secret Manager:
gcloud secrets versions access latest --secret=HF_TOKEN
Deberías ver que se recupera tu token de acceso y se muestra en la ventana de la terminal.
5. Crea una cuenta de servicio
Para mejorar la seguridad y administrar el acceso de manera eficaz en un entorno de producción, los servicios deben operar con cuentas de servicio dedicadas que se limiten estrictamente a los permisos necesarios para sus tareas específicas.
Ejecuta este comando para crear una cuenta de servicio
gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'
El siguiente comando adjunta el permiso necesario
gcloud secrets add-iam-policy-binding HF_TOKEN \
--member="serviceAccount:${SERVICE_ACC_EMAIL}" \
--role="roles/secretmanager.secretAccessor"
6. Crea una imagen en Artifact Registry
En este paso, se crea una imagen de Docker que incluye los pesos del modelo y vLLM preinstalado.
1. Crea un repositorio de Docker en Artifact Registry
Creemos un repositorio de Docker en Artifact Registry para enviar tus imágenes compiladas. Ejecuta el siguiente comando en la terminal:
gcloud artifacts repositories create ${AR_REPO_NAME} \
--repository-format docker \
--location ${REGION}
2. Almacena el modelo
Según la documentación de prácticas recomendadas para GPUs, puedes almacenar modelos de AA dentro de imágenes de contenedores o optimizar su carga desde Cloud Storage. Por supuesto, cada enfoque tiene sus propias ventajas y desventajas. Puedes leer la documentación para obtener más información sobre ellos. Para simplificar, solo almacenaremos el modelo en la imagen del contenedor.
3. Crea un archivo de Docker
Crea un archivo llamado Dockerfile y copia el siguiente contenido en él:
FROM vllm/vllm-openai:v0.9.0
ARG MODEL_NAME
ARG HF_TOKEN
ENV HF_HOME=/model-cache
ENV MODEL_NAME=${MODEL_NAME}
# Use the HF_TOKEN argument to log in and download the model
RUN huggingface-cli login --token ${HF_TOKEN} && \
huggingface-cli download ${MODEL_NAME}
ENV HF_HUB_OFFLINE=1
EXPOSE 8080
ENTRYPOINT python3 -m vllm.entrypoints.openai.api_server \
--port ${PORT:-8080} \
--model ${MODEL_NAME} \
--gpu-memory-utilization 0.90 \
${MAX_MODEL_LEN:+--max-model-len "$MAX_MODEL_LEN"}
4. Crea un archivo cloudbuild.yaml
A continuación, crea un archivo llamado cloudbuild.yaml en el mismo directorio. Este archivo define los pasos que debe seguir Cloud Build. Copia y pega el siguiente contenido en cloudbuild.yaml:
steps:
- name: 'gcr.io/cloud-builders/docker'
entrypoint: 'bash'
args:
- '-c'
- |
docker build \
--build-arg MODEL_NAME=${_MODEL_NAME} \
--build-arg HF_TOKEN=$$HF_TOKEN_SECRET \
-t ${_IMAGE_NAME} .
secretEnv: ['HF_TOKEN_SECRET']
images:
- '${_IMAGE_NAME}'
availableSecrets:
secretManager:
- versionName: projects/${PROJECT_ID}/secrets/HF_TOKEN/versions/latest
env: 'HF_TOKEN_SECRET'
5. Envía la compilación a Cloud Build
Copia y pega el siguiente código y ejecútalo en la terminal:
gcloud builds submit . \
--config=cloudbuild.yaml \
--region=${REGION} \
--substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}
Este comando sube tu código (Dockerfile y cloudbuild.yaml), pasa tus variables de shell como sustituciones (_MODEL_NAME y _IMAGE_NAME) y comienza la compilación.
Cloud Build ahora ejecutará los pasos definidos en cloudbuild.yaml. Puedes seguir los registros en tu terminal o hacer clic en el vínculo a los detalles de la compilación en la consola de Cloud. Una vez que finalice, la imagen de contenedor estará disponible en tu repositorio de Artifact Registry, lista para la implementación.
7. Prueba el servicio
Ejecuta el siguiente comando en la terminal para crear un proxy y poder acceder al servicio mientras se ejecuta en localhost:
gcloud run services proxy ${SERVICE_NAME} --region ${REGION}
En una nueva ventana de terminal, ejecuta este comando de curl en la terminal para probar la conexión.
curl -X POST http://localhost:8080/v1/completions \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d '{
"model": "google/gemma-3-1b-it",
"prompt": "Cloud Run is a ",
"max_tokens": 128,
"temperature": 0.90
}'
Si ves un resultado similar al siguiente:
{"id":"cmpl-e96d05d2893d42939c1780d44233defa","object":"text_completion","created":1746870778,"model":"google/gemma-3-1b-it","choices":[{"index":0,"text":"100% managed Kubernetes service. It's a great option for many use cases.\n\nHere's a breakdown of key features and considerations:\n\n* **Managed Kubernetes:** This means Google handles the underlying infrastructure, including scaling, patching, and maintenance. You don't need to worry about managing Kubernetes clusters.\n* **Serverless:** You only pay for the compute time your application actually uses. No charges when your code isn't running.\n* **Scalability:** Cloud Run automatically scales your application based on demand. You can easily scale up or down to handle fluctuating traffic.\n*","logprobs":null,"finish_reason":"length","stop_reason":null,"prompt_logprobs":null}],"usage":{"prompt_tokens":6,"total_tokens":134,"completion_tokens":128,"prompt_tokens_details":null}}
8. Conclusión
¡Felicitaciones! Completaste este codelab correctamente. Aprendiste a hacer lo siguiente:
- Elige un tamaño de modelo adecuado para una implementación de destino.
- Configura vLLM para que entregue una API compatible con OpenAI.
- Organiza de forma segura en contenedores el servidor de vLLM y las ponderaciones del modelo con Docker.
- Envía una imagen de contenedor a Google Artifact Registry.
- Implementa un servicio acelerado por GPU en Cloud Run.
- Probar un modelo implementado y autenticado
No dudes en explorar la implementación de otros modelos interesantes, como Llama, Mistral o Qwen, para continuar tu recorrido de aprendizaje.
9. Limpieza
Para evitar que se generen cargos en el futuro, es importante que borres los recursos que creaste. Ejecuta los siguientes comandos para limpiar tu proyecto.
1. Borra el servicio de Cloud Run:
gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet
2. Borra el repositorio de Artifact Registry:
gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet
3. Borra la cuenta de servicio:
gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet
4. Borra el secreto de Secret Manager:
gcloud secrets delete HF_TOKEN --quiet