在 Cloud Run 上运行 Gemma 3

本指南介绍了如何使用预构建的容器在 Cloud Run 上部署 Gemma 3 开放模型，并提供了有关如何将已部署的 Cloud Run 服务与 Google Gen AI SDK 搭配使用的指南。

准备工作

如果您使用 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.

1. 在 Google Cloud 项目中设置 Cloud Run 开发环境。
2. 安装并初始化 gcloud CLI。
3. 确保您的账号已获授以下 IAM 角色：
   • Cloud Run Admin (roles/run.admin)
   • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
   • Service Usage Consumer (roles/serviceusage.serviceUsageConsumer)

了解如何授予角色

控制台

1. 在 Google Cloud 控制台中，前往 IAM 页面。

   前往 IAM
2. 选择相应项目。
3. 点击 person_add 授予访问权限。

4. 在新的主账号字段中，输入您的用户标识符。这通常是用于部署 Cloud Run 服务的 Google 账号电子邮件地址。

5. 在选择角色列表中，选择一个角色。
6. 如需授予其他角色，请点击 add 添加其他角色，然后添加其他各个角色。
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 服务的 Google 账号电子邮件地址。
• ROLE 替换为要添加到部署者账号的角色。
4. 前往配额和系统限额页面并进入 Cloud Run Admin API 下方以请求 Total Nvidia L4 GPU allocation, per project per region 配额。
5. 查看 Cloud Run 价格页面。如需根据您的预计使用量来估算费用，请使用价格计算器。

使用预构建容器部署 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 替换为将部署 Cloud Run 的 Google Cloud 区域，例如 europe-west1。如果您需要修改区域，请参阅 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 开发者代理：

1. 启动代理，当系统提示安装 cloud-run-proxy 组件时，选择 Y：

   gcloud run services proxy ollama-gemma --port=9090

2. 在单独的终端标签页中向该组件发送请求，让代理保持运行状态。 请注意，代理在 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 服务后，您可以将 Cloud Run 端点与 Google Gen AI SDK 搭配使用。

在使用 Google Gen AI SDK 之前，请确保传入的请求传递了相应的身份令牌。如需详细了解如何使用 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 服务
• 容器映像

后续步骤

• 配置 GPU
• 最佳实践：在 Cloud Run 上使用 GPU 进行 AI 推理
• 使用各种 AI 运行时框架运行 Gemma 3 模型