KI-Agents mit Gemma 4-Modellen in Cloud Run ausführen

In dieser Anleitung wird beschrieben, wie Sie offene Gemma 4-Modelle in Cloud Run mit einem vorgefertigten Container mit der vLLM Inferenzbibliothek bereitstellen. Außerdem erhalten Sie eine Anleitung zur Verwendung des bereitgestellten Cloud Run-Dienstes mit KI-Agenten, die mit dem Agent Development Kit erstellt wurden.

Gemma 4 ist die effizienteste Familie von Open-Weight-Modellen von Google und bietet starke logische Schlussfolgerungen und agentische Funktionen.

Mit langem Kontext, Multimodalität, logischen Schlussfolgerungen und Tool-Aufrufen kann Gemma 4 komplexe Logik, mehrstufige Planung, Programmierung und agentische Workflows verarbeiten.

Hinweis

Melden Sie sich in Ihrem Google Cloud Konto an. Wenn Sie noch kein Google Cloud-Konto haben, erstellen Sie ein Konto, um zu sehen, wie sich unsere Produkte in realen Szenarien schlagen. Neukunden erhalten außerdem ein Guthaben von 300 $, um Arbeitslasten auszuführen, zu testen und bereitzustellen.

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

Verify that billing is enabled for your Google Cloud project.

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

Verify that billing is enabled for your Google Cloud project.

Richten Sie Ihre Cloud Run-Entwicklungsumgebung ein in Ihrem Google Cloud Projekt.
Installieren und initialisieren Sie die gcloud CLI.
Prüfen Sie, ob Ihrem Konto die folgenden IAM-Rollen zugewiesen sind:
- Cloud Run-Administrator (roles/run.admin)
- Project IAM Admin (roles/resourcemanager.projectIamAdmin)
- Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

Rollen zuweisen

Console

Rufen Sie in der Google Cloud Console die Seite IAM auf.
IAM aufrufen
Wählen Sie das Projekt aus.
Klicken Sie auf „“ Zugriffsrechte erteilen.
Geben Sie im Feld Neue Hauptkonten Ihre Nutzer-ID ein. Dies ist in der Regel die E‑Mail-Adresse, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.
Wählen Sie in der Liste Rolle auswählen eine Rolle aus.
Klicken Sie auf Weitere Rolle hinzufügen, wenn Sie weitere Rollen zuweisen möchten.
Klicken Sie auf Speichern.

gcloud

So weisen Sie Ihrem Konto die erforderlichen IAM-Rollen für Ihr Projekt zu:

        gcloud projects add-iam-policy-binding PROJECT_ID \
            --member=PRINCIPAL \
            --role=ROLE

Ersetzen Sie:

PROJECT_NUMBER durch Ihre Google Cloud Projekt nummer.
PROJECT_ID durch Ihre Google Cloud Projekt-ID.
PRINCIPAL durch das Konto, für das Sie die Bindung hinzufügen. Dies ist in der Regel die E‑Mail-Adresse, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.
ROLE durch die Rolle, die Sie dem Bereitsteller Konto hinzufügen.

Fordern Sie bei Bedarf unter „Cloud Run Admin API“ auf der Seite Kontingente und Systemlimits das Kontingent Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region an.
Lesen Sie die Cloud Run-Preisseite. Mit dem Preisrechner können Sie eine Kostenschätzung für Ihre voraussichtliche Nutzung vornehmen.

Gemma 4-Modell mit einem vLLM-Container bereitstellen

Gemma 4 bietet erweiterte agentische Funktionen, darunter logische Schlussfolgerungen, Funktionsaufrufe, Codegenerierung und strukturierte Ausgabe.

Mit dem Agent Development Kit (ADK) können Sie voll funktionsfähige KI-Agenten mit Gemma 4 erstellen.

Verwenden Sie vLLM, um Gemma als OpenAI API-Endpunkt bereitzustellen. vLLM bietet eine schnelle und effiziente Bereitstellung für generative Modelle im großen Maßstab mit modernstem Durchsatz, effizienter Speicherverwaltung mit PagedAttention, kontinuierlicher Batchverarbeitung eingehender Anfragen, Quantisierungsunterstützung und optimierten CUDA-Kernels.

