OpenAI Assistants API：线程、文件、代码解释器——以及你现在需要的迁移

首先，重要状态更新：OpenAI 已弃用 Assistants API，转而支持 Responses API——在 Responses API 达到功能对等后，OpenAI 宣布了 Assistants API 的日落（迁移窗口至 2026 年）。如果你是新项目：请基于 Responses API 构建。如果你在生产环境中运行 Assistants：本指南涵盖了你已有的内容、映射关系以及如何在不丢失你采用它的功能（线程、文件搜索、代码解释器）的情况下进行迁移。

Assistants API 提供了什么（以及为什么人们使用它）

其卖点是*托管状态*：无需每次调用重新发送对话历史，你可以创建一个 Assistant（指令 + 模型 + 工具），为每个用户打开一个 Thread，追加 Messages，并触发 Runs。OpenAI 持久化对话，自动截断上下文，并托管了两个杀手级工具：

File Search —— 将文档上传到向量存储；助手自动检索相关块（托管 RAG，无需构建管道）

Code Interpreter —— 一个沙盒 Python 运行时，用于数据分析、文件处理和图表生成

这种便利正是 Responses API 现在以更简洁的设计提供的。

迁移映射表

Assistants 概念Responses API 等价物

Assistant 对象（指令/模型/工具）代码中的提示/配置（或存储的提示）；每个请求声明工具 Thread + Messagesprevious_response_id 链式调用（服务端状态）或自行传递消息 Run / run 轮询已消失——响应*就是*结果；无需轮询循环 File Search + 向量存储相同的 file_search 工具，相同的向量存储——直接沿用 Code InterpreterResponses 下的相同工具 函数调用相同概念，更简洁的线缆格式

最大的胜利：笨拙的 create-run-then-poll 循环消失了。Assistants 让你创建运行并轮询其状态，而 Responses 直接返回（或流式传输）答案：

python
from openai import OpenAI
client = OpenAI()
托管 RAG，Responses 风格
resp = client.responses.create(
    model='gpt-5',
    input='我们的退款政策对部分退款有什么规定？',
    tools=[{'type': 'file_search', 'vector_store_ids': [VECTOR_STORE_ID]}],
)
print(resp.output_text)
多轮对话：通过 ID 链式调用，而不是管理线程对象
followup = client.responses.create(
    model='gpt-5',
    previous_response_id=resp.id,
    input='具体到数字商品呢？',
)

python
Code Interpreter，Responses 风格
resp = client.responses.create(
    model='gpt-5',
    input='分析附件的 CSV：月度收入趋势 + 一张图表。',
    tools=[{'type': 'code_interpreter', 'container': {'type': 'auto', 'file_ids': [file_id]}}],
)

实际可行的迁移计划

盘点你实际使用的 Assistants 功能。 大多数应用使用线程 + 一个工具；小众功能（运行步骤检查、每次运行模型覆盖）较少见，需要单独映射。

向量存储直接沿用 —— 你上传/索引的文件无需重新导入；将 file_search 指向相同的存储 ID。

用响应链替换线程生命周期 —— 在你之前存储线程 ID 的地方，存储每个用户最新的 response_id。（决定你的保留策略：链式调用将状态存储在 OpenAI；自行传递完整消息则将状态保留在你的数据库中。）

删除轮询代码。 流式传输取代了它；你的延迟会免费改善。

在标志后同时运行两条路径 一个发布周期，在实际流量上对比输出，然后在日落日期前切换。

请查阅 OpenAI 官方迁移指南以获取当前日落时间线——日期之前有过变动。

更大的教训

Assistants→Responses 的转变提醒我们，托管状态 API 是供应商表面，而非标准——值得在你的服务层背后进行抽象，这样下一次迁移就只是模块变更，而不是应用重写。如果你无论如何都要重建，这是一个评估替代方案的自然时机：自托管 RAG（pgvector + 语义搜索）以获得控制权，框架编排（LangGraph）用于复杂代理，或者如果你正在多样化供应商，Claude API 的等价物。

FAQ

我必须立即迁移吗？ 不——有一个弃用窗口，期间继续提供支持。但新功能只会在 Responses 上发布，所以等待的成本会累积。

Responses 更便宜吗？ 相同的每 token 模型定价；你节省了浪费的轮询调用，并获得了提示缓存友好的模式。工具使用（文件搜索存储、代码解释器会话）计费类似——请查看定价页面确认费率。

我构建的 ChatGPT "GPTs" 呢？ 不同的产品表面（消费者 ChatGPT），不受此 API 迁移影响。

---

*最后更新：2026 年 6 月。请对照 OpenAI 官方文档验证当前的弃用时间线和 Responses API 参数——这个过渡有变动的日期。*