openai-assistants

OpenAI Assistants API v2

状态：已可用于生产环境（已弃用，2026 年上半年） | 软件包：[email protected] 最后更新：2025-11-21 | v2 停用时间：2026 年上半年

---

⚠️ 重要：弃用通知

OpenAI 宣布将弃用 Assistants API，转而采用 Responses API。

时间线：

• ✅ 2024 年 12 月 18 日：Assistants API v1 已弃用
• ⏳ 2026 年上半年：计划停用 Assistants API v2
• ✅ 现在：Responses API 已推出（推荐新项目使用）

你还应该使用此技能吗？

• ✅ 是，如果：你已有 Assistants API 代码（有 12–18 个月的迁移窗口）
• ✅ 是，如果：你需要维护旧版应用
• ✅ 是，如果：计划从 Assistants 迁移到 Responses
• ❌ 否，如果：你要启动新项目（请改用 openai-responses 技能）

**迁移路径：**完整迁移指南请参阅 references/migration-to-responses.md。

---

快速入门（5 分钟）

1. 安装

bun add [email protected]  # preferred
# or: npm install [email protected]

2. 环境设置

export OPENAI_API_KEY="sk-..."

3. 基本助手

import OpenAI from 'openai'

const openai = new OpenAI({ apiKey: process.env.OPENAI_API_KEY })

// 1. Create an assistant
const assistant = await openai.beta.assistants.create({
  name: "Math Tutor",
  instructions: "You are a helpful math tutor. Answer math questions clearly.",
  model: "gpt-4-1106-preview",
})

// 2. Create a thread (conversation)
const thread = await openai.beta.threads.create()

// 3. Add a message
await openai.beta.threads.messages.create(thread.id, {
  role: "user",
  content: "What is 12 * 34?",
})

// 4. Create and poll run
const run = await openai.beta.threads.runs.createAndPoll(thread.id, {
  assistant_id: assistant.id,
})

// 5. Get messages
if (run.status === 'completed') {
  const messages = await openai.beta.threads.messages.list(thread.id)
  console.log(messages.data[0].content[0].text.value)
}

重要：

• Assistant 是持久化的（存储在服务端）
• Thread 是持久化的（保留对话历史）
• Run 会在 Thread 上执行 Assistant
• 始终轮询或流式传输 Run（它们是异步的）
• 为简化操作，请使用 createAndPoll；如需实时响应，请使用流式传输

---

核心概念

4 个关键对象：

1. Assistant = 带有指令和工具的 AI Agent
2. Thread = 对话（保留消息）
3. Message = Thread 中的单条消息（用户或助手）
4. Run = 在 Thread 上执行 Assistant

生命周期：

Assistant (create once) + Thread (per conversation) + Message (add user input) → Run (execute) → Messages (get response)

完整的架构、对象、工作流和定价详情，请加载 references/assistants-api-v2.md。

---

关键规则

务必做到

✅ 轮询或流式传输 Run——Run 是异步的，不要假设它会立即完成 ✅ 检查 Run 状态——处理 requires_action、failed、cancelled、expired ✅ 处理函数调用——当状态为 requires_action 时提交工具输出 ✅ 存储 Thread ID——在多轮对话中重复使用 Thread ✅ 设置超时——大型文件的向量存储索引可能需要几分钟 ✅ 验证文件上传——检查支持的格式和大小限制 ✅ 使用结构化指令——为 Assistant 提供清晰、具体的指令 ✅ 处理速率限制——实现指数退避 ✅ 清理未使用的资源——删除旧的 Assistant/Thread，以节省费用 ✅ 使用最新的 API 版本——Assistants API v2（v1 已于 2024 年 12 月弃用）

切勿

❌ 切勿跳过 Run 轮询——Run 不会立即完成 ❌ 切勿重复使用 Run ID——每次交互都要创建新的 Run ❌ 切勿假设文件索引会立即完成——向量存储需要时间 ❌ 切勿忽略 requires_action 状态——函数调用需要你作出响应 ❌ 切勿硬编码 Assistant ID——使用环境变量 ❌ 切勿每次请求都创建新的 Assistant——重复使用 Assistant ❌ 切勿超出文件限制——每个向量存储最多 10,000 个文件，每个文件最大 10GB ❌ 切勿在生产环境中使用 Code Interpreter——请改用沙盒执行 ❌ 切勿跳过错误处理——API 调用可能失败 ❌ 切勿使用 Assistants API 启动新项目——请改用 Responses API

---

预防 5 大错误

此技能可预防 15 个已记录的错误。以下是排名前 5 的错误：

错误 #1：“Thread 已有活动 Run”

错误：Can't create run: thread_xyz already has an active run 预防方法：创建新的 Run 前，检查是否有活动 Run：

