Usa vLLM en GKE para ejecutar la inferencia con DeepSeek-V3.2-Speciale

En este instructivo, se muestra cómo implementar y entregar un modelo de lenguaje DeepSeek-V3.2-Speciale con el framework de vLLM. Implementas este modelo en un clúster de Google Kubernetes Engine (GKE) Autopilot y consumes una sola máquina virtual (VM) A4 que tiene ocho GPUs B200.

En este instructivo, se supone que revisaste el modelo de lenguaje DeepSeek-V3.2-Speciale y verificaste que sus capacidades cumplen con los requisitos de tu caso de uso.

Este instructivo está dirigido a ingenieros de aprendizaje automático (AA), administradores y operadores de plataformas, y especialistas en datos y AA que estén interesados en usar las capacidades de organización de contenedores de Kubernetes para controlar las cargas de trabajo de inferencia.

Objetivos

Accede a DeepSeek-V3.2-Speciale con Hugging Face.
Prepara el entorno.
Crea un clúster de GKE en modo Autopilot.
Crea un secreto de Kubernetes para las credenciales de Hugging Face.
Implementa un contenedor de vLLM en tu clúster de GKE.
Interactúa con DeepSeek-V3.2-Speciale con curl.
Realiza una limpieza

Costos

En este instructivo, se usan componentes facturables de Google Cloud, que incluyen lo siguiente:

Para generar una estimación de costos en función del uso previsto, usa la calculadora de precios.

Antes de comenzar

Accede a tu Google Cloud cuenta de. Si eres nuevo en Google Cloud, crea una cuenta para evaluar el rendimiento de nuestros productos en situaciones reales. Los clientes nuevos también obtienen $300 en créditos gratuitos para ejecutar, probar y, además, implementar cargas de trabajo.

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén más información para otorgar roles.

Crea un proyecto de: Google Cloud
```
gcloud projects create PROJECT_ID
```
Reemplaza PROJECT_ID por un nombre para el Google Cloud proyecto de que estás creando.
Selecciona el Google Cloud proyecto de que creaste:
```
gcloud config set project PROJECT_ID
```
Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto de.

Verifica que la facturación esté habilitada para tu Google Cloud proyecto.

Habilita la API necesaria:

Roles necesarios para habilitar las APIs

Para habilitar las APIs, necesitas el rol de IAM de administrador de Service Usage (roles/serviceusage.serviceUsageAdmin), que contiene el serviceusage.services.enable permiso. Obtén más información para otorgar roles.

gcloud services enable container.googleapis.com

Instala Google Cloud CLI.

Si usas un proveedor de identidad externo (IdP), primero debes acceder a la gcloud CLI con tu identidad federada.

Para inicializar gcloud CLI, ejecuta el siguiente comando:

gcloud init

Crea o selecciona un Google Cloud proyecto.

Roles necesarios para seleccionar o crear un proyecto

Selecciona un proyecto: Para seleccionar un proyecto, no se requiere un rol de IAM específico. Puedes seleccionar cualquier proyecto en el que se te haya otorgado un rol.
Crea un proyecto: Para crear un proyecto, necesitas el rol de creador de proyectos (roles/resourcemanager.projectCreator), que contiene el resourcemanager.projects.create permiso. Obtén más información para otorgar roles.

Crea un proyecto de: Google Cloud
```
gcloud projects create PROJECT_ID
```
Reemplaza PROJECT_ID por un nombre para el Google Cloud proyecto de que estás creando.
Selecciona el Google Cloud proyecto de que creaste:
```
gcloud config set project PROJECT_ID
```
Reemplaza PROJECT_ID por el nombre de tu Google Cloud proyecto de.

Verifica que la facturación esté habilitada para tu Google Cloud proyecto.

Habilita la API necesaria:

Roles necesarios para habilitar las APIs

gcloud services enable container.googleapis.com

