在 Devin 中试用 DeepWiki 处理私有仓库
DeepWiki

openai/openai-cookbook

菜单

助手 API

相关源文件

助手 API 是 OpenAI 的聊天补全 API 的有状态演进，旨在通过内置的长期会话和专用工具支持，简化类似助手的体验创建。本文档解释了助手 API 系统的架构、组件和使用模式。有关聊天补全等其他 OpenAI API 的信息，请参阅 高级 API 功能。

概述

助手 API 提供了一种结构化的方式来构建可以

  • 维护会话状态
  • 使用专用工具（代码解释器、文件搜索、函数调用）
  • 处理文件和文档
  • 执行多步操作

与需要手动管理会话历史记录和工具执行的更基础的聊天补全 API 不同，助手 API 通过有状态的架构自动处理这些细节。

来源： examples/Assistants_API_overview_python.ipynb13-15

架构概述

聊天补全 API 与助手 API 对比

聊天补全 API 是无状态的，它对单个 Messages 进行操作，您使用 Completion 和 Model。虽然功能强大，但它要求开发人员手动管理

  • 对话历史
  • 工具定义
  • 检索文档
  • 代码执行

助手 API 引入了三个关键原语来处理状态和执行

  • Assistants：封装基础模型、指令、工具和上下文文档
  • Threads：表示会话状态（消息历史记录）
  • Runs：为助手在线程上的执行提供动力，处理响应和多步工具使用

来源： examples/Assistants_API_overview_python.ipynb28-38

助手 API 代码实体架构

来源： examples/Assistants_API_overview_python.ipynb33-38 examples/Assistants_API_overview_python.ipynb209-221 examples/Assistants_API_overview_python.ipynb273-275 examples/Assistants_API_overview_python.ipynb396-402

核心组件

助手对象

助手是一个持久化的对象，它封装了

  • LLM 模型（例如 gpt-4o，gpt-4o-mini）
  • 定义助手行为的指令
  • 助手可以使用的工具
  • 用于检索的可选文件

助手一旦创建，就可以在多个对话（线程）中重复使用。

助手对象结构示例

{
  "id": "asst_qvXmYlZV8zhABI2RtPzDfV6z",
  "created_at": 1736340398,
  "description": null,
  "instructions": "You are a personal math tutor. Answer questions briefly, in a sentence or less.",
  "metadata": {},
  "model": "gpt-4o",
  "name": "Math Tutor",
  "object": "assistant",
  "tools": [],
  "response_format": "auto",
  "temperature": 1.0,
  "top_p": 1.0
}

来源： examples/Assistants_API_overview_python.ipynb33-36 examples/Assistants_API_overview_python.ipynb182-222

线程对象

线程代表了对话的状态。它包含

  • 用户和助手之间的消息历史记录
  • 线程独立于任何特定的助手而存在
  • 多个助手可以处理同一个线程

线程对象结构示例

{
  "id": "thread_j4dc1TiHPfkviKUHNi4aAsA6",
  "created_at": 1736340398,
  "metadata": {},
  "object": "thread",
  "tool_resources": {"code_interpreter": null, "file_search": null}
}

来源： examples/Assistants_API_overview_python.ipynb34-35 examples/Assistants_API_overview_python.ipynb254-275

消息对象

消息包含在线程中，代表用户和助手之间的通信。主要特点

  • 消息按时间倒序排列（最新的在前）
  • 每条消息都有一个 role（“user”或“assistant”）
  • 消息可以包含文本内容和附件
  • 助手消息包含有关哪个运行创建了它们的信息

消息对象结构示例

{
  "id": "msg_1q4Y7ZZ9gIcPoAKSx9UtrrKJ",
  "assistant_id": null,
  "attachments": [],
  "completed_at": null,
  "content": [{"text": {"annotations": [], "value": "I need to solve the equation `3x + 11 = 14`. Can you help me?"}, "type": "text"}],
  "created_at": 1736340400,
  "incomplete_at": null,
  "incomplete_details": null,
  "metadata": {},
  "object": "thread.message",
  "role": "user",
  "run_id": null,
  "status": null,
  "thread_id": "thread_j4dc1TiHPfkviKUHNi4aAsA6"
}

