Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

Utiliser vLLM sur GKE pour exécuter l'inférence avec Llama 4

Ce tutoriel explique comment déployer et diffuser un modèle Llama 4 Scout (17Bx16E), un grand modèle de langage (LLM) de 17 milliards de paramètres, à l'aide du framework vLLM. Vous déployez ce modèle 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

Accédez à Llama 4 à l'aide de Hugging Face.
Préparez votre environnement.
Créer un cluster GKE en mode Autopilot
Créez un secret Kubernetes pour les identifiants Hugging Face.
Déployez un conteneur vLLM sur votre cluster GKE.
Interagissez avec Llama 4 à l'aide de curl.
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

Connectez-vous à votre compte Google Cloud . Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de nos produits en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits sans frais pour exécuter, tester et déployer des charges de travail.

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

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

gcloud init

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

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

Sélectionnez 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 devez disposer 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 projet Google Cloud :
```
gcloud projects create PROJECT_ID
```
Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.
Sélectionnez le projet Google Cloud que vous avez créé :
```
gcloud config set project PROJECT_ID
```
Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

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

Activez l'API requise :

Rôles requis pour activer les API

Pour activer les API, vous devez disposer de l'autorisation serviceusage.services.enable. Si vous avez créé le projet, vous disposez probablement déjà de cette autorisation grâce au rôle Propriétaire (roles/owner). Sinon, vous pouvez obtenir cette autorisation grâce au rôle Administrateur Service Usage (roles/serviceusage.serviceUsageAdmin). Découvrez comment attribuer des rôles.

gcloud services enable container.googleapis.com

Installez la Google Cloud CLI.

Si vous utilisez un fournisseur d'identité (IdP) externe, vous devez d'abord vous connecter à la gcloud CLI avec votre identité fédérée.

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

gcloud init

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

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

Sélectionnez 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 devez disposer 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 projet Google Cloud :
```
gcloud projects create PROJECT_ID
```
Remplacez PROJECT_ID par le nom du projet Google Cloud que vous créez.
Sélectionnez le projet Google Cloud que vous avez créé :
```
gcloud config set project PROJECT_ID
```
Remplacez PROJECT_ID par le nom de votre projet Google Cloud .

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

Activez l'API requise :

Rôles requis pour activer les API

gcloud services enable container.googleapis.com

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 :
- PROJECT_ID : ID de votre projet
- USER_IDENTIFIER : identifiant de votre compte utilisateur . Par exemple, myemail@example.com.
- ROLE : rôle IAM que vous accordez à votre compte utilisateur.
Connectez-vous à votre compte Hugging Face ou créez-en un.

Accéder à Llama 4 à l'aide de Hugging Face

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

Signez le contrat de consentement pour utiliser Llama 4.
Créez un jeton d'accès read Hugging Face.
Copiez et enregistrez la valeur du jeton d'accès read. Vous en aurez besoin dans la suite de ce tutoriel.

Préparer votre environnement

Pour préparer votre environnement, définissez les variables suivantes :

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_NAME="YOUR_RESERVATION_NAME"
export REGION="YOUR_CLUSTER_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export HF_TOKEN="YOUR_HUGGING_FACE_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 :

YOUR_PROJECT_ID : ID du Google Cloud projet dans lequel vous souhaitez créer le cluster GKE.
YOUR_RESERVATION_NAME : 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 : YOUR_RESERVATION_NAME
- La réservation existe dans un autre projet et votre projet peut l'utiliser. Spécifiez le chemin d'accès complet, souvent appelé RESERVATION_URL : projects/YOUR_RESERVATION_PROJECT_ID/reservations/YOUR_RESERVATION_NAME. Remplacez YOUR_RESERVATION_PROJECT_ID par l'ID du projet dans lequel la réservation partagée a été créée.
  
  Assurez-vous que votre projet dispose des autorisations nécessaires pour utiliser les réservations de l'autre projet.
YOUR_CLUSTER_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ù se trouve votre réservation.
YOUR_CLUSTER_NAME : nom du cluster GKE à créer.
YOUR_HUGGING_FACE_TOKEN : jeton d'accès Hugging Face que vous avez créé dans la section précédente.
YOUR_NETWORK_NAME : 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.
YOUR_SUBNETWORK_NAME : 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 situé dans la même région que la réservation.
- Sinon, spécifiez default.

Créer et configurer des ressources Google Cloud

Suivez les instructions de cette section pour créer les ressources requises.

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 a terminé de créer votre cluster, accédez à Clusters Kubernetes dans la console Google Cloud .

Créer un secret Kubernetes pour stocker vos identifiants Hugging Face

Pour créer un secret Kubernetes permettant de stocker vos identifiants Hugging Face, procédez comme suit :

Configurez kubectl pour communiquer avec votre cluster GKE :

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

Créez un secret Kubernetes contenant le jeton read access Hugging Face que vous avez créé lors d'une étape précédente :