Otorga roles a tu cuenta de usuario. Ejecuta el siguiente comando una vez para cada uno de los siguientes roles de IAM: roles/container.admin
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
```
Reemplaza lo siguiente:
- PROJECT_ID: ID del proyecto
- USER_IDENTIFIER: Es el identificador de tu cuenta de usuario. Por ejemplo, myemail@example.com.
- ROLE: Es el rol de IAM que otorgas a tu cuenta de usuario.
Accede a una cuenta de Hugging Face o crea una.

Accede a DeepSeek-V3.2-Speciale con Hugging Face

Para usar Hugging Face y acceder al modelo DeepSeek-V3.2-Speciale, haz lo siguiente:

Accede a Hugging Face.
Crea un token de acceso read de Hugging Face.
Copia y guarda el valor del token de acceso read. Lo usarás más adelante en este instructivo.

Prepara el entorno

Para preparar tu entorno, configura las siguientes variables:

gcloud config set project PROJECT_ID
gcloud config set billing/quota_project PROJECT_ID
export PROJECT_ID=$(gcloud config get project)
export RESERVATION_URL=RESERVATION_URL
export REGION=REGION
export CLUSTER_NAME=CLUSTER_NAME
export HUGGING_FACE_TOKEN=HUGGING_FACE_TOKEN
export NETWORK=NETWORK_NAME
export SUBNETWORK=SUBNETWORK_NAME

Reemplaza lo siguiente:

PROJECT_ID: Es el ID del Google Cloud proyecto de en el que deseas crear el clúster de GKE.
RESERVATION_URL: Es la URL de la reserva que deseas usar para crear tu clúster de GKE. Según el proyecto en el que existe la reserva, especifica uno de los siguientes valores:
- La reserva existe en tu proyecto: RESERVATION_NAME
- La reserva existe en un proyecto diferente y tu proyecto puede usarla: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
REGION: Es la región en la que deseas crear tu clúster de GKE. Solo puedes crear el clúster en la región en la que existe tu reserva.
CLUSTER_NAME: Es el nombre del clúster de GKE que se creará.
HUGGING_FACE_TOKEN: Es el token de acceso de Hugging Face que creaste en la sección anterior.
NETWORK_NAME: Es la red que usa el clúster de GKE. Especifica uno de los siguientes valores:
- Si creaste una red personalizada, especifica el nombre de tu red.
- De lo contrario, especifica default.
SUBNETWORK_NAME: Es la subred que usa el clúster de GKE. Especifica uno de los siguientes valores:
- Si creaste una subred personalizada, especifica el nombre de tu subred. Solo puedes especificar una subred que exista en la misma región que la reserva.
- De lo contrario, especifica default.

Crea y configura Google Cloud recursos

Sigue estas instrucciones en esta sección para crear los recursos necesarios.

Crea un clúster de GKE en modo Autopilot

Para crear un clúster de GKE en modo Autopilot, ejecuta el siguiente comando:

gcloud container clusters create-auto $CLUSTER_NAME \
    --project=$PROJECT_ID \
    --region=$REGION \
    --release-channel=rapid \
    --network=$NETWORK \
    --subnetwork=$SUBNETWORK

La creación del clúster de GKE puede tardar un tiempo en completarse. Para verificar que Google Cloud haya terminado de crear tu clúster, ve a Clústeres de Kubernetes en la consola de Google Cloud .

Crea un secreto de Kubernetes para almacenar tus credenciales de Hugging Face

Para crear un secreto de Kubernetes para almacenar tus credenciales de Hugging Face, haz lo siguiente:

Configura kubectl para comunicarse con tu clúster de GKE:

gcloud container clusters get-credentials $CLUSTER_NAME \
    --location=$REGION

Crea un secreto de Kubernetes que contenga el token de read access de Hugging Face que creaste en un paso anterior:

kubectl create secret generic hf-secret \
    --from-literal=hf_token=${HUGGING_FACE_TOKEN} \
    --dry-run=client -o yaml | kubectl apply -f -

Implementa un contenedor de vLLM en tu clúster de GKE

Para implementar el contenedor de vLLM para entregar el modelo deepseek-ai/DeepSeek-V3.2-Speciale, haz lo siguiente:

Crea un archivo vllm-deepseek3-2.yaml con la implementación de vLLM que elegiste:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: deepseek3-2-deploy
spec:
  replicas: 1
  selector:
    matchLabels:
      app: deepseek
  template:
    metadata:
      labels:
        app: deepseek
        ai.gke.io/model: deepseek-v3-2
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: vllm-inference
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:model-garden.pytorch-vllm-serve-release_20251126.00_p0
        resources:
          requests:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "1Ti"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "1Ti"
            nvidia.com/gpu: "8"
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=$(MODEL_ID)
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=131072
        - --max-num-seqs=16
        - --enable-chunked-prefill
        - --gpu-memory-utilization=0.90
        - --enforce-eager
        - --trust-remote-code
        env:
        - name: MODEL_ID
          value: deepseek-ai/DeepSeek-V3.2-Speciale
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 1800
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 1800
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
          medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: $RESERVATION_URL
        cloud.google.com/reservation-affinity: "specific"
        cloud.google.com/gke-gpu-driver-version: latest

---
apiVersion: v1
kind: Service
metadata:
  name: deepseek-service
spec:
  selector:
    app: deepseek
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: deepseek-monitoring
spec:
  selector:
    matchLabels:
      app: deepseek
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

Aplica el archivo vllm-deepseek3-2.yaml a tu clúster de GKE:
```
  envsubst < vllm-deepseek3-2.yaml | kubectl apply -f -
