Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

vLLM in GKE verwenden, um Inferenzen mit Qwen3 auszuführen

Clustered GPUs

In dieser Anleitung wird gezeigt, wie Sie ein Qwen3-LLM (Large Language Model) mit dem vLLM-Bereitstellungs-Framework bereitstellen und verfügbar machen. Sie stellen das Modell auf einer einzelnen virtuellen A4-Maschine (VM) in Google Kubernetes Engine (GKE) bereit.

Diese Anleitung richtet sich an ML-Entwickler (Machine Learning), Plattformadministratoren und ‑operatoren sowie an Daten- und KI-Spezialisten, die daran interessiert sind, Kubernetes-Container-Orchestrierungsfunktionen zum Verarbeiten von Inferenz-Arbeitslasten zu verwenden.

Ziele

Über Hugging Face auf Qwen3 zugreifen
Bereiten Sie Ihre Umgebung vor.
Erstellen Sie einen GKE-Cluster im Autopilot-Modus.
Cloud Storage-Bucket erstellen
Erstellen Sie ein Kubernetes-Secret für Hugging Face-Anmeldedaten.
Konfigurieren Sie die Workload Identity-Föderation für Cloud Storage.
Füllen Sie den Cloud Storage-Bucket mit dem Qwen3-Modell.
Stellen Sie einen vLLM-Container in Ihrer GKE bereit.
Mit Qwen3 über curl interagieren
bereinigen.

Kosten

In dieser Anleitung werden kostenpflichtige Komponenten von Google Cloudverwendet, darunter:

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

Hinweis

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.

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

So erstellen Sie ein Google Cloud Projekt:
```
gcloud projects create PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud Projekt, das Sie erstellen.
Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projekt aktiviert ist.

Aktivieren Sie die erforderliche 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

gcloud services enable container.googleapis.com

Installieren Sie die Google Cloud CLI.

Wenn Sie einen externen Identitätsanbieter (IdP) verwenden, müssen Sie sich zuerst mit Ihrer föderierten Identität in der gcloud CLI anmelden.

Führen Sie den folgenden Befehl aus, um die gcloud CLI zu initialisieren:

gcloud init

Erstellen Sie ein Google Cloud Projekt oder wählen Sie eines aus.

Rollen, die zum Auswählen oder Erstellen eines Projekts erforderlich sind

Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können jedes Projekt auswählen, für das Ihnen eine Rolle zugewiesen wurde.
Projekt erstellen: Zum Erstellen eines Projekts benötigen Sie die Rolle „Projektersteller“ (roles/resourcemanager.projectCreator), die die Berechtigung resourcemanager.projects.create enthält. Weitere Informationen zum Zuweisen von Rollen

So erstellen Sie ein Google Cloud Projekt:
```
gcloud projects create PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch einen Namen für das Google Cloud Projekt, das Sie erstellen.
Wählen Sie das von Ihnen erstellte Google Cloud Projekt aus:
```
gcloud config set project PROJECT_ID
```
Ersetzen Sie PROJECT_ID durch den Namen Ihres Projekts in Google Cloud .

Prüfen Sie, ob die Abrechnung für Ihr Google Cloud Projekt aktiviert ist.

Aktivieren Sie die erforderliche API:

Rollen, die zum Aktivieren von APIs erforderlich sind

gcloud services enable container.googleapis.com

Weisen Sie Ihrem Nutzerkonto Rollen zu. Führen Sie den folgenden Befehl für jede der folgenden IAM-Rollen einmal aus: roles/container.admin
```
gcloud projects add-iam-policy-binding PROJECT_ID --member="user:USER_IDENTIFIER" --role=ROLE
```
Ersetzen Sie Folgendes:
- PROJECT_ID: Ihre Projekt-ID.
- USER_IDENTIFIER: Die Kennung für Ihr Nutzerkonto . Beispiel: myemail@example.com
- ROLE: Die IAM-Rolle, die Sie Ihrem Nutzerkonto zuweisen.
Melden Sie sich in einem Hugging Face-Konto an oder erstellen Sie ein Konto.

Über Hugging Face auf Qwen3 zugreifen

So greifen Sie über Hugging Face auf Qwen3 zu:

Bei Hugging Face anmelden
Erstellen Sie ein Hugging Face-Zugriffstoken für read. Klicken Sie auf Profil > Einstellungen > Zugriffstokens > +Neuen Token erstellen.
Geben Sie einen Namen Ihrer Wahl für das Token an und wählen Sie dann eine Rolle aus. Die niedrigste Berechtigungsstufe, die Sie für dieses Tutorial auswählen können, ist Lesen.
Wählen Sie Token erstellen aus.
Kopieren Sie das generierte Token in die Zwischenablage und speichern Sie es. Sie benötigen sie später in dieser Anleitung.

