面向后端团队的 Gemini API 生产就绪检查清单

一个成功的 Gemini API 演示只能证明模型可以回答一个请求。它并不能证明你的应用能够保护凭据、保持响应契约、承受速率限制、控制成本、处理模型变更，或在发生事故后恢复。

这份Gemini API 生产检查清单将原型转变为可运营的生产依赖项。它专为支持 Web 应用、移动端后端、SaaS 产品、内部工具和面向客户工作流的后端团队设计，而不只是面向自主 AI 代理。

时效性认证说明： Google 当前的 Gemini API 密钥文档指出，该服务正在迁移到 Google Cloud API 密钥。过渡将于 2026 年 8 月 31 日 开始，Google 预计将于 2026 年 9 月 23 日 完全强制执行。在这些日期之前或跨越这些日期发布的团队，应在目标环境中验证密钥所有权、项目关联、限制和轮换，而不要假设原型密钥会一直有效。

简版：上线前的 18 项检查

将此清单用作发布门禁。下面的详细部分会说明如何实现每一项。

访问与安全

• 生产调用来自受信任的后端，而不是浏览器或移动端二进制文件。
• API 密钥属于一个命名的 Google Cloud 项目和工作负载所有者。
• 密钥限制、轮换、吊销和紧急替换都有文档记录。
• 预发和生产使用 अलग جدا的凭据、配额和监控。

模型与响应契约

• 应用固定一个有意指定的模型标识符，而不是静默跟随别名。
• 必需的模态、区域、上下文大小、工具和输出特性都经过测试。
• 结构化输出使用模式和验证层。
• 供应商特定的请求和响应字段被隔离在适配器之后。

可靠性与运维

• 每次调用都有连接超时、响应截止时间和总重试预算。
• 重试仅限于瞬时故障，并使用带抖动的指数退避。
• 并发经过负载测试，以匹配项目当前的速率限制。
• 日志记录模型、延迟、令牌数、状态、重试次数和相关 ID。
• 仪表板区分提供方错误、应用验证错误和用户取消。

质量、成本与发布

• 代表性评估集设有发布阈值。
• 安全性和拒绝行为已使用真实产品场景进行测试。
• 令牌和请求预算按用户、租户或工作流进行强制限制。
• 发布使用预发、金丝雀流量、熔断开关以及经过测试的回滚。
• 关键工作负载存在备用路径。

1. 有意识地选择集成层

在编写生产代码之前，先决定应用实际上要集成的是哪个 Google 接口。Gemini Developer API 针对直接的 Gemini 开发进行了优化，而 Vertex AI 则增加了对企业部署可能重要的 Google Cloud 控制，例如更广泛的身份、治理和平台集成。

不要让 SDK 导入无意间替你做出这个架构决策。写下来：

对于许多产品来说，最好的初始设计是由后端负责的一个小型提供方适配器。它应接受应用层请求并返回应用层结果。身份验证、模型名称、提供方错误、令牌元数据和 SDK 对象都保留在适配器内部。

这种边界可防止 Gemini 特定字段扩散到业务逻辑中。它还使后续可控的多模型测试成为可能。如果可移植性已经是一个需求，那么在集成变得难以拆解之前，请先查看 OpenAI-compatible API gateway migration checklist。

2. 将凭证移出客户端代码

切勿在前端 JavaScript、桌面应用包、浏览器扩展或移动应用中发布 Gemini API 密钥。混淆不是安全边界。决心足够强的用户可以检查网络流量、二进制文件、存储或运行时内存并恢复该密钥。

请改用以下请求路径：

用户设备 → 经过身份验证的后端 → Gemini API

后端应强制执行：

1. 用户身份验证：识别是谁发起了请求。
2. 授权：验证该用户或租户是否可以运行此工作流。
3. 输入限制：限制负载大小、文件类型、媒体时长和提示长度。
4. 使用限制：在调用模型之前，按用户和按租户执行预算限制。
5. 审计上下文：附加内部关联 ID，默认不记录敏感内容。

将密钥存储在秘密管理器或部署密钥存储中。记录其所有者、项目、环境、创建日期、限制、轮换间隔和撤销流程。保留一条经过测试的紧急密钥替换路径，不需要完整应用发布。

