OpenAI Assistants API：生产工程指南

何时使用 Assistants API 与 Chat Completions

场景使用 Assistants API使用 Chat Completions

带记忆的多轮对话✅手动实现 文件分析（PDF、数据）✅ 内置手动 RAG 设置 代码执行✅ 内置外部沙箱 自定义工具调用✅✅ 最大控制权❌✅ 最低延迟❌✅ 最低成本❌✅

结论：Assistants API 用控制权换取便利性。当需要快速开发时使用它；当需要优化时切换到 Chat Completions。

架构模式：SaaS 中的 Assistants API

用户登录 → 创建/获取用户的 Thread
    ↓
用户消息 → 添加到 Thread → 创建 Run
    ↓
轮询/流式获取 Run 状态
    ↓
如果 requires_action → 执行工具 → 提交结果
    ↓
Run 完成 → 获取消息
    ↓
返回给用户

线程管理最佳实践

线程生命周期

javascript
// 首次会话创建线程
const thread = await openai.beta.threads.create();
await db.users.update({ threadId: thread.id }, { where: { userId } });
// 后续对话复用
const { threadId } = await db.users.findOne({ where: { userId } });

线程成本管理

线程存储所有消息（每次运行时按输入令牌计费）：

长线程 → 运行成本高

截断策略：truncation_strategy: { type: "last_messages", last_messages: 10 }

对于非常长的对话，定期归档并重新开始

函数调用（工具使用）

定义工具

javascript
const assistant = await openai.beta.assistants.create({
  model: "gpt-4o",
  tools: [{
    type: "function",
    function: {
      name: "get_account_balance",
      description: "获取用户账户的当前余额",
      parameters: {
        type: "object",
        properties: {
          account_id: { type: "string", description: "账户 ID" }
        },
        required: ["account_id"]
      }
    }
  }]
});

处理工具调用

javascript
async function handleRun(threadId, runId) {
  let run = await openai.beta.threads.runs.retrieve(threadId, runId);
  
  while (run.status === "requires_action") {
    const toolCalls = run.required_action.submit_tool_outputs.tool_calls;
    const outputs = [];
    
    for (const toolCall of toolCalls) {
      if (toolCall.function.name === "get_account_balance") {
        const { account_id } = JSON.parse(toolCall.function.arguments);
        const balance = await db.accounts.getBalance(account_id);
        outputs.push({ tool_call_id: toolCall.id, output: JSON.stringify({ balance }) });
      }
    }
    
    run = await openai.beta.threads.runs.submitToolOutputs(threadId, runId, {
      tool_outputs: outputs
    });
  }
  
  return run;
}

流式响应

javascript
const stream = openai.beta.threads.runs.stream(threadId, {
  assistant_id: assistantId
});
for await (const event of stream) {
  if (event.event === "thread.message.delta") {
    const delta = event.data.delta.content[0]?.text?.value;
    if (delta) {
      res.write(data: ${JSON.stringify({ text: delta })}\n\n);
    }
  }
}

文件搜索（内置 RAG）

javascript
// 创建包含文档的向量存储
const vectorStore = await openai.beta.vectorStores.create({
  name: "公司文档"
});
await openai.beta.vectorStores.fileBatches.uploadAndPoll(
  vectorStore.id,
  [fs.createReadStream("handbook.pdf"), fs.createReadStream("faq.pdf")]
);
// 附加到助手
const assistant = await openai.beta.assistants.create({
  tools: [{ type: "file_search" }],
  tool_resources: {
    file_search: { vector_store_ids: [vectorStore.id] }
  }
});

成本优化

策略节省

简单任务使用 gpt-4o-mini比 gpt-4o 节省 95% 截断旧消息长线程节省 30-50% 缓存助手响应通过提示缓存节省 25-40% 批量处理非实时请求通过 Batch API 节省 50%