Autoscaler la diffusion de modèles vLLM avec des métriques GPU

Ce tutoriel explique comment effectuer l'autoscaling de vos services Cloud Run qui mettent en service des LLM avec vLLM en fonction de métriques GPU personnalisées à l'aide de l'autoscaling des métriques externes Cloud Run (CREMA).

Bien que Cloud Run effectue l'autoscaling par défaut en fonction de l'utilisation du processeur et de la simultanéité, les charges de travail d'inférence intensives en GPU nécessitent souvent un autoscaling basé sur des métriques de file d'attente, telles que le nombre de requêtes en cours d'exécution ou l'utilisation du cache KV. CREMA intègre l'autoscaling basé sur les événements Kubernetes (KEDA) à Cloud Run pour permettre un scaling dynamique basé sur les métriques Prometheus. vLLM expose les métriques Prometheus et les envoie à Cloud Monitoring.

Objectifs

Au cours de ce tutoriel, vous allez :

Coûts

Dans ce document, vous utilisez les composants facturables de suivants Google Cloud:

Obtenez une estimation des coûts en fonction de votre utilisation prévue, utilisez le simulateur de coût.

Les nouveaux utilisateurs de Google Cloud peuvent bénéficier d'un essai sans frais.

Avant de commencer

  1. Connectez-vous à votre Google Cloud compte. 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.

  2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  3. Verify that billing is enabled for your Google Cloud project.

  4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

    Roles required to select or create a project

    • Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
    • Create a project: To create a project, you need the Project Creator role (roles/resourcemanager.projectCreator), which contains the resourcemanager.projects.create permission. Learn how to grant roles.

    Go to project selector

  5. Verify that billing is enabled for your Google Cloud project.

  6. Activez les API Cloud Run, Parameter Manager, Artifact Registry, Cloud Build, Secret Manager et Cloud Monitoring.

    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 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.

    Activer les API

  7. Installez et initialisez gcloud CLI.
  8. Définissez les variables d'environnement utilisées tout au long de ce tutoriel : 
    export PROJECT_ID=PROJECT_ID
export REGION=us-central1
export VLLM_SERVICE_NAME=vllm-service
export MODEL_NAME=gemma-2-2b-it
export REPO_NAME=vllm-repo
export BUCKET_NAME=my-vllm-models-${PROJECT_ID}
export CREMA_SERVICE_NAME=crema-service
     Remplacez PROJECT_ID par l'ID de votre Google Cloud projet.
  9. Définissez la configuration de votre projet : 
    gcloud config set project $PROJECT_ID
  10. Si vous n'en avez pas déjà un, créez un compte sur Hugging Face. Ensuite, créez un jeton read (lecture) sur le site Hugging Face. Hugging Face n'affiche le jeton qu'une seule fois. Enregistrez-le dans un emplacement sécurisé, car vous ne pourrez plus le consulter.
  11. Accédez à la page du modèle gemma-2-2b-it sur Hugging Face et acceptez les conditions d'utilisation du modèle.

Rôles requis

Pour obtenir les autorisations nécessaires pour suivre le tutoriel, demandez à votre administrateur de vous accorder les rôles IAM suivants sur votre projet :

Pour en savoir plus sur l'attribution de rôles, consultez Gérer l'accès aux projets, aux dossiers et aux organisations.

Vous pouvez également obtenir les autorisations requises via des rôles personnalisés ou d'autres rôles prédéfinis.

Télécharger et importer des pondérations de modèle dans Cloud Storage

Téléchargez les pondérations de modèle depuis Hugging Face et transférez-les vers un bucket Cloud Storage pour les rendre disponibles pour la mise en service du modèle :

  1. Installez la CLI Hugging Face :

    pip install -U "huggingface_hub[cli]"

  2. Téléchargez les pondérations de modèle localement à l'aide de la CLI Hugging Face :

    export HF_TOKEN="HF_TOKEN"