由于 Google 已宣布将在 2026 年迁移到 Google Cloud API 密钥，生产团队应将密钥迁移视为一项活跃的发布依赖，而不是未来的整理任务。在上线前，请在 Google 的 Gemini API key documentation 中核实当前要求。

如需更广泛的跨提供方策略，请使用这份 secure API key management guide。

3. 固定模型并记录其契约

模型标识符是生产 API 契约的一部分。即使应用代码不变，模型更改也可能改变延迟、令牌用量、安全行为、支持的功能，以及输出的形状或质量。

在配置中创建模型清单，而不是在代码库中散落模型名称：

workload: support_reply_draft
provider: google
model: configured-stable-model-id
required_capabilities:
  - text_input
  - structured_output
  - streaming
max_output_tokens: 900
timeout_ms: 20000
fallback_workload: support_reply_draft_backup
evaluation_suite: support-replies-v4

具体的模型 ID 必须来自当前的 Gemini 模型文档。除非某个仅预览版才有的能力值得承担额外的变更风险，否则生产环境应优先选择稳定版模型。如果使用预览版模型，请添加明确的复审日期和替换负责人。

测试你的应用真正需要的能力。一次通用的 “hello world” 调用并不能验证：

• 图像、音频、视频或文档输入；
• 流式行为；
• 工具或函数调用；
• 结构化输出约束；
• 上下文限制和 token 计数；
• 安全行为；
• 文件生命周期；
• 缓存行为；
• 真实并发下的延迟。

为每个发布记录 SDK 版本、API 表面、模型 ID、请求配置和评估数据集。这样当结果发生变化时，你就拥有可复现的基线。

4. 将模型输出视为不可信输入

自然语言输出具有概率性。即使是强大的模型，也可能遗漏字段、产生意料之外的枚举值、包含额外评论，或者返回一个语法正确但违反业务规则的对象。

对于机器消费的输出，请使用 Gemini 的 结构化输出能力，并在你的应用中再次验证结果。

使用四层校验：

1. 响应 schema： 约束预期的对象形状。
2. 解析器验证： 拒绝格式错误的 JSON 和错误类型。
3. 业务验证： 强制允许的状态、范围、所有权以及数据库规则。
4. 修复策略： 决定是重试、让模型修复、使用回退方案，还是将案例交给人工处理。

例如，模型生成的退款建议可能是有效的 JSON，但仍可能超出用户权限、引用不可用产品，或违反退款窗口。schema 验证不能替代应用层授权。

像 API 契约一样为 schema 版本化。为有效输出、缺失字段、未知枚举值、null、超长字符串、重复操作以及对抗性内容添加固定测试样例。不要把无效响应悄悄强制转换为有效的业务操作。

5. 为函数调用设置策略边界

函数调用有助于模型提出工具调用建议，但模型不应拥有授权或执行策略。Google 的 函数调用文档描述了模型到工具的模式；你的应用仍然负责决定某个建议的调用是否被允许。

对于每一个可调用函数：

• 使用简洁的名称和 schema；
• 仅允许必要的字段；
• 在服务端验证每个参数；
• 在执行时重新检查用户授权；
• 设置执行超时和结果大小限制；
• 尽可能使副作用具备幂等性；
• 对高影响操作要求确认；
• 记录决策和结果，但不要暴露密钥。

将只读工具与写入工具分开。产品搜索和付款扣款不应共享相同的审批策略。对于破坏性操作或具有财务影响的操作，在执行前向用户或授权审阅者展示拟执行的操作。

同时要防御从检索到的页面、文档、邮件和工具结果中出现的 prompt injection。把外部内容视为数据，而不是受信任的指令。工具策略应写在模型提示词之外的代码中。

6. 将安全性和产品行为一起定义

提供方的安全控制与产品策略解决的是不同问题。Gemini 安全设置可以帮助分类或阻止某些有害内容，但你的产品仍然需要针对年龄限制、受监管工作流、品牌风险、滥用、敏感数据和升级处理制定规则。

构建一个涵盖以下内容的安全测试矩阵：

查看 Google 当前的 Gemini 安全设置，然后定义你自己的应用层行为。将策略版本与评估结果一起存储，这样对阈值或用户消息的更改就可以被审计。