来源： examples/Assistants_API_overview_python.ipynb276-323 examples/Assistants_API_overview_python.ipynb489-541

运行对象

运行是将助手连接到线程的操作，允许助手处理线程中的消息并生成响应。要点

  • 运行是异步操作（与聊天补全不同）
  • 运行具有一个 status，该状态会随着处理的进行而改变
  • 可能的状态：queued（排队中）、in_progress（进行中）、completed（已完成）、failed（失败）等。
  • 运行包含多个步骤，代表离散的操作

运行对象结构示例

{
  "id": "run_qVYsWok6OCjHxkajpIrdHuVP",
  "assistant_id": "asst_qvXmYlZV8zhABI2RtPzDfV6z",
  "cancelled_at": null,
  "completed_at": 1736340406,
  "created_at": 1736340403,
  "expires_at": null,
  "failed_at": null,
  "instructions": "You are a personal math tutor. Answer questions briefly, in a sentence or less.",
  "last_error": null,
  "metadata": {},
  "model": "gpt-4o",
  "object": "thread.run",
  "status": "completed",
  "thread_id": "thread_j4dc1TiHPfkviKUHNi4aAsA6",
  "tools": [],
  "usage": {
    "completion_tokens": 35,
    "prompt_tokens": 66,
    "total_tokens": 101
  }
}

来源： examples/Assistants_API_overview_python.ipynb36-37 examples/Assistants_API_overview_python.ipynb342-348 examples/Assistants_API_overview_python.ipynb389-411

运行步骤和 step_details

通过 client.beta.threads.runs.steps.list() 检索到的运行由步骤组成

步骤类型描述step_details 结构
tool_calls工具执行（code_interpreter、file_search、function）step_details.tool_calls[].code_interpreter.input/outputs
message_creation助手消息生成step_details.message_creation.message_id

代码解释器步骤详情

step_details.tool_calls 结构包含

  • tool_call.id：工具调用的唯一标识符
  • tool_call.type：工具类型（code_interpreter、file_search、function）
  • tool_call.code_interpreter.input：执行的 Python 代码
  • tool_call.code_interpreter.outputs：代码执行结果

来源： examples/Assistants_API_overview_python.ipynb918-921 examples/Assistants_API_overview_python.ipynb928-977

可用工具和配置

助手 API 通过 tools 参数支持三种主要工具类型

代码解释器工具

在 tools 数组中使用 {"type": "code_interpreter"} 配置

功能

  • 在沙盒环境中执行 Python 代码
  • 生成可视化图表
  • 进行数学计算
  • 通过 tool_resources.code_interpreter.file_ids 访问文件

该工具使用 code_interpreter.input 和 code_interpreter.outputs 创建 step_details.tool_calls。

来源： examples/Assistants_API_overview_python.ipynb856-862 examples/Assistants_API_overview_python.ipynb928-943

文件搜索工具

使用 {"type": "file_search"} 和向量存储配置

功能

  • 跨上传文档进行语义搜索
  • RAG（检索增强生成）工作流程
  • 通过 client.beta.vector_stores 管理向量存储
  • 通过 client.files.create() 处理文件

来源： examples/Assistants_API_overview_python.ipynb1052-1073 examples/Assistants_API_overview_python.ipynb1000-1012

函数调用工具

使用 {"type": "function", "function": {...}} 模式配置

函数调用使 Assistants 能够在其 Run 执行中调用开发者定义的函数。函数定义遵循与 Chat Completions API 相同的模式，但通过 Run Steps 机制进行处理。

来源： examples/Assistants_API_overview_python.ipynb802-803

代码实体执行流程

来源： examples/Assistants_API_overview_python.ipynb419-428 examples/Assistants_API_overview_python.ipynb396-402 examples/Assistants_API_overview_python.ipynb553-555

关键操作和代码模式

使用 client.beta.assistants.create() 创建 Assistant

可以通过以下方式创建 Assistants：

  1. OpenAI 仪表板上的 Assistants Playground
  2. 使用 client.beta.assistants.create() 的 API

client.beta.assistants.create() 的关键参数

  • name：Assistant 的人类可读名称
  • instructions：定义 Assistant 行为的指令
  • model：基础模型（例如，gpt-4o）
  • tools：工具对象数组（例如，[{"type": "code_interpreter"}]）
  • temperature：控制响应的随机性
  • tool_resources：工具的可选文件资源

