Gemma 3 mit vLLM in Cloud Run bereitstellen

1. Einführung

Large Language Models (LLMs) verändern die Art und Weise, wie wir intelligente Anwendungen entwickeln. Es kann jedoch schwierig sein, diese leistungsstarken Modelle für den Einsatz in der Praxis vorzubereiten. Sie benötigen viel Rechenleistung, insbesondere Grafikkarten (GPUs), und intelligente Methoden, um viele Anfragen gleichzeitig zu verarbeiten. Außerdem möchten Sie die Kosten niedrig halten und dafür sorgen, dass Ihre Anwendung reibungslos und ohne Verzögerungen ausgeführt wird.

In diesem Codelab erfahren Sie, wie Sie diese Herausforderungen meistern können. Wir verwenden dazu zwei wichtige Tools:

vLLM: Stellen Sie sich das als superschnelle Engine für LLMs vor. Dadurch laufen Ihre Modelle viel effizienter, da mehr Anfragen gleichzeitig verarbeitet werden können und der Arbeitsspeicherverbrauch sinkt.
Google Cloud Run: Dies ist die serverlose Plattform von Google. Es eignet sich hervorragend für die Bereitstellung von Anwendungen, da die gesamte Skalierung für Sie übernommen wird – von null auf Tausende von Nutzern und wieder zurück. Das Beste daran: Cloud Run unterstützt jetzt GPUs, die für das Hosten von LLMs unerlässlich sind.

Zusammen bieten vLLM und Cloud Run eine leistungsstarke, flexible und kostengünstige Möglichkeit, Ihre LLMs bereitzustellen. In diesem Leitfaden stellen Sie ein offenes Modell bereit, das als Standard-Web-API verfügbar ist.

Lerninhalte

So wählen Sie die richtige Modellgröße und ‑variante für die Bereitstellung aus.
vLLM für die Bereitstellung von OpenAI-kompatiblen API-Endpunkten einrichten
vLLM-Server mit Docker in einen Container packen
Container-Image per Push an Google Artifact Registry übertragen
So stellen Sie den Container in Cloud Run mit GPU-Beschleunigung bereit.
So testen Sie Ihr bereitgestelltes Modell.

Voraussetzungen

Ein Browser wie Chrome für den Zugriff auf die Google Cloud Console
Eine zuverlässige Internetverbindung
Ein Google Cloud-Projekt mit aktivierter Abrechnung
Ein Hugging Face-Zugriffstoken (hier erstellen, falls Sie noch keines haben)
Grundkenntnisse in Python, Docker und der Befehlszeile
Neugier und Lernbereitschaft

2. Vorbereitung

Google Cloud-Projekt einrichten

Für dieses Codelab ist ein Google Cloud-Projekt mit einem aktiven Rechnungskonto erforderlich.

Bei Kursen mit Kursleiter:Wenn Sie sich in einem Kursraum befinden, stellt Ihnen der Kursleiter die erforderlichen Projekt- und Abrechnungsinformationen zur Verfügung. Folgen Sie der Anleitung Ihres Kursleiters, um die Einrichtung abzuschließen.
Für unabhängige Lernende:Wenn Sie diesen Kurs allein durchführen und kein aktives Abrechnungskonto haben, müssen Sie ein Abrechnungskonto mit Ihren eigenen Zahlungsinformationen einrichten. Dokumentation zur Abrechnung für Google Cloud

Google Cloud-Projekt erstellen

Damit alle Ihre Arbeiten für dieses Codelab organisiert und von anderen Projekten getrennt sind, erstellen Sie zuerst ein neues Google Cloud-Projekt.

Klicken Sie auf , um die Seite zum Erstellen von Projekten zu öffnen.

Geben Sie auf der Seite zum Erstellen von Projekten die erforderlichen Informationen ein:

Projektname: Sie können einen beliebigen Namen eingeben, z. B. „genai-workshop“.
Standort: Lassen Sie die Einstellung auf Keine Organisation.
Rechnungskonto: Wenn diese Option angezeigt wird, wählen Sie „Google Cloud Platform Trial Billing Account“ (Rechnungskonto für den kostenlosen Testzeitraum von Google Cloud Platform) oder Ihr eigenes Rechnungskonto aus. Wenn diese Option nicht angezeigt wird, können Sie mit dem nächsten Schritt fortfahren.

