English
主导航

推荐

入门

核心概念

Apps SDK

工具

运行与扩展

评估

实时与音频

模型优化

专业模型

正式上线

旧版 API

资源

API 仪表板

Assistants API 深入解析

关于创建和管理 Assistants 的深度指南。

在 Responses API 实现功能对等后，我们已弃用了 Assistants API。该 API 将于 2026 年 8 月 26 日关闭。请参阅 迁移指南 to update your integration. 了解更多.

概览

请勿在 Assistants API 上开始新的集成。我们已宣布计划在不久后将其弃用，因为 Responses API 现已提供相同的功能以及更优雅的集成方式。

使用 Assistants API 构建应用涉及多个概念，以下内容涵盖了这些概念，以期对您的 向 Responses 迁移.

创建 Assistants

我们建议将 OpenAI 的 最新模型 与 Assistants API 结合使用，以获得最佳效果并与工具实现最大程度的兼容。

在开始之前，创建 Assistant 只需指定要使用的 model 。但您可以进一步自定义 Assistant 的行为：

  1. 使用 instructions 参数来引导 Assistant 的个性并定义其目标。指令类似于 Chat Completions API 中的系统消息。
  2. 使用 tools 参数以赋予 Assistant 最多 128 个工具的访问权限。您可以为其授予 OpenAI 内置工具的访问权限，例如 code_interpreter and file_search，或者通过 function calling.
  3. 使用 tool_resources 参数以赋予 code_interpreter and file_search 等工具访问文件的权限。文件需使用 File 上传端点 and must have the purpose 进行上传，并将其设置为 assistants 以用于此 API。

例如，要创建一个能够根据 .csv 文件创建数据可视化的 Assistant，首先需要上传文件。

1
2
3
4
file = client.files.create(
  file=open("revenue-forecast.csv", "rb"),
  purpose='assistants'
)

然后，创建一个启用了 code_interpreter 工具的 Assistant，并将该文件作为资源提供给该工具。

1
2
3
4
5
6
7
8
9
10
11
assistant = client.beta.assistants.create(
  name="Data visualizer",
  description="You are great at creating beautiful data visualizations. You analyze data present in .csv files, understand trends, and come up with data visualizations relevant to those trends. You also share a brief text summary of the trends observed.",
  model="gpt-4o",
  tools=[{"type": "code_interpreter"}],
  tool_resources={
    "code_interpreter": {
      "file_ids": [file.id]
    }
  }
)

您最多可以将 20 个文件附加到 code_interpreter and 10,000 files to file_search （使用 vector_store 对象）。对于 2025 年 11 月及之后创建的向量存储，上限为 1 亿个文件。 file_search 每个文件最大为 512 MB，且最多包含 5,000,000 个 token。默认情况下，每个项目总共最多可存储 2.5 TB 的文件。没有组织级别的存储限制。您可以联系我们的支持团队来提高此上限。

管理 Thread 和 Message

Thread 和 Message 表示助手与用户之间的对话会话。每个 Thread 最多包含 100,000 条 Message。一旦 Message 的大小超过模型的上下文窗口，Thread 将尝试智能地截断消息，然后才会完全丢弃它认为最不重要的消息。

您可以像这样创建包含初始 Message 列表的 Thread：

Message 可以包含文本、图像或文件附件。Message 的

1
2
3
4
5
6
7
8
9
10
11
12
13
14
thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": "Create 3 data visualizations based on the trends in this file.",
      "attachments": [
        {
          "file_id": file.id,
          "tools": [{"type": "code_interpreter"}]
        }
      ]
    }
  ]
)

是用于将文件添加到 thread 的辅助方法 attachments 创建图像输入内容 tool_resources 调用第三方工具。你还可以选择将文件添加到 thread.tool_resources directly.

Message 内容可以包含外部图像 URL 或通过

消息内容可以包含外部图片 URL 或通过 上传的文件 ID。支持。仅 视觉 的模型可以接受图像输入。支持的图像内容类型包括 png、jpg、gif 和 webp。在创建图像文件时，请传入 purpose="vision" 以便您稍后可以下载和显示输入内容。项目总文件存储空间限制为 2.5 TB，且没有组织级别的存储限制。请联系我们以请求提高限额。

除非特别指定，否则工具无法访问图像内容。要将图像文件传递给 Code Interpreter，请在消息的 attachments 列表中添加文件 ID，以便该工具读取和分析输入内容。目前 Code Interpreter 无法下载图像 URL。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
file = client.files.create(
  file=open("myimage.png", "rb"),
  purpose="vision"
)
thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is the difference between these images?"
        },
        {
          "type": "image_url",
          "image_url": {"url": "https://example.com/image.png"}
        },
        {
          "type": "image_file",
          "image_file": {"file_id": file.id}
        },
      ],
    }
  ]
)

