Implémentation de référence de la mise en service de modèles ouverts sur Google Distributed Cloud (logiciel uniquement)

Présentation

Ce document sert de guide de mise en œuvre de la solution de référence (SRI). Il décrit les étapes concrètes requises pour déployer, diffuser et valider la solution Open Model Serving sur Google Distributed Cloud (logiciel uniquement).

Ce guide implémente le déploiement du moteur de diffusion vLLM optimisé exécutant Gemma 4 (google/gemma-4-31B-it) sur une configuration de cluster à nœud unique logicielle Google Distributed Cloud destinée au déploiement en périphérie utilisant des ressources de GPU NVIDIA physiques (par exemple, RTX PRO 6000).

Ce tutoriel est conçu pour être exécuté à partir d'un client de terminal CLI ayant un accès kubectl au cluster Google Distributed Cloud (logiciel uniquement).

Objectifs

En suivant cette implémentation de solution de référence, vous allez :

  • Configurez les paramètres de l'environnement de diffusion via un fichier .env local.
  • Déployez une revendication de volume persistant (PVC) à l'aide de la classe de stockage local-shared pour conserver les pondérations du modèle.
  • Déployez le moteur de diffusion vLLM optimisé à l'aide de conteneurs qualifiés Vertex AI, en mappant les ressources nvidia.com/gpu physiques.
  • Déployez l'UI Web Gradio pour fournir une interface de chat interactive.
  • Établissez des tunnels de transfert de port locaux pour valider la réactivité de la diffusion via les API et l'interface utilisateur Web.
  • Vérifiez l'intégration de l'observabilité en confirmant l'ingestion des journaux et des métriques (y compris la télémétrie GPU) dans Cloud Logging et Cloud Monitoring.

Avant de commencer

Prérequis (configuration du cluster)

Ce guide suppose que vous disposez d'un cluster Google Distributed Cloud logiciel uniquement en cours d'exécution avec la compatibilité GPU configurée. Pour installer le cluster, consultez la documentation officielle de Google Distributed Cloud (logiciel uniquement) pour Bare Metal. La configuration du GPU doit être conforme à la documentation officielle Google Cloudpour configurer et utiliser des GPU NVIDIA.

Prérequis pour le poste de travail client

Assurez-vous que les outils suivants sont installés et configurés dans votre environnement de terminal local :

  • gcloud CLI : requis pour configurer le projet et interroger les journaux. Doit être authentifié (gcloud auth login) et configuré sur le projetGoogle Cloud actif dans lequel le cluster Google Distributed Cloud (logiciel uniquement) est enregistré.
  • kubectl : requis pour gérer les ressources du cluster. Doit être configuré avec le contexte approprié pour accéder au cluster Google Distributed Cloud (logiciel uniquement) cible (par exemple, via une passerelle de connexion ou un accès direct au réseau local).
  • curl : requis pour envoyer des requêtes de test au point de terminaison de diffusion.
  • jq : requis pour analyser la sortie JSON du point de terminaison de diffusion.

Accès aux modèles Hugging Face