```
Durante el proceso de implementación, el contenedor debe descargar el modelo deepseek-ai/DeepSeek-V3.2-Speciale de Hugging Face. Por este motivo, la implementación del contenedor puede tardar hasta 30 minutos en completarse.
Para ver el estado de finalización, ejecuta el siguiente comando:
```
  kubectl wait \
      --for=condition=Available \
      --timeout=1800s deployment/deepseek3-2-deploy
```
La marca --timeout=1800s permite que el comando supervise la implementación durante un máximo de 30 minutos.

Interactúa con DeepSeek-V3.2-Speciale con curl

Para verificar el modelo DeepSeek-V3.2-Speciale que implementaste, haz lo siguiente:

Configura la redirección de puertos a DeepSeek-V3.2-Speciale:
```
kubectl port-forward service/deepseek-service 8000:8000
```

Abre una nueva ventana de terminal. Luego, puedes chatear con tu modelo con curl:

time curl http://127.0.0.1:8000/v1/completions \
   -X POST \
   -H "Content-Type: application/json" \
   -d '{
     "model": "deepseek-ai/DeepSeek-V3.2-Speciale",
     "prompt": "<|im_start|>user\nExplain the ReAct (Reasoning + Acting) pattern in Agentic AI. Provide a concise Python pseudocode example showing the loop. Keep the explanation under 300 words.<|im_end|>\n<|im_start|>assistant\n",
     "max_tokens": 1024,
     "temperature": 0.7,
     "stream": false,
     "stop": ["<|im_end|>"]
   }'

El resultado que ves es similar al siguiente:

{
"id": "cmpl-be345f0499e949ed8500e533be2cfe3f",
"object": "text_completion",
"created": 1764803171,
"model": "deepseek-ai/DeepSeek-V3.2-Speciale",
"choices": [
  {
    "index": 0,
    "text": "The ReAct pattern integrates reasoning (thoughts) and actions (tool calls) within an agentic loop... [TRUNCATED FOR BREVITY] ...ReAct improves transparency and reliability by explicit reasoning steps.",
    "logprobs": null,
    "finish_reason": "stop",
    "stop_reason": "<|im_end|>",
    "token_ids": null,
    "prompt_logprobs": null,
    "prompt_token_ids": null
  }
],
"service_tier": null,
"system_fingerprint": null,
"usage": {
  "prompt_tokens": 57,
  "total_tokens": 317,
  "completion_tokens": 260,
  "prompt_tokens_details": null
},
"kv_transfer_params": null
}

Observa el rendimiento del modelo

Para observar el rendimiento de tu modelo, puedes usar la integración del panel de vLLM en Cloud Monitoring. Puedes usar este panel para ver métricas de rendimiento críticas, como la capacidad de procesamiento de tokens, la latencia de las solicitudes y las tasas de error.

Para obtener información sobre el uso de Google Cloud Managed Service para Prometheus para recopilar métricas de tu modelo, consulta la vLLM de vLLM en la documentación de Cloud Monitoring.

Limpia

Para evitar que se apliquen cargos a tu cuenta de Google Cloud por los recursos usados en este instructivo, borra el proyecto que contiene los recursos o conserva el proyecto y borra los recursos individuales.

Borra tu proyecto

Precaución: Borrar un proyecto tiene las siguientes consecuencias:

Se borra todo su contenido. Si usaste un proyecto existente para las tareas de este documento, cuando lo borres, también se borrará cualquier otro trabajo que hayas realizado en el proyecto.
Se pierden los IDs personalizados de los proyectos. Cuando creaste este proyecto, es posible que hayas creado un ID personalizado del proyecto que desees utilizar en el futuro. Para conservar las URLs que usan el ID del proyecto, como una URL appspot.com, borra los recursos seleccionados dentro del proyecto, en lugar de todo el proyecto.

Si planeas explorar varios instructivos, arquitecturas o guías de inicio rápido, reutilizar proyectos puede ser útil para no exceder los límites de cuota de los proyectos.

Borra un Google Cloud proyecto de:

gcloud projects delete PROJECT_ID

Borra recursos

Para borrar la implementación y el servicio en el archivo vllm-deepseek3-2.yaml y el secreto de Kubernetes del clúster de GKE, ejecuta el siguiente comando:
```
kubectl delete -f vllm-deepseek3-2.yaml
kubectl delete secret hf-secret
```

Para borrar tu clúster de GKE, ejecuta el siguiente comando:

gcloud container clusters delete $CLUSTER_NAME \
        --region=$REGION

¿Qué sigue?

Administra clústeres de GKE optimizados para IA