低或高保真度图像理解

通过控制 detail 参数（它有三个选项）， low, high, or auto, 您可以控制模型如何处理图像并生成其文本理解。

  • low 将启用“低分辨率”模式。模型将接收 512px x 512px 的低分辨率版本图像，并使用 85 个 token 的预算来表示该图像。这使得 API 能够针对不需要高细节的使用场景返回更快的响应，并消耗更少的输入 token。
  • high 将启用“高分辨率”模式，该模式首先允许模型查看低分辨率图像，然后根据输入图像的尺寸创建输入图像的详细裁剪。使用 定价计算器 查看各种图像尺寸的 token 计数。
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What is this an image of?"
        },
        {
          "type": "image_url",
          "image_url": {
            "url": "https://example.com/image.png",
            "detail": "high"
          }
        },
      ],
    }
  ]
)

上下文窗口管理

Assistants API 会自动管理截断操作，以确保其保持在模型的最大上下文长度内。您可以通过指定希望单次运行使用的最大 token 数和/或希望包含在单次运行中的最近消息的最大数量来自定义此行为。

最大 Completion 和最大 Prompt Token

要控制单次 Run 中的 token 使用量，请在创建 Run 时设置 max_prompt_tokens and max_completion_tokens 。这些限制适用于 Run 整个生命周期内所有 completion 所使用的 token 总数。

例如，发起一个 Run 时将 max_prompt_tokens 设为 500 并将 max_completion_tokens 设为 1000，意味着第一次补全会将线程截断至 500 个 token，并将输出限制在 1000 个 token。如果第一次补全仅使用了 200 个 prompt token 和 300 个 completion token，则第二次补全的可用限额将分别为 300 个 prompt token 和 700 个 completion token。

如果补全达到了 max_completion_tokens 限制，Run 将终止，其状态为 incomplete, 并且详细信息将在 incomplete_details Run 对象的 字段。

当使用 File Search 工具时，我们建议将 max_prompt_tokens 设置为不低于 20,000。对于较长的对话或与 File Search 的多次交互，可以考虑将此限制提高到 50,000，最理想的情况是完全移除 max_prompt_tokens 限制，以获得最高质量的结果。

截断策略

您还可以指定截断策略，以控制应如何将您的线程填充到模型的上下文窗口中。使用类型为 auto 的截断策略将使用 OpenAI 的默认截断策略。使用类型为 last_messages 的截断策略将允许您指定要包含在上下文窗口中的最新消息数量。

消息注解

由 Assistant 创建的 Message 可能会在对象的 annotations 数组中包含 content 。注解提供了有关您应如何对 Message 中的文本进行注释的信息。

Annotations 有两种类型：

  1. file_citation: 文件引用由 file_search 工具，并定义了对由 Assistant 上传并用于生成响应的特定文件的引用。
  2. file_path: 文件路径注释由 code_interpreter 工具，并包含对该工具生成的文件的引用。

当 Message 对象中存在注解时，您会在文本中看到难以辨认的由模型生成的子字符串，您应该用注解替换它们。这些字符串可能类似于 【13†source】 or sandbox:/mnt/data/file.csv创建。以下是一个 Python 代码片段示例，用于将这些字符串替换为注释。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
# Retrieve the message object
message = client.beta.threads.messages.retrieve(
  thread_id="...",
  message_id="..."
)

# Extract the message content

message_content = message.content[0].text
annotations = message_content.annotations
citations = []

# Iterate over the annotations and add footnotes

for index, annotation in enumerate(annotations): # Replace the text with a footnote
message_content.value = message_content.value.replace(annotation.text, f' [{index}]')

    # Gather citations based on annotation attributes
    if (file_citation := getattr(annotation, 'file_citation', None)):
        cited_file = client.files.retrieve(file_citation.file_id)
        citations.append(f'[{index}] {file_citation.quote} from {cited_file.filename}')
    elif (file_path := getattr(annotation, 'file_path', None)):
        cited_file = client.files.retrieve(file_path.file_id)
        citations.append(f'[{index}] Click <here> to download {cited_file.filename}')
        # Note: File download functionality not implemented above for brevity

# Add footnotes to the end of the message before displaying to user

message_content.value += '\n' + '\n'.join(citations)

Runs 和 Run Steps

当您从 Thread 中获取到用户的所有上下文后，您可以使用您选择的 Assistant 来运行该 Thread。