Pour télécharger et déployer le modèle Gemma 4, vous devez avoir accès au dépôt Hugging Face :

  1. Compte Hugging Face : assurez-vous d'avoir un compte enregistré sur Hugging Face.
  2. Accepter la licence du modèle : accédez à la page du modèle Gemma 4 31B IT et acceptez les conditions de licence pour accéder aux pondérations du modèle fermé.
  3. Générer un jeton d'accès : générez un jeton d'accès utilisateur avec des autorisations de lecture à partir des paramètres de votre compte Hugging Face (Paramètres -> Jetons d'accès). Ce jeton sera utilisé comme HF_TOKEN dans votre configuration.

Configuration de référence centrale

Tous les paramètres de déploiement sont gérés via un fichier .env central situé à l'emplacement <local-config-dir>/.env. Assurez-vous que ce fichier existe et qu'il contient vos paramètres spécifiques (jeton Hugging Face, espace de noms, nom du modèle, etc.).

Exemple de structure .env :

# GDCso Cluster Namespace
NAMESPACE_NAME="your-custom-namespace"

# Hugging Face Token (Required to download gated Gemma models)
HF_TOKEN="your-hf-token-here"

# Model Sizing Parameters
MODEL_NAME="google/gemma-4-31B-it"
SAFE_MODEL_NAME="google-gemma-4-31B-it"

# Hyperparameters
MAX_MODEL_LEN=8192
GPU_MEMORY_UTILIZATION=0.95
MAX_NUM_SEQS=512
MAX_NUM_BATCHED_TOKENS=4096
DTYPE="bfloat16"

# Pod Sizing Requests
CPU_REQUEST="4"
MEMORY_REQUEST="80"

Configurer l'environnement et les identifiants

Créer un espace de noms et un secret Hugging Face

Avant de procéder au déploiement, vous devez créer l'espace de noms et le secret du jeton Hugging Face :

# Navigate to your project root
cd <local-working-dir>

# Sourced from your local .env file
source <local-config-dir>/.env

# Create namespace
kubectl create namespace ${NAMESPACE_NAME} --dry-run=client -o yaml | kubectl apply -f -

# Create Hugging Face token secret
kubectl create secret generic hf-token-secret \
  --from-literal=token="${HF_TOKEN}" \
  -n "${NAMESPACE_NAME}" --dry-run=client -o yaml | kubectl apply -f -

Déploiement vLLM sur Kubernetes

Le déploiement se compose de trois fichiers manifestes principaux : PVC, Service et Deployment. Ces modèles utilisent des variables d'environnement qui sont remplacées au moment du déploiement.

Persistent Volume Claim (PVC)

La PVC garantit la persistance des pondérations du modèle lors des redémarrages des pods, à l'aide de la classe de stockage local-shared de Google Distributed Cloud (logiciel uniquement).

Créez un fichier nommé vllm-pvc.yaml avec le contenu suivant :

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: model-cache-pvc
  namespace: ${NAMESPACE_NAME}
spec:
  accessModes:
    - ReadWriteOnce
  storageClassName: local-shared
  resources:
    requests:
      storage: 100Gi

Service

Expose le serveur d'API vLLM en interne sur le port 8000.

Créez un fichier nommé vllm-service.yaml avec le contenu suivant :

apiVersion: v1
kind: Service
metadata:
  name: vllm-service
  namespace: ${NAMESPACE_NAME}
  labels:
    app: vllm
  annotations:
    prometheus.io/scrape: "true"
    prometheus.io/path: "/metrics"
    prometheus.io/port: "8000"
spec:
  ports:
    - name: http
      port: 8000
      targetPort: 8000
  selector:
    app: vllm
  type: ClusterIP

Déploiement

Exécute le conteneur vLLM, installe le volume de cache du modèle et demande des ressources GPU physiques. Bien que 96 Go de VRAM puissent contenir des pondérations BF16 non quantifiées (~62 Go), cette implémentation de référence active la quantification Blackwell FP8 (--quantization=fp8, ~31 Go de pondérations) pour étendre le cache KV à 56,53 Gio (61,728 jetons) afin d'obtenir un débit simultané plus élevé.

Créez un fichier nommé vllm-deployment.yaml avec le contenu suivant :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-deployment
  namespace: ${NAMESPACE_NAME}
  labels:
    app: vllm
    ai.gke.io/inference-server: vllm
    ai.gke.io/model: ${SAFE_MODEL_NAME}
spec:
  replicas: 1
  strategy:
    type: Recreate
  selector:
    matchLabels:
      app: vllm
  template:
    metadata:
      labels:
        app: vllm
        examples.ai.gke.io/source: user-guide
        ai.gke.io/inference-server: vllm
        ai.gke.io/model: ${SAFE_MODEL_NAME}
    spec:
      runtimeClassName: nvidia
      containers:
        - name: vllm-container
          image: us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4
          imagePullPolicy: IfNotPresent
          command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
          args:
            - --model=$(MODEL_ID)
            - --host=0.0.0.0
            - --port=8000
            - --tensor-parallel-size=1
            - --enable-log-requests
            - --max-model-len=${MAX_MODEL_LEN}
            - --gpu-memory-utilization=${GPU_MEMORY_UTILIZATION}
            - --max-num-seqs=${MAX_NUM_SEQS}
            - --max-num-batched-tokens=${MAX_NUM_BATCHED_TOKENS}
            - --dtype=${DTYPE}
            - --trust-remote-code
            - --enable-prefix-caching
            - --enable-chunked-prefill
            - --quantization=fp8
          env:
            - name: MODEL_ID
              value: ${MODEL_NAME}
            - name: HUGGING_FACE_HUB_TOKEN
              valueFrom:
                secretKeyRef:
                  name: hf-token-secret
                  key: token
            - name: LD_LIBRARY_PATH
              value: "/usr/local/nvidia/lib64"
          ports:
            - name: http
              containerPort: 8000
          resources:
            requests:
              cpu: ${CPU_REQUEST}
              memory: "${MEMORY_REQUEST}Gi"
              nvidia.com/gpu: "1"
            limits:
              cpu: ${CPU_REQUEST}
              memory: "${MEMORY_REQUEST}Gi"
              nvidia.com/gpu: "1"
          volumeMounts:
            - mountPath: /root/.cache/huggingface
              name: cache-volume
            - mountPath: /dev/shm
              name: dshm
      volumes:
        - name: cache-volume
          persistentVolumeClaim:
            claimName: model-cache-pvc
        - name: dshm
          emptyDir:
            medium: Memory
            sizeLimit: 16Gi

Déploiement de l'UI Gradio

L'UI Gradio fournit une interface Web interactive pour discuter avec le modèle. Il est déployé dans le cluster et se connecte au service vLLM via le réseau Kubernetes interne.

Déploiement Gradio

Créez un fichier nommé gradio-deployment.yaml avec le contenu suivant :

apiVersion: apps/v1
kind: Deployment
metadata:
  name: gradio-deployment
  namespace: ${NAMESPACE_NAME}
  labels:
    app: gradio
spec:
  replicas: 1
  selector:
    matchLabels:
      app: gradio
  template:
    metadata:
      labels:
        app: gradio
    spec:
      containers:
      - name: gradio
        image: us-docker.pkg.dev/google-samples/containers/gke/gradio-app:v1.0.4
        resources:
          requests:
            cpu: "250m"
            memory: "512Mi"
          limits:
            cpu: "500m"
            memory: "512Mi"
        env:
        - name: CONTEXT_PATH
          value: "/v1/chat/completions"
        - name: HOST
          value: "http://vllm-service:8000"
        - name: MODEL_ID
          value: "${MODEL_NAME}"
        ports:
        - containerPort: 7860

Service Gradio

Créez un fichier nommé gradio-service.yaml avec le contenu suivant :

apiVersion: v1
kind: Service
metadata:
  name: gradio-service
  namespace: ${NAMESPACE_NAME}
spec:
  selector:
    app: gradio
  ports:
  - protocol: TCP
    port: 8080
    targetPort: 7860
  type: ClusterIP

Configuration de l'observabilité

Pour en savoir plus sur la configuration de la journalisation et de la surveillance des applications, consultez le guide officiel Journalisation et surveillance des applications.

Surveillance de vLLM

Pour activer la récupération des métriques vLLM par Google Cloud Managed Service pour Prometheus (GMP), nous déployons une ressource PodMonitoring ciblant les pods vLLM.

Créez un fichier nommé vllm-pod-monitoring.yaml avec le contenu suivant :

apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-pod-monitoring
  namespace: ${NAMESPACE_NAME}
spec:
  selector:
    matchLabels:
      app: vllm
  endpoints:
  - port: http
    interval: 30s

Surveillance des GPU

Pour permettre à Google Cloud Managed Service pour Prometheus (GMP) de récupérer les métriques GPU de l'exportateur NVIDIA DCGM, nous déployons une ressource PodMonitoring dans l'espace de noms gpu-operator. Pour en savoir plus, consultez Envoyer des métriques GPU à Cloud Monitoring.

Créez un fichier nommé gpu-pod-monitoring.yaml avec le contenu suivant :

apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: dcgm-gmp
  namespace: gpu-operator
spec:
  selector:
    matchLabels:
      app: nvidia-dcgm-exporter
  endpoints:
  - port: metrics
    interval: 30s

Étapes d'exécution

Déployer des fichiers manifestes

Appliquez les fichiers manifestes au cluster. Étant donné que les fichiers YAML contiennent des espaces réservés pour les variables d'environnement, utilisez envsubst pour remplacer les variables de votre fichier .env avant de les appliquer.

  1. Accédez au répertoire de travail contenant les fichiers YAML :

    cd <local-working-dir>
    
  2. Définissez les variables d'environnement :

    source <local-config-dir>/.env
    
  3. Appliquez les fichiers manifestes dans l'ordre :

    # Apply core serving manifests
    envsubst < vllm-pvc.yaml | kubectl apply -f -
    envsubst < vllm-service.yaml | kubectl apply -f -
    envsubst < vllm-deployment.yaml | kubectl apply -f -
    
    # Apply observability manifests
    envsubst < vllm-pod-monitoring.yaml | kubectl apply -f -
    kubectl apply -f gpu-pod-monitoring.yaml
    
    # Apply Gradio UI manifests
    envsubst < gradio-deployment.yaml | kubectl apply -f -
    envsubst < gradio-service.yaml | kubectl apply -f -
    

Validation

Surveiller la séquence de démarrage des pods

Diffusez les journaux du conteneur pour suivre la séquence de démarrage :

# 1. Check pod status (wait until it is Running)
kubectl get pods -n ${NAMESPACE_NAME} -l app=vllm

# 2. Stream logs to verify model loading
kubectl logs -f -l app=vllm -n ${NAMESPACE_NAME}

Attendez que le signal indiquant que la diffusion active est prête s'affiche dans vos journaux :

INFO: Application startup complete.

Établir un tunnel de transfert de port

Pour tester le point de terminaison localement, transférez le port de service 8000 :

kubectl port-forward service/vllm-service 8000:8000 -n ${NAMESPACE_NAME}

Laissez ce terminal ouvert ou exécutez-le en arrière-plan.

Point de terminaison de diffusion des requêtes

Dans un autre terminal, testez la réactivité de l'API :

1. Liste des modèles de requête

curl -s http://localhost:8000/v1/models | jq

2. Interroger les complétions de chat

curl -s http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"${MODEL_NAME}"'",
    "messages": [
      {"role": "user", "content": "What is AGI in 100 words"}
    ],
    "max_tokens": 150
  }' | jq