Notieren Sie sich die generierte Projekt-ID, da Sie sie später benötigen.

Wenn alles in Ordnung ist, klicken Sie auf die Schaltfläche Erstellen.

Cloud Shell konfigurieren

Cloud Shell ist eine vorkonfigurierte Umgebung mit allen Tools, die Sie für dieses Codelab benötigen. Nachdem Ihr Projekt erfolgreich erstellt wurde, führen Sie die folgenden Schritte aus, um Cloud Shell einzurichten.

Cloud Shell aufrufen

Klicken Sie zum Starten von Cloud Shell auf .

Wenn ein Pop-up zur Autorisierung angezeigt wird, klicken Sie auf Autorisieren.

Projekt-ID festlegen

Ersetzen Sie replace-with-your-project-id durch Ihre tatsächliche Projekt-ID aus dem Schritt zur Projekterstellung oben. Führen Sie den folgenden Befehl im Cloud Shell-Terminal aus, um die richtige Projekt-ID festzulegen.

gcloud config set project replace-with-your-project-id

Im Cloud Shell-Terminal sollte nun das richtige Projekt ausgewählt sein. Die ausgewählte Projekt-ID wird gelb hervorgehoben.

Erforderliche APIs aktivieren

Wenn Sie Google Cloud-Dienste wie Cloud Run verwenden möchten, müssen Sie zuerst die entsprechenden APIs für Ihr Projekt aktivieren. Führen Sie die folgenden Befehle in Cloud Shell aus, um die für dieses Codelab erforderlichen Dienste zu aktivieren:

gcloud services enable run.googleapis.com
gcloud services enable cloudbuild.googleapis.com
gcloud services enable secretmanager.googleapis.com
gcloud services enable artifactregistry.googleapis.com

3. Das richtige Modell auswählen

Viele offene Modelle finden Sie auf Websites wie Hugging Face Hub und Kaggle. Wenn Sie eines dieser Modelle in einem Dienst wie Google Cloud Run verwenden möchten, müssen Sie eines auswählen, das zu den verfügbaren Ressourcen passt (z.B. NVIDIA L4-GPU).

Denken Sie nicht nur an die Größe, sondern auch daran, was das Modell tatsächlich leisten kann. Modelle sind nicht alle gleich. Jedes hat seine eigenen Vor- und Nachteile. Einige Modelle können beispielsweise verschiedene Arten von Eingaben verarbeiten (z. B. Bilder und Text – das wird als multimodale Funktion bezeichnet), während andere sich mehr Informationen gleichzeitig merken und verarbeiten können (d. h. sie haben größere Kontextfenster). Größere Modelle haben oft erweiterte Funktionen wie Funktionsaufrufe und Denken.

Außerdem ist es wichtig, zu prüfen, ob das gewünschte Modell vom Serving-Tool (in diesem Fall vLLM) unterstützt wird. Hier finden Sie alle Modelle, die von vLLM unterstützt werden.

Sehen wir uns nun Gemma 3 an, die neueste Familie von öffentlich verfügbaren Large Language Models (LLMs) von Google. Gemma 3 ist in vier verschiedenen Größen erhältlich, die auf ihrer Komplexität basieren, gemessen in Parametern: 1 Milliarde, 4 Milliarden, 12 Milliarden und 27 Milliarden.

Für jede dieser Größen gibt es zwei Haupttypen:

Eine Basisversion (vortrainiert): Dies ist das Foundation Model, das mit einer riesigen Datenmenge trainiert wurde.
Eine auf Anweisungen abgestimmte Version: Diese Version wurde weiter verfeinert, um bestimmte Anweisungen oder Befehle besser zu verstehen und zu befolgen.

Die größeren Modelle (4 Milliarden, 12 Milliarden und 27 Milliarden Parameter) sind multimodal, d. h. sie können sowohl Bilder als auch Text verstehen und verarbeiten. Die kleinste Variante mit 1 Milliarde Parametern konzentriert sich jedoch ausschließlich auf Text.

In diesem Codelab verwenden wir 1 Milliarde Varianten von Gemma 3: gemma-3-1b-it. Wenn Sie ein kleineres Modell verwenden, lernen Sie auch, wie Sie mit begrenzten Ressourcen arbeiten. Das ist wichtig, um die Kosten niedrig zu halten und dafür zu sorgen, dass Ihre App reibungslos in der Cloud ausgeführt wird.

