Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

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

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

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

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

事前準備

登入 Google Cloud 帳戶。如果您未曾使用過 Google Cloud，歡迎建立帳戶，親自體驗實際使用我們產品的成效。新客戶還能獲得價值 $300 美元的免費抵免額，用於執行、測試及部署工作負載。

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.

在 Google Cloud 專案中設定 Cloud Run 開發環境。
安裝並初始化 gcloud CLI。
確認您的帳戶已獲派下列 IAM 角色：
- Cloud Run 管理員 (roles/run.admin)
- 專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
- 服務使用情形消費者 (roles/serviceusage.serviceUsageConsumer)

瞭解如何授予角色

控制台

前往 Google Cloud 控制台的「IAM」頁面。
前往「IAM」頁面
選取專案。
按一下「Grant access」(授予存取權)。
在「New principals」(新增主體) 欄位中，輸入您的使用者 ID。這通常是用來部署 Cloud Run 服務的電子郵件地址。
在「Select a role」(選取角色) 清單中，選取角色。
如要授予其他角色，請按一下「Add another role」(新增其他角色)，然後新增其他角色。
按一下「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：要新增至部署者帳戶的角色。

根據預設，新專案在初始部署時會自動獲得 3,000 milliGPU 配額。如需更多配額，請前往「Quotas and system limits」(配額與系統限制) 頁面，在 Cloud Run Admin API 下方要求 Total Nvidia RTX Pro 6000 GPU allocation, in milli GPU, without zonal redundancy, per project per region 配額。
查看 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 替換為 Cloud Run 支援 nvidia-rtx-pro-6000 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 模型大小，但未啟用直連虛擬私有雲輸出，建議將啟動探測逾時時間設為至少 240 秒。

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

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

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

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

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

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

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

執行下列指令，在另一個終端機分頁中傳送要求，讓 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 服務後，您可以使用 Cloud Run 端點搭配 Gemma 4，透過 Agent Development Kit 建立 AI 代理。

使用 Agent Development Kit 前，請確認傳入的要求會傳遞適當的身分權杖。如要進一步瞭解如何使用 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 資源：

Cloud Run 服務

後續步驟

如要使用 Run:ai Model Streamer 處理大型 AI 模型並縮短啟動時間，請參閱程式碼實驗室「在搭載 RTX 6000 Pro GPU 的 Cloud Run 搭配 vLLM 執行 Gemma 4 模型推論」。
設定 GPU
最佳做法：在 Cloud Run 中使用 GPU 進行 AI 推論
使用各種 AI 執行階段框架執行 Gemma 4 模型

在 Cloud Run 使用 Gemma 4 模型執行代理 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

瞭解如何授予角色

控制台

gcloud

使用 vLLM 容器部署 Gemma 4 模型

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

設定並行數量，達到最佳效能

盡可能提高使用率

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

清除所用資源

後續步驟

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