// Get runs and check status
const runs = await openai.beta.threads.runs.list(thread.id)
const activeRun = runs.data.find(r => ['in_progress', 'queued'].includes(r.status))

if (activeRun) {
  // Cancel or wait
  await openai.beta.threads.runs.cancel(thread.id, activeRun.id)
}

// Now create new run
const run = await openai.beta.threads.runs.create(thread.id, {...})

参见：references/top-errors.md #1

错误 #2：向量存储索引超时

错误：文件上传后立即搜索，结果为空 预防方法：等待索引完成：

// Upload file
const file = await openai.files.create({
  file: fs.createReadStream('document.pdf'),
  purpose: 'assistants',
})

// Add to vector store
await openai.beta.vectorStores.files.create(vectorStore.id, {
  file_id: file.id,
})

// Wait for indexing (poll file_counts)
let vs = await openai.beta.vectorStores.retrieve(vectorStore.id)
while (vs.file_counts.in_progress > 0) {
  await new Promise(resolve => setTimeout(resolve, 1000))
  vs = await openai.beta.vectorStores.retrieve(vectorStore.id)
}

参见：references/top-errors.md #2

错误 #3：Run 状态轮询陷入无限循环

错误：轮询一直无法终止，永久挂起 预防方法：添加超时和终止状态检查：

const maxAttempts = 60 // 60 seconds
let attempts = 0

while (attempts < maxAttempts) {
  const run = await openai.beta.threads.runs.retrieve(thread.id, run.id)

  if (['completed', 'failed', 'cancelled', 'expired', 'requires_action'].includes(run.status)) {
    break
  }

  await new Promise(resolve => setTimeout(resolve, 1000))
  attempts++
}

if (attempts >= maxAttempts) {
  throw new Error('Run polling timeout')
}

参见：references/top-errors.md #3

错误 #4：函数调用未提交

错误：运行永久卡在 requires_action 状态 预防措施：需要时提交工具输出：

const run = await openai.beta.threads.runs.createAndPoll(thread.id, {
  assistant_id: assistant.id,
})

if (run.status === 'requires_action') {
  const toolCalls = run.required_action.submit_tool_outputs.tool_calls

  const toolOutputs = toolCalls.map(call => ({
    tool_call_id: call.id,
    output: JSON.stringify(executeTool(call.function.name, call.function.arguments)),
  }))

  await openai.beta.threads.runs.submitToolOutputsAndPoll(thread.id, run.id, {
    tool_outputs: toolOutputs,
  })
}

参见：references/top-errors.md #4

错误 #5：不支持文件上传格式

错误：Invalid file format for Code Interpreter 预防措施：上传前验证文件格式：

const supportedFormats = {
  code_interpreter: ['.c', '.cpp', '.csv', '.docx', '.html', '.java', '.json', '.md', '.pdf', '.php', '.pptx', '.py', '.rb', '.tex', '.txt', '.css', '.js', '.sh', '.ts'],
  file_search: ['.c', '.cpp', '.docx', '.html', '.java', '.json', '.md', '.pdf', '.php', '.pptx', '.py', '.rb', '.tex', '.txt', '.css', '.js', '.sh', '.ts'],
}

const fileExtension = path.extname(filePath)

if (!supportedFormats.code_interpreter.includes(fileExtension)) {
  throw new Error(`Unsupported file format: ${fileExtension}`)
}

// Now safe to upload
const file = await openai.files.create({
  file: fs.createReadStream(filePath),
  purpose: 'assistants',
})

参见：references/top-errors.md #5

完整错误目录（共 15 个错误）：参见 references/top-errors.md

---

常见用例

用例 1：简单问答聊天机器人

模板：templates/basic-assistant.ts | 耗时：10 分钟

const assistant = await openai.beta.assistants.create({
  name: "Support Bot",
  instructions: "Answer customer questions professionally.",
  model: "gpt-4-1106-preview",
})
// Per conversation: create thread → add message → run → get response

用例 2：基于 RAG 的文档问答

模板：templates/file-search-assistant.ts | 耗时：30 分钟 参考资料：加载 references/file-search-rag-guide.md 和 references/vector-stores.md，了解完整实现。

用例 3：代码执行助手

模板：templates/code-interpreter-assistant.ts | 耗时：20 分钟 参考资料：加载 references/code-interpreter-guide.md，了解设置、替代方案和故障排除。

用例 4：函数调用助手

模板：templates/function-calling-assistant.ts | 耗时：25 分钟

用例 5：流式聊天机器人

模板：templates/streaming-assistant.ts | 耗时：15 分钟

---

何时加载详细参考资料

