vLLM-Modellbereitstellung mit GPU-Messwerten automatisch skalieren

In dieser Anleitung wird beschrieben, wie Sie Ihre Cloud Run-Dienste, die LLMs mit vLLM bereitstellen, anhand benutzerdefinierter GPU-Messwerte mit Cloud Run External Metrics Autoscaling (CREMA) automatisch skalieren.

Cloud Run wird standardmäßig anhand der CPU-Auslastung und Parallelität automatisch skaliert. GPU-intensive Inferenzarbeitslasten erfordern jedoch häufig ein Autoscaling basierend auf Warteschlangenmesswerten wie der Anzahl der ausgeführten Anfragen oder der KV-Cache-Auslastung. CREMA integriert das Kubernetes-basierte Event Driven Autoscaling (KEDA) in Cloud Run, um eine dynamische Skalierung basierend auf Prometheus-Messwerten zu ermöglichen. vLLM stellt die Prometheus-Messwerte bereit und sendet sie an Cloud Monitoring.

Ziele

In dieser Anleitung wird Folgendes beschrieben:

Kosten

In diesem Dokument verwenden Sie die folgenden kostenpflichtigen Komponenten von Google Cloud:

Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen. Verwenden Sie den Preisrechner.

Neuen Nutzern von Google Cloud steht möglicherweise eine kostenlose Testversion zur Verfügung.

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie ein Konto, um die Leistungsfähigkeit unserer Produkte in der Praxis sehen und bewerten zu können. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

  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. Aktivieren Sie die Cloud Run API, die Parameter Manager API, die Artifact Registry API, die Cloud Build API, die Secret Manager API und die Cloud Monitoring API.

    Rollen, die zum Aktivieren von APIs erforderlich sind

    Zum Aktivieren von APIs benötigen Sie die Berechtigung serviceusage.services.enable. Wenn Sie das Projekt erstellt haben, haben Sie diese Berechtigung wahrscheinlich bereits über die Rolle „Inhaber“ (roles/owner). Andernfalls können Sie diese Berechtigung über die Rolle „Service Usage-Administrator“ (roles/serviceusage.serviceUsageAdmin) erhalten. Informationen zum Zuweisen von Rollen.

    APIs aktivieren

  7. Installieren und initialisieren Sie die gcloud CLI.
  8. Legen Sie die Umgebungsvariablen fest, die in dieser Anleitung verwendet werden: 
    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
     Ersetzen Sie PROJECT_ID durch Ihre Google Cloud Projekt-ID.
  9. Legen Sie Ihre Projektkonfiguration fest: 
    gcloud config set project $PROJECT_ID
  10. Wenn Sie noch kein Konto haben, erstellen Sie ein Konto bei Hugging Face. Erstellen Sie dann auf der Hugging Face-Website ein Lesetoken. Hugging Face zeigt das Token nur einmal an. Speichern Sie es an einem sicheren Ort, da Sie es nicht noch einmal aufrufen können.
  11. Rufen Sie die Modellseite gemma-2-2b-it auf Hugging Face auf und akzeptieren Sie die Nutzungsbedingungen des Modells.

Erforderliche Rollen

Bitten Sie Ihren Administrator, Ihnen die folgenden IAM-Rollen für Ihr Projekt zuzuweisen, um die Berechtigungen zu erhalten, die Sie zum Ausführen der Anleitung benötigen:

Weitere Informationen zum Zuweisen von Rollen finden Sie unter Zugriff auf Projekte, Ordner und Organisationen verwalten.

Sie können die erforderlichen Berechtigungen auch über benutzerdefinierte Rollen oder andere vordefinierte Rollen erhalten.

Modellgewichte herunterladen und in Cloud Storage hochladen

Laden Sie Modellgewichte von Hugging Face herunter und übertragen Sie sie in einen Cloud Storage-Bucket, um sie für die Modellbereitstellung verfügbar zu machen:

  1. Installieren Sie die Hugging Face CLI:

    pip install -U "huggingface_hub[cli]"

  2. Laden Sie die Modellgewichte lokal mit der Hugging Face CLI herunter:

    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

    Ersetzen Sie HF_TOKEN durch Ihr Hugging Face-Nutzerzugriffstoken. Das Token sollte mit hf_ beginnen, gefolgt von 35 zufälligen alphanumerischen Zeichen (z. B. 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).

  3. Erstellen Sie einen Cloud Storage-Bucket und kopieren Sie die heruntergeladenen Gewichte:

    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/

Das vLLM-Container-Image per Push an Artifact Registry übertragen

Rufen Sie Ihre Container-Images für die Modellbereitstellung ab und übertragen Sie sie per Push in ein Repository in Artifact Registry:

  1. Erstellen Sie ein Docker-Repository in Artifact Registry:

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

  2. Authentifizieren Sie den lokalen Docker-Daemon bei der Registry:

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

  3. Rufen Sie das vLLM-Image ab, taggen Sie es und übertragen Sie es per Push an 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