来源： examples/Assistants_API_overview_python.ipynb209-221 examples/Assistants_API_overview_python.ipynb144-168

Thread 操作（使用 client.beta.threads）

使用 client.beta.threads.create() 创建 Thread

使用 client.beta.threads.messages.create() 添加消息

使用 client.beta.threads.messages.list() 检索消息

来源： examples/Assistants_API_overview_python.ipynb273-275 examples/Assistants_API_overview_python.ipynb317-323 examples/Assistants_API_overview_python.ipynb553-555

Run 管理（使用 client.beta.threads.runs）

使用 client.beta.threads.runs.create() 创建 Run

使用 client.beta.threads.runs.retrieve() 轮询完成

使用 client.beta.threads.runs.steps.list() 检索 Run 步骤

来源： examples/Assistants_API_overview_python.ipynb396-402 examples/Assistants_API_overview_python.ipynb419-428 examples/Assistants_API_overview_python.ipynb918-921

数据模型关系

来源： examples/Assistants_API_overview_python.ipynb33-37 examples/Assistants_API_overview_python.ipynb182-222 examples/Assistants_API_overview_python.ipynb254-275 examples/Assistants_API_overview_python.ipynb389-411

核心实现函数

Cookbook 演示了管理 Assistants API 工作流的关键辅助函数

辅助函数定义

函数用法模式

此模式支持

  • 通过 submit_message() 和 wait_on_run() 进行异步对话管理
  • Thread 重用，用于继续对话
  • 适当的状态轮询以完成 Run
  • 使用 get_response() 检索消息历史记录

来源： examples/Assistants_API_overview_python.ipynb658-677 examples/Assistants_API_overview_python.ipynb694-707 examples/Assistants_API_overview_python.ipynb759-785

与 Chat Completions 的主要区别

  1. 有状态 vs. 无状态：Assistants API 在 Threads 中维护对话状态，而 Chat Completions 要求在每次请求时都传递完整的对话历史。

  2. 异步 vs. 同步：Assistants API 中的 Run 是异步操作，可能需要一段时间才能完成，尤其是在涉及工具时。Chat Completions 会立即返回响应。

  3. 内置工具支持：Assistants API 为 Code Interpreter 和 File Search 提供了内置支持，在使用 Chat Completions 时需要手动实现这些功能。

  4. 多步推理：Run 可能涉及多个步骤，Assistant 在提供最终响应之前可能会多次使用工具。

  5. 消息顺序：默认情况下，Threads 中的消息按反向时间顺序排列，这与 Chat Completions 中使用的正向时间顺序不同。

来源： examples/Assistants_API_overview_python.ipynb28-38 examples/Assistants_API_overview_python.ipynb559-563

最佳实践

  1. 错误处理：始终通过检查 Run 的状态和任何错误消息来处理 Run 执行期间可能发生的错误。

  2. 超时和过期：Run 有一个过期时间（默认为 10 分钟）；确保您的轮询逻辑包含适当的超时。

  3. Thread 管理：为不同的对话创建新的 Threads；为继续现有对话而重用 Threads。

  4. 工具选择：仅启用 Assistant 所需的工具；不必要的工具可能导致意外行为。

  5. 消息解析：检索消息时，请记住它们默认按反向时间顺序排列；如果需要正向时间顺序，请使用 order="asc" 参数。

来源： examples/Assistants_API_overview_python.ipynb559-563 examples/Assistants_API_overview_python.ipynb389-411

限制和注意事项

  1. Token 成本：每次运行都会产生整个对话历史的 Token 成本，即使您无需手动重新发送。

  2. 轮询开销：异步特性需要轮询，这与同步请求相比增加了复杂性。

  3. 工具限制：每个工具都有特定的限制（文件大小限制、代码解释器的执行时间限制等）。

  4. 持久化：助手、线程和消息存储在 OpenAI 的服务器上，并计入您组织的存储限制。

  5. 最大 Token 上下文：每个模型都有一个最大 Token 上下文，限制了对话历史加上响应的总大小。

来源： examples/Assistants_API_overview_python.ipynb327-331