export LOCAL_DIR="/tmp/$MODEL_NAME"
HF_HOME=/tmp/huggingface python -m huggingface_hub.cli.hf download google/$MODEL_NAME --token $HF_TOKEN --local-dir=$LOCAL_DIR

    Remplacez HF_TOKEN par votre jeton d'accès utilisateur Hugging Face. Le jeton doit commencer par hf_, suivi de 35 caractères alphanumériques aléatoires (par exemple, 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).

  3. Créez un bucket Cloud Storage et copiez les pondérations téléchargées :

    gcloud storage buckets create gs://$BUCKET_NAME \
    --project=$PROJECT_ID \
    --location=$REGION \
    --uniform-bucket-level-access

gcloud storage cp -r $LOCAL_DIR gs://$BUCKET_NAME/

Transférer l'image de conteneur vLLM vers Artifact Registry

Extrayez les images de conteneur de mise en service de votre modèle et transférez-les vers un dépôt dans Artifact Registry :

  1. Créez un dépôt Docker dans Artifact Registry :

    gcloud artifacts repositories create $REPO_NAME \
    --repository-format=docker \
    --location=$REGION \
    --description="vLLM Docker Images"

  2. Authentifiez le daemon Docker local auprès du registre :

    gcloud auth configure-docker ${REGION}-docker.pkg.dev

  3. Extrayez l'image vLLM, balisez-la et transférez-la vers Artifact Registry :

    docker pull docker.io/vllm/vllm-openai:latest
docker tag docker.io/vllm/vllm-openai:latest ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/vllm-openai:latest
docker push ${REGION}-docker.pkg.dev/${PROJECT_ID}/${REPO_NAME}/vllm-openai:latest

Déployer le service d'autoscaling CREMA

Configurez les rôles de compte de service et les fichiers manifestes de paramètres pour CREMA avant de déployer le service d'autoscaling.

Créer un compte de service personnalisé

Créez un compte de service personnalisé avec les autorisations minimales requises pour utiliser les ressources provisionnées. Ce compte de service sert d'identité à l'autoscaler. Exécutez la commande suivante pour créer le compte de service CREMA :

export CREMA_SA="crema-autoscaler@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud iam service-accounts create crema-autoscaler \
    --description="Service account for Cloud Run CREMA to read metrics and scale workloads" \
    --display-name="CREMA Autoscaler System"

Accorder des autorisations supplémentaires à votre compte de service personnalisé

Pour mettre à l'échelle le service, accordez les autorisations suivantes sur le compte de service personnalisé :

  1. Accordez à votre compte de service CREMA l'autorisation de lire à partir de Parameter Manager :

    gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$CREMA_SA" \
    --role="roles/parametermanager.parameterViewer"

  2. Accordez à votre compte de service CREMA l'autorisation de mettre à l'échelle le service :

    gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$CREMA_SA" \
    --role="roles/run.developer"

  3. Attribuez à votre compte de service CREMA le rôle d'utilisateur de compte de service :

    gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$CREMA_SA" \
    --role="roles/iam.serviceAccountUser"

  4. Accordez à votre compte de service CREMA l'autorisation d'afficher les métriques :

    gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$CREMA_SA" \
    --role="roles/monitoring.viewer"

Créer et enregistrer la configuration CREMA

Définissez les seuils et les règles de scaling dans un fichier manifeste de configuration CREMA et enregistrez-le dans Parameter Manager :

  1. Enregistrez la configuration suivante sous my-crema-config.yaml. Cette configuration déclenche le scaling lorsque le nombre de requêtes en cours d'exécution (vllm:num_requests_running) dépasse 2 :

    apiVersion: crema/v1
kind: CremaConfig
spec:
  pollingInterval: 15
  triggerAuthentications:
    - metadata:
        name: adc-trigger-auth
      spec:
        podIdentity:
          provider: gcp
  scaledObjects:
    - spec:
        scaleTargetRef:
          name: projects/PROJECT_ID/locations/us-central1/services/vllm-service
        minReplicaCount: 1
        maxReplicaCount: 5
        triggers:
          - type: prometheus
            authenticationRef:
              name: adc-trigger-auth
            metadata:
              serverAddress: https://monitoring.googleapis.com/v1/projects/PROJECT_ID/location/global/prometheus
              metric: vllm:num_requests_running
              query: sum(vllm:num_requests_running)
              threshold: '2'

  2. Enregistrez le fichier de configuration dans Parameter Manager :

    gcloud parametermanager parameters create crema-config \
    --location=global \
    --parameter-format=YAML