Verwenden Sie den folgenden gcloud CLI-Befehl mit den empfohlenen Einstellungen, um Gemma-Modelle in Cloud Run bereitzustellen:

CONTAINER_ARGS=(
    "serve"
    "MODEL_NAME"
    "--enable-chunked-prefill"
    "--enable-prefix-caching"
    "--generation-config=auto"
    "--enable-auto-tool-choice"
    "--tool-call-parser=gemma4"
    "--reasoning-parser=gemma4"
    "--dtype=bfloat16"
    "--max-num-seqs=64"
    "--gpu-memory-utilization=0.95"
    "--tensor-parallel-size=1"
    "--port=8080"
    "--host=0.0.0.0"
)
gcloud beta run deploy SERVICE_NAME \
    --image "us-docker.pkg.dev/vertex-ai/vertex-vision-model-garden-dockers/pytorch-vllm-serve:gemma4" \
    --project PROJECT \
    --region REGION \
    --execution-environment gen2 \
    --no-allow-unauthenticated \
    --cpu 20 \
    --memory 80Gi \
    --gpu 1 \
    --gpu-type nvidia-rtx-pro-6000 \
    --no-gpu-zonal-redundancy \
    --no-cpu-throttling \
    --max-instances 3 \
    --concurrency 64 \
    --timeout 600 \
    --startup-probe tcpSocket.port=8080,initialDelaySeconds=240,failureThreshold=1,timeoutSeconds=240,periodSeconds=240 \
    --command "vllm" \
    --args=$(IFS=','; echo "${CONTAINER_ARGS[*]}")

Ersetzen Sie:

SERVICE_NAME durch einen eindeutigen Namen für den Cloud Run-Dienst.
PROJECT durch Ihre Google Cloud Projekt-ID.
REGION durch eine Google Cloud Region, in der nvidia-rtx-pro-6000-GPUs für Cloud Run unterstützt werden, z. B. us-central1. Eine vollständige Liste der unterstützten Regionen für GPU-fähige Bereitstellungen finden Sie unter GPU-Konfiguration.
MODEL_NAME durch den vollständigen Namen einer Gemma 4-Variante.
- Gemma 4 2B: google/gemma-4-E2B-it
- Gemma 4 4B: google/gemma-4-E4B-it

Die anderen Einstellungen sind wie folgt:

Option	Beschreibung
`--concurrency`	Die maximale Anzahl von Anfragen, die von einer bestimmten Instanz gleichzeitig verarbeitet werden können, z. B. `8`. Empfehlungen zur optimalen Anfragelatenz finden Sie unter Nebenläufigkeit für optimale Leistung festlegen.
`--cpu`	Die Menge der zugewiesenen CPU für Ihren Dienst, z. B. `20`.
`--set-env-vars`	Die für Ihren Dienst festgelegten Umgebungsvariablen. Beispiel: `HF_TOKEN="..."`
`--gpu`	Der GPU-Wert für Ihren Dienst, z. B. `1`.
`--gpu-type`	Der GPU-Typ, der für Ihren Dienst verwendet werden soll, z. B. `nvidia-rtx-pro-6000`.
`--max-instances`	Die maximale Anzahl von Containerinstanzen für Ihren Dienst, z. B. `1`.
`--memory`	Die Menge des zugewiesenen Arbeitsspeichers für Ihren Dienst, z. B. `80Gi`.
`--no-invoker-iam-check`	IAM-Prüfungen für Aufrufer deaktivieren. Empfehlungen zum besseren Schutz Ihrer Anwendung finden Sie in der Anleitung zum Sichern von Cloud Run-Diensten.
`--no-cpu-throttling`	Mit dieser Einstellung wird die CPU-Drosselung deaktiviert, wenn der Container keine Anfragen aktiv verarbeitet.
`--timeout`	Die Zeit, innerhalb derer eine Antwort zurückgegeben werden muss, z. B. `600` Sekunden.
`--startup-probe`	Durch Kommas getrennte Einstellungen für die Startbereitschaftsprüfung im Format KEY=VALUE. Weitere Informationen finden Sie unter Cloud Run-Startbereitschaftsprüfung. Bei Modellgrößen von Gemma 4 wird empfohlen, das Zeitlimit für die Startbereitschaftsprüfung auf mindestens 240 Sekunden festzulegen, wenn Sie Direct VPC Egress nicht verwenden.

