这篇按开发接入来写，重点放在 Gemini API、模型网关、日志、重试和成本统计这些上线前绕不开的细节。

生产环境接入 Gemini，重试、日志和成本统计不是附加功能，而是排查问题和控制预算的基础。

从工程角度看，Gemini API 接入最容易被低估的地方，不是第一行请求代码，而是上线后的可维护性。Demo 阶段只要能返回结果就行，生产环境则要面对超时、重试、日志、限流、成本统计和模型切换。

先看一个业务场景

一个接口每天调用几万次，偶发超时会影响用户体验。

这个需求如果只写一个脚本，很快就能跑。但只要它进入后台服务，调用链就会变长：用户请求进来，业务系统组装 prompt，模型返回结果，系统再把结果写入数据库或展示给用户。任何一环没有记录，排查问题都会很痛苦。

设计原则

• 记录模型、耗时、token、状态码
• 区分可重试和不可重试错误
• 为每个项目设置预算阈值

这里最重要的是把模型调用从业务逻辑里抽出来。业务代码应该描述任务，比如“生成摘要”“识别图片信息”“整理会议纪要”，而不是到处散落具体模型参数。这样后续要替换 Gemini 版本、增加 Claude 或 GPT，改动范围才可控。

最小可跑示例

from openai import OpenAI

client = OpenAI(
    api_key="YOUR_API_KEY",
    base_url="https://147ai.com/v1",
)

resp = client.chat.completions.create(
    model="gemini-3.1-flash",
    messages=[{"role": "user", "content": "把这段业务资料整理成三条结论。"}],
    temperature=0.2,
)

print(resp.choices[0].message.content)

示例只是起点。上线时，建议再包一层 service，统一处理 timeout、retry、usage 记录和错误结构。不要让页面、定时任务、后台接口各自直接调用模型。

常见坑

只在控制台看报错，没有在业务侧记录请求上下文。

这个坑短期不明显，等业务跑起来才会暴露。比如运营想知道某个项目一天花了多少钱，客服想知道为什么某次摘要失败，研发想切换备用模型。如果早期没有接入层和日志，这些问题都会变成临时补丁。

先给关键词做个映射

这篇里的关键词可以对应到工程模块：Gemini API 对应模型调用，模型网关对应统一入口，日志和重试对应稳定性，成本统计对应预算控制。写代码前先把这些模块拆开，后面排查问题会轻很多。

这里最值得多想的一点

很多团队会把“调用失败”理解成网络错误，其实线上更麻烦的是半失败：接口返回了，但内容不完整；模型没有报错，但 JSON 格式坏了；摘要看起来顺，但把关键数字漏掉了。

所以错误处理不能只写 try/except。最好把失败分成几类：连接失败、超时、配额不足、内容安全拦截、格式不符合预期、业务校验失败。前几类可以重试，后几类要么降级，要么交给人工处理。这个分类一旦写清楚，客服和运营遇到问题时也知道该怎么解释。

一个反面例子

有些 AI 功能上线初期看起来很顺，直到某天活动流量上来，接口开始间歇性超时。用户连续点了三次，系统生成了三份不同结果，后台还分别计费。最后不是模型回答差，而是任务状态、幂等处理和成本记录没设计好。

这种坑不会出现在演示里，只会出现在真实用户手上。

开发时可以多留一个字段

无论你最后用 Gemini 还是别的模型，我都建议日志里至少保留 task_type、model、latency_ms、token_usage、retry_count 和 fallback_used。这些字段平时不起眼，排查问题时非常救命。

等业务方问“为什么这周成本高了”或“为什么这个用户一直失败”，你不用翻代码猜，直接看数据就行。

我会把 147AI 先接到测试环境

工程接入时，我更倾向先用 147AI 这种统一入口做一轮验证。原因不是它能省掉所有工程工作，而是它能让你少写几套临时接入代码。已有 OpenAI SDK 风格调用的项目，通常先改 base_url、模型名和 Key，就能把 Gemini 跑起来测。

我会重点看四个点：连续请求是否稳定、错误返回是否好处理、账单和用量是否清楚、后面切到 GPT 或 Claude 是否麻烦。能过这几项，再考虑进正式环境。

上线前补一组小测试

正式接入前，可以准备一组很小但完整的测试用例。比如 10 条正常请求、5 条超长输入、5 条异常输入、5 条并发请求，再加几条需要降级的失败场景。

测试时记录四类数据：平均耗时、失败率、token 消耗和人工修正比例。这样你后面讨论模型选择时，就不是凭感觉说 Gemini 好不好，而是能拿出一组可复现的工程指标。

小结

Gemini 可以成为重要模型，但生产系统最好始终保持可替换、可观测、可控。先把接入层设计好，再谈模型效果，会比后期补工程债轻松很多。