Umgebung vorbereiten

Legen Sie die Standardumgebungsvariablen fest, um Ihre Umgebung vorzubereiten:

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_NAME="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
export GCS_BUCKET_NAME="YOUR_GCS_BUCKET"
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}"

Ersetzen Sie Folgendes:

YOUR_PROJECT_ID: die ID des Google Cloud Projekts, in dem Sie den GKE-Cluster erstellen möchten.
YOUR_RESERVATION_NAME: Der Name der Reservierung, die Sie zum Erstellen Ihres GKE-Cluster verwenden möchten. Geben Sie je nach Projekt, in dem die Reservierung vorhanden ist, einen der folgenden Werte an:
- Die Reservierung ist in Ihrem Projekt vorhanden: RESERVATION_NAME
- Die Reservierung ist in einem anderen Projekt vorhanden und Ihr Projekt kann sie nutzen: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME
YOUR_REGION: die Region, in der Sie Ihren GKE-Cluster erstellen möchten. Sie können den Cluster nur in der Region erstellen, in der Ihre Reservierung vorhanden ist.
YOUR_CLUSTER_NAME: Der Name des zu erstellenden GKE-Cluster.
YOUR_BUCKET_NAME: Der Name des regionalen Cloud Storage-Bucket, der erstellt werden soll.
YOUR_HF_TOKEN: Das Hugging Face-Zugriffstoken, das Sie im vorherigen Abschnitt erstellt haben.
YOUR_NETWORK_NAME: Das Netzwerk, das der GKE-Cluster verwendet. Geben Sie einen der folgenden Werte an:
- Wenn Sie ein benutzerdefiniertes Netzwerk erstellt haben, geben Sie den Namen Ihres Netzwerks an.
- Geben Sie andernfalls default an.
YOUR_SUBNETWORK_NAME: Das Subnetzwerk, das vom GKE-Cluster verwendet wird. Geben Sie einen der folgenden Werte an:
- Wenn Sie ein benutzerdefiniertes Subnetzwerk erstellt haben, geben Sie den Namen des Subnetzwerks an. Sie können nur ein Subnetzwerk angeben, das sich in derselben Region wie die Reservierung befindet.
- Geben Sie andernfalls default an.

GKE-Cluster im Autopilot-Modus erstellen

Führen Sie den folgenden Befehl aus, um einen GKE-Cluster im Autopilot-Modus zu erstellen:

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

Das Erstellen des GKE-Cluster kann einige Zeit dauern. Rufen Sie in der Google Cloud Console die Seite Kubernetes-Cluster auf, um zu prüfen, ob Google Cloud den Cluster erstellt hat.

Cloud Storage-Bucket erstellen

Führen Sie den folgenden Befehl aus, um einen regionalen Cloud Storage-Bucket zum Speichern Ihres Modells zu erstellen:

gcloud storage buckets create gs://$GCS_BUCKET_NAME \
    --project=$PROJECT_ID \
    --location=$REGION

Kubernetes-Secret für Hugging Face-Anmeldedaten erstellen

So erstellen Sie ein Kubernetes-Secret für Hugging Face-Anmeldedaten:

Konfigurieren Sie kubectl für die Kommunikation mit Ihrem GKE-Cluster:

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

Erstellen Sie ein Kubernetes-Secret zum Speichern Ihres Hugging Face-Tokens:

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

Workload Identity-Föderation für Cloud Storage konfigurieren

Damit GKE sicher auf den Cloud Storage-Bucket zugreifen kann, richten Sie die GKE-Workload Identity-Föderation ein:

gcloud iam service-accounts create qwen-gcs-sa \
    --project=$PROJECT_ID

gcloud storage buckets add-iam-policy-binding gs://$GCS_BUCKET_NAME \
    --member="serviceAccount:qwen-gcs-sa@$PROJECT_ID.iam.gserviceaccount.com" \
    --role="roles/storage.objectAdmin"

kubectl create serviceaccount qwen-ksa \
    --namespace=default

gcloud iam service-accounts add-iam-policy-binding qwen-gcs-sa@$PROJECT_ID.iam.gserviceaccount.com \
    --project=$PROJECT_ID \
    --role=roles/iam.workloadIdentityUser \
    --member="serviceAccount:$PROJECT_ID.svc.id.goog[default/qwen-ksa]"

kubectl annotate serviceaccount qwen-ksa \
    --namespace=default \
    iam.gke.io/gcp-service-account="qwen-gcs-sa@$PROJECT_ID.iam.gserviceaccount.com"

Cloud Storage-Bucket mit den Qwen3-Modellgewichten füllen