kubectl create secret generic hf-secret \
    --from-literal=hf_api_token="${HF_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 Llama-4-Scout-17B-16E-Instruct, procédez comme suit :

Créez un fichier vllm-l4-17b.yaml avec le déploiement vLLM de votre choix :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-llama4-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: llama4-server
  template:
    metadata:
      labels:
        app: llama4-server
        ai.gke.io/model: llama-4-scout-17b
        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:20250722_0916_RC01
        resources:
          requests:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "240Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "240Gi"
            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: meta-llama/Llama-4-Scout-17B-16E-Instruct
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        startupProbe:
          httpGet:
            path: /health
            port: 8000
          failureThreshold: 200
          periodSeconds: 15
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 15
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 15
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: ${RESERVATION_NAME}
        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: llama4-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-llama4-monitoring
spec:
  selector:
    matchLabels:
      app: llama4-server
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

Appliquez le fichier vllm-l4-17b.yaml à votre cluster GKE :
```
envsubst < vllm-l4-17b.yaml | kubectl apply -f -
```
Pendant le processus de déploiement, le conteneur doit télécharger le modèle Llama-4-Scout-17B-16E-Instruct depuis Hugging Face. C'est pourquoi le déploiement du conteneur peut prendre jusqu'à 30 minutes.
Pour afficher l'état d'achèvement, exécutez la commande suivante :
```
kubectl wait \
    --for=condition=Available \
    --timeout=3000s \
    deployment/vllm-llama4-deployment
```
L'indicateur --timeout=3000s permet à la commande de surveiller le déploiement pendant 50 minutes maximum.

Interagir avec Llama 4 à l'aide de curl

Pour valider le modèle Llama 4 Scout que vous avez déployé, procédez comme suit :

Configurez un transfert de port vers Llama 4 Scout :
```
kubectl port-forward service/llm-service 8000:8000
```

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": "meta-llama/Llama-4-Scout-17B-16E-Instruct",
       "messages": [
         {
           "role": "user",
           "content": "Describe a sailboat in one short sentence?"
         }
       ]
     }' | jq .

Le résultat renvoyé ressemble à ceci :

{
      "id": "chatcmpl-ec0ad6310c494a889b17600881c06e3d",
      "object": "chat.completion",
      "created": 1754073279,
      "model": "meta-llama/Llama-4-Scout-17B-16E-Instruct",
      "choices": [
        {
          "index": 0,
          "message": {
            "role": "assistant",
            "content": "A sailboat is a type of watercraft that uses the wind for propulsion, typically featuring a hull, mast, and one or more sails.",
            "refusal": null,
            "annotations": null,
            "audio": null,
            "function_call": null,
            "tool_calls": [],
            "reasoning_content": null
          },
          "logprobs": null,
          "finish_reason": "stop",
          "stop_reason": null
        }
      ],
      "service_tier": null,
      "system_fingerprint": null,
      "usage": {
        "prompt_tokens": 19,
        "total_tokens": 49,
        "completion_tokens": 30,
        "prompt_tokens_details": null
      },
      "prompt_logprobs": null,
      "kv_transfer_params": null
    }

Observer les performances du modèle

Pour observer les performances de votre modèle, vous pouvez utiliser l'intégration du tableau de bord vLLM dans Cloud Monitoring. Vous pouvez utiliser ce tableau de bord pour afficher les métriques de performances critiques telles que le débit de jetons, la latence des requêtes et les taux d'erreur.

Pour savoir comment utiliser Google Cloud Managed Service pour Prometheus afin de collecter des métriques à partir de votre modèle, consultez les conseils d'observabilité vLLM dans la documentation Cloud Monitoring.

Effectuer un nettoyage

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

Pour supprimer le déploiement et le service dans le fichier vllm-l4-17b.yaml, ainsi que le secret Kubernetes du cluster GKE, exécutez la commande suivante :
```
kubectl delete -f vllm-l4-17b.yaml
kubectl delete secret hf-secret
```

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

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

Supprimer votre projet

Attention : La suppression d'un projet entraîne les effets décrits ci-dessous :

Tout le contenu du projet est supprimé. Si vous avez utilisé un projet existant pour les tâches décrites dans ce document et que vous le supprimez, vous supprimerez également tout autre travail effectué dans le projet.
Les ID de projets personnalisés sont perdus. Lorsque vous avez créé ce projet, vous avez peut-être créé un ID de projet personnalisé que vous souhaitez utiliser à l'avenir. Pour conserver les URL qui utilisent l'ID de projet, telle qu'une URL appspot.com, supprimez les ressources sélectionnées dans le projet au lieu de supprimer l'ensemble du projet.

Si vous envisagez d'explorer plusieurs architectures, tutoriels et guides de démarrage rapide, réutiliser des projets peut vous aider à ne pas dépasser les limites de quotas des projets.

Supprimer un projet Google Cloud :

gcloud projects delete PROJECT_ID

Étapes suivantes

Découvrez comment gérer les clusters GKE optimisés pour l'IA.