4. Umgebungsvariablen und Secrets

Umgebungsdatei erstellen

Bevor wir fortfahren, ist es ratsam, alle Konfigurationen, die Sie in diesem Codelab verwenden, an einem Ort zu speichern. So gehts:

Erstellen Sie einen neuen Ordner für dieses Projekt.
Wechseln Sie zum neu erstellten Ordner.
Erstellen Sie eine leere .env-Datei in diesem Ordner. Diese Datei enthält später Ihre Umgebungsvariablen.

Hier ist der Befehl, mit dem Sie diese Schritte ausführen können:

mkdir vllm-gemma3 && cd vllm-gemma3 && cloudshell edit .env

Kopieren Sie als Nächstes die unten aufgeführten Variablen und fügen Sie sie in die gerade erstellte .env-Datei ein.

PROJECT_ID=your_project_id
REGION=your_region

MODEL_PROVIDER=google
MODEL_VARIANT=gemma-3-1b-it
MODEL_NAME=${MODEL_PROVIDER}/${MODEL_VARIANT}

AR_REPO_NAME=vllm-gemma3-repo
SERVICE_NAME=${MODEL_VARIANT}-service
IMAGE_NAME=${REGION}-docker.pkg.dev/${PROJECT_ID}/${AR_REPO_NAME}/${SERVICE_NAME}

SERVICE_ACC_NAME=${SERVICE_NAME}-sa
SERVICE_ACC_EMAIL=${SERVICE_ACC_NAME}@${PROJECT_ID}.iam.gserviceaccount.com

Ersetzen Sie die Platzhalterwerte (your_project_id und your_region) durch die spezifischen Informationen für Ihr Projekt. Beispiel: PROJECT_ID=unique-ai-project und REGION=us-central1. Eine Liste der Regionen, die GPUs in Cloud Run unterstützen, finden Sie hier.

Nachdem Sie die .env-Datei bearbeitet und gespeichert haben, geben Sie diesen Befehl ein, um die Umgebungsvariablen in die Terminalsitzung zu laden:

source .env

Sie können testen, ob die Variablen erfolgreich geladen wurden, indem Sie eine der Variablen ausgeben. Beispiel:

echo $SERVICE_NAME

Wenn Sie denselben Wert erhalten, den Sie in der .env-Datei zugewiesen haben, wurden die Variablen erfolgreich geladen.

Secret in Secret Manager speichern

Für alle vertraulichen Daten, einschließlich Zugangscodes, Anmeldedaten und Passwörter, wird die Verwendung eines Secret-Managers empfohlen.

Bevor Sie Gemma 3-Modelle verwenden können, müssen Sie zuerst die Nutzungsbedingungen bestätigen, da der Zugriff darauf eingeschränkt ist. Sie können die Nutzungsbedingungen über die Gamma 3-Modellkarte im Hugging Face-Hub bestätigen.

Sobald Sie das Hugging Face-Zugriffstoken haben, rufen Sie die Secret Manager-Seite auf und erstellen Sie ein Secret. Folgen Sie dazu dieser Anleitung.

Google Cloud Console aufrufen
Wählen Sie das Projekt im Drop-down-Menü oben links aus.
Suchen Sie in der Suchleiste nach Secret Manager und klicken Sie auf diese Option, wenn sie angezeigt wird.

So rufen Sie die Secret Manager-Seite auf:

Klicken Sie auf die Schaltfläche + Secret erstellen.
Geben Sie die folgenden Informationen ein:
Name: HF_TOKEN
Secret-Wert: <your_hf_access_token>
Klicken Sie auf die Schaltfläche Secret erstellen, wenn Sie fertig sind.

Sie sollten jetzt das Hugging Face-Zugriffstoken als Secret in Google Cloud Secret Manager haben.

Sie können Ihren Zugriff auf das Secret testen, indem Sie den folgenden Befehl im Terminal ausführen. Dadurch wird es aus Secret Manager abgerufen:

gcloud secrets versions access latest --secret=HF_TOKEN

Ihr Zugriffstoken sollte abgerufen und im Terminalfenster angezeigt werden.

Cloud Build-Dienstkonto Zugriff auf Secret gewähren

Da das Secret jetzt sicher in Secret Manager gespeichert ist,

Führen Sie dazu die folgenden Befehle im Terminal aus:

# Get the project number
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')

