一句话定义:Assistants API 是 OpenAI 提供的一组“有状态”接口,它把一次 AI 对话拆成三个对象——助手(Assistant)、线程(Thread)、运行(Run),让服务端替你保存对话历史和文件,你只负责发消息、取结果。
三个对象分别在干什么
打个比方,你要开一家客服中心:
- Assistant(助手) 是岗位说明书:用哪个模型、人设和指令怎么写、能用哪些工具(代码解释器、文件检索、自定义函数)。它本身不会说话,只是一份配置。
- Thread(线程) 是某个客户专属的会话记录本。消息(Message)一条条贴进去,用户说的、模型说的都在里面。记录本有 ID,你下次接着用它就行,不用把历史重新贴一遍。
- Run(运行) 是“让这个助手拿着这本记录本干一次活”。你调用一次 Run,服务端就开始跑:读线程里的消息 → 调模型 → 如果模型要求调工具,Run 会停在“需要你提供工具结果”的中间态 → 你把函数返回值交回去 → 继续跑到完成。
所以典型流程是:建助手(一次性)→ 建线程 → 塞用户消息 → 起一个 Run → 轮询或等待它结束 → 从线程里读新消息。同一个线程可以反复起 Run,历史自动累积。
和相邻概念的区别
最容易搞混的是 Chat Completions API。它是无状态的:每次请求你都得把完整对话历史重新打包发过去,服务端不留任何东西。Assistants API 反过来,状态放在服务端,客户端只传 ID。
| 维度 | Chat Completions | Assistants |
|---|---|---|
| 状态 | 无状态,历史自己带 | 有状态,服务端存线程 |
| 一次交互的粒度 | 一次请求 = 一次模型调用 | 一次 Run = 可能多次模型调用 + 多次工具调用 |
| 客户端职责 | 拼上下文、自己跑工具循环 | 只需在 Run 要求时补交工具结果 |
| 适合场景 | 简单问答、自己掌控全流程 | 多轮长会话、带文件、带工具的助手 |
为什么值得理解它
因为它是“把编排搬进服务端”的一次典型尝试。好处很直接:多轮历史、文件上传与检索、工具调用循环这些脏活由平台托管,客户端逻辑变薄。代价是抽象层数变多——助手、线程、运行、消息、运行步骤,调试时要沿着 ID 一层层查,出问题不如“一发一收”那么直观。
后来的 Responses API 某种意义上是在纠偏:重新把“一次调用”当中心,减少对象数量,同时保留工具与状态能力。看懂 Assistants 的三件套,你才能理解那些设计取舍到底在取舍什么——是让平台记住上下文,还是让调用方保持简单可控。
实际建议:如果你只是做一次性问答或需要完全自控的流水线,无状态接口更省心;如果你要做带文件、多轮、多工具的常驻助手,有状态抽象能省不少代码。具体对象字段与能力边界以官方文档页面为准。
