vLLM in GKE verwenden, um die Inferenz von Gemma 3 27B bereitzustellen

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

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

Ziele

  1. Auf Gemma 3 mit Hugging Face zugreifen.

  2. Umgebung vorbereiten.

  3. GKE-Cluster im Autopilot-Modus erstellen.

  4. Kubernetes-Secret für Hugging Face-Anmeldedaten erstellen.

  5. vLLM-Container in Ihrem GKE-Cluster bereitstellen.

  6. Mit Gemma 3 über „curl“ interagieren.

  7. Bereinigen.

Kosten

In dieser Anleitung werden kostenpflichtige Komponenten von Google Cloud verwendet, darunter:

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

Hinweis

  1. Installieren Sie die Google Cloud CLI.

  2. Konfigurieren Sie die gcloud CLI für die Verwendung Ihrer föderierten Identität.

    Weitere Informationen finden Sie unter Mit Ihrer föderierten Identität in der gcloud CLI anmelden.

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

    gcloud init

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

    Erforderliche Rollen zum Auswählen oder Erstellen eines Projekts

    • Projekt auswählen: Für die Auswahl eines Projekts ist keine bestimmte IAM-Rolle erforderlich. Sie können ein beliebiges 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 resourcemanager.projects.create Berechtigung enthält. Rollen zuweisen.

    • Google Cloud Projekt erstellen:

      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 Google Cloud Projekt aus, das Sie erstellt haben:

      gcloud config set project PROJECT_ID

      Ersetzen Sie PROJECT_ID durch Ihren Google Cloud Projektnamen.

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

  6. Aktivieren Sie die erforderliche API:

    Erforderliche Rollen zum Aktivieren von APIs

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

    gcloud services enable container.googleapis.com

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

  8. Melden Sie sich in einem Hugging Face Konto an oder erstellen Sie eines.

Auf Gemma 3 mit Hugging Face zugreifen

So greifen Sie mit Hugging Face auf Gemma 3 zu:

  1. Melden Sie sich bei Hugging Face an.
  2. Erstellen Sie ein Hugging Face-readZugriffstoken. Klicken Sie auf Mein Profil > Einstellungen > Zugriffstokens > +Neues Token erstellen.
  3. Kopieren und speichern Sie den read access Token-Wert. Sie verwenden es später in dieser Anleitung.

Umgebung vorbereiten

Legen Sie die Standardumgebungsvariablen fest, um Ihre Umgebung vorzubereiten:

export PROJECT_ID="YOUR_PROJECT_ID"
export RESERVATION_URL="YOUR_RESERVATION_NAME"
export REGION="YOUR_REGION"
export CLUSTER_NAME="YOUR_CLUSTER_NAME"
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:

  • PROJECT_ID: Die ID des Google Cloud Projekts , in dem Sie den GKE-Cluster erstellen möchten.

  • RESERVATION_URL: Die URL 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 die Reservierung verwenden: projects/RESERVATION_PROJECT_ID/reservations/RESERVATION_NAME

  • REGION: Die Region, in der Sie Ihren GKE-Cluster erstellen möchten. Sie können den Cluster nur in der Region erstellen, in der sich Ihre Reservierung befindet.

  • CLUSTER_NAME: Der Name des zu erstellenden GKE-Cluster.

  • YOUR_HF_TOKEN: Das Hugging Face-Zugriffstoken, das Sie im vorherigen Abschnitt erstellt haben.

  • NETWORK: 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.

  • SUBNETWORK: Das Subnetzwerk, das der GKE-Cluster verwendet. Geben Sie einen der folgenden Werte an:

    • Wenn Sie ein benutzerdefiniertes Subnetzwerk erstellt haben, geben Sie den Namen Ihres 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. Prüfen Sie in der Google Cloud Console unter „ Kubernetes-Cluster“, ob Google Cloud die Erstellung des Clusters abgeschlossen ist.

Kubernetes-Secret für Hugging Face-Anmeldedaten erstellen

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

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

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

  2. Erstellen Sie ein Kubernetes-Secret, um Ihr Hugging Face-Token zu speichern:

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

vLLM-Container in Ihrem GKE-Cluster bereitstellen