Vérifier les allocations de GPU et de VRAM

Pour vous assurer que le modèle utilise efficacement le matériel et que l'espace mémoire utilisé est correct, vous pouvez exécuter un audit du GPU.

Auditer le GPU via nvidia-smi dans le pod

Récupérez le nom de votre pod vLLM actif et exécutez nvidia-smi dans le conteneur :

# Dynamically get the pod name
export VLLM_POD_NAME=$(kubectl get pods -n ${NAMESPACE_NAME} -l app=vllm -o jsonpath='{.items[0].metadata.name}')

# Run nvidia-smi inside the container
kubectl exec ${VLLM_POD_NAME} -n ${NAMESPACE_NAME} -- nvidia-smi

Résultat attendu : le résultat doit indiquer une utilisation de la VRAM physique correspondant à votre paramètre GPU_MEMORY_UTILIZATION. Par exemple, sur un poste de travail équipé d'un GPU NVIDIA RTX PRO 6000 (environ 96 Go de VRAM) exécutant google/gemma-4-31B-it avec GPU_MEMORY_UTILIZATION=0.95, vous devriez voir environ 95 800 Mio alloués à VLLM::EngineCore :

+-----------------------------------------------------------------------------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA RTX PRO 6000 Blac...    On  |   00000000:05:00.0 Off |                    0 |
| N/A   36C    P0             85W /  600W |   95805MiB /  97887MiB |      0%      Default |
+-----------------------------------------+------------------------+----------------------+

