OpenAI Assistants API将在8月26日关闭：迁移Responses API最后阶段完整清单

文章摘要

OpenAI已经明确，Assistants API将在2026年8月26日停止服务。距离关闭日期不足一个月时，仍依赖Assistant、Thread、Run和Run Step对象的团队不能只把接口地址替换为Responses API。新架构使用Prompt或应用代码管理配置，以Conversation承载输入与输出Item，以Response取代Run，并要求应用更明确地管理工具循环、状态裁剪、重试和结构化输出。本文给出资产盘点、对象映射、数据迁移、工具调用、流式响应、双轨验证和切换回滚清单。

一、哪些系统需要立刻检查

如果代码中出现以下对象，应进入迁移范围：

Assistant
Thread
Message
Run
Run Step
required_action
submit_tool_outputs

常见接口：

/v1/assistants
/v1/threads
/v1/threads/{id}/runs
/v1/threads/{id}/messages

还要检查：

• 使用Assistants的低代码平台；
• 第三方SDK封装；
• 内部API网关；
• 定时任务；
• 后台批处理；
• 已经很久没有维护的实验项目。

不要只搜索主仓库，历史脚本和服务配置也可能继续调用旧API。

二、对象关系如何变化

核心映射：

新模型更接近：

输入Items
→ Response
→ 输出Items

而不是：

创建Run
→ 轮询Run状态
→ 读取Run Steps

三、不要直接照搬Assistant对象

旧Assistant可能包含：

name
instructions
model
tools
metadata
response_format

迁移时要决定哪些内容放到：

• 应用代码；
• Prompt版本；
• 数据库配置；
• 环境变量；
• Tool Registry；
• 策略中心。

不建议继续把全部配置绑定在一个远程持久对象中。

推荐拆分：

Prompt行为
→ Prompt Registry

工具定义
→ Tool Registry

模型与参数
→ Model Routing Policy

权限
→ Application Policy

四、Prompt版本怎么迁移

旧系统可能在Assistant中直接保存instructions。

迁移前导出：

assistant_id
instructions
model
tools
response_format
created_at
updated_at

形成版本：

customer-service:v12
code-review:v7
sales-proposal:v4

每次调用记录：

prompt_key
prompt_version
model
schema_version
tool_set_version

不要只保留“当前Prompt”，否则无法还原历史行为。

五、Thread数据怎么处理

并非所有历史Thread都必须迁移为在线Conversation。

可以分三类：

活跃会话

最近仍在使用，需要继续对话。

迁移方式：

导出最近消息
→ 生成摘要
→ 创建Conversation
→ 写入必要上下文

历史只读会话

用于页面展示和审计，不需要继续调用模型。

迁移到自己的Chat History数据库即可。

无价值实验会话

按保留政策删除或归档。

不要把几年历史全部塞进新Conversation，否则成本和延迟都会失控。

六、消息要迁移为Item思维

Responses API中的Item可能是：

• 用户消息；
• 助手消息；
• 工具调用；
• 工具结果；
• 推理相关输出；
• 文件和多模态内容。

因此，自己的数据库也建议从单一Message表升级为事件结构：

{
  "itemId": "I1001",
  "conversationId": "C9001",
  "itemType": "TOOL_CALL",
  "role": "assistant",
  "payload": {},
  "createdAt": "2026-08-02T08:30:00Z"
}

七、工具循环需要重新验证

旧Assistants链路：

Run进入requires_action
→ 应用执行工具
→ submit_tool_outputs
→ Run继续

Responses架构中，应用应更清晰地处理：

模型返回工具调用Item
→ 校验工具名称与参数
→ 权限判断
→ 审批
→ 执行工具
→ 提交工具结果
→ 继续Response

必须重新验证：

• 多个工具并行；
• 工具失败；
• 工具超时；
• 重复工具调用；
• 幂等；
• 人工审批；
• 工具结果过大；
• 用户取消。

八、工具调用不能只看名称相同

旧Assistant工具定义和新工具定义即使名称相同，Schema也可能不同。

建立版本：

query-order:v3
create-ticket:v5
refund-order:v2

兼容检查：

字段新增是否可选
字段删除是否影响旧Prompt
枚举是否变化
类型是否变化
默认值是否变化

