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 估改造成本。

導讀