安全测试必须包含误报。一个阻止过多的系统，与一个阻止过少的系统一样不可用。

7. 管理上下文、文件和缓存生命周期的预算

大型提示和多模态输入带来的不只是成本问题。它们还会影响延迟、限流消耗、超时行为、存储、隐私和调试。

为以下内容设置明确限制：

• 提示和对话长度；
• 文件大小和可接受的媒体类型；
• 音频或视频时长；
• 图片数量和分辨率；
• 检索到的文档数量；
• 最大输出 token 数；
• 缓存上下文的生命周期；
• 用户和租户的消耗。

在开发期间以及在实际可行时于昂贵调用之前使用 token 计数。Google 在其 token 指南中记录了 token 行为。如果重复的长上下文主导了工作负载，可以评估 上下文缓存，但应将缓存内容视为受管理的数据资产，并为其所有权、过期、失效和删除制定规则。

不要假设每个文件都应该完整发送。提取相关页面，适当压缩图像，移除不受支持的元数据，并拒绝超出产品限制的文件。跟踪原始资产、转换后的资产、上传状态、保留策略和删除结果。

8. 围绕总时间预算设计重试机制

重试可以提升可靠性，也可能放大中断。区别在于它们是否有边界、是否有选择性，以及是否可观测。

在重试之前先对失败进行分类：

每个请求都需要三个限制：

1. 连接超时，用于建立请求。
2. 单次尝试截止时间，用于一次提供方调用。
3. 总工作流截止时间，涵盖重试和回退。

使用带随机抖动的指数退避。限制尝试次数。尊重取消。通过并发限制和熔断器防止重试风暴。对于面向用户的交互，优先使用快速回退或降级响应，而不是一个用户不可见、持续一分钟的重试循环。

Gemini 的限制会因模型、层级和项目而异，因此请从 Google 的 Gemini API rate limits 获取当前值，而不是将某个数字复制到永久文档中。

9. 让使用情况、质量和失败变得可观测

生产仪表板应能快速回答三个问题：

1. 提供方是否健康？
2. 应用集成是否健康？
3. 用户是否以可接受的成本获得了可接受的结果？

为每次调用记录结构化元数据：

• 时间戳和环境；
• 应用工作负载和版本；
• 已配置的模型 ID；
• 内部关联 ID；
• 延迟和首个 token 的时间；
• 可用时的输入和输出 token 用量；
• 状态类别和标准化错误代码；
• 重试和回退次数；
• 架构校验结果；
• 安全或拒绝结果；
• 使用隐私安全标识符的用户、租户或功能分组；
• 估算或对账后的成本。

默认情况下，避免记录完整的提示和响应。内容日志可能带来安全、隐私、合规和保留风险。优先使用元数据、哈希、脱敏样本以及明确受治理的调试捕获。

为身份验证失败、速率限制升高、提供方错误、延迟、架构失败、回退触发、成本激增和安全性漂移创建告警。确保每个仪表板都包含模型和应用版本，以便关联变化。

10. 衡量每个成功产品结果的成本

仅凭 token 价格，并不能判断一个集成是否高效。如果一个更便宜的请求需要更长的提示词、更多重试、更多修复调用或更多人工审核，那么它在每个成功任务上的成本可能更高。

请跟踪：

每个成功任务的成本 =
  模型请求
  + 重试
  + 修复调用
  + 回退调用
  + 检索和存储
  + 人工审核

在多个层级设置预算控制：

• 每次请求的最大 token 数；
• 每个工作流的最大请求数；
• 按用户和按租户的配额；
• 每日异常告警；
• 功能级成本上限；
• 紧急停用开关。

在选择生产默认模型之前，请查看当前的模型访问和定价，然后使用一套有代表性的评估集对模型进行比较，而不要仅仅根据价格表来决定。

11. 在模型变更前建立评估门禁

基于真实产品场景、已清洗的生产示例、边缘案例和已知失败情况创建一个带版本的数据集。对工作流中重要的属性进行评分：

• 任务完成度；
• 事实一致性；
• schema 有效性；
• 安全性和拒绝质量；
• 延迟；
• token 使用量；
• 每个成功任务的成本；
• 在适当情况下的人类偏好。