So stellen Sie den vLLM-Container bereit, um das Gemma 3 27B-Modell mit Kubernetes-Bereitstellungen bereitzustellen:

  1. Erstellen Sie eine vllm-3-27b-it.yaml-Datei mit der von Ihnen ausgewählten vLLM-Bereitstellung:

    apiVersion: apps/v1
kind: Deployment
metadata:
  name: vllm-gemma-deployment
spec:
  progressDeadlineSeconds: 900
  replicas: 1
  selector:
    matchLabels:
      app: gemma-server
  template:
    metadata:
      labels:
        app: gemma-server
        ai.gke.io/model: gemma-3-27b-it
        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:20250801_0916_RC01
        resources:
          requests:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "120Gi"
            nvidia.com/gpu: "8"
          limits:
            cpu: "10"
            memory: "128Gi"
            ephemeral-storage: "120Gi"
            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: google/gemma-3-27b-it
        - name: HUGGING_FACE_HUB_TOKEN
          valueFrom:
            secretKeyRef:
              name: hf-secret
              key: hf_api_token
        volumeMounts:
        - mountPath: /dev/shm
          name: dshm
        livenessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 720
          periodSeconds: 10
        readinessProbe:
          httpGet:
            path: /health
            port: 8000
          initialDelaySeconds: 720
          periodSeconds: 5
      volumes:
      - name: dshm
        emptyDir:
            medium: Memory
      nodeSelector:
        cloud.google.com/gke-accelerator: nvidia-b200
        cloud.google.com/reservation-name: $RESERVATION_URL
        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: gemma-server
  type: ClusterIP
  ports:
    - protocol: TCP
      port: 8000
      targetPort: 8000

  2. Wenden Sie die Datei vllm-3-27b-it.yaml auf Ihren GKE-Cluster an:

    envsubst < vllm-3-27b-it.yaml | kubectl apply -f -

    Während der Bereitstellung muss der Container Gemma 3 von Hugging Face herunterladen. Aus diesem Grund kann die Bereitstellung des Containers bis zu 30 Minuten dauern.

  3. Warten Sie, bis die Bereitstellung abgeschlossen ist:

    kubectl wait \
    --for=condition=Available \
    --timeout=1800s deployment/vllm-gemma-deployment

Mit Gemma 3 über „curl“ interagieren

So prüfen Sie die bereitgestellten, für die Anleitung abgestimmten Modelle von Gemma 3 27B:

  1. Richten Sie die Portweiterleitung zu Gemma 3 ein:

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

  2. Öffnen Sie ein neues Terminalfenster. Sie können dann mit curl mit Ihrem Modell chatten:

    curl http://127.0.0.1:8000/v1/chat/completions \
-X POST \
-H "Content-Type: application/json" \
-d '{
  "model": "google/gemma-3-27b-it",
  "messages": [
    {
      "role": "user",
      "content": "Why is the sky blue?"
    }
  ]
}' | jq .

    Die Ausgabe sieht etwa so aus:

    {
  "id": "chatcmpl-e4a2e624bea849d9b09f838a571c4d9e",
  "object": "chat.completion",
  "created": 1741763029,
  "model": "google/gemma-3-27b-it",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "reasoning_content": null,
        "content": "Okay, let's break down why the sky appears blue! It's a fascinating phenomenon rooted in physics, specifically something called **Rayleigh scattering**. Here's the explanation: ...",
        "tool_calls": []
      },
      "logprobs": null,
      "finish_reason": "stop",
      "stop_reason": 106
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "total_tokens": 668,
    "completion_tokens": 653,
    "prompt_tokens_details": null
  },
  "prompt_logprobs": null
}

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

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.

Ressourcen löschen

  1. Führen Sie den folgenden Befehl aus, um die in der Datei vllm-3-27b-it.yaml definierte Bereitstellung und den Dienst sowie das Kubernetes-Secret aus dem GKE-Cluster zu löschen:

    envsubst < vllm-3-27b-it.yaml | kubectl delete -f -
kubectl delete secret hf-secret

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

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

Projekt löschen

Google Cloud Projekt löschen:

gcloud projects delete PROJECT_ID

Nächste Schritte