本頁面由 Cloud Translation API 翻譯而成。

在 Cloud Run 上執行 Gemma 3

本指南說明如何使用預先建構的容器，在 Cloud Run 上部署 Gemma 3 開放模型，並提供相關指引，說明如何搭配 Google Gen AI SDK 使用已部署的 Cloud Run 服務。

事前準備

如果您使用 Google AI Studio 部署至 Cloud Run，請跳到「安全地與 Google Gen AI SDK 互動」一節。

如果您未使用 Google AI Studio，請先按照下列步驟操作，再使用 Cloud Run 建立新服務。

Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

Go to project selector

Make sure 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.

Go to project selector

Make sure that billing is enabled for your Google Cloud project.

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

瞭解如何授予角色

控制台

前往 Google Cloud 控制台的「IAM」IAM頁面。
前往 IAM
選取專案。
按一下「授予存取權」。
在「New principals」(新增主體) 欄位中輸入使用者 ID。這通常是部署 Cloud Run 服務時使用的 Google 帳戶電子郵件地址。
在「Select a role」(選取角色) 清單中，選取角色。
如要授予其他角色，請按一下「新增其他角色」，然後新增每個其他角色。
按一下 [Save]。

gcloud

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

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

取代：

將 PROJECT_NUMBER 改成您的 Google Cloud 專案編號。
將 PROJECT_ID 改成您的專案 ID。 Google Cloud
PRINCIPAL，並為該帳戶新增繫結。這通常是部署 Cloud Run 服務時使用的 Google 帳戶電子郵件地址。
ROLE，並將角色新增至部署者帳戶。

在「配額與系統限制」頁面，要求 Cloud Run Admin API 的 Total Nvidia L4 GPU allocation, per project per region 配額。
請參閱 Cloud Run 定價頁面。如要根據預測用量估算費用，請使用 Pricing Calculator。

使用預先建構的容器部署 Gemma 模型

Cloud Run 提供預先建構的容器，可在 Cloud Run 上提供 Gemma 開放原始碼模型。

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

gcloud run deploy SERVICE_NAME \
   --image us-docker.pkg.dev/cloudrun/container/gemma/GEMMA_PARAMETER \
   --concurrency 4 \
   --cpu 8 \
   --set-env-vars OLLAMA_NUM_PARALLEL=4 \
   --gpu 1 \
   --gpu-type nvidia-l4 \
   --max-instances 1 \
   --memory 32Gi \
   --no-allow-unauthenticated \
   --no-cpu-throttling \
   --timeout=600 \
   --region REGION

取代：

SERVICE_NAME，並為 Cloud Run 服務指定專屬名稱。
GEMMA_PARAMETER 使用的 Gemma 模型：
- Gemma 3 1B (gemma-3-1b-it)：gemma3-1b
- Gemma 3 4B (gemma-3-4b-it)：gemma3-4b
- Gemma 3 12B (gemma-3-12b-it)：gemma3-12b
- Gemma 3 27B (gemma-3-27b-it)：gemma3-27b
(選用) 將整個映像檔網址替換為您從 Gemma-on-Cloudrun GitHub 存放區建構的 Docker 映像檔。
REGION，例如 europe-west1，請將 REGION 換成要部署 Cloud Run 的 Google Cloud 地區。如要修改區域，請參閱「GPU 設定」，瞭解支援 GPU 部署作業的區域。

其他設定如下：

選項	說明
`--concurrency`	特定執行個體 (例如 `4`) 可同時處理的要求數量上限。如需最佳要求延遲的建議，請參閱「設定並行以獲得最佳效能」。
`--cpu`	服務的已分配 CPU 數量，例如 `8`。
`--set-env-vars`	為服務設定的環境變數。例如，`OLLAMA_NUM_PARALLEL=4`。如需最佳要求延遲的建議，請參閱「設定並行以獲得最佳效能」。
`--gpu`	服務的 GPU 值，例如 `1`。
`--gpu-type`	服務要使用的 GPU 類型，例如 `nvidia-l4`。
`--max-instances`	服務的容器執行個體數量上限，例如 `1`。
`--memory`	服務的已分配記憶體量，例如 `32Gi`。
`--no-invoker-iam-check`	停用叫用者 IAM 檢查。如需如何加強應用程式安全性的建議，請參閱「安全地與 Google Gen AI SDK 互動」。
`--no-cpu-throttling`	如果容器未主動處理要求，這項設定會停用 CPU 節流。
`--timeout`	必須傳回回應的時間，例如 `600` 秒。

