OpenAI Assistants API 2026 年 8 月 26 日 Sunset：如何迁移 Responses API？

8 月 26 日到底关什么

被关闭的是整个 Assistants 平台，不是某一个模型。Assistant 配置（instructions、tools、model 绑定）、Thread 里累积的消息、Run 及其 steps——这些对象在 sunset 之后都无法再通过 API 读写。Chat Completions 不在此次下线范围内；Realtime API 也不受影响。容易误判的是：代码里仍 import OpenAI 客户端、仍用 gpt-4o，但只要路径还在 beta.threads 或 beta.assistants，8 月 27 日就会整段挂掉。

OpenAI 没有提供 Thread → Conversation 的自动迁移工具。官方文档写明：现有 Thread 历史需要你自己 iterate messages，按 Conversations API 的 item 类型写回。Vector store 与已上传文件则继续可用——file_search 在 Responses API 里仍引用 vs_ 开头的 ID，不必重新上传索引。

时间线要记两个日期：2025-08-26 公告与一年迁移期；2026-08-26 硬下线。GPT-5 等新模型已只走 Responses API，继续押在 Assistants 上等于同时承担「协议死亡」和「模型够不着」两层风险。

对象映射：Assistants → Responses

官方迁移指南用一张对照表描述概念迁移。纸面上名字一一对应，工程上职责变了：

Assistants 把「配置」和「会话」都托管在 OpenAI 侧，很多团队从未把 thread_id 当成一等公民建模。迁移后 Conversations API 仍托管状态，但你要显式创建 conversation_id、决定何时归档、以及 Thread 数据不会自动出现。若业务依赖「2024 年某条 thread 里的客服记录」，sunset 前必须导出或回填。

详细对象说明见 OpenAI 文档Migrate to the Responses API 与 Conversations API。

心智模型：从轮询 Run 到一次 Response

Assistants 典型流程：create thread → add message → create run → while status in queued/in_progress → list messages。网络往返多、失败面在 run_id 与 step 上，调试时要对照 run steps 与 message 顺序。Responses API 把「这次模型调用」收成单一 API：input（字符串或 item 数组）、instructions、tools、previous_response_id 或 conversation 绑定，都在同一请求里。

Stateful 并没有消失，而是从「隐式 Thread」变成「显式 Conversation 或 previous_response_id 链」。多轮 Agent 仍可把 tool output 作为下一跳的 input items 传回，只是不再创建 Run 对象。Streaming 时读 response.output 事件即可，不必再 poll。

对 JSON 流水线而言，最大的利好是 Structured Output 在 Responses API 是一等公民：text.format 下挂 json_schema，规则与 Chat Completions 的 response_format 相同，只是外壳字段名不同。站内AI Structured Output 教程已按 Chat Completions 讲过 json_schema + strict；迁到 Responses 时把同一 Schema 挪到 text.format 即可，本地校验流程不变。

迁移清单与 Thread 历史

建议按下面顺序做，避免漏网之鱼：

• 代码库 grep：beta.threads、beta.assistants、/v1/threads、/v1/assistants、OpenAI-Beta.*assistants、run_steps、create_and_poll
• 盘查数据库与环境变量里的 assistant_id、thread_id；标记哪些 thread 仍活跃、哪些可归档
• Sunset 前对必须保留的 thread 写导出脚本：list messages → 转成 Conversations items → conversations.create + items.create
• 把 instructions 与 tools 从 Assistant 对象迁到代码常量、配置中心或 Prompt 管理——长期不建议绑 Dashboard Prompt（2026-11-30 弃用）
• 用 staging 跑通一条 responses.create（含 file_search 或 function tool），对比旧 Assistants 输出；JSON 结果用 JSONVue 做格式化与 Schema 校验
• 删除所有 run polling 与 run_id 持久化；改为存 response.id 或 conversation.id

Thread 回填不是 copy-paste：Thread 只存 role/content 消息，Conversation items 还要容纳 tool_call、tool_result 等类型。若历史里只有 user/assistant 文本，映射相对直接；若跑过 code_interpreter 或 file_search，要按官方 item schema 补全 type 字段。

代码对照：旧 Assistants 与新 Responses

旧式 Assistants（8 月 26 日后报错）大致如下：

thread = client.beta.threads.create()
client.beta.threads.messages.create(
    thread_id=thread.id,
    role="user",
    content="Summarize ticket #8842 for billing.",
)
run = client.beta.threads.runs.create_and_poll(
    thread_id=thread.id,
    assistant_id="asst_abc123",
)
messages = client.beta.threads.messages.list(thread_id=thread.id)

等价 Responses 调用把 instructions 与 tools 内联，并用 previous_response_id 或 conversation 维持多轮：

response = client.responses.create(
    model="gpt-4o",
    instructions="You are a billing assistant.",
    input="Summarize ticket #8842 for billing.",
    tools=[{"type": "file_search", "vector_store_ids": ["vs_abc123"]}],
    # previous_response_id="resp_..."  # or conversation="conv_..."
)
print(response.output_text)

注意：function 工具在 Responses 里返回的仍是结构化 item；arguments 是 JSON 字符串时，执行层仍要 JSON.parse + Schema 校验——与Stateless MCP文里讲的 tools/call 参数校验是同一类问题。

工具、文件搜索与 Structured Output

Vector store ID（vs_…）可继续用于 Responses 的 file_search 工具，无需重新 embedding。已上传文件与 Assistants 时代共用同一套 Files API。code_interpreter 在 Responses 侧以内置 tool 形式提供，配置方式与 Assistants 不同，需对照最新 tool 文档逐项迁移。

若最终答复需要固定 JSON 形状，在 Responses 请求里使用 Structured Output，而不是在 instructions 里重复写字段表。示例片段：

response = client.responses.create(
    model="gpt-4o-2024-08-06",
    input=[{"role": "user", "content": "Extract ticket fields."}],
    text={
        "format": {
            "type": "json_schema",
            "name": "support_ticket",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "summary": {"type": "string"},
                    "category": {
                        "type": "string",
                        "enum": ["billing", "bug", "other"],
                    },
                },
                "required": ["summary", "category"],
                "additionalProperties": False,
            },
        }
    },
)

响应体里按 output item 取 text；整段即为 JSON 字符串时，走 JSON.parse → 本地 Schema 二次校验。迁移期建议双写对比：同一 prompt 在 sunset 前用 Assistants 跑一次、staging 用 Responses 跑一次，用JSON Diff看键名是否漂移。

延伸阅读：AI Structured Output 教程、DeepSeek V4-Flash 与 JSON 输出、Stateless MCP 解析。

常见问题 FAQ

总结与下一步

Assistants API sunset 是一次架构切换：四个服务端对象合并成 Responses + Conversations，Run 轮询消失，Thread 历史不会自动跟过来。Vector store 可复用，Structured Output 的 JSON Schema 契约可平移。真正的工作量在于找出所有 thread/assistant 依赖、回填必要历史、重写 orchestration。

下一步：grep 代码库确认无遗漏，在 staging 用 responses.create 跑通主流程，并把模型 JSON 贴进 JSONVue 校验。需要对比 Schema 约束时阅读 Structured Output 教程；需要 Remote 工具协议时阅读 Stateless MCP 文。