# Grant Cloud Build access to the Hugging Face Token secret
gcloud secrets add-iam-policy-binding HF_TOKEN \
  --member="serviceAccount:${PROJECT_NUMBER}@cloudbuild.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

5. Dienstkonto erstellen

Um die Sicherheit zu erhöhen und den Zugriff in einer Produktionsumgebung effektiv zu verwalten, sollten Dienste unter dedizierten Dienstkonten ausgeführt werden, die streng auf die für ihre spezifischen Aufgaben erforderlichen Berechtigungen beschränkt sind.

Führen Sie diesen Befehl aus, um ein Dienstkonto zu erstellen.

gcloud iam service-accounts create $SERVICE_ACC_NAME --display-name='Cloud Run vLLM Model Serving SA'

Mit dem folgenden Befehl wird die erforderliche Berechtigung angehängt.

gcloud secrets add-iam-policy-binding HF_TOKEN \
  --member="serviceAccount:${SERVICE_ACC_EMAIL}" \
  --role="roles/secretmanager.secretAccessor"

6. Image in Artifact Registry erstellen

In diesem Schritt erstellen Sie ein Docker-Image, das die Modellgewichte und ein vorinstalliertes vLLM enthält.

1. Docker-Repository in Artifact Registry erstellen

Erstellen wir ein Docker-Repository in Artifact Registry, in das Sie Ihre erstellten Images übertragen können. Führen Sie im Terminal den folgenden Befehl aus:

gcloud artifacts repositories create ${AR_REPO_NAME} \
  --repository-format docker \
  --location ${REGION}

2. Modell speichern

Gemäß der Dokumentation zu GPU-Best Practices können Sie ML-Modelle entweder in Container-Images speichern oder das Laden aus Cloud Storage optimieren.

Jeder Ansatz hat natürlich seine Vor- und Nachteile. Weitere Informationen finden Sie in der Dokumentation. Der Einfachheit halber speichern wir das Modell im Container-Image. Das machen Sie in der nächsten Sitzung.

3. Dockerfile erstellen

Erstellen Sie eine Datei mit dem Namen Dockerfile und kopieren Sie den folgenden Inhalt hinein:

FROM vllm/vllm-openai:v0.16.0

ARG MODEL_NAME
ARG HF_TOKEN

ENV HF_HOME=/model-cache
ENV MODEL_NAME=${MODEL_NAME}

# Use the HF_TOKEN argument to log in and download the model
RUN huggingface-cli login --token ${HF_TOKEN} && \
    huggingface-cli download ${MODEL_NAME}

# Prevent vLLM from trying to download the model again at runtime
ENV HF_HUB_OFFLINE=1

EXPOSE 8080

ENTRYPOINT python3 -m vllm.entrypoints.openai.api_server \
    --port ${PORT:-8080} \
    --model ${MODEL_NAME} \
    --gpu-memory-utilization 0.90 \
    ${MAX_MODEL_LEN:+--max-model-len "$MAX_MODEL_LEN"}

4. YAML-Datei für das Deployment erstellen

Erstellen Sie als Nächstes im selben Verzeichnis eine Datei mit dem Namen cloudbuild.yaml. Diese Datei definiert die Schritte, die Cloud Build ausführen soll. Kopieren Sie den folgenden Inhalt und fügen Sie ihn in die Datei „cloudbuild.yaml“ ein:

steps:
- name: 'gcr.io/cloud-builders/docker'
  entrypoint: 'bash'
  args:
  - '-c'
  - |
    docker build \
      --build-arg MODEL_NAME=${_MODEL_NAME} \
      --build-arg HF_TOKEN=$$HF_TOKEN_SECRET \
      -t ${_IMAGE_NAME} .
  secretEnv: ['HF_TOKEN_SECRET']

images:
- '${_IMAGE_NAME}'

availableSecrets:
  secretManager:
  - versionName: projects/${PROJECT_ID}/secrets/HF_TOKEN/versions/latest
    env: 'HF_TOKEN_SECRET'

5. Build an Cloud Build senden

Kopieren Sie den folgenden Code und führen Sie ihn im Terminal aus:

gcloud builds submit . \
    --config=cloudbuild.yaml \
    --region=${REGION} \
    --substitutions=_MODEL_NAME=${MODEL_NAME},_IMAGE_NAME=${IMAGE_NAME}