如要修改預設設定，或為 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 ollama-gemma --port=9090
```

在另一個終端機分頁中傳送要求，讓 Proxy 保持執行狀態。請注意，Proxy 會在 localhost:9090 上執行：

curl http://localhost:9090/api/generate -d '{
  "model": "gemma3:4b",
  "prompt": "Why is the sky blue?"
}'

這個指令應會提供類似以下的串流輸出內容：

{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.641492408Z","response":"That","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.687529153Z","response":"'","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.753284927Z","response":"s","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.812957381Z","response":" a","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.889102649Z","response":" fantastic","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.925748116Z","response":",","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.958391572Z","response":" decept","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.971035028Z","response":"ively","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.989678484Z","response":" tricky","done":false}
{"model":"gemma3:4b","created_at":"2025-03-10T03:02:18.999321940Z","response":" question","done":false}
...

安全地與 Google Gen AI SDK 互動

部署 Cloud Run 服務後，您可以使用 Google Gen AI SDK 搭配 Cloud Run 端點。

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

下列範例說明如何搭配使用 Google Gen AI SDK 與 IAM 驗證。

JavaScript 或 TypeScript

如果您使用適用於 JavaScript 和 TypeScript 的 Google Gen AI SDK，程式碼可能如下所示：

import { GoogleGenAI, setDefaultBaseUrls } from "@google/genai";
import { GoogleAuth} from 'google-auth-library'

const cloudrunurl = 'https://CLOUD_RUN_SERVICE_URL';
const targetAudience = url;

const auth = new GoogleAuth();

async function main() {

  const client = await auth.getIdTokenClient(targetAudience);
  const headers = await client.getRequestHeaders(targetAudience);
  const idToken = headers['Authorization']

const ai = new GoogleGenAI({
  apiKey:"placeholder",
  httpOptions: { baseUrl: url, headers: {'Authorization': idToken}  },
});

  const response = await ai.models.generateContent({
    model: "gemma-3-1b-it",
    contents: "I want a pony",
  });
  console.log(response.text);
}

main();

curl

如果使用 curl，請執行下列指令來連上 Google Gen AI SDK 端點：

如要生成內容，請使用 /v1beta/{model=models/*}:generateContent：根據輸入內容 GenerateContentRequest 生成模型回覆。

curl "<cloud_run_url>/v1beta/models/<model>:generateContent" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $(gcloud auth print-identity-token)" \
-X POST \
-d '{
  "contents": [{
    "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
    }]
    }'

如要串流生成內容，請使用 /v1beta/{model=models/*}:streamGenerateContent：根據輸入內容 GenerateContentRequest，生成串流回覆。

curl "<cloud_run_url>/v1beta/models/<model>:streamGenerateContent" \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $(gcloud auth print-identity-token)" \
  -X POST \
  -d '{
    "contents": [{
      "parts":[{"text": "Write a story about a magic backpack. You are the narrator of an interactive text adventure game."}]
      }]
      }'

設定並行數以獲得最佳成效

本節提供建議並行設定的背景資訊。為達到最佳要求延遲時間，請確保 --concurrency 設定等於 Ollama 的 OLLAMA_NUM_PARALLEL 環境變數。

OLLAMA_NUM_PARALLEL 決定每個模型可用的要求配額數量，以便同時處理推論要求。
--concurrency 決定 Cloud Run 同時傳送給 Ollama 執行個體的要求數量。

如果 --concurrency 超過 OLLAMA_NUM_PARALLEL，Cloud Run 傳送至 Ollama 模型的要求數量，可能會超過可用的要求時段。這會導致 Ollama 內的要求排隊，進而增加排隊要求的延遲時間。此外，由於佇列中的要求不會觸發 Cloud Run 擴充及啟動新執行個體，因此自動調度資源的回應速度也會變慢。

Ollama 也支援從單一 GPU 提供多個模型。如要完全避免 Ollama 例項上的要求排隊，您仍應將 --concurrency 設為與 OLLAMA_NUM_PARALLEL 相符。

請注意，增加 OLLAMA_NUM_PARALLEL 也會導致平行要求耗費更長時間。

最佳化使用率

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

清除所用資源

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

在 Cloud Run 上執行 Gemma 3 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

瞭解如何授予角色

控制台

gcloud

使用預先建構的容器部署 Gemma 模型

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

安全地與 Google Gen AI SDK 互動

JavaScript 或 TypeScript

curl

設定並行數以獲得最佳成效

最佳化使用率

清除所用資源

後續步驟

在 Cloud Run 上執行 Gemma 3