Vérifier l'allocation du cache KV dans les journaux

Vous pouvez également consulter les journaux d'allocation interne vLLM pour vérifier la taille du cache KV et la simultanéité des jetons :

kubectl logs ${VLLM_POD_NAME} -n ${NAMESPACE_NAME} | grep -E "Available KV cache|GPU KV cache size"

Résultat attendu :

(EngineCore pid=362) INFO 06-18 15:03:43 [gpu_worker.py:456] Available KV cache memory: 56.53 GiB
(EngineCore pid=362) INFO 06-18 15:03:43 [kv_cache_utils.py:1316] GPU KV cache size: 61,728 tokens

Cela confirme que 56,53 Gio de VRAM sont réservés au cache KV de contexte, ce qui permet un grand nombre de jetons simultanés.

Vérifier le déploiement de l'UI Gradio

Une fois que le pod Gradio est en cours d'exécution, vous pouvez accéder à l'UI en établissant un tunnel de transfert de port.

Surveiller l'état du pod Gradio

Assurez-vous que le pod Gradio est en cours d'exécution :

kubectl get pods -n ${NAMESPACE_NAME} -l app=gradio

Résultat attendu :

NAME                                READY   STATUS    RESTARTS   AGE
gradio-deployment-yyyyyyyy-yyyyy    1/1     Running   0          1m

Établir un tunnel de transfert de port vers Gradio

Transférez le port 8080 du service Gradio vers votre port local 7860 :