Mit diesem Befehl wird Ihr Code (Dockerfile und cloudbuild.yaml) hochgeladen, Ihre Shell-Variablen werden als Ersetzungen (_MODEL_NAME und _IMAGE_NAME) übergeben und der Build wird gestartet.

Cloud Build führt nun die in cloudbuild.yaml definierten Schritte aus. Sie können die Logs in Ihrem Terminal verfolgen oder auf den Link zu den Build-Details in der Cloud Console klicken. Nach Abschluss des Vorgangs ist das Container-Image in Ihrem Artifact Registry-Repository verfügbar und kann bereitgestellt werden.

6. In Cloud Run bereitstellen

Sie können den Dienst jetzt in Cloud Run bereitstellen. Führen Sie diesen Befehl im Terminal aus:

gcloud run deploy ${SERVICE_NAME} \
  --image ${IMAGE_NAME} \
  --region ${REGION} \
  --service-account ${SERVICE_ACC_EMAIL} \
  --gpu 1 \
  --gpu-type nvidia-l4 \
  --cpu 4 \
  --memory 16Gi \
  --max-instances 3 \
  --concurrency 80 \
  --no-allow-unauthenticated

7. Dienst testen

Führen Sie den folgenden Befehl im Terminal aus, um einen Proxy zu erstellen, damit Sie auf den Dienst zugreifen können, während er auf localhost ausgeführt wird:

gcloud run services proxy ${SERVICE_NAME} --region ${REGION}

Führen Sie in einem neuen Terminalfenster diesen curl-Befehl im Terminal aus, um die Verbindung zu testen.

curl -X POST http://localhost:8080/v1/completions \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-H "Content-Type: application/json" \
-d '{
  "model": "google/gemma-3-1b-it",
  "prompt": "Cloud Run is a ",
  "max_tokens": 128,
  "temperature": 0.90
}'

Wenn Sie eine ähnliche Ausgabe wie unten sehen:

{"id":"cmpl-e96d05d2893d42939c1780d44233defa","object":"text_completion","created":1746870778,"model":"google/gemma-3-1b-it","choices":[{"index":0,"text":"100% managed Kubernetes service. It's a great option for many use cases.\n\nHere's a breakdown of key features and considerations:\n\n* **Managed Kubernetes:**  This means Google handles the underlying infrastructure, including scaling, patching, and maintenance.  You don't need to worry about managing Kubernetes clusters.\n* **Serverless:**  You only pay for the compute time your application actually uses.  No charges when your code isn't running.\n* **Scalability:**  Cloud Run automatically scales your application based on demand. You can easily scale up or down to handle fluctuating traffic.\n*","logprobs":null,"finish_reason":"length","stop_reason":null,"prompt_logprobs":null}],"usage":{"prompt_tokens":6,"total_tokens":134,"completion_tokens":128,"prompt_tokens_details":null}}

8. Fazit

Glückwunsch! Sie haben dieses Codelab erfolgreich abgeschlossen. Sie haben Folgendes gelernt:

Wählen Sie eine geeignete Modellgröße für die Zielbereitstellung aus.
vLLM für die Bereitstellung einer OpenAI-kompatiblen API einrichten
vLLM-Server und Modellgewichte mit Docker sicher containerisieren
Container-Image per Push an Google Artifact Registry übertragen
GPU-beschleunigten Dienst in Cloud Run bereitstellen
Ein authentifiziertes, bereitgestelltes Modell testen

Sie können auch andere interessante Modelle wie Llama, Mistral oder Qwen bereitstellen, um Ihren Lernprozess fortzusetzen.

9. Bereinigen

Um zukünftige Gebühren zu vermeiden, ist es wichtig, die von Ihnen erstellten Ressourcen zu löschen. Führen Sie die folgenden Befehle aus, um Ihr Projekt zu bereinigen.

1. Löschen Sie den Cloud Run-Dienst:

gcloud run services delete ${SERVICE_NAME} --region=${REGION} --quiet

2. Löschen Sie das Artifact Registry-Repository:

gcloud artifacts repositories delete ${AR_REPO_NAME} --location=${REGION} --quiet

3. Löschen Sie das Dienstkonto:

gcloud iam service-accounts delete ${SERVICE_ACC_EMAIL} --quiet

4. Löschen Sie das Secret aus Secret Manager:

gcloud secrets delete HF_TOKEN --quiet