Gemini 兼容层与原生接口的路由差异

Gemini 有原生 generateContent 接口，也有官方的 OpenAI 兼容层。两者在网关侧的配额、计费和错误码并不共享，中转站如果只接了其中一条路径，行为会与文档不一致。

原生接口的请求体是 contents 数组，每项带 role 与 parts；兼容层则是标准 messages。中转做转换时，最容易丢的是多轮对话中的角色映射：原生只区分 user 与 model，而 OpenAI 语义里有 assistant，转换不当会让模型把历史回答当作用户输入。

返回结构也不同。原生返回 candidates 与 usageMetadata，兼容层返回 choices 与 usage；其中 promptTokenCount 与 prompt_tokens 的统计口径可能相差系统提示部分。做账单核对时，应以实际返回的 usage 为准，而不是自己按字数估算。

限流维度同样有差异。原生接口常按每分钟请求数与每分钟 token 数双重限制，兼容层有时只保留请求数限制。这意味着同一账号在兼容层上看起来还有余量，切回原生接口就会立刻 429。

多模态是另一处差异点。原生接口支持 inline_data 与 file_data 两种媒体引用，兼容层只支持 base64 或可公开访问的 URL。需要处理 PDF、音频时，优先用原生接口，或在网关侧先上传再引用。

选型建议是把两条路径都保留：日常对话走兼容层以复用现有代码，涉及长文档与多模态时切到原生接口。两条路径各自的超时与重试策略要分开配置，不要共用同一套参数。