Um Ihren Cloud Storage-Bucket mit den Qwen3-Modellgewichten zu füllen, führen Sie einen Kubernetes-Job aus, der den Cloud Storage FUSE-CSI-Treiber verwendet, um Ihren Bucket als Volume bereitzustellen. Der Job lädt das Modell von Hugging Face herunter, falls es noch nicht im Bucket vorhanden ist.

Erstellen Sie eine Datei mit dem Namen qwen3-model-loader.yaml und dem folgendem Inhalt:

apiVersion: batch/v1
kind: Job
metadata:
  name: qwen3-model-loader
spec:
  template:
    metadata:
      annotations:
        gke-gcsfuse/volumes: "true"
        gke-gcsfuse/cpu-limit: "0"
        gke-gcsfuse/memory-limit: "0"
        gke-gcsfuse/ephemeral-storage-limit: "0"
    spec:
      serviceAccountName: qwen-ksa
      restartPolicy: OnFailure
      containers:
      - name: downloader
        image: python:3.11-slim
        resources:
          requests:
            cpu: "4"
            memory: "16Gi"
            ephemeral-storage: "100Gi"
          limits:
            cpu: "4"
            memory: "16Gi"
            ephemeral-storage: "100Gi"
        command: ["/bin/sh", "-c"]
        args:
        - |
          pip install huggingface_hub
          python3 -c '
          import os
          from huggingface_hub import snapshot_download
          model_id = "Qwen/Qwen3-235B-A22B-Instruct-2507"
          local_dir = "/data/Qwen/Qwen3-235B-A22B-Instruct-2507"
          config_path = os.path.join(local_dir, "config.json")
          if os.path.exists(config_path):
              print(f"Model already exists at {local_dir}. Skipping download.")
          else:
              print(f"Downloading model {model_id} to {local_dir}...")
              snapshot_download(
                  repo_id=model_id,
                  local_dir=local_dir,
                  local_dir_use_symlinks=False,
                  token=os.environ.get("HUGGING_FACE_HUB_TOKEN")
              )
              print("Download completed successfully!")
          '
        env:
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        volumeMounts:
        - name: gcs-fuse-volume
          mountPath: /data
      volumes:
      - name: gcs-fuse-volume
        csi:
          driver: gcsfuse.csi.storage.gke.io
          volumeAttributes:
            bucketName: $GCS_BUCKET_NAME
            mountOptions: "implicit-dirs"

Wenden Sie das qwen3-model-loader.yaml-Manifest an, um den Downloadjob zu initialisieren:
```
envsubst < qwen3-model-loader.yaml | kubectl apply -f -
```

So prüfen Sie, ob der Job ausgeführt wird:

kubectl logs -f job/qwen3-model-loader -c downloader

Warten Sie, bis der Job zum Herunterladen des Modells abgeschlossen ist:

kubectl wait \
    --for=condition=Complete \
    --timeout=1800s job/qwen3-model-loader

Führen Sie den folgenden Befehl aus, um den Job zu löschen:
```
kubectl delete job qwen3-model-loader --ignore-not-found
```

vLLM-Container in Ihrem GKE-Cluster bereitstellen

So stellen Sie den vLLM-Container für das Qwen3-Modell mit Kubernetes-Bereitstellungen bereit:

Erstellen Sie eine qwen3-235b-deploy.yaml-Datei mit der von Ihnen ausgewählten vLLM-Bereitstellung:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-qwen3-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: qwen3-server
  template:
    metadata:
      labels:
        app: qwen3-server
        ai.gke.io/model: Qwen3-235B-A22B-Instruct-2507
        ai.gke.io/inference-server: vllm
        examples.ai.gke.io/source: user-guide
    spec:
      serviceAccountName: qwen-ksa
      containers:
      - name: qwen-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: "1000Gi"
            ephemeral-storage: "500Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "1000Gi"
            ephemeral-storage: "500Gi"
            nvidia.com/gpu: "8"
        command: ["python3", "-m", "vllm.entrypoints.openai.api_server"]
        args:
        - --model=$(MODEL_ID)
        - --load-format=runai_streamer
        - --model-loader-extra-config={"distributed":true}
        - --tensor-parallel-size=8
        - --host=0.0.0.0
        - --port=8000
        - --max-model-len=8192
        - --max-num-seqs=4
        - --dtype=bfloat16
        env:
        - name: MODEL_ID
          value: "gs://$GCS_BUCKET_NAME/Qwen/Qwen3-235B-A22B-Instruct-2507"
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 200
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 200
          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: qwen3-service
spec:
  selector:
    app: qwen3-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000