在运行候选方案之前先定义阈值。为关键行为保留一组“绝不能回归”的用例。当模型、提示词、schema、SDK、安全设置或检索策略发生变化时，重新运行同一套测试。

对于跨提供商评估，请使用可重复的多模型提示测试工作流，以便每个候选方案接收等价的输入、限制和评分。

12. 使用金丝雀发布和回滚机制进行上线

不要因为预发布测试通过，就立即切换全部流量。

请使用以下发布顺序：

1. 离线评估：通过质量、安全、schema、延迟和成本阈值。
2. 预发布环境：验证凭据、配额、文件、回调、流式传输和仪表盘。
3. 影子流量：在策略允许的情况下，比较输出而不影响用户。
4. 内部金丝雀：向员工或测试租户开放发布。
5. 小流量生产金丝雀：将一小部分受控的合格流量路由过去。
6. 渐进式放量：仅在指标保持健康时增加流量。
7. 全面发布：保留立即回退配置的能力。

回滚应该是一次配置变更，而不是代码部署。在观察窗口结束之前，请保留之前的模型、提示词、schema 和路由策略可用。

关键工作流需要一个回退层级。根据产品不同，这可能是：

主 Gemini 模型
→ 备用 Gemini 模型
→ 兼容的提供商或网关路由
→ 确定性的降级体验
→ 人工队列

回退机制必须经过测试，而不只是配置完成。请验证响应 schema、安全行为、工具可用性和成本控制仍然有效。

13. 准备 Gemini 事件响应手册

在第一次事故发生之前就编写好响应手册。包括：

• 凭证所有者和轮换步骤；
• 提供商状态和升级链接；
• 模型和配置历史；
• 仪表盘和告警定义；
• 已知错误映射；
• 断路器和熔断开关控制；
• 备用方案启用流程；
• 用户沟通负责人；
• 数据暴露评估步骤；
• 回滚验证；
• 事后评估更新。

至少针对四种场景进行一次演练日：凭证被吊销、持续速率限制、延迟升高以及无效的结构化输出。确认值班工程师能够识别故障域，并在不修改生产环境中的提示词的情况下稳定产品。

生产就绪工作表

将此表复制到发布工单中，并为每一行指定负责人。

常见问题

生产应用可以直接从浏览器调用 Gemini API 吗？

不可以。请将提供商调用放在经过身份验证的后端之后，这样 API 密钥就能保持机密，并且你可以强制执行授权、配额、验证、日志记录和滥用控制。

生产环境中应该使用 Gemini 的“latest”别名吗？

更推荐使用有意指定且有文档记录的模型标识符，以及受控的升级流程。别名可用于实验，但生产工作负载需要可重复的评估和可回滚目标。

结构化输出能保证满足我的业务规则吗？

不能。结构化输出有助于约束语法和形状。你的应用仍然必须验证权限、范围、所有权、状态转换以及每一个副作用。

我应该重试哪些 Gemini API 错误？

在严格的总耗时和尝试次数预算内，重试瞬时网络故障、速率限制以及选定的服务器故障。不要在不加更改的情况下重试身份验证、权限或无效请求错误。

我应该在什么时候添加多模型网关？

当单独的提供商凭证、配额、日志、计费、评估和备用路径正在拖慢交付时，添加网关。如果提供商原生功能在战略上很重要，并且你的团队能够运维额外复杂性，则保持直接集成。

交付你能够运维的集成

最安全的 Gemini API 上线，并不是那个提示词最复杂的方案，而是具备明确责任归属、受保护的凭据、固定的模型契约、经过验证的输出、受限的故障行为、可衡量的质量、成本控制，以及经过测试的回滚机制的方案。

首先，把调用移到后端之后，并完成生产就绪工作表。然后，使用你选定的 Gemini 模型以及至少一个回退方案，运行同一套评估集。如果多提供商运维成为瓶颈，可以使用 Flatkey integration starter，通过一个密钥和一个 OpenAI 兼容的基础 URL 来测试兼容工作负载。

Google 官方参考资料

• Gemini API 密钥
• Gemini 模型
• 结构化输出
• 函数调用
• 安全设置
• Token 计数
• 上下文缓存
• 速率限制