高风险工具迁移时应先只读运行或影子执行。

九、File Search和向量数据怎么迁移

如果旧系统使用：

• File Search；
• Vector Store；
• 文件附件；
• Assistant级资源；

需要建立清单：

assistant_id
vector_store_id
file_id
file_name
checksum
owner
retention

核对：

• 新架构如何引用文件；
• 文件权限是否按会话隔离；
• 旧文件是否仍需要；
• 是否存在重复文件；
• 是否需要重新解析；
• 删除要求是否同步执行。

不要假设“模型配置迁移后，文件自然会跟过去”。

十、结构化输出迁移

旧代码可能使用：

response_format

Responses API的结构化输出定义位置和调用形态与旧接口不同。

迁移时：

保存旧JSON Schema
→ 建立Schema版本
→ 在新API配置结构化输出
→ 本地再次校验
→ 对比新旧成功率

需要覆盖：

• 必填字段；
• 顶层数组；
• 枚举；
• 日期；
• 额外字段；
• 嵌套对象；
• 失败重试。

十一、流式接口不能只验证“能显示文字”

需要验证事件语义：

response.created
output_item.added
content_part.added
tool_call
response.completed
response.failed

客户端状态机应正确处理：

• 文本增量；
• 工具调用增量；
• 连接断开；
• 用户取消；
• 最终Usage；
• 错误事件；
• 重连和重复事件。

不要把所有事件都当成普通Token字符串。

十二、previous_response_id和Conversation怎么选

Responses API可以通过响应关联或Conversation管理上下文。

previous_response_id

适合：

• 简单连续调用；
• 轻量对话；
• 不需要复杂会话管理。

Conversation

适合：

• 长期会话；
• 多类Item；
• 工具轨迹；
• 跨服务；
• 需要会话对象治理。

企业项目仍应独立保存完整Chat History和业务状态，不要把Provider会话对象当唯一数据库。

十三、迁移测试矩阵

至少覆盖：

十四、新旧系统双轨验证

推荐影子模式：

真实请求
→ 旧Assistants API正常服务
→ 同步复制给Responses API
→ 新结果不返回用户
→ 对比结果和轨迹

对比：

任务成功率
结构化输出成功率
工具调用准确率
平均步骤数
P95延迟
Token
成本
安全拦截

不要只比较最终文本相似度。

十五、灰度切换

内部员工
→ 测试租户
→ 1%
→ 10%
→ 30%
→ 50%
→ 100%

每阶段设置退出条件：

错误率高于阈值
工具异常增加
成本超预算
安全事件

一旦触发，自动回退旧链路。

十六、8月执行时间表

8月2日至7日

• 搜索所有旧API调用；
• 导出Assistant配置；
• 分类Thread；
• 建立迁移负责人。

8月8日至14日

• 完成Responses适配层；
• 迁移工具循环；
• 迁移结构化输出；
• 建立影子流量。

8月15日至20日

• 完成File Search和会话迁移；
• 压测；
• 安全测试；
• 灰度生产流量。

8月21日至25日

• 全量切换；
• 保留紧急回滚；
• 停止创建新Assistant；
• 导出最终历史数据。

8月26日

• 确认无旧API流量；
• 关闭旧凭证和定时任务；
• 完成迁移审计。

十七、最容易遗漏的事项

□ 后台脚本仍调用旧API
□ 第三方平台内部依赖Assistants
□ 旧Thread没有导出
□ 工具Schema发生变化
□ File Search权限丢失
□ 流式事件状态机不完整
□ Usage统计口径变化
□ 结构化输出没有回归
□ 新系统没有回滚开关
□ 团队仍在创建新Assistant

总结

Assistants API迁移的本质不是对象名称替换，而是把更多编排责任明确交还给应用：

Prompt版本
＋Conversation与Item
＋工具循环
＋历史裁剪
＋结构化输出
＋重试和评测

距离8月26日关闭日期不足一个月，生产系统应立即进入双轨验证和灰度切换阶段，而不是继续等待最后一周。

延伸阅读

想持续跟踪大模型、AI Agent、RAG、MCP与开发者生态的最新变化，欢迎访问 智元界：

https://www.zyentor.com/

智元界将持续分享AI热点解读、技术实战、工具推荐与企业落地案例。