Gemini Interactions API 迁移验收清单：6 类断言覆盖 steps、工具和 SSE

如果你的 Gemini Interactions API 代码还在读取 interaction.outputs，或者把 response_mime_type 直接放在请求顶层，迁移时不能只改单个字段。2026 年这次 schema 变化同时影响响应遍历、函数调用、服务端工具、无状态历史、流式事件和结构化输出配置；旧版 Interactions API schema 已在 2026 年 6 月 8 日移除。

先判断影响面：你到底依赖了哪一层旧字段

这次升级最容易漏掉的地方，是业务代码没有直接写旧 schema，而是把旧结构藏在几个适配函数里。例如前端只取 outputs[0].text，网关把 response_mime_type 透传到请求顶层，或者历史管理器把上一轮的 outputs 原样塞进下一次 input。单元测试若只覆盖纯文本场景，问题会拖到工具调用或流式页面上线后才暴露。

先在代码库里搜索 outputs、response_mime_type、response_modalities、step.delta 和 function_call。把结果分成四组：响应读取、请求格式、历史续接、流式监听。迁移清单按这四组推进，比全局替换更安全。

版本和灰度怎么选：REST 与 SDK 不是一条路径

官方迁移规则给出了清晰的过渡窗口。REST 请求可以通过 Api-Revision: 2026-05-20 提前使用新格式；默认切换后，仍可短暂用 Api-Revision: 2026-05-07 退回旧格式，但旧 schema 在 6 月 8 日之后不再可用。Python 2.x 和 JavaScript 2.x SDK 会自动选择新 schema，旧版 SDK 只在过渡期继续返回旧响应。

curl -X POST "https://generativelanguage.googleapis.com/v1beta/interactions" \
  -H "x-goog-api-key: $GEMINI_API_KEY" \
  -H "Api-Revision: 2026-05-20" \
  -H "Content-Type: application/json" \
  -d '{"model":"gemini-3.7-flash","input":"用一句话解释缓存"}'

生产迁移建议先让一小部分 REST 流量显式带新 revision，并在日志中记录 revision、SDK 版本和响应中的步骤类型。确认工具调用和历史续接都正常后，再升级 SDK。不要让 SDK 升级和业务字段重构放在同一个不可回滚的发布中操作。

响应读取要从 outputs 改成 steps

steps 不只是把数组换了名字。它把用户输入、模型输出、函数调用和服务端工具动作放在一条有顺序的执行链里。文本提取可以优先找 model_output，但遇到工具调用时必须继续遍历，而不是看到第一步就直接结束。

for _, step := range interaction.Steps {
    switch step.Type {
    case "user_input":
        recordUserInput(step)
    case "model_output":
        appendText(step)
    case "function_call", "google_search_call":
        dispatchTool(step)
    case "google_search_result":
        saveToolEvidence(step)
    }
}

实际 SDK 的字段名可能随语言不同，但判断原则不变：先看步骤类型，再决定读取哪一段内容。服务端工具步骤也不能当作普通文本拼进回答，否则前端会把工具调用参数展示给用户，或者在工具尚未完成时提前结束会话。

历史续接不能再保存一份旧 outputs

如果应用使用无状态历史，下一次请求需要把上一轮的 steps 作为输入的一部分传回，而不是只保存最终文本。这样才能保留用户输入、模型输出、函数调用和工具结果之间的顺序关系。建议把历史序列化层独立出来，避免业务层到处拼装半截响应。

history = [
  {"type": "user_input", "text": "查北京天气"},
  {"type": "model_output", "text": "我先查询天气"},
  {"type": "google_search_call", "id": "call_17"},
  {"type": "google_search_result", "id": "call_17", "data": {...}}
]

next_request = {
  "model": "gemini-3.7-flash",
  "input": history + [{"type": "user_input", "text": "只告诉我最高温"}]
}

