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 vordefinierten Container mit der Inferenzbibliothek vLLM bereitstellen. Außerdem wird erläutert, wie Sie den bereitgestellten Cloud Run-Dienst mit KI-Agenten verwenden, die mit dem Agent Development Kit erstellt wurden.

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

Dank des langen Kontexts, der Multimodalität, der Schlussfolgerungsfähigkeit und des Toolaufrufs kann Gemma 4 komplexe Logik, mehrstufige Planung, Programmierung und agentische Workflows bewältigen.

Hinweis

  1. Melden Sie sich in Ihrem Google Cloud -Konto an. Wenn Sie mit Google Cloudnoch nicht vertraut sind, erstellen Sie einfach 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.

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

  3. Verify that billing is enabled for your Google Cloud project.

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

  5. Verify that billing is enabled for your Google Cloud project.

  6. Richten Sie Ihre Cloud Run-Entwicklungsumgebung in Ihrem Google Cloud -Projekt ein.
  7. Installieren und initialisieren Sie die gcloud CLI.
  8. Prüfen Sie, ob Ihrem Konto die folgenden IAM-Rollen zugewiesen sind:

    9. Informationen zum Zuweisen der Rollen

    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. Dies ist in der Regel 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 in Ihrem Projekt die erforderlichen IAM-Rollen zu:

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

    Ersetzen Sie:

    • PROJECT_NUMBER durch Ihre Google Cloud Projektnummer.
    • 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 Deployer-Konto hinzufügen.
  9. Standardmäßig erhalten neue Projekte bei der ersten Bereitstellung automatisch ein Kontingent von 3.000 Milli-GPUs. Wenn Sie ein zusätzliches Kontingent benötigen, fordern Sie unter „Cloud Run Admin API“ auf der Seite Kontingente und Systemlimits ein Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region-Kontingent an.
  10. Sehen Sie sich die Seite Cloud Run-Preise an. 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 Schlussfolgern, 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 modernem Bereitstellungsdurchsatz, effizienter Speicherverwaltung mit PagedAttention, kontinuierlichem Batching 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:

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 zur besseren Absicherung Ihrer Anwendung finden Sie im Tutorial für sichere Cloud Run-Dienste.
--no-cpu-throttling

Mit dieser Einstellung wird die CPU-Drosselung deaktiviert, wenn der Container nicht aktiv Anfragen verarbeitet.
--timeout

Die Zeit, in der eine Antwort zurückgegeben werden muss, z. B. 600 Sekunden.
--startup-probe

Kommagetrennte Einstellungen für die Startprüfung im Format SCHLÜSSEL=WERT. Weitere Informationen finden Sie unter Cloud Run-Startprüfung. Wenn Sie bei Gemma 4-Modellgrößen keinen ausgehenden Direct VPC-Traffic verwenden, sollten Sie das Zeitlimit für die Startprüfung auf mindestens 240 Sekunden festlegen.

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

Nach Abschluss des bereitgestellten Dienstes wird eine Erfolgsmeldung zusammen mit der Cloud Run-Endpunkt-URL angezeigt, die auf 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 eine Anfrage in einem separaten Terminaltab zu senden, und lassen Sie den Proxy laufen. Der Proxy wird auf localhost:9090 ausgeführt. Geben Sie das Gemma-Modell an, das Sie zuvor verwendet haben:

    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 Ausgabe ähnlich der folgenden 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) pro 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 überschreitet, 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 horizontal 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 erfordern.

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 KI-Agenten mit dem Agent Development Kit zu erstellen.

Bevor Sie das Agent Development Kit verwenden, müssen Sie dafür sorgen, dass eingehende Anfragen das entsprechende Identitätstoken übergeben. Weitere Informationen zur Verwendung der IAM-Authentifizierung und Cloud Run finden Sie unter Dienst-zu-Dienst-Authentifizierung.

Im folgenden Beispiel wird gezeigt, wie Sie das Agent Development Kit in Python mit 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 erstellten Google Cloud -Ressourcen:

Nächste Schritte