Utiliser vLLM sur GKE pour diffuser l'inférence Gemma 3 27B

Ce tutoriel explique comment déployer et diffuser un grand modèle de langage (LLM) Gemma 3 27B avec le framework de diffusion vLLM. Vous déployez Gemma 3 sur une instance de machine virtuelle (VM) A4 unique sur Google Kubernetes Engine (GKE).

Ce tutoriel est destiné aux ingénieurs en machine learning (ML), aux administrateurs et opérateurs de plate-forme, ainsi qu'aux spécialistes des données et de l'IA qui souhaitent utiliser les fonctionnalités d'orchestration de conteneurs Kubernetes pour gérer les charges de travail d'inférence.

Objectifs

  1. Accéder à Gemma 3 à l'aide de Hugging Face.

  2. Préparer votre environnement.

  3. Créer un cluster GKE en mode Autopilot.

  4. Créer un secret Kubernetes pour les identifiants Hugging Face.

  5. Déployer un conteneur vLLM sur votre cluster GKE.

  6. Interagir avec Gemma 3 à l'aide de curl.

  7. Effectuer un nettoyage.

Coûts

Ce tutoriel utilise des composants facturables de Google Cloud, dont :

Vous pouvez obtenir une estimation des coûts en fonction de votre utilisation prévue à l'aide du simulateur de coût.

Avant de commencer

  1. Installez la Google Cloud CLI.

  2. Configurez la gcloud CLI afin d'utiliser votre identité fédérée.

    Pour en savoir plus, consultez Se connecter à la gcloud CLI avec votre identité fédérée.

  3. Pour initialiser la gcloud CLI, exécutez la commande suivante : 

    gcloud init

  4. Créez ou sélectionnez un Google Cloud projet.

    Rôles requis pour sélectionner ou créer un projet

    • Sélectionner un projet : la sélection d'un projet ne nécessite pas de rôle IAM spécifique Vous pouvez sélectionner n'importe quel projet pour lequel un rôle vous a été attribué.
    • Créer un projet : pour créer un projet, vous avez besoin du rôle Créateur de projet (roles/resourcemanager.projectCreator), qui contient l'autorisation resourcemanager.projects.create. Découvrez comment attribuer des rôles.

    • Créez un Google Cloud projet :

      gcloud projects create PROJECT_ID

      Remplacez PROJECT_ID par un nom pour le Google Cloud projet que vous créez.

    • Sélectionnez le Google Cloud projet que vous avez créé :

      gcloud config set project PROJECT_ID

      Remplacez PROJECT_ID par le nom de votre Google Cloud projet.

  5. Vérifiez que la facturation est activée pour votre Google Cloud projet.

  6. Activez l'API requise :

    Rôles requis pour activer les API

    Pour activer les API, vous avez besoin de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation via le rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation via le rôle Administrateur d'utilisation du service (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles. 

    gcloud services enable container.googleapis.com

  7. Attribuez des rôles à votre compte utilisateur. Exécutez la commande suivante une fois pour chacun des rôles IAM suivants : roles/container.admin 

    gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE

    Remplacez les éléments suivants :

  8. Connectez-vous à un compte Hugging Face ou créez-en un.

Accéder à Gemma 3 à l'aide de Hugging Face

Pour utiliser Hugging Face afin d'accéder à Gemma 3, procédez comme suit :

  1. Connectez-vous à Hugging Face.
  2. Créez un jeton d'accès read Hugging Face. Cliquez sur Your Profile > Settings > Access tokens > +Create new token (Votre profil > Paramètres > Jetons d'accès > +Créer un jeton).
  3. Copiez et enregistrez la valeur du jeton read access. Vous l'utiliserez plus tard dans ce tutoriel.

Préparer votre environnement

Pour préparer votre environnement, définissez les variables d'environnement par défaut :

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_URL="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export HUGGING_FACE_TOKEN="YOUR_HF_TOKEN"
export NETWORK="YOUR_NETWORK_NAME"
export SUBNETWORK="YOUR_SUBNETWORK_NAME"

gcloud config set project "${PROJECT_ID}"
gcloud config set billing/quota_project "${PROJECT_ID}"