---
apiVersion: monitoring.googleapis.com/v1
kind: PodMonitoring
metadata:
  name: vllm-qwen3-monitoring
spec:
  selector:
    matchLabels:
      app: qwen3-server
  endpoints:
  - port: 8000
    path: /metrics
    interval: 30s

Wenden Sie die Datei qwen3-235b-deploy.yaml auf Ihren GKE-Cluster an:
```
envsubst < qwen3-235b-deploy.yaml | kubectl apply -f -
```
Da der Container Run:ai Model Streamer verwendet, um Modellgewichte direkt aus Cloud Storage zu streamen, wird die Startzeit erheblich verkürzt.
Führen Sie den folgenden Befehl aus, um den Abschlussstatus aufzurufen:
```
kubectl wait \
    --for=condition=Available \
    --timeout=1800s deployment/vllm-qwen3-deployment
```
Mit dem Flag --timeout=600s kann der Befehl die Bereitstellung bis zu 10 Minuten lang überwachen.

Mit Qwen3 über curl interagieren

So prüfen Sie das bereitgestellte Qwen3-Modell:

Richten Sie die Portweiterleitung zu Qwen3 ein:

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

Öffnen Sie ein neues Terminalfenster. Anschließend können Sie mit Ihrem Modell chatten, indem Sie curl verwenden:

curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
  "messages": [
    {
      "role": "user",
      "content": "Describe a GPU in one short sentence?"
    }
  ],
  "stream": false
}' | jq .

Die Ausgabe sieht etwa so aus:

{
  "id": "chatcmpl-a926ddf7ef2745ca832bda096e867764",
  "object": "chat.completion",
  "created": 1755023619,
  "model": "Qwen/Qwen3-235B-A22B-Instruct-2507",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "A GPU is a specialized electronic circuit designed to rapidly process and render graphics and perform parallel computations.",
        "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": 16,
    "total_tokens": 36,
    "completion_tokens": 20,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null,
  "kv_transfer_params": null
}

Modellleistung beobachten

Wenn Sie die Leistung Ihres Modells beobachten möchten, können Sie die vLLM-Dashboard-Integration in Cloud Monitoring verwenden. In diesem Dashboard können Sie wichtige Leistungsmesswerte für Ihr Modell wie Token-Durchsatz, Netzwerklatenz und Fehlerraten ansehen. Weitere Informationen finden Sie unter vLLM in der Dokumentation zu Monitoring.

Bereinigen

Damit Ihrem Google Cloud-Konto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, löschen Sie entweder das Projekt, das die Ressourcen enthält, oder Sie behalten das Projekt und löschen die einzelnen Ressourcen.

Damit Ihrem Cloud-Rechnungskonto die in dieser Anleitung verwendeten Ressourcen nicht in Rechnung gestellt werden, können Sie entweder das Projekt löschen, das die Ressourcen enthält, oder das Projekt beibehalten und die einzelnen Ressourcen löschen.

Ressourcen löschen

Führen Sie die folgenden Befehle aus, um die Ressourcen der Anleitung zu löschen:

envsubst < qwen3-235b-deploy.yaml | kubectl delete -f -
envsubst < qwen3-model-loader.yaml | kubectl delete -f -
kubectl delete secret hf-secret
kubectl delete serviceaccount qwen-ksa

gcloud iam service-accounts delete qwen-gcs-sa@$PROJECT_ID.iam.gserviceaccount.com \
    --project=$PROJECT_ID --quiet

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

GKE-Cluster löschen

Führen Sie den folgenden Befehl aus, um Ihren GKE-Cluster zu löschen:

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

Projekt löschen

Achtung: Das Löschen von Projekten hat folgende Auswirkungen:

Alle Inhalte des Projekts werden gelöscht. Wenn Sie für die Aufgaben in diesem Dokument ein bereits bestehendes Projekt verwendet haben und dieses löschen, werden auch alle anderen im Rahmen des Projekts erstellten Daten gelöscht.
Benutzerdefinierte Projekt-IDs gehen verloren. Beim Erstellen dieses Projekts haben Sie möglicherweise eine benutzerdefinierte Projekt-ID erstellt, die Sie weiterhin verwenden möchten. Damit die URLs, die die Projekt-ID nutzen, zum Beispiel eine appspot.com-URL, erhalten bleiben, sollten Sie ausgewählte Ressourcen innerhalb des Projekts löschen, anstatt das gesamte Projekt.

Wenn Sie mehrere Architekturen, Anleitungen und Kurzanleitungen durcharbeiten möchten, können Sie die Überschreitung von Projektkontingenten verhindern, indem Sie Projekte wiederverwenden.

Google Cloud -Projekt löschen:

gcloud projects delete PROJECT_ID