gcloud parametermanager parameters versions create 1 \
    --location=global \
    --parameter=crema-config \
    --payload-data-from-file=my-crema-config.yaml

Déployer le service CREMA

Déployez l'image CREMA en tant que service d'arrière-plan interne sur Cloud Run :

gcloud run deploy $CREMA_SERVICE_NAME \
    --image=us-central1-docker.pkg.dev/cloud-run-oss-images/crema-v1/autoscaler:1.0 \
    --region=$REGION \
    --service-account="$CREMA_SA" \
    --no-allow-unauthenticated \
    --no-cpu-throttling \
    --cpu=1 \
    --memory=1Gi \
    --min-instances=1 \
    --max-instances=1 \
    --ingress=internal \
    --base-image=us-central1-docker.pkg.dev/serverless-runtimes/google-24/runtimes/java25 \
    --set-env-vars="CREMA_CONFIG=projects/$PROJECT_ID/locations/global/parameters/crema-config/versions/1,OUTPUT_SCALER_METRICS=True"

Configurer les autorisations du service vLLM

Accordez au compte de service Compute Engine par défaut les autorisations d'exporter des métriques et de lire les pondérations de modèle à partir de Cloud Storage :

  1. Récupérez le numéro de votre projet :

    export PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

  2. Accordez à votre compte de service l'autorisation d'écrire des métriques :

    gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/monitoring.metricWriter"

  3. Accordez à votre compte de service l'autorisation de lire les pondérations de modèle à partir de Cloud Storage :

    gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member="serviceAccount:$PROJECT_NUMBER-compute@developer.gserviceaccount.com" \
    --role="roles/storage.objectViewer"

Déployer le service vLLM avec un side-car OpenTelemetry

Déployez votre conteneur de mise en service vLLM principal sur Cloud Run avec les pondérations de modèle montées à partir de Cloud Storage. Étant donné que le déploiement de services multiconteneurs avec des side-cars sur Cloud Run nécessite une spécification de service YAML déclarative, vous configurez le moteur vLLM principal avec un collecteur side-car OpenTelemetry pour extraire et exporter les métriques vLLM :

  1. Enregistrez la spécification de déploiement multiconteneur suivante sous vllm-service.yaml :

    apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: vllm-service
  labels:
    cloud.googleapis.com/location: us-central1
  annotations:
    run.googleapis.com/scalingMode: manual
    run.googleapis.com/manualInstanceCount: "1"
