Assistants API 开发指南

最后更新：2026-08-12· 17 分钟阅读

🚀 快速通道

ChatGPT 国内版：点击直达↗
稳定镜像站：打开镜像↗
官方 ChatGPT：chatgpt.com ↗

Assistants API 开发指南

更新时间：2026-08-12

导读

Assistants API 用 Assistant + Thread + Run 提供有状态对话，内置 Code Interpreter、File Search 等工具，适合快速验证「带文件的知识库机器人」。平台演进中，Responses API 与 Agents SDK 可能是新项目更长期的路径；Assistants 可能处于维护或迁移期——立项与续维护前务必读官方文档的 deprecation / migration 说明。

重要： 若官方标记 Assistants 为 legacy，新项目勿默认选型；存量项目按迁移指南规划。下文 endpoint 与对象以 API reference 为准；model 为示例 ID。

核心对象模型

Assistant（配置：instructions / model / tools）
    │
Thread（会话容器）
    └── Messages
         │
Run（一次执行：queued → in_progress → completed）

对象	职责	你通常持久化
Assistant	人设与工具配置	`assistant_id`
Thread	多轮历史	每用户 `thread_id`
Message	单条输入/输出	可选本地镜像
Run	一次模型执行	轮询 / webhook
File / Vector Store	检索素材	文件 id 列表

对比无状态 API：Chat Completions / Responses 由你维护 messages[]；Assistants 由 OpenAI 存 Thread——便利但有 vendor 绑定与计费维度差异。

新项目 vs 存量：怎么选

情况	建议
文档 Quickstart 指向 Responses	读 Responses API 指南，勿新上 Assistants
已有 Thread + Vector Store 投产	维护 + 制定迁移计划
POC 验证文件问答	Assistants 上手快；POC 后评估长期方案
多租户、细粒度 RAG 控制	倾向 embeddings + Completions / Responses

三步 curl 流程（形状示例）

1. 创建 Assistant

curl https://api.openai.com/v1/assistants \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "name": "policy-bot",
    "instructions": "只根据检索文件回答；资料不足则说明未找到。",
    "model": "gpt-4o-mini",
    "tools": [{"type": "file_search"}]
  }'

2. 创建 Thread 并加消息

curl https://api.openai.com/v1/threads \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{
    "messages": [{"role": "user", "content": "手册里退货窗口是几天？"}]
  }'

3. 创建 Run

curl https://api.openai.com/v1/threads/thread_abc/runs \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -H "OpenAI-Beta: assistants=v2" \
  -d '{"assistant_id": "asst_abc"}'

生产应：

轮询 GET /threads/{id}/runs/{run_id} 或官方 streaming / webhook
处理 requires_action（提交 function output）
设 Run 超时与失败重试

File Search 工作流

POST /v1/files 上传（purpose 以文档为准）
创建 Vector Store 并关联 Assistant
用户提问 → Run → 模型经 file_search 取片段

实践	说明
文件版本	更新后重建索引；清理旧 vector
多租户	勿共用 Assistant 存机密文件
评测	「文档有」与「文档无」两类 case

自建 RAG：Embeddings 指南 + Chat Completions / Responses。

Code Interpreter 注意

适合数据分析 POC；生产需评估沙箱安全、成本、可重复性。
勿传入含密钥、PII 的数据。
若允许下载输出文件，做大小限制与扫描。

迁移至 Responses / Agents SDK

能力	Assistants	Responses / Agents
有状态会话	Thread 内置	自管 session 或 SDK
工具	内置 + functions	统一 tools（查文档）
长期支持	可能弱化	Quickstart 倾向

通用迁移步骤（以官方 migration guide 为准）：

instructions → system 模板（Prompt Engineering）
file_search → 自建 vector 或官方新方案
Thread 历史 → 导入 DB 或摘要冷启动
dual-write 评测后切流量

计费与监控

Run 消耗 model token；file_search、code_interpreter 可能有附加计费。
轮询不产生 token，但频繁轮询占 QPS。
按 assistant_id、Run 状态聚合失败率。

生产清单（若继续使用）

确认 API 版本未 sunset（如 OpenAI-Beta: assistants=v2）
租户级 Assistant / Vector Store 隔离
Run 超时与用户降级文案
requires_action 路径测试覆盖
迁移预案链到 Responses API

常见问题

新项目还能上 Assistants 吗？

先看官方文档。 若 legacy 或推荐 Responses，新项目不应默认 Assistants。

Thread 数据存多久？

以 OpenAI 数据政策为准；合规业务应自行备份关键会话。

能当「免费 ChatGPT」后端吗？

不行。按 API 计费；Run + 工具可能更贵；ChatGPT 订阅不覆盖。

file_search vs 自建 RAG？

Assistants 上手快；自建 RAG 多租户与成本可控性更好。

Run 一直 in_progress？

可能工具执行久或排队；设超时，查 status 页，必要时 cancel 并重试。

官方资源

下一步阅读

行动路径

今天：在官方文档确认 Assistants 状态（active / legacy / migration）。明天：存量项目列出全部 assistant_id 与文件依赖。本周：5 条问答建迁移评测集，对照 Responses Quickstart 估改造成本。

导读