在 Cloud Run 使用 Gemma 4 模型執行代理

本指南說明如何使用預先建構的容器和 vLLM 推論程式庫，在 Cloud Run 上部署 Gemma 4 開放模型，並提供相關指引，說明如何搭配使用已部署的 Cloud Run 服務和使用 Agent Development Kit 建構的 AI 代理。

Gemma 4 是 Google 最高效的開放權重模型系列，可提供強大的推論和代理能力。

Gemma 4 具備長脈絡、多模態、推論和工具呼叫功能，可處理複雜邏輯、多步驟規劃、程式設計和代理功能工作流程。

事前準備

  1. 登入 Google Cloud 帳戶。如果您是 Google Cloud新手，歡迎 建立帳戶，親自評估產品在實際工作環境中的成效。新客戶還能獲得價值 $300 美元的免費抵免額，可用於執行、測試及部署工作負載。

  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. 在 Google Cloud 專案中設定 Cloud Run 開發環境。
  7. 安裝並初始化 gcloud CLI。
  8. 請確認您已將下列 IAM 角色授予帳戶：

    9. 瞭解如何授予角色

    控制台

    1. 前往 Google Cloud 控制台的「IAM」頁面。

      前往「IAM」頁面
    2. 選取專案。
    3. 按一下「Grant access」(授予存取權)。

    4. 在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。這通常是部署 Cloud Run 服務時使用的電子郵件地址。

    5. 在「Select a role」(選取角色) 清單中，選取角色。
    6. 如要授予其他角色，請按一下「Add another role」(新增其他角色)，然後新增其他角色。
    7. 按一下「Save」(儲存)。

    gcloud

    如要在專案中授予帳戶必要的 IAM 角色，請按照下列步驟操作：

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

    更改項目：

    • 將 PROJECT_NUMBER 改成您的 Google Cloud 專案編號。
    • 將 PROJECT_ID 替換為 Google Cloud 專案 ID。
    • PRINCIPAL，您要為該帳戶新增繫結。這通常是用於部署 Cloud Run 服務的電子郵件地址。
    • ROLE，並將角色新增至部署者帳戶。
  9. 如有需要，請在「配額與系統限制」頁面，為 Cloud Run Admin API 申請 Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region 配額。
  10. 請參閱「Cloud Run 定價」頁面。您可以使用 Pricing Calculator 根據預測用量估算費用。

使用 vLLM 容器部署 Gemma 4 模型

Gemma 4 提供進階代理能力，包括推論、函式呼叫、程式碼生成和結構化輸出。

Agent Development Kit (ADK) 可協助您使用 Gemma 4 建構功能齊全的 AI 代理。

使用 vLLM 將 Gemma 做為 OpenAI API 端點提供服務。vLLM 可大規模快速且有效率地提供生成模型服務，具備最先進的服務處理量、透過 PagedAttention 進行有效率的記憶體管理、持續批次處理傳入的要求、量化支援，以及最佳化的 CUDA 核心。

如要在 Cloud Run 上部署 Gemma 模型，請使用下列 gcloud CLI 指令，並採用建議設定：

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[*]}")

更改項目：

  • SERVICE_NAME，並為 Cloud Run 服務指定專屬名稱。
  • 將 PROJECT 改成您的 Google Cloud 專案 ID。

  • REGION，請將 REGION 換成 nvidia-rtx-pro-6000 支援 Cloud Run GPU 的 Google Cloud 區域，例如 us-central1。如需支援 GPU 部署作業的完整區域清單，請參閱「GPU 設定」。

  • 將 MODEL_NAME 替換為 Gemma 4 變體版本的全名。

    • Gemma 4 2B：google/gemma-4-E2B-it
    • Gemma 4 4B：google/gemma-4-E4B-it

其他設定如下：

選項 說明
--concurrency

特定執行個體 (例如 8) 可同時處理的要求數量上限。如需最佳要求延遲的建議，請參閱「設定並行以獲得最佳效能」。
--cpu

服務的CPU 分配量，例如 20。
--set-env-vars

為服務設定的環境變數。例如：HF_TOKEN="..."
--gpu

服務的 GPU 值，例如 1。
--gpu-type

