OpenAI Assistants API 8月26日关闭：迁移到Responses API前先核对这6类对象

浩风祭月

329人浏览 · 2026-08-24 10:42:23

浩风祭月 · 2026-08-24 10:42:23 发布

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上执行Assistant；
Run step记录执行步骤；
文件、Vector Store和工具资源挂在Assistant或Thread周围。

Responses API的心智模型不同。官方迁移表给出的主要变化是：

旧对象	新对象	迁移时真正要处理的内容
Assistants	Prompts／应用配置	模型、instructions、工具Schema、输出格式和版本
Threads	Conversations	会话ID、用户归属、metadata和历史项目
Messages	Conversation items	文本、图片、工具调用与工具输出的类型转换
Runs	Responses	请求执行、状态、错误、输出和用量
Run steps	Items	消息、工具调用、工具输出不再只看Run step
工具与文件	重新配置	File Search、函数调用、文件ID、Vector Store和权限

所以真正的迁移对象不是一行代码，而是一整套状态、配置、工具和权限模型。

迁移到Responses API前先核对这6类对象

二、第一类：先盘点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	后端A	`prompt_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，然后不断轮询：

import time

run = client.beta.threads.runs.create(
    thread_id=thread_id,
    assistant_id=assistant_id,
)

while run.status in ("queued", "in_progress"):
    time.sleep(1)
    run = client.beta.threads.runs.retrieve(
        thread_id=thread_id,
        run_id=run.id,
    )

Responses API可以直接接收输入，并把输出作为items返回。下面是按照官方迁移示例压缩后的基本结构：

import os
from openai import OpenAI

client = OpenAI()

conversation = client.conversations.create(
    items=[
        {
            "role": "user",
            "content": "请检查这段部署日志中的失败原因",
        }
    ],
    metadata={"user_id": "user_123"},
)

response = client.responses.create(
    model=os.environ["OPENAI_MODEL"],
    conversation=conversation.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

新用户和新会话走Conversations＋Responses；
旧路径保留短期回退开关，但不再扩展功能；
同一组输入同时跑旧、新路径，比较答案、工具调用和用量。

阶段3：按需回填活跃历史

优先迁移最近活跃且确实依赖历史的Thread；
转换所有content类型，而不是只复制第一段文本；
记录回填状态，失败可重试且不能重复插入。

阶段4：验收与收尾

关闭旧接口入口；
保留可审计的迁移清单；
按数据政策删除不再需要的旧对象；
在8月26日前做一次生产流量和错误率确认。

九、上线前最小验收表

检查项	通过标准
新会话	不再创建Thread，能够持续写入Conversation
普通回复	文本、结构化输出和流式结果正常
工具调用	参数校验、权限、幂等和失败回传正常
文件检索	召回内容、文件引用和用户隔离正确
历史会话	活跃Thread能按需回填，顺序与角色不乱
监控	错误率、延迟、用量、请求ID和工具失败可追踪
回退	新路径异常时有受控回退，不产生双写脏数据
数据	保留、删除、日志脱敏和对象授权符合现有政策