Wenn Sie die Standardeinstellungen ändern oder Ihrem Cloud Run-Dienst weitere benutzerdefinierte Einstellungen hinzufügen möchten, lesen Sie Dienste konfigurieren.

Nach Abschluss der Bereitstellung des Dienstes wird eine Erfolgsmeldung zusammen mit der Cloud Run-Endpunkt-URL angezeigt, die mit run.app endet.

Bereitgestellten Gemma-Dienst mit curl testen

Nachdem Sie den Gemma-Dienst bereitgestellt haben, können Sie Anfragen an ihn senden. Wenn Sie jedoch eine Anfrage direkt senden, antwortet Cloud Run mit HTTP 401 Unauthorized. Das ist beabsichtigt, da eine LLM-Inferenz-API für andere Dienste gedacht ist, z. B. für eine Frontend-Anwendung. Weitere Informationen zur Dienst-zu-Dienst Authentifizierung in Cloud Run finden Sie unter Dienst-zu-Dienst-Authentifizierung.

Wenn Sie Anfragen an den Gemma-Dienst senden möchten, fügen Sie den Anfragen einen Header mit einem gültigen OIDC-Token hinzu, z. B. mit dem Cloud Run Entwicklerproxy:

Starten Sie den Proxy und wählen Sie Y aus, wenn Sie aufgefordert werden, die Komponente cloud-run-proxy zu installieren:
```
gcloud run services proxy SERVICE_NAME \
  --project PROJECT \
  --region REGION \
  --port=9090
```

Führen Sie den folgenden Befehl aus, um eine Anfrage in einem separaten Terminaltab zu senden, und lassen Sie den Proxy laufen. Der Proxy wird unter localhost:9090 ausgeführt. Geben Sie das zuvor verwendete Gemma Modell an:

curl http://localhost:9090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_NAME",
    "messages": [{"role": "user", "content": "Why is the sky blue?"}],
    "chat_template_kwargs": {
         "enable_thinking": true
     },
     "skip_special_tokens": false
  }'

Dieser Befehl sollte eine ähnliche Ausgabe wie diese liefern:

{
 "id": "chatcmpl-9cf1ab1450487047",
 "object": "chat.completion",
 "created": 1774904187,
 "model": "google/gemma-4-E2B-it",
 "choices": [
   {
     "index": 0,
     "message": {
       "role": "assistant",
       "content": "The short answer is a phenomenon called **Rayleigh scattering**...",
       "function_call": null,
       "tool_calls": [],
       "reasoning": "*   Question: \"Why is the sky blue?\"\n..."
     },
     "finish_reason": "stop",
     "stop_reason": 106
   }
 ],
 "usage": {
   "prompt_tokens": 21,
   "total_tokens": 877,
   "completion_tokens": 856
 }
}

Nebenläufigkeit für optimale Leistung festlegen

In diesem Abschnitt finden Sie weitere Informationen zu den empfohlenen Einstellungen für die Nebenläufigkeit. Für eine optimale Anfragelatenz muss die Einstellung --concurrency dem Befehlszeilenargument --max-num-seqs von vLLM entsprechen.

Mit --max-num-seqs wird festgelegt, wie viele Sequenzen (Anfragen) für jede vLLM-Instanz verfügbar sind, um Inferenzen gleichzeitig zu verarbeiten.
Mit --concurrency wird festgelegt, wie viele Anfragen Cloud Run gleichzeitig an eine vLLM-Instanz sendet.