kubectl port-forward service/gradio-service 7860:8080 -n ${NAMESPACE_NAME}

Laissez ce terminal ouvert ou exécutez-le en arrière-plan :

kubectl port-forward service/gradio-service 7860:8080 -n ${NAMESPACE_NAME} > pf_gradio.log 2>&1 & sleep 3

Accéder à l'UI Web

  • Si vous utilisez un poste de travail local : ouvrez votre navigateur et accédez directement à http://localhost:7860.
  • Si vous exécutez l'application dans Cloud Shell : utilisez le bouton Aperçu sur le Web, sélectionnez Modifier le port, saisissez 7860, puis cliquez sur Modifier et prévisualiser.

L'interface du chatbot Gradio devrait s'afficher. Vous pouvez saisir un message pour interagir avec le modèle Gemma. Le pod Gradio acheminera la requête en interne vers le point de terminaison vllm-service.

Nettoyer les tunnels

Pour arrêter le tunnel de transfert de port :

pkill -f "port-forward service/gradio-service"

Vérification de la surveillance

Une fois que vLLM est déployé et que la ressource PodMonitoring est appliquée, vous pouvez vérifier que les métriques sont ingérées dans Cloud Monitoring.

Vérifier l'état de PodMonitoring

Assurez-vous que la ressource PodMonitoring est créée et active :

kubectl get podmonitoring -n ${NAMESPACE_NAME}

Vérifier l'ingestion des métriques à l'aide de la console Google Cloud

Vous pouvez vérifier que les métriques sont ingérées à l'aide de la console Google Cloud (Explorateur de métriques) :

  1. Ouvrez l'explorateur de métriques dans la console Google Cloud  :
    • Accédez à https://console.cloud.google.com/monitoring/metrics-explorer (assurez-vous de sélectionner votre projet ${GCP_PROJECT_ID}).
  2. Dans le menu déroulant Sélectionner une métrique, recherchez et sélectionnez :
    • prometheus.googleapis.com/vllm:num_requests_running/gauge pour vérifier les métriques vLLM.
    • prometheus.googleapis.com/DCGM_FI_DEV_GPU_UTIL/gauge pour vérifier les métriques d'utilisation des GPU.
  3. Observez le graphique pour vérifier que les points de données sont bien tracés.

Validation de la journalisation

Une fois la charge de travail en cours d'exécution, vous pouvez vérifier que les journaux sont exportés vers Cloud Logging.

Vérifier l'ingestion des journaux vLLM

Vérifiez que les journaux du conteneur vLLM sont exportés vers Cloud Logging :

project_id=$(gcloud config get-value project)

gcloud logging read "resource.type=\"k8s_container\" AND resource.labels.namespace_name=\"${NAMESPACE_NAME}\" AND resource.labels.container_name=\"vllm-container\"" --limit=10 --project=${project_id}

Vérifier l'ingestion des journaux de l'exportateur de GPU

Vérifiez que les journaux du conteneur de l'exportateur de GPU sont exportés vers Cloud Logging :

project_id=$(gcloud config get-value project)

gcloud logging read "resource.type=\"k8s_container\" AND resource.labels.namespace_name=\"gpu-operator\" AND resource.labels.container_name=\"nvidia-dcgm-exporter\"" --limit=10 --project=${project_id}

Vérifier les journaux à l'aide de la console Google Cloud (explorateur de journaux)

Vous pouvez également vérifier l'ingestion des journaux à l'aide de la console Google Cloud  :

  1. Ouvrez l'explorateur de journaux dans la console Google Cloud  :
    • Accédez à https://console.cloud.google.com/logs/query (assurez-vous de sélectionner votre projet ${GCP_PROJECT_ID}).
  2. Dans le champ Requête, saisissez la requête suivante pour afficher les journaux vLLM :

    resource.type="k8s_container"
    resource.labels.namespace_name="<NAMESPACE_NAME>"
    resource.labels.container_name="vllm-container"
    

    (Remplacez <NAMESPACE_NAME> par votre espace de noms réel, par exemple your-custom-namespace.)

  3. Cliquez sur Exécuter la requête. Les entrées de journal du conteneur vLLM devraient s'afficher.

  4. Pour vérifier les journaux de l'exportateur de GPU, exécutez la requête suivante :

    resource.type="k8s_container"
    resource.labels.namespace_name="gpu-operator"
    resource.labels.container_name="nvidia-dcgm-exporter"