在以下情况下加载 references/assistants-api-v2.md：

• 用户需要完整的 API 参考
• 用户询问特定端点或参数
• 用户需要速率限制信息或配额
• 用户想了解架构详情

在以下情况下加载 references/code-interpreter-guide.md：

• 用户正在实现代码执行
• 用户询问 Code Interpreter 支持的文件格式
• 用户需要 Code Interpreter 的替代方案（E2B、Modal）
• 用户遇到 Code Interpreter 错误

在以下情况下加载 references/file-search-rag-guide.md：

• 用户正在构建 RAG 应用
• 用户询问向量存储的设置
• 用户需要文件搜索优化策略
• 用户需要将文档搜索扩展到基础设置之外

在以下情况下加载 references/migration-from-v1.md：

• 用户提到 Assistants API v1
• 用户要从 v1 升级到 v2
• 用户询问不兼容的变更（retrieval → file_search）
• 用户遇到 v1 弃用错误

在以下情况下加载 references/migration-to-responses.md：

• 用户计划将来迁移到 Responses API
• 用户询问 Responses API 的对比信息
• 用户提到弃用时间线
• 用户正在构建新项目（建议使用 Responses API）

在以下情况下加载 references/thread-lifecycle.md：

• 用户正在构建多轮对话
• 用户询问线程持久化模式
• 用户需要对话管理策略
• 用户要优化线程使用或清理

在以下情况下加载 references/top-errors.md：

• 用户遇到任何错误（已记录全部 15 个）
• 用户询问故障排除
• 用户想预防已知问题
• 用户正在调试生产环境问题

在以下情况下加载 references/vector-stores.md：

• 用户要将文件搜索扩展到基础设置之外
• 用户询问文件数量限制（10,000 个文件）
• 用户需要优化索引
• 用户要管理向量存储成本（$0.10/GB/天）

---

可用模板

templates/ 中的生产就绪代码示例：

• basic-assistant.ts - 最简助手设置（快速入门）
• code-interpreter-assistant.ts - 代码执行（Python 代码运行器）
• file-search-assistant.ts - 文档问答（RAG 应用）
• function-calling-assistant.ts - 外部工具（API 集成）
• streaming-assistant.ts - 实时响应（流式输出）
• thread-management.ts - 多轮对话（聊天机器人）
• vector-store-setup.ts - 向量存储配置（文件搜索设置）
• package.json - 依赖项（项目设置）

---

依赖项

必需：

• [email protected] - OpenAI Node.js SDK

可选：

• fs - 文件系统操作（内置）
• path - 路径实用工具（内置）

---

官方文档

• Assistants API：https://platform.openai.com/docs/assistants/overview
• API 参考：https://platform.openai.com/docs/api-reference/assistants
• Responses API：https://platform.openai.com/docs/guides/responses（推荐用于新项目）
• 迁移指南：https://platform.openai.com/docs/guides/migration
• 社区论坛：https://community.openai.com/

---

软件包版本（已于 2025-10-25 验证）

{
  "dependencies": {
    "openai": "^6.7.0"
  }
}

版本说明：

• OpenAI SDK 6.7.0 是最新稳定版本
• 支持 Assistants API v2
• Assistants API v1 已于 2024 年 12 月 18 日弃用
• Assistants API v2 计划于 2026 年上半年停止服务

---

生产环境示例

此技能基于生产环境中的实际使用：

• 节省 Token：相比手动实现约节省 60%
• 避免的错误：记录了 15 个问题
• 设置时间：基础聊天机器人少于 30 分钟
• 验证结果：✅ 文件搜索正常运行，✅ 流式传输正常，✅ 函数调用已测试

---

完整设置清单

• 已安装 [email protected]
• 已设置 OPENAI_API_KEY 环境变量
• 已创建至少一个助手
• 已测试线程创建和消息添加
• 已实现运行轮询或流式传输
• 已处理 requires_action 状态（如使用函数调用）
• 已测试文件上传（如使用 Code Interpreter 或 File Search）
• 已为所有 API 调用实现错误处理
• 已存储线程 ID，以便持久化对话
• 已规划迁移到 Responses API（适用于新项目）
• 已设置速率限制监控
• 已实现未使用资源的清理

---

有疑问？遇到问题？

1. 查看官方文档：https://platform.openai.com/docs/assistants/overview
2. 查看 references/top-errors.md，了解记录的全部 15 个错误
3. 查看 templates/，获取可用于生产环境的代码示例
4. 查看 references/migration-to-responses.md，为未来做好准备
5. 加入社区：https://community.openai.com/

---

⚠️ 提醒：此 API 已弃用。新项目请改用 Responses API。迁移指南请参阅 references/migration-to-responses.md。