Remplacez les éléments suivants :

  • PROJECT_ID : ID du Google Cloud projet dans lequel vous souhaitez créer le cluster GKE.

  • RESERVATION_URL: URL de la réservation que vous souhaitez utiliser pour créer votre cluster GKE. En fonction du projet dans lequel la réservation existe, spécifiez l'une des valeurs suivantes :

    • La réservation existe dans votre projet : RESERVATION_NAME

    • La réservation existe dans un autre projet, et votre projet peut utiliser la réservation : projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME

  • REGION: région dans laquelle vous souhaitez créer votre cluster GKE. Vous ne pouvez créer le cluster que dans la région où votre réservation existe.

  • CLUSTER_NAME: nom du cluster GKE à créer.

  • YOUR_HF_TOKEN: jeton d'accès Hugging Face que vous avez créé dans la section précédente.

  • NETWORK: réseau utilisé par le cluster GKE. Spécifiez une des valeurs suivantes :

    • Si vous avez créé un réseau personnalisé, spécifiez son nom.

    • Sinon, spécifiez default.

  • SUBNETWORK: sous-réseau utilisé par le cluster GKE. Spécifiez une des valeurs suivantes :

    • Si vous avez créé un sous-réseau personnalisé, spécifiez son nom. Vous ne pouvez spécifier qu'un sous-réseau qui existe dans la même région que la réservation.

    • Sinon, spécifiez default.

Créer un cluster GKE en mode Autopilot

Pour créer un cluster GKE en mode Autopilot, exécutez la commande suivante :

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

La création du cluster GKE peut prendre un certain temps. Pour vérifier que Google Cloud la création de votre cluster est terminée, accédez à Clusters Kubernetes dans la Google Cloud console.

Créer un secret Kubernetes pour les identifiants Hugging Face

Pour créer un secret Kubernetes pour les identifiants Hugging Face, procédez comme suit :

  1. Configurez kubectl pour communiquer avec votre cluster GKE :

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

  2. Créez un secret Kubernetes pour stocker votre jeton Hugging Face :

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

Déployer un conteneur vLLM sur votre cluster GKE

Pour déployer le conteneur vLLM afin de diffuser le modèle Gemma 3 27B à l'aide de déploiements Kubernetes, procédez comme suit :

  1. Créez un fichier vllm-3-27b-it.yaml avec le déploiement vLLM de votre choix :

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gemma-deployment
spec:
  progressDeadlineSeconds: 900
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-3-27b-it
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      containers:
      - name: inference-server
        image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:20250801_0916_RC01
        resources:
          requests:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "120Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "120Gi"
            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=4096
        - --max-num-seqs=4
        env:
        - name: MODEL_ID
          value: google/gemma-3-27b-it
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 720
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 720
          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: llm-service
spec:
  selector:
    app: gemma-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000

  2. Appliquez le fichier vllm-3-27b-it.yaml à votre cluster GKE :

    envsubst < vllm-3-27b-it.yaml | kubectl apply -f -

    Pendant le processus de déploiement, le conteneur doit télécharger Gemma 3 depuis Hugging Face. Pour cette raison, le déploiement du conteneur peut prendre jusqu'à 30 minutes.

  3. Attendez la fin du déploiement :

    kubectl wait \
    --for=condition=Available \
    --timeout=1800s deployment/vllm-gemma-deployment

Interagir avec Gemma 3 à l'aide de curl

Pour vérifier les modèles adaptés aux instructions Gemma 3 27B que vous avez déployés, procédez comme suit :

  1. Configurez le transfert de port vers Gemma 3 :

    kubectl port-forward service/llm-service 8000:8000

  2. Ouvrez une nouvelle fenêtre de terminal. Vous pouvez ensuite discuter avec votre modèle à l'aide de curl :

    curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "google/gemma-3-27b-it",
  "messages": [
    {
      "role": "user",
      "content": "Why is the sky blue?"
    }
  ]
}' | jq .

    Le résultat ressemble à ce qui suit :

    {
  "id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
  "object": "chat.completion",
  "created": 1741763029,
  "model": "google/gemma-3-27b-it",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning_content": null,
        "content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
        "tool_calls": []
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": 106
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "total_tokens": 668,
    "completion_tokens": 653,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null
}

Si vous souhaitez observer les performances de votre modèle, vous pouvez utiliser l'intégration du tableau de bord vLLM dans Cloud Monitoring. Ce tableau de bord vous permet d'afficher des métriques de performances critiques pour votre modèle, telles que le débit de jetons, la latence réseau et les taux d'erreur. Pour en savoir plus, consultez vLLM dans la documentation de Monitoring.

Libérer de l'espace

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

  1. Pour supprimer le déploiement et le service définis dans le fichier vllm-3-27b-it.yaml, ainsi que le secret Kubernetes du cluster GKE, exécutez la commande suivante :

    envsubst < vllm-3-27b-it.yaml | kubectl delete -f -
kubectl delete secret hf-secret

  2. Pour supprimer votre cluster GKE, exécutez la commande suivante :

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

Supprimer votre projet

Supprimez un Google Cloud projet :

gcloud projects delete PROJECT_ID

Étape suivante