Wenn --concurrency --max-num-seqs übersteigt, kann Cloud Run mehr Anfragen an eine vLLM-Instanz senden, als für die verfügbaren Anfrageslots vorgesehen sind. Dies führt zu einer Anfragewarteschlange in vLLM, was die Anfragelatenz für die anstehenden Anfragen erhöht. Außerdem führt es zu einem weniger reaktionsfähigen Autoscaling, da die anstehenden Anfragen nicht dazu führen, dass Cloud Run skaliert und neue Instanzen startet.

Um Anfragen in der vLLM-Instanz vollständig zu vermeiden, sollten Sie --concurrency auf --max-num-seqs festlegen.

Beachten Sie, dass parallele Anfragen bei einer Erhöhung von --max-num-seqs auch länger dauern und mehr GPU-Arbeitsspeicher für den KV-Cache erforderlich ist.

Auslastung optimieren

Für eine optimale GPU-Auslastung erhöhen Sie --concurrency, wobei der Wert unter dem Doppelten von --max-num-seqs liegen muss. Dies führt zwar zu einer Anfragewarteschlange in vLLM, kann aber die Auslastung verbessern: vLLM-Instanzen können Anfragen aus ihrer Warteschlange sofort verarbeiten und die Warteschlangen helfen, Trafficspitzen abzufangen.

KI-Agenten mit dem Agent Development Kit und Gemma 4 erstellen

Nachdem Sie Ihren Cloud Run-Dienst bereitgestellt haben, können Sie den Cloud Run-Endpunkt mit Gemma 4 verwenden, um mit dem Agent Development KitKI-Agenten zu erstellen.

Bevor Sie das Agent Development Kit verwenden, prüfen Sie, ob eingehende Anfragen das entsprechende Identitätstoken übergeben. Weitere Informationen zur Verwendung der IAM Authentifizierung und von Cloud Run finden Sie unter Dienst-zu-Dienst-Authentifizierung.

Das folgende Beispiel zeigt, wie Sie das Agent Development Kit in Python mit der IAM-Authentifizierung verwenden:

import subprocess
from google.adk.models.lite_llm import LiteLlm
from google.adk.agents import Agent

# Get the identity token using gcloud
id_token = subprocess.run(
    ["gcloud", "auth", "print-identity-token"],
    capture_output=True, text=True
).stdout.strip()

gemma_model = LiteLlm(
    model=f'openai/MODEL_NAME',
    base_url='https://YOUR_CLOUD_RUN_SERVICE_URL/v1',
    extra_body={
        "chat_template_kwargs": {
            "enable_thinking": True
        },
        "skip_special_tokens": False
    },
    extra_headers={
        "Authorization": f"Bearer {id_token}",
    },
)

root_agent = Agent(
    model=gemma_model,
    name='assistant',
    instruction="You are a helpful assistant",
)

Bereinigen

Löschen Sie die folgenden Google Cloud erstelltenRessourcen:

Cloud Run-Dienst

Nächste Schritte

Für größere Modelle und eine schnellere Startzeit mit Run:ai Model Streamer verwenden Sie das Codelab Run inference of Gemma 4 model on Cloud Run with RTX 6000 Pro GPU with vLLM.
GPU konfigurieren
Best Practices: KI-Inferenz in Cloud Run mit GPUs
Gemma 4-Modelle mit verschiedenen KI-Laufzeit-Frameworks ausführen

KI-Agents mit Gemma 4-Modellen in Cloud Run ausführen Mit Sammlungen den Überblick behalten Sie können Inhalte basierend auf Ihren Einstellungen speichern und kategorisieren.

Hinweis

Rollen zuweisen

Console

gcloud

Gemma 4-Modell mit einem vLLM-Container bereitstellen

Bereitgestellten Gemma-Dienst mit curl testen

Nebenläufigkeit für optimale Leistung festlegen

Auslastung optimieren

KI-Agenten mit dem Agent Development Kit und Gemma 4 erstellen

Bereinigen

Nächste Schritte

KI-Agents mit Gemma 4-Modellen in Cloud Run ausführen