spec:
  template:
    metadata:
      annotations:
        run.googleapis.com/execution-environment: gen2
        run.googleapis.com/cpu-throttling: "false"
        run.googleapis.com/gpu-zonal-redundancy-disabled: "true"
        autoscaling.knative.dev/minScale: "1"
    spec:
      containerConcurrency: 80
      nodeSelector:
        run.googleapis.com/accelerator: nvidia-l4
      volumes:
        - name: gcs-volume
          csi:
            driver: gcsfuse.run.googleapis.com
            volumeAttributes:
              bucketName: my-vllm-models-PROJECT_ID
      containers:
        # Primary container: vLLM serving engine
        - name: vllm-container
          image: us-central1-docker.pkg.dev/PROJECT_ID/vllm-repo/vllm-openai:latest
          ports:
            - containerPort: 8080
          resources:
            limits:
              cpu: "4"
              memory: 16Gi
              nvidia.com/gpu: "1"
          args:
            - "--model"
            - "/gcs/gemma-2-2b-it"
            - "--port"
            - "8080"
            - "--max-model-len"
            - "2048"
            - "--chat-template"
            - "{% for msg in messages %}{{ msg['content'] }}{% endfor %}"
          volumeMounts:
            - name: gcs-volume
              mountPath: /gcs
          startupProbe:
            httpGet:
              path: /health
              port: 8080
            periodSeconds: 10
            failureThreshold: 24

        # Sidecar container: OpenTelemetry Collector
        - name: otel-collector
          image: otel/opentelemetry-collector-contrib:latest
          resources:
            limits:
              cpu: "1"
              memory: 1Gi
          args:
            - |
              --config=yaml:
              receivers:
                prometheus:
                  config:
                    scrape_configs:
                      - job_name: 'vllm'
                        scrape_interval: 10s
                        metrics_path: '/metrics'
                        static_configs:
                          - targets: ['localhost:8080']
              processors:
                resourcedetection:
                  detectors: [gcp]
                  timeout: 2s
                transform:
                  metric_statements:
                    - context: datapoint
                      statements:
                        - set(attributes["exported_location"], attributes["location"])
                        - delete_key(attributes, "location")
                        - set(attributes["exported_cluster"], attributes["cluster"])
                        - delete_key(attributes, "cluster")
                        - set(attributes["exported_namespace"], attributes["namespace"])
                        - delete_key(attributes, "namespace")
                        - set(attributes["exported_job"], attributes["job"])
                        - delete_key(attributes, "job")
                        - set(attributes["exported_instance"], attributes["instance"])
                        - delete_key(attributes, "instance")
              exporters:
                googlemanagedprometheus:
              service:
                pipelines:
                  metrics:
                    receivers: [prometheus]
                    processors: [resourcedetection, transform]
                    exporters: [googlemanagedprometheus]

  2. Remplacez la configuration de service existante par le fichier manifeste multiconteneur :

    gcloud run services replace vllm-service.yaml

Vérifier les journaux du service CREMA

  1. Dans la Google Cloud console, accédez à la page Cloud Run.
  2. Sélectionnez votre crema-service.

  3. Cliquez sur l'onglet Journaux et vérifiez que les cycles d'interrogation des métriques sont actifs :

    [INFO] [METRIC-PROVIDER] Starting metric collection cycle
[INFO] [METRIC-PROVIDER] Successfully fetched scaled object metrics ...
[INFO] [METRIC-PROVIDER] Sending scale request ...
[INFO] [SCALER] Received ScaleRequest ...
[INFO] [SCALER] Current instances ...
[INFO] [SCALER] Recommended instances ...

Exécuter un test de charge

Pour tester l'autoscaling, exécutez un script de test de charge afin d'envoyer des requêtes simultanées au service vLLM :

  1. Dans votre répertoire de travail, créez un fichier nommé load-test.sh et ajoutez le code suivant :

    #!/bin/bash

export SERVICE_URL=$(gcloud run services describe $VLLM_SERVICE_NAME --region $REGION --format='value(status.url)')

echo "Launching 5 parallel heavy requests to trigger autoscaling..."

for i in {1..5}; do
    curl -s -X POST "${SERVICE_URL}/v1/chat/completions" \
        -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
        -H "Content-Type: application/json" \
        -d "{
            \"model\": \"/gcs/${MODEL_NAME}\",
            \"messages\": [{\"role\": \"user\", \"content\": \"Write an exceptionally long, detailed, and exhaustive essay about the entire history of the universe from the Big Bang to the modern day.\"}]
        }" > /dev/null &
done

echo "All 5 requests dispatched. Waiting for requests to complete..."
wait
echo "Done."

  2. Rendez le script exécutable et exécutez le test de charge :

    chmod +x load-test.sh
./load-test.sh

  3. Vérifiez à nouveau les journaux crema-service et le tableau de bord des métriques Cloud Run pour vous assurer que le nombre d'instances recommandé augmente en réponse aux requêtes mises en file d'attente.

Explorer les métriques vLLM dans Cloud Monitoring

Après avoir exécuté le test de charge, découvrez comment le trafic affecte les métriques de mise en service du modèle dans Cloud Monitoring :

  1. Dans la Google Cloud console, accédez à la page Explorateur de métriques dans Cloud Monitoring.

    Accéder à l'explorateur de métriques

  2. Cliquez sur Sélectionner une métrique.

  3. Développez Cible Prometheus > Vllm et sélectionnez l'une des métriques disponibles se terminant par /gauge. Par exemple, sélectionnez prometheus/vllm:num_requests_running/gauge pour afficher le nombre de requêtes actives pendant le test de charge.

