把聊天请求换成 Gemini generateContent 时的笔记
把已有聊天程序接到 Gemini 时，第一步不是替换模型名称，而是确定保留哪种协议。generateContent 是 Gemini 原生的内容生成方法；OpenAI 兼容聊天接口则提供另一套请求与响应结构。两者都能承载多轮对话，但字段、角色和结束状态不能直接互换。下面按同一个调用过程并排记录差异。
§ 入口：模型放在哪里
Gemini 原生：典型请求使用 POST，路径形如 /v1beta/models/{model}:generateContent，模型标识位于路径中。OpenAI 兼容：聊天请求通常发往 /v1/chat/completions，模型标识放在请求体的 model 字段中。迁移时应同时检查路径与请求体，不能只替换其中一处。
Vana API 在 https://api.vanaapi.com 提供统一入口，同时支持 OpenAI 兼容协议、Anthropic Messages 和 Gemini 原生协议。已有 OpenAI SDK 的应用可以先保留兼容接口；需要直接处理 Gemini 原生字段时，再选择原生协议。实际模型标识、鉴权方式与可用路径，应以平台当前文档为准。
§ 输入：消息数组与内容片段
Gemini 原生：对话放在 contents 中，每条内容通常包含 role 和 parts。用户角色是 user，模型回复角色是 model；文本放在 parts 内的 text 字段。OpenAI 兼容：对话通常放在 messages 中，使用 user、assistant 等角色，正文由 content 承载。把 assistant 原样复制为 Gemini 的角色，会造成结构错误。
系统指令也需要单独映射。Gemini 使用顶层 systemInstruction，而不是在 contents 中插入一条 system 消息。图片等多模态输入则要按照各自协议组织内容片段；原生协议可以使用 inlineData 或 fileData 等结构，但具体支持范围仍取决于模型、接口及中转能力。
§ 生成设置：相似名称不等于相同语义
Gemini 原生：temperature、maxOutputTokens 等设置放在 generationConfig 中。OpenAI 兼容：参数通常位于请求体顶层，输出长度参数还可能因接口或模型而异。迁移时宜逐项建立映射，而不是把旧参数整体嵌入新请求。
结构化输出同样需要检查。Gemini 原生可通过 responseMimeType、responseSchema 等设置约束输出；兼容接口采用自己的格式声明。两侧支持的约束范围不一定一致。即使要求输出 JSON，应用仍应进行解析、字段校验和失败处理，不能把格式设置视为业务正确性的保证。
§ 响应：不要只改一个取值路径
Gemini 原生：生成结果位于 candidates，候选内容通常在 content.parts 中，结束原因由 finishReason 表示，用量见 usageMetadata。OpenAI 兼容：聊天结果通常从 choices 中读取，正文、结束原因与用量采用另一套字段。
解析 Gemini 响应时，不宜固定读取第一个 part 的 text。内容可能包含多个片段，也可能返回工具调用。还应检查 HTTP 状态、候选是否存在，以及 promptFeedback 或候选中的安全反馈。没有正文不必然意味着网络故障；达到输出上限、安全限制和工具调用都需要不同的处理分支。
§ 流式与工具：处理事件，而不是拼接字符串
Gemini 原生：流式生成通常使用 streamGenerateContent，采用 SSE 时可使用 alt=sse。OpenAI 兼容：通常在聊天请求中设置 stream，并读取增量事件。两侧的事件结构和结束信号不同，因此可以共用连接管理逻辑，却不应共用未经转换的事件解析器。
工具调用也有对应关系：Gemini 原生通过 functionCall 表达调用，再以 functionResponse 回传结果；兼容聊天接口通常使用 tool_calls 和工具消息。应用应保留工具名称、参数、调用关联信息及执行结果，按照所用协议与版本维护对话顺序。模型提出调用不代表工具已经执行，权限检查仍由应用负责。
§ 接入：先验证一轮，再扩展功能
可以先用 Gemini 2.5 Flash 做最小文本请求，再依次验证多轮上下文、流式输出、工具调用和异常响应。对照日志时记录请求标识、结束原因、耗时与用量，避免记录密钥或不必要的用户内容。质量比较应使用相同任务和相近输出预算，而不是只看一次回答。
通过 Vana API 接入时，保留现有 SDK 往往改动更少；采用 Gemini 原生协议则更便于直接处理原生结构，但仍需确认目标功能的支持情况。平台按实际 token 用量计费，无月费，预算应结合用量记录核对。可以创建一个 Vana API 账户，用同一段脱敏对话分别验证两种请求，确认解析与错误处理后再切换生产流量。