Den CREMA-Autoscaler-Dienst bereitstellen

Konfigurieren Sie die Dienstkontorollen und Parameter-Manifeste für CREMA, bevor Sie den Autoscaler-Dienst bereitstellen.

Benutzerdefiniertes Dienstkonto erstellen

Erstellen Sie ein benutzerdefiniertes Dienstkonto mit den Mindestberechtigungen, die erforderlich sind, um die bereitgestellten Ressourcen zu verwenden. Dieses Dienstkonto fungiert als Identität für den Autoscaler. Führen Sie den folgenden Befehl aus, um das CREMA-Dienstkonto zu erstellen:

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"

Dem benutzerdefinierten Dienstkonto zusätzliche Berechtigungen gewähren

Um den Dienst zu skalieren, gewähren Sie dem benutzerdefinierten Dienstkonto die folgenden Berechtigungen:

  1. Gewähren Sie Ihrem CREMA-Dienstkonto die Berechtigung zum Lesen aus dem Parameter Manager:

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

  2. Gewähren Sie Ihrem CREMA-Dienstkonto die Berechtigung zum Skalieren des Dienstes:

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

  3. Weisen Sie Ihrem CREMA-Dienstkonto die Rolle „Dienstkontonutzer“ zu:

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

  4. Gewähren Sie Ihrem CREMA-Dienstkonto die Berechtigung zum Aufrufen von Messwerten:

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

CREMA-Konfiguration erstellen und registrieren

Definieren Sie Skalierungsgrenzwerte und -regeln in einem CREMA-Konfigurationsmanifest und registrieren Sie es im Parameter Manager:

  1. Speichern Sie die folgende Konfiguration als my-crema-config.yaml. Diese Konfiguration löst die Skalierung aus, wenn die Anzahl der ausgeführten Anfragen (vllm:num_requests_running) 2 überschreitet:

    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. Registrieren Sie die Konfigurationsdatei im 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

CREMA-Dienst bereitstellen

Stellen Sie das CREMA-Image als internen Hintergrunddienst in Cloud Run bereit:

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"

Berechtigungen für den vLLM-Dienst konfigurieren

Gewähren Sie dem Standarddienstkonto von Compute Engine die Berechtigungen zum Exportieren von Messwerten und zum Lesen von Modellgewichten aus Cloud Storage:

  1. Rufen Sie Ihre Projektnummer ab:

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

  2. Gewähren Sie Ihrem Dienstkonto die Berechtigung zum Schreiben von Messwerten:

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

  3. Gewähren Sie Ihrem Dienstkonto die Berechtigung zum Lesen von Modellgewichten aus Cloud Storage:

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

Den vLLM-Dienst mit OpenTelemetry-Sidecar bereitstellen

Stellen Sie Ihren primären vLLM-Bereitstellungscontainer in Cloud Run bereit, wobei die Modellgewichte aus Cloud Storage eingebunden werden. Da für die Bereitstellung von Diensten mit mehreren Containern und Sidecars in Cloud Run eine deklarative YAML-Dienstspezifikation erforderlich ist, konfigurieren Sie die primäre vLLM-Engine zusammen mit einem OpenTelemetry-Sidecar-Collector, um vLLM-Messwerte zu erfassen und zu exportieren:

  1. Speichern Sie die folgende Spezifikation für die Bereitstellung mit mehreren Containern als 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. Ersetzen Sie die vorhandene Dienstkonfiguration durch das Manifest für mehrere Container:

    gcloud run services replace vllm-service.yaml

CREMA-Dienstlogs prüfen

  1. Wechseln Sie in der Google Cloud Console zur Seite Cloud Run.
  2. Wählen Sie Ihren crema-service aus.

  3. Klicken Sie auf den Tab Logs und prüfen Sie, ob die Zyklen für die Messwerterfassung aktiv sind:

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

Lasttest ausführen

Um das Autoscaling zu testen, führen Sie ein Lasttestskript aus, um gleichzeitige Anfragen an den vLLM-Dienst zu senden:

  1. Erstellen Sie in Ihrem Arbeitsverzeichnis eine Datei mit dem Namen load-test.sh und fügen Sie den folgenden Code hinzu:

    #!/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. Machen Sie das Skript ausführbar und führen Sie den Lasttest aus:

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

  3. Prüfen Sie noch einmal die crema-service-Logs und das Cloud Run-Dashboard für Messwerte, um zu bestätigen, dass die empfohlene Anzahl von Instanzen als Reaktion auf die Anfragen in der Warteschlange erhöht wird.

vLLM-Messwerte in Cloud Monitoring untersuchen