这里要做两项保护。第一，保存前限制历史长度，避免把重复的工具证据无限追加；第二，给每个工具步骤保留关联 ID，重试时不能把同一个工具结果当成新的用户消息。历史数据是可回放输入，应该像请求日志一样可追踪、可脱敏。

response_format 怎么改：文本、图片和音频统一收口

旧请求中常见的 response_mime_type 需要移动到 response_format.mime_type。原来的 JSON Schema 也要包进文本格式对象；如果是图像生成，要把图像配置放到 type=image 的格式项中；音频则使用 type=audio。同时请求多种输出模态时，response_format 由对象变成数组。

{
  "model": "gemini-3.7-flash",
  "input": "返回一个订单摘要",
  "response_format": {
    "type": "text",
    "mime_type": "application/json",
    "schema": {
      "type": "object",
      "properties": {"status": {"type": "string"}},
      "required": ["status"]
    }
  }
}

迁移时不要只检查 HTTP 200 状态。把响应格式声明、实际步骤内容和业务 JSON 校验放在同一条验收链里：配置被服务端接受，模型返回了可解析文本，最后业务字段仍满足必填和枚举约束。严格 schema 校验也不能替代业务逻辑校验。

流式调用的验收点：监听新事件，而不是只等一段文本

流式响应新增了 interaction.created、step.delta 等事件。旧客户端如果只监听文本增量，可能看起来“没有输出”，但后台已经收到了工具调用或步骤状态。前端状态机至少要区分交互创建、步骤增量、工具开始、工具结果和完成/失败状态。

测试时固定记录事件序号、步骤 ID 和最后一次可见文本。断线重连后，不要把已经渲染的 delta 再拼接一遍；可以按步骤 ID 建立缓冲区，收到相同片段时覆盖或跳过。工具步骤没有文本内容是正常情况，不应直接当作空回答处理。

一份可以落地的迁移验收清单

1. 普通文本：新 revision 和旧 SDK 适配层都能得到预期的 steps，最终文本提取不依赖 outputs。
2. 函数调用：能在 steps 中找到 function_call，执行工具后把结果正确关联回原交互。
3. 服务端工具：能区分调用步骤与结果步骤，不把搜索参数或内部状态直接展示给用户。
4. 历史续接：第二轮请求带回完整步骤序列，且重复工具结果不会出现内容扩大或顺序错位。
5. 结构化输出：文本、图像、音频和多模态请求分别校验 response_format 的对象/数组形态。
6. 流式断线：重连后按步骤 ID 去重，最终状态不会停在“正在生成”。

如果必须保留回滚开关，开关应该放在适配层，不要让业务代码同时写两套字段。上线后统计旧字段命中次数、未知 step 类型、工具结果缺失和 JSON 校验失败；这些指标全部归零后再删除兼容分支。

相关问题

只调用纯文本，还需要迁移 steps 吗？

需要。纯文本可能暂时看不出差异，但旧 schema 已按官方时间线移除，而且后续新能力只会出现在新 steps 响应中。

REST 请求现在还要手动加 Api-Revision 吗？

如果要显式选择某个兼容版本，就应该加；生产环境更重要的是记录实际使用的 revision，避免不同服务的默认值不一致。

为什么 response_format 变成数组？

数组用于表达多种输出模态，例如同时请求文本和音频。只请求一种模态时仍使用单个对象即可。

旧 SDK 能不能一直不升级？

不能把它当长期方案。官方迁移页只给旧 SDK 开放一个过渡窗口，升级后还要同步改响应读取逻辑和流式事件处理。

把一次字段替换变成可回滚的迁移

这次 Interactions API 升级的真正工作量在适配层：把有顺序的 steps 作为统一事实源，把 response_format 变成明确的模态配置，再把工具调用、历史续接和 SSE 监听纳入同一套状态机。先用 revision 做灰度，记录旧字段和未知步骤的命中情况，再升级 SDK、删除兼容分支，迁移过程就能被观察、被回滚，也不会因为一次纯文本测试通过就漏掉生产环境里的工具链异常。