服務要使用的 GPU 類型，例如 nvidia-rtx-pro-6000。
--max-instances

服務的容器執行個體數量上限，例如 1。
--memory

服務的分配記憶體量，例如 80Gi。
--no-invoker-iam-check

停用叫用者 IAM 檢查。如需如何加強應用程式安全性的建議，請參閱保護 Cloud Run 服務安全教學課程。
--no-cpu-throttling

如果容器未主動處理要求，這項設定會停用 CPU 節流。
--timeout

必須傳回回應的時間，例如 600 秒。
--startup-probe

以半形逗號分隔的啟動探查設定，格式為 KEY=VALUE。詳情請參閱「Cloud Run 啟動探查」。使用 Gemma 4 的模型大小時，如果沒有使用 Direct VPC Egress，建議將啟動探查逾時時間設為至少 240 秒。

如要修改預設設定，或為 Cloud Run 服務新增更多自訂設定，請參閱「設定服務」。

部署服務完成後，畫面會顯示成功訊息，以及結尾為 run.app 的 Cloud Run 端點網址。

使用 curl 測試已部署的 Gemma 服務

Gemma 服務部署完成後，您就可以向該服務傳送要求。不過，如果您直接傳送要求，Cloud Run 會以 HTTP 401 Unauthorized 回應。這是刻意設計，因為 LLM 推論 API 適用於其他服務呼叫，例如前端應用程式。如要進一步瞭解 Cloud Run 的服務對服務驗證，請參閱「服務對服務驗證」。

如要向 Gemma 服務傳送要求，請在要求中加入含有有效 OIDC 權杖的標頭，例如使用 Cloud Run 開發人員 Proxy：

  1. 啟動 Proxy，並在系統提示安裝 cloud-run-proxy 元件時選擇 Y：

    gcloud run services proxy SERVICE_NAME \
  --project PROJECT \
  --region REGION \
  --port=9090

  2. 執行下列指令，在獨立的終端機分頁中傳送要求，並讓 Proxy 保持執行狀態。Proxy 會在 localhost:9090 上執行，指定先前使用的 Gemma 模型：

    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
  }'

    這個指令應會輸出如下的內容：

    {
 "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
 }
}

設定並行數，爭取最佳成效

本節提供建議並行設定的背景資訊。如要達到最佳要求延遲時間，請確保 --concurrency 設定等於 vLLM 的 --max-num-seqs 指令列引數。

  • --max-num-seqs 決定每個 vLLM 執行個體可同時處理的序列 (要求) 數量。
  • --concurrency 決定 Cloud Run 同時傳送至 vLLM 執行個體的要求數量。

如果 --concurrency 超過 --max-num-seqs，Cloud Run 傳送至 vLLM 執行個體的要求可能會超過可用的要求時段。這會導致 vLLM 內的要求排隊，增加排隊要求的延遲時間。此外，由於佇列中的要求不會觸發 Cloud Run 水平擴展及啟動新執行個體，自動調度資源的反應也會較慢。

如要完全避免 vLLM 執行個體上的要求排隊，請將 --concurrency 設為與 --max-num-seqs 相符。

請注意，增加 --max-num-seqs 也會延長平行要求所需的時間，並需要更多 GPU 記憶體來儲存 KV 快取。

盡可能提高使用率

為達到最佳 GPU 使用率，請增加 --concurrency，但不要超過 --max-num-seqs 值的兩倍。雖然這會導致 vLLM 中的要求排隊，但有助於提高使用率：vLLM 執行個體可以立即處理佇列中的要求，而佇列則有助於吸收流量尖峰。

使用 Gemma 4 和 Agent Development Kit 建構 AI 代理

部署 Cloud Run 服務後，您可以使用 Gemma 4 的 Cloud Run 端點，透過 Agent Development Kit 建立 AI 代理程式。

使用 Agent Development Kit 前，請確保傳入的要求會傳遞適當的 ID 權杖。如要進一步瞭解如何使用 IAM 驗證和 Cloud Run，請參閱「服務對服務驗證」。

以下範例說明如何在 Python 中使用 Agent Development Kit，並透過 IAM 驗證：

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",
)

清除所用資源

刪除下列 Google Cloud 建立的資源：

後續步驟