批量调用 Gemini 2.5 Flash：双协议客户端的七步改造

旗舰模型ZH2026-10-267 次阅读

同一批处理服务接入 Gemini 原生接口和 OpenAI 兼容接口，变化不只是请求地址。两条路径可能使用相同模型，却采用不同的消息结构、流式事件和工具交互方式。对持续跑量的团队，正确目标是保留统一调度，同时把协议差异关进适配层，而不是让业务代码到处判断接口类型。

01 · 第一步：为批处理队列分开记录模型与协议

先把客户端配置拆成模型、协议、凭据和路由四部分。以 Gemini 2.5 Flash 为例，不要仅凭模型名称决定发送兼容格式还是原生格式；应显式选择协议，再由适配器组装请求。原生接口是否可用、支持哪些模型及参数，需要按中继实际能力确认，不能从兼容接口可用反推。

Quanta 适合把多模型持续调用放在同一余额下管理，但统一余额不代表统一报文。保留现有兼容客户端，在旁边新增原生适配器，通常比直接替换公共调用函数更容易控制影响范围。

建立内部消息对象，分别记录说话方、文本、图片、工具请求和工具结果。兼容协议常用消息列表承载对话；原生协议通常围绕内容及其片段组织输入，系统指令也可能单独传递。适配器必须显式转换，不能直接改字段名。

逐项核对输出长度、随机性、停止条件、结构化输出和思考配置。相似名称不保证相同语义，某个兼容参数被接受，也不意味着它实际生效。能力表至少记录支持情况、默认行为、取值约束和不支持时的处理方式。

先用固定样例验证 Gemini 2.5 Flash 的两条路径，再加入其他模型。不要为了追求统一接口，把原生能力硬塞进含义模糊的通用字段；可以保留受控的协议专属配置。

流式处理不能只提取文本。原生响应可能携带候选结果、内容片段、结束原因、安全信息和用量数据；兼容响应则有自己的增量结构。两者都应先解析为内部事件，再交给展示层或任务消费者。

网络连接结束不等于任务成功。分别识别正常完成、长度截断、安全拦截、工具请求和传输中断。用量也可能在较晚的事件中出现，不要在收到最后一段可见文本时就提前关闭计费记录。

把工具名称、参数结构、调用标识和执行结果作为独立对象保存。不同协议对函数声明、调用关联及结果回传的要求可能不同；客户端需要按各自规则恢复下一轮输入，而不是把工具结果拼成普通用户文本。

如果响应包含必须回传的签名或协议元数据，也要原样保留。对会写入外部系统的工具增加幂等控制：请求超时后重试，不能顺带把一次付款或工单创建执行两遍。

Quanta 按实际令牌计量，缓存写入与缓存读取分别计价。客户端应保留原始用量，再映射到输入、输出、缓存写入和缓存读取等账本字段；缺失数据标记为未知，不要当成零。

不要假设两种协议共享缓存、缓存命中方式相同，或相同提示词必然产生相同用量。将协议、模型、任务标识和重试次数一起记入日志，才能定位预算变化来自哪里。敏感提示词与凭据则应脱敏。

先离线回放文本、多模态、工具和异常样例，再给少量低风险任务启用原生路径。比较任务完成率、结果可解析性、延迟、实际令牌及重试量，而不是只看回复是否相似。

保留按队列切回兼容路径的开关，但不要在部分输出或工具执行后盲目自动切换，以免重复消费。若团队希望集中管理多模型预算，可以开通一个 Quanta 账户，从单个队列开始验证。最终验收标准是：协议可以切换，业务语义、账本和故障边界仍然清楚。