OpenAI官方文档确认Assistants API将在2026年8月26日关闭。迁移并不是把threads.runs.create替换成responses.create就结束Assistant配置、Threads与Messages、Runs与Run steps、工具调用、文件资源以及权限和数据保留都需要逐项核对。本文给出对象映射、Python代码对照和一套先切新会话、再按需回填历史的上线方案。核验日期2026年8月24日。接口、SDK和迁移时间线可能继续调整实施前请再次查看OpenAI官方文档。OpenAI已经在官方迁移指南中明确Assistants API完成弃用并将在2026年8月26日关闭新集成应转向Responses API。如果项目中仍然出现下面这些调用现在需要处理的不是“以后有空再升级”而是确认生产请求是否仍经过旧接口client.beta.assistants.create(...)client.beta.threads.create(...)client.beta.threads.messages.create(...)client.beta.threads.runs.create(...)client.beta.threads.runs.retrieve(...)先澄清一个容易误解的地方这次关闭针对开发者使用的Assistants API不等于ChatGPT网页、普通聊天或ChatGPT Plus订阅在8月26日关闭。一、为什么不能只替换一个接口名称旧Assistants API把多种职责拆成了持久化对象Assistant保存模型、instructions和工具Thread保存会话Message保存消息Run在Thread上执行AssistantRun step记录执行步骤文件、Vector Store和工具资源挂在Assistant或Thread周围。Responses API的心智模型不同。官方迁移表给出的主要变化是旧对象新对象迁移时真正要处理的内容AssistantsPrompts应用配置模型、instructions、工具Schema、输出格式和版本ThreadsConversations会话ID、用户归属、metadata和历史项目MessagesConversation items文本、图片、工具调用与工具输出的类型转换RunsResponses请求执行、状态、错误、输出和用量Run stepsItems消息、工具调用、工具输出不再只看Run step工具与文件重新配置File Search、函数调用、文件ID、Vector Store和权限所以真正的迁移对象不是一行代码而是一整套状态、配置、工具和权限模型。二、第一类先盘点Assistant里的配置每一个生产Assistant至少要导出或记录这些字段assistant_id model instructions tools tool_resources response_format temperature / top_p metadata官方迁移指南将Assistants映射到Prompts可以在控制台把Assistant配置创建为Prompt并通过Prompt ID在Responses请求中引用。但这里不能机械操作。当前官方页面同时提示可复用Prompt对象也有自己的弃用时间线。长期项目在采用Prompt ID前应再次核对该时间线如果选择由应用代码管理配置也要做好版本、审查和回滚不能只把一大段instructions散落在环境变量里。建议建立配置清单Assistant ID业务用途模型工具配置负责人新配置版本asst_xxx客服问答环境变量指定file_search、function后端Aprompt_xxx或Git版本迁移前先回答三个问题哪些Assistant仍有生产流量哪些只是测试对象可以直接停用哪些工具Schema和instructions已经与线上代码不一致三、第二类Threads和Messages不能自动整体搬家官方迁移指南明确说明不会提供把Threads自动迁移为Conversations的工具。推荐做法是让新会话进入Conversations旧Thread仅在确有需要时回填。这意味着数据库至少需要暂时保留一张映射user_id / session_id old_thread_id new_conversation_id migration_status last_active_at不要在截止日前对所有历史Thread做一次无差别全量搬迁。更稳妥的顺序是新建会话全部写入Conversations最近仍活跃的用户在首次访问时按需回填长期不活跃历史只保留必要索引和合规策略无业务价值或不应继续保存的数据按既定删除规则处理。官方示例的核心转换逻辑是按时间顺序读取旧Thread的Messages再转换成Conversation items用户文本映射为input_text助手文本映射为output_text图片等内容则按对应item类型处理。迁移时最容易漏掉的不是纯文本而是Message中的图片与文件附件annotation和文件引用metadata工具调用及工具输出一条消息中包含的多种content类型。如果代码只复制message.content[0].text.value历史会话很可能被截断或丢失结构。四、第三类Runs和Run steps要改成Response与Items思维旧代码通常是创建Run然后不断轮询importtime runclient.beta.threads.runs.create(thread_idthread_id,assistant_idassistant_id,)whilerun.statusin(queued,in_progress):time.sleep(1)runclient.beta.threads.runs.retrieve(thread_idthread_id,run_idrun.id,)Responses API可以直接接收输入并把输出作为items返回。下面是按照官方迁移示例压缩后的基本结构importosfromopenaiimportOpenAI clientOpenAI()conversationclient.conversations.create(items[{role:user,content:请检查这段部署日志中的失败原因,}],metadata{user_id:user_123},)responseclient.responses.create(modelos.environ[OPENAI_MODEL],conversationconversation.id,input[{role:user,content:请给出排查顺序,}],)print(response.output_text)实际项目不能只确认output_text能打印。还要覆盖成功、失败、不完整和取消状态流式输出与断线重连超时与重试是否造成重复执行token用量和请求ID是否继续记录原来依赖Run step的审计页面如何改读Items后台任务是否需要background、webhook或其他异步机制。五、第四类函数调用的工具循环要由应用显式验收官方迁移指南强调Responses中的工具调用循环需要显式管理。旧系统里如果只等待Run进入requires_action再提交工具输出迁移后必须重新检查完整循环模型请求工具 → 应用校验工具名和参数 → 执行业务函数 → 保存幂等键和执行结果 → 把工具输出交回模型 → 获取最终Response重点检查四件事工具参数是否仍经过Schema和业务权限校验同一个调用重试时会不会重复扣款、发消息或创建订单工具输出是否与正确的call ID关联工具失败时模型能否拿到明确、可恢复的错误而不是无限重试。不要因为Responses API代码更短就把原有的权限判断、幂等控制和审计日志一起删掉。六、第五类文件与Vector Store要单独核对文件相关功能最容易被“聊天已经通了”掩盖。至少核对当前项目中有哪些File ID和Vector Store ID哪些文件挂在Assistant哪些挂在Thread或工具资源新请求是否仍能检索到相同资料文件引用和citation能否回到正确来源不同用户能否错误读取彼此的文件历史文件是否还需要保留。不要假设Thread迁成Conversation后所有附件和检索资源会自动跟着迁移。先选一组包含PDF、图片和多轮引用的真实样本逐条验证召回内容与引用位置。七、第六类权限、对象归属和数据保留要重新检查OpenAI官方数据访问说明提醒Assistants、Threads、Messages和Vector Stores按Project划分拥有该Project API key的人可能读取或修改其中对象。因此应用仍应在自己的数据库中维护“哪个终端用户可以访问哪个对象ID”不能把拿到thread_id或conversation_id等同于已经授权。迁移时至少检查API key和Project成员是否最小权限用户、Thread和Conversation的归属映射管理后台是否可能越权查看其他用户内容日志中是否打印完整文件内容、密钥或隐私数据删除流程是否同时覆盖应用数据库和OpenAI对象。数据保留规则也不能沿用想象。OpenAI当前数据控制文档显示Responses API的应用状态默认有30天保留期Assistants相关对象如果没有通过API或控制台删除可能持续保留Assistants相关对象删除后官方说明为30天后从服务器删除。是否使用store、后台模式或特定数据控制方案会影响实际行为。迁移上线前应按组织当前配置再次核对不能把“接口关闭”误解成“历史对象会自动立即清空”。八、推荐的上线顺序先切新会话再迁活跃历史在只剩两天的情况下优先级应是降低生产中断而不是一次完成所有历史清理。阶段1当天完成清点搜索代码中的beta.assistants、beta.threads和runs列出生产Assistant、工具、文件资源和负责人确认哪些入口仍在创建新Thread为旧ID到新ID建立映射字段。阶段2让新会话进入Responses新用户和新会话走ConversationsResponses旧路径保留短期回退开关但不再扩展功能同一组输入同时跑旧、新路径比较答案、工具调用和用量。阶段3按需回填活跃历史优先迁移最近活跃且确实依赖历史的Thread转换所有content类型而不是只复制第一段文本记录回填状态失败可重试且不能重复插入。阶段4验收与收尾关闭旧接口入口保留可审计的迁移清单按数据政策删除不再需要的旧对象在8月26日前做一次生产流量和错误率确认。九、上线前最小验收表检查项通过标准新会话不再创建Thread能够持续写入Conversation普通回复文本、结构化输出和流式结果正常工具调用参数校验、权限、幂等和失败回传正常文件检索召回内容、文件引用和用户隔离正确历史会话活跃Thread能按需回填顺序与角色不乱监控错误率、延迟、用量、请求ID和工具失败可追踪回退新路径异常时有受控回退不产生双写脏数据数据保留、删除、日志脱敏和对象授权符合现有政策十、几个常见问题1. 8月26日后ChatGPT Plus还能正常使用吗这次通知针对Assistants API。不要把开发者接口关闭扩写成ChatGPT网页或Plus订阅关闭。2. 只使用Chat Completions API需要迁移吗本次关闭对象是Assistants API。如果代码没有创建Assistant、Thread或Run不能仅凭这则通知判断必须迁移但新Agent类集成可以单独评估Responses API。3. Threads会自动变成Conversations吗不会。官方迁移指南明确表示不会提供自动迁移工具建议新会话先切换旧会话按需回填。4. 旧Thread里的文件会自动进入Conversation吗不要这样假设。消息内容、附件、文件资源和检索配置需要分别清点和验证。5. 迁移后还需要轮询吗不能简单回答“完全不需要”。普通Response可以直接返回结果但流式、后台任务、工具循环和长任务仍要按实际模式设计状态、重试和通知机制。结语Assistants API迁移最危险的误区是把它当成一次SDK方法改名。真正需要核对的是六类对象Assistant配置、Threads与Messages、Runs与Run steps、工具调用、文件资源、权限与数据保留。距离8月26日只剩很短时间时最稳妥的策略不是全量搬历史而是先让新会话切到ConversationsResponses再按业务价值迁移活跃历史最后清理旧对象。这样既能先降低停机风险也能避免在仓促全量迁移中丢失消息结构、工具记录和用户权限。官方资料OpenAIAssistants API迁移指南OpenAIAssistants API deep diveOpenAI数据控制与端点保留规则