OpenAI Responses API 迁移方向如何影响旧式 Assistants 集成

如果项目还在使用 Assistants、Threads 和 Runs，迁移重点不是把一个 URL 改成 /v1/responses，而是把“平台托管的会话运行状态”重新拆成应用自己的会话、工具调用和回归记录。OpenAI 官方文档已经将 Assistants API 标记为 deprecated，并给出了 2026 年 8 月 26 日的关闭日期；新集成不应继续建立在旧接口上。

最稳妥的做法是先做一层适配器：保留业务侧的会话 ID、权限和工具执行记录，把旧的 Assistant/Thread/Run 映射到 Responses 的 instructions、input、output、tools 与 previous_response_id，再用固定评测集灰度切换。

先确认哪些旧对象真的被业务依赖

先把代码和数据库里的对象列出来：Assistant 通常保存模型、instructions 和 tools；Thread 保存消息上下文；Run 负责一次执行并可能进入 requires_action；Vector Store 和文件则为检索或代码解释器提供资源。很多系统表面上只调用 Run，实际却把 thread_id 当成用户会话主键，把 run_id 当成订单或任务状态，这正是迁移时最容易丢状态的地方。

官方 Assistants 深入文档还说明，Run 执行期间 Thread 会被锁定，新的消息和 Run 不能继续写入。这个约束不能简单照搬到 Responses；迁移后应由应用侧决定同一会话是否串行、是否允许并发，以及工具调用失败后如何恢复。

旧对象到 Responses 的映射应该怎么做

Responses 创建接口支持文本、图片或文件输入，也支持内置工具和自定义函数调用。SDK 提供的 output_text 是便捷聚合字段；如果业务需要审计工具调用、拒答、多个消息或结构化结果，仍应遍历完整的 output item。

迁移代码时先改状态边界

可以先用一个很小的适配函数隔离 SDK 差异。下面的示例只负责发起响应，业务工具仍由自己的服务执行；生产代码要为每个会话保存请求摘要、响应 ID、工具 call_id 和最终结果。

import OpenAI from "openai";

const client = new OpenAI();

export async function ask(session, text) {
  // 会话权限和业务主键由本地数据库控制，不直接信任客户端传来的 ID。
  const response = await client.responses.create({
    model: session.model,
    instructions: session.instructions,
    input: [{ role: "user", content: [{ type: "input_text", text }] }],
    tools: session.tools,
    previous_response_id: session.previousResponseId || undefined,
    store: false // 对敏感场景显式确认平台状态是否需要保留。
  });

  // 不假设 output[0] 一定是最终文本，先记录完整 item 再提取展示内容。
  return { responseId: response.id, text: response.output_text, items: response.output };
}

如果返回了函数调用，应用应校验函数名、租户权限和参数，再执行本地工具，并用同一个 call_id 关联结果。不要为了追求“兼容旧 Run”而把任意工具输出拼回普通字符串；这样会让重试、幂等和审计都变得模糊。

一套可回滚的迁移顺序

1. 建立基线。选取真实但可脱敏的问答、检索、函数调用和失败样本，记录延迟、工具成功率、文本结构和人工评分。
2. 加适配层。让旧业务接口仍接收原有 session_id，内部先转换为 Responses 请求；新旧结果并行记录，但不要同时执行有副作用的工具。
3. 迁移状态。把会话权限、工具执行、幂等键、超时和删除策略放回自己的数据库。平台的 response、conversation 或文件 ID 只作为外部引用。
4. 灰度切换。先切无副作用的只读场景，再切检索和写操作；按租户或会话开关灰度，出现结构回归时可以退回旧适配器。
5. 完成清理。确认旧 Assistant、Thread、Vector Store 和文件的访问权限、备份与删除方案，避免旧资源继续被无人维护的密钥读取。

几个容易误判的迁移边界

第一，Responses 的能力更集中，并不意味着原有业务状态自动迁移；旧 Thread 中的历史消息、文件关联和权限仍要盘点。第二，store、会话对象和后台处理会影响数据保留，合规项目应以当前官方数据控制文档和组织配置为准。第三，官方页面给出的关闭日期属于平台时间表，项目仍应结合 SDK 版本、地区能力和内部变更窗口安排发布，不要把一次“能请求成功”当成迁移完成。

常见问题

只把 beta.assistants 替换成 responses 就够了吗？

不够。至少要重做会话状态、工具结果关联、输出解析、权限校验和评测；否则只是换了入口，旧的 Thread/Run 假设仍会在并发和重试时暴露。

迁移后还要保存 previous_response_id 吗？

如果采用它维护多轮上下文，就应把它当作可过期的外部引用保存，并同时保存自己的会话主键、权限和关键业务事实。需要更强控制时，可以由应用自行组织 input，而不是把全部业务状态交给平台上下文。

官方参考：Assistants API 深入文档、Responses 创建接口、OpenAI API 数据控制。这些页面用于核对接口和生命周期事实，具体迁移仍应以项目自己的评测结果为准。