文章摘要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。二、对象关系如何变化核心映射Assistants APIResponses API方向说明AssistantPrompt或应用配置模型、指令、工具配置ThreadConversation由Item组成的会话流MessageInput/Output Item不再局限于普通消息RunResponse一次模型执行Run StepItem消息、工具调用、工具结果等submit_tool_outputs显式工具循环应用负责继续提交结果新模型更接近输入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 SearchVector Store文件附件Assistant级资源需要建立清单assistant_id vector_store_id file_id file_name checksum owner retention核对新架构如何引用文件文件权限是否按会话隔离旧文件是否仍需要是否存在重复文件是否需要重新解析删除要求是否同步执行。不要假设“模型配置迁移后文件自然会跟过去”。十、结构化输出迁移旧代码可能使用response_formatResponses 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会话对象当唯一数据库。十三、迁移测试矩阵至少覆盖场景必测内容普通问答文本一致性多轮会话上下文连续性File Search引用和权限单工具参数和结果多工具顺序、并行、失败结构化输出Schema成功率流式事件、取消、错误长任务超时和恢复安全注入、越权、泄露成本Token和调用数量十四、新旧系统双轨验证推荐影子模式真实请求 → 旧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日关闭日期不足一个月生产系统应立即进入双轨验证和灰度切换阶段而不是继续等待最后一周。