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 bereitstellen. Dazu verwenden Sie einen vorgefertigten Container mit der vLLM Inferenzbibliothek. 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 Modellen mit offenem Gewicht von Google und bietet starke Schlussfolgerungs- und agentische Funktionen.

Mit langem Kontext, Multimodalität, Schlussfolgerungen und Tool-Aufrufen kann Gemma 4 komplexe Logik, mehrstufige Planung, Programmierung und Agenten-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 testen, 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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

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.

Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

Go to project selector

Verify that billing is enabled for your Google Cloud project.

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

Rollen zuweisen

Console

1. Rufen Sie in der Google Cloud Console die Seite IAM auf.

   IAM aufrufen
2. Wählen Sie das Projekt aus.
3. Klicken Sie auf „“ Zugriffsrechte erteilen.

4. Geben Sie im Feld Neue Hauptkonten Ihre Nutzer-ID ein. In der Regel ist das die E‑Mail-Adresse, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.

5. Wählen Sie in der Liste Rolle auswählen eine Rolle aus.
6. Klicken Sie auf Weitere Rolle hinzufügen, wenn Sie weitere Rollen zuweisen möchten.
7. 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. In der Regel ist das die E‑Mail-Adresse, die zum Bereitstellen des Cloud Run-Dienstes verwendet wird.
• ROLE durch die Rolle, die Sie dem Konto des Bereitstellers hinzufügen.
4. Standardmäßig erhalten neue Projekte bei der ersten Bereitstellung automatisch ein Kontingent von 3.000 milliGPU. Wenn Sie zusätzliches Kontingent benötigen, beantragen Sie 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.
5. Lesen Sie die Seite Cloud Run-Preise. 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 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. Es zeichnet sich durch einen hochmodernen Bereitstellungsdurchsatz, eine effiziente Speicherverwaltung mit PagedAttention, kontinuierliches Batching eingehender Anfragen, Quantisierungsunterstützung und optimierte CUDA-Kernel aus.

Hinweis: Für Gemma 4 26B und 31B ist eine erweiterte Cloud Run- und vLLM-Konfiguration mit Direct VPC Egress und Run:ai Model Streamer erforderlich.

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 an zugewiesener 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 an zugewiesenem Arbeitsspeicher 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 Cloud Run-Dienste sichern.
--no-cpu-throttling	Mit dieser Einstellung wird die CPU-Drosselung deaktiviert, wenn der Container keine Anfragen aktiv verarbeitet.
--timeout	Die Zeit, in der eine Antwort zurückgegeben werden muss, z. B. 600 Sekunden.
--startup-probe	Durch Kommas getrennte Einstellungen für die Startbereitschaftsprüfung im Format SCHLÜSSEL=WERT. 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:

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

2. Führen Sie den folgenden Befehl aus, um in einem separaten Terminaltab eine Anfrage 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
    }
   }
   

   Erfolg: Sie haben einen GPU-fähigen Cloud Run-Dienst mit Gemma 4 bereitgestellt und eine Inferenzanfrage an ihn gesendet.

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 mit dem Befehlszeilenargument --max-num-seqs von vLLM übereinstimmen.

• 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