Comme décrit dans la documentation sur les métriques de production vLLM, les métriques vLLM supplémentaires exportées vers Cloud Monitoring incluent les suivantes :

  • prometheus/vllm:num_requests_waiting/gauge : nombre de requêtes en attente dans la file d'attente pour être traitées par le moteur vLLM.
  • prometheus/vllm:num_requests_running/gauge : nombre de requêtes exécutées dans des lots de modèles.
  • prometheus/vllm:gpu_cache_usage_perc/gauge : pourcentage de mémoire du cache KV du GPU utilisée.
  • prometheus/vllm:num_requests_swapped/gauge : nombre de requêtes dont le cache KV a été échangé avec la mémoire du processeur hôte en raison d'une pression sur la mémoire.

Bien que ce tutoriel effectue le scaling en fonction de vllm:num_requests_running, vous pouvez utiliser n'importe laquelle de ces métriques vLLM dans votre configuration CREMA pour personnaliser les règles d'autoscaling de vos charges de travail en fonction de la taille de la file d'attente, de l'utilisation du cache KV ou de l'échange de requêtes.

Contrairement aux métriques de simultanéité des requêtes HTTP standards qui traitent toutes les requêtes de manière égale, les métriques internes de vLLM tiennent compte de l'empreinte mémoire GPU dynamique des différentes longueurs d'invite. Le scaling sur vllm:num_requests_running vous permet d'effectuer un scaling proactif en fonction de la charge GPU réelle. Cela permet de maintenir une mémoire tampon de capacité active avant que le serveur ne soit obligé de mettre en file d'attente les requêtes dans vllm:num_requests_waiting, ce qui protège les utilisateurs contre les pics de latence importants du délai d'émission du premier jeton (TTFT).

Libérer de l'espace

Pour éviter des frais supplémentaires sur votre Google Cloud compte, supprimez toutes les ressources que vous avez déployées avec ce tutoriel.

Supprimer le projet

Si vous avez créé un projet pour ce tutoriel, supprimez-le. Si vous avez utilisé un projet existant et que vous devez le conserver sans les modifications que vous avez ajoutées dans ce tutoriel, supprimez les ressources que vous avez créées pour ce tutoriel.

Le moyen le plus simple d'empêcher la facturation est de supprimer le projet que vous avez créé pour ce tutoriel.

Pour supprimer le projet :

  1. Dans la Google Cloud console, accédez à la page Gérer les ressources.

    Accéder à la page "Gérer les ressources"

  2. Dans la liste des projets, sélectionnez le projet que vous souhaitez supprimer, puis cliquez sur Supprimer.
  3. Dans la boîte de dialogue, saisissez l'ID du projet, puis cliquez Arrêter pour supprimer le projet.

Supprimer les ressources du tutoriel

  1. Supprimez le service Cloud Run que vous avez déployé dans ce tutoriel. Les services Cloud Run n'entraînent pas de coûts tant qu'ils ne reçoivent pas de requêtes.

    Pour supprimer votre service Cloud Run, exécutez la commande suivante :

    gcloud run services delete SERVICE-NAME

    Remplacez SERVICE-NAME par le nom du service.

    Vous pouvez également supprimer des services Cloud Run à partir de la Google Cloud console.

  2. Supprimez la configuration régionale gcloud par défaut que vous avez ajoutée lors de la configuration du tutoriel :

     gcloud config unset run/region

  3. Supprimez la configuration du projet :

     gcloud config unset project

  4. Supprimez la configuration CREMA attribuée à Parameter Manager :

    gcloud parametermanager parameters delete crema-config \
    --location=global \
    --quiet

  5. Supprimez le compte de service personnalisé créé pour CREMA :

    gcloud iam service-accounts delete $CREMA_SA \
    --quiet

  6. Supprimez le bucket Cloud Storage contenant le modèle :

    gcloud storage rm --recursive gs://$BUCKET_NAME

  7. Supprimez les autres Google Cloud ressources créées dans ce tutoriel :

Étape suivante