Nachdem Sie den Lasttest ausgeführt haben, untersuchen Sie, wie sich der Traffic auf die Messwerte für die Modellbereitstellung in Cloud Monitoring auswirkt:

  1. Wechseln Sie in der Google Cloud Console zur Seite Metrics Explorer in Cloud Monitoring.

    Zum Metrics Explorer

  2. Klicken Sie auf Messwert auswählen.

  3. Maximieren Sie Prometheus-Ziel > Vllm und wählen Sie einen der verfügbaren Messwerte aus, der mit /gauge endet. Wählen Sie beispielsweise prometheus/vllm:num_requests_running/gauge aus, um die Anzahl der aktiven Anfragen während des Lasttests aufzurufen.

Wie in der Dokumentation zu vLLM-Produktionsmesswerten beschrieben, werden zusätzlich die folgenden vLLM-Messwerte nach Cloud Monitoring exportiert:

  • prometheus/vllm:num_requests_waiting/gauge: Die Anzahl der Anfragen, die in der Warteschlange auf die Verarbeitung durch die vLLM-Engine warten.
  • prometheus/vllm:num_requests_running/gauge: Die Anzahl der Anfragen, die in Modellbatches ausgeführt werden.
  • prometheus/vllm:gpu_cache_usage_perc/gauge: Der Prozentsatz des verwendeten GPU-KV-Cache-Speichers.
  • prometheus/vllm:num_requests_swapped/gauge: Die Anzahl der Anfragen, deren KV-Cache aufgrund von Speichermangel in den CPU-Arbeitsspeicher des Hosts ausgelagert wurde.

In dieser Anleitung wird die Skalierung anhand von vllm:num_requests_running durchgeführt. Sie können jedoch jeden dieser vLLM-Messwerte in Ihrer CREMA-Konfiguration verwenden, um die Autoscaling-Regeln für Ihre Arbeitslasten basierend auf der Warteschlangengröße, der KV-Cache-Auslastung oder dem Auslagern von Anfragen anzupassen.

Im Gegensatz zu Standardmesswerten für die Parallelität von HTTP-Anfrage, bei denen alle Anfragen gleich behandelt werden, berücksichtigen die internen Messwerte von vLLM den dynamischen GPU-Arbeitsspeicherbedarf unterschiedlicher Promptlängen. Durch die Skalierung anhand von vllm:num_requests_running können Sie proaktiv basierend auf der tatsächlichen GPU-Last skalieren. So wird ein aktiver Kapazitätspuffer aufrechterhalten, bevor der Server Anfragen in die Warteschlange vllm:num_requests_waiting stellen muss. Dadurch werden Nutzer vor starken Spitzen bei der TTFT-Latenz (Time To First Token) geschützt.

Bereinigen

Löschen Sie alle Ressourcen , die Sie mit dieser Anleitung bereitgestellt haben, um zusätzliche Kosten für Ihr Google Cloud Konto zu vermeiden.

Projekt löschen

Wenn Sie ein neues Projekt für diese Anleitung erstellt haben, löschen Sie das Projekt. Wenn Sie ein vorhandenes Projekt verwendet haben und es beibehalten möchten, ohne die Änderungen in dieser Anleitung hinzuzufügen , löschen Sie die für die Anleitung erstellten Ressourcen.

Am einfachsten vermeiden Sie weitere Kosten, wenn Sie das zum Ausführen der Anleitung erstellte Projekt löschen.

So löschen Sie das Projekt:

  1. Wechseln Sie in der Google Cloud Console zur Seite Ressourcen verwalten.

    Zur Seite „Ressourcen verwalten“

  2. Wählen Sie in der Projektliste das Projekt aus, das Sie löschen möchten, und klicken Sie auf Löschen.
  3. Geben Sie im Dialogfeld die Projekt-ID ein und klicken Sie auf Shut down (Herunterfahren), um das Projekt zu löschen.

Anleitungsressourcen löschen

  1. Löschen Sie den Cloud Run-Dienst, den Sie in dieser Anleitung bereitgestellt haben. Für Cloud Run-Dienste fallen erst Kosten an, wenn sie Anfragen erhalten.

    Führen Sie den folgenden Befehl aus, um Ihren Cloud Run-Dienst zu löschen:

    gcloud run services delete SERVICE-NAME

    Ersetzen Sie SERVICE-NAME durch den Namen Ihres Dienstes.

    Sie können Cloud Run-Dienste auch über die Google Cloud Console löschen.

  2. Entfernen Sie die Konfiguration der Standardregion gcloud, die Sie während der Einrichtung für die Anleitung hinzugefügt haben:

     gcloud config unset run/region

  3. Entfernen Sie die Projektkonfiguration:

     gcloud config unset project

  4. Löschen Sie die CREMA-Konfiguration, die Parameter Manager zugewiesen ist:

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

  5. Löschen Sie das benutzerdefinierte Dienstkonto, das für CREMA erstellt wurde:

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

  6. Löschen Sie den Cloud Storage-Bucket, der das Modell enthält:

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

  7. Löschen Sie andere Google Cloud Ressourcen, die in dieser Anleitung erstellt wurden:

Nächste Schritte