1
2
3
4
run = client.beta.threads.runs.create(
  thread_id=thread.id,
  assistant_id=assistant.id
)

默认情况下，Run 将使用 Assistant 对象中指定的 model and tools 配置，但您可以在创建 Run 时覆盖其中的大部分配置以增加灵活性：

1
2
3
4
5
6
7
run = client.beta.threads.runs.create(
  thread_id=thread.id,
  assistant_id=assistant.id,
  model="gpt-4o",
  instructions="New instructions that override the Assistant instructions",
  tools=[{"type": "code_interpreter"}, {"type": "file_search"}]
)

Note: tool_resources 与 Assistant 关联的 不能在 Run 创建期间被覆盖。您必须使用 修改 Assistant 端点来执行此操作。

Run 生命周期

Run 对象可以具有多种状态。

Run lifecycle - diagram showing possible status transitions

状态定义
queued当首次创建 Run 或当您完成 required_action，它们会进入排队状态。它们几乎应该会立即变为 in_progress.
in_progress在 in_progress 期间，Assistant 使用模型和工具来执行步骤。您可以通过检查 运行步骤.
completedRun 成功完成！您现在可以查看 Assistant 添加到 Thread 中的所有 Message，以及 Run 采取的所有步骤。您还可以通过向 Thread 添加更多用户 Message 并创建另一个 Run 来继续对话。
requires_action当使用 函数调用 工具时，一旦模型确定了要调用的函数名称和参数，Run 就会进入 required_action 状态。然后您必须运行这些函数并在 Run 继续之前 提交输出 。如果在 expires_at 时间戳（大约在创建后 10 分钟）之前未提供输出，Run 将变为过期状态。
expired这种情况发生在 function calling 的输出未在 expires_at 之前提交且 Run 过期时。此外，如果 Run 执行时间过长，超出了 expires_at，我们的系统将使该运行过期。
cancelling中规定的时间 in_progress 您可以尝试使用 取消运行 端点来取消 处于 的 cancelled。系统会尝试取消，但不保证成功。
cancelledRun。一旦取消尝试成功，Run 的状态将变为
failedRun 已成功取消。 last_error 您可以通过查看 Run 中的 failed_at.
incomplete对象来了解失败的原因。失败的时间戳将记录在 max_prompt_tokens or max_completion_tokens Run 因达到 incomplete_details 而结束。您可以通过查看 Run 中的

对象来了解具体原因。

轮询更新 如果您没有使用，为了保持运行状态处于最新，您必须定期 流式传输 检索 Run

对象。您可以在每次检索对象时检查 Run 的状态，以确定您的应用程序接下来应该做什么。 您可以选择在我们 Node and Python SDK 中使用轮询助手 (Polling Helpers) 来协助您。这些助手会自动为您轮询 Run 对象，并在其处于终止状态时返回该 Run 对象。

线程锁定

当 Run 处于 in_progress 且不在终止状态时，Thread 会被锁定。这意味着：

  • 无法向 Thread 中添加新 Messages。
  • 无法在 Thread 上创建新 Run。

Run 步骤

Run steps lifecycle - diagram showing possible status transitions

Run 步骤状态的含义与 Run 状态相同。

Run Step 对象中大部分有意义的细节位于 step_details 字段中。步骤详情分为两种类型：

  1. message_creation: 当 Assistant 在 Thread 上创建 Message 时，会创建此 Run Step。
  2. tool_calls: 当 Assistant 调用工具时，会创建此 Run Step。相关详细信息在以下相关章节中介绍： 工具 guide.

数据访问指南

目前，通过 API 创建的 Assistants、Threads、Messages 和 Vector Stores 的作用域限定在其被创建的 Project 内。因此，任何拥有该项目 API 密钥访问权限的人都可以读取或写入该项目中的 Assistants、Threads、Messages 和 Runs。

我们强烈建议采取以下数据访问控制措施：

  • 实施授权机制。 在对 Assistants、Threads、Messages 和 Vector Stores 执行读取或写入操作之前，请确保终端用户已获得相应授权。例如，在您的数据库中存储终端用户有权访问的对象 ID，并在通过 API 获取该对象 ID 之前进行核对检查。
  • 限制 API 密钥访问权限。 请慎重考虑组织中哪些人员应该持有 API 密钥并成为 Project 成员。定期审查此名单。API 密钥允许执行大范围的操作，包括读取和修改敏感信息（如 Messages 和 Files）。
  • 创建独立账户。 考虑为不同的应用创建独立的 Projects，以便隔离多个应用之间的数据。