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

统一 SDK 风格可以降低迁移成本，让团队先验证 Gemini，再按任务接入其他模型。

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

先看一个业务场景

已有 OpenAI 调用逻辑的项目想增加 Gemini 模型。

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

设计原则

• 把模型名、base_url、key 做成配置
• 统一错误结构
• 为不同任务保留模型映射表

这里最重要的是把模型调用从业务逻辑里抽出来。业务代码应该描述任务，比如“生成摘要”“识别图片信息”“整理会议纪要”，而不是到处散落具体模型参数。这样后续要替换 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 对应模型调用，模型网关对应统一入口，日志和重试对应稳定性，成本统计对应预算控制。写代码前先把这些模块拆开，后面排查问题会轻很多。

工程上最该省的不是这一层

模型网关、配置表、检查表这些东西听起来不性感，但它们决定后面能不能少返工。AI 应用变化太快，今天测 Gemini，明天可能要加 Claude，后天又想把某个任务切到更便宜的模型。

如果业务代码里到处散落模型名、超时时间、重试策略和计费逻辑，后期每一次调整都像拆墙。把模型调用集中起来，不是为了架构好看，而是为了让团队敢改。

一个反面例子

一个内容生成产品最开始只有一个模型，研发直接在三个业务接口里写了调用逻辑。后来运营想给用户提供“快速/高质量/低成本”三种模式，结果每个接口都要改，日志字段也对不上。

问题不是当初选错模型，而是当初没有给模型变化留位置。

开发时可以多留一个字段

无论你最后用 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 可以成为重要模型，但生产系统最好始终保持可替换、可观测、可控。先把接入层设计好，再谈模型效果，会比后期补工程债轻松很多。