API文档（api-reference）
助手 API -（Tools）

Tools Beta

提供给助手对 OpenAI 托管工具的访问权限，如代码解释器和知识检索，或使用函数调用构建你自己的工具。

代码解释器

代码解释器允许助手 API 编写并在沙盒执行环境中运行 Python 代码。此工具能处理具有多种数据和格式的文件，并生成带有数据和图表图片的文件。代码解释器使你的助手能够迭代地运行代码以解决复杂的编码和数学问题。当助手编写的代码无法运行时，它可以通过尝试运行不同的代码直到代码执行成功为止。

启用代码解释器

要启用代码解释器，将 code_interpreter 传递给助手对象的 tools 参数：

assistant = client.beta.assistants.create(
  instructions="你是个人数学导师。当被问及数学问题时，编写并运行代码以回答问题。",
  model="gpt-4-1106-preview",
  tools=[{"type": "code_interpreter"}]
)

模型随后决定何时在 Run 中调用代码解释器，这取决于用户请求的性质。可以通过在助手的指令中提示（例如，“编写代码以解决这个问题”）来推动此行为。

代码解释器的解析文件中的数据

代码解释器可以解析文件中的数据。当你想向助手提供大量数据或允许你的用户上传他们自己的文件进行分析时，这会非常有用。

在助手级别传递的文件，对于此助手的所有 Run 都是可访问的：

# 上传一个“助手”用途的文件
file = client.files.create(
  file=open("speech.py", "rb"),
  purpose='assistants'
)
 
# 使用文件 ID 创建助手
assistant = client.beta.assistants.create(
  instructions="你是个人数学导师。当被问及数学问题时，编写并运行代码以回答问题。",
  model="gpt-4-1106-preview",
  tools=[{"type": "code_interpreter"}],
  file_ids=[file.id]
)

文件也可以在 Thread 级别传递。这些文件只在特定的 Thread 中可访问。使用文件上传端点上传文件，然后在创建消息请求时传递文件 ID：

thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": "我需要解决方程 `3x + 11 = 14`。你能帮忙吗？",
      "file_ids": [file.id]
    }
  ]
)

文件最大大小为 512 MB。代码解释器支持多种文件格式，包括 .csv、.pdf、.json 等等。在下面的支持文件部分可以找到关于文件扩展名（及其对应的 MIME 类型）的更多细节。

代码解释器的生成图像图表、CSV 和 PDF 文件

API 中的代码解释器也输出文件，例如生成图像图表、CSV 和 PDF 文件。生成的文件有两种类型：

  • 图像
  • 数据文件（例如，助手生成的带有数据的 csv 文件）

当代码解释器生成图像时，你可以在助手消息响应的 file_id 字段中查找并下载该文件：

{
    "id": "msg_OHGpsFRGFYmz69MM1u8KYCwf",
    "object": "thread.message",
    "created_at": 1698964262,
    "thread_id": "thread_uqorHcTs46BZhYMyPn6Mg5gW",
    "role": "assistant",
    "content": [
      {
        "type": "image_file",
        "image_file": {
          "file_id": "file-WsgZPYWAauPuW4uvcgNUGcb"
        }
      }
    ]
    // ...
}

然后可以通过将文件 ID 传递到文件 API 来下载文件内容：

content = client.files.retrieve_content(file.id)

当代码解释器引用文件路径（例如，“下载这个 csv 文件”）时，文件路径被列为注释。你可以将这些注释转换为下载文件的链接：

{
  "id": "msg_3jyIh3DgunZSNMCOORflDyih",
  "object": "thread.message",
  "created_at": 1699073585,
  "thread_id": "thread_ZRvNTPOoYVGssUZr3G8cRRzE",
  "role": "assistant",
  "content": [
    {
      "type": "text",
      "text": {
        "value": "The rows of the CSV file have been shuffled and saved to a new CSV file. You can download the shuffled CSV file from the following link:\n\n[Download Shuffled CSV File](sandbox:/mnt/data/shuffled_file.csv)",
        "annotations": [
          {
            "type": "file_path",
            "text": "sandbox:/mnt/data/shuffled_file.csv",
            "start_index": 167,
            "end_index": 202,
            "file_path": {
              "file_id": "file-oSgJAzAnnQkVB3u7yCoE9CBe"
            }
          }
          ...

注意：只有当助手使用代码解释器时，生成的文件才会有文件 ID。如果助手只是生成文本，则不会有文件 ID。

代码解释器的输入输出日志

通过列出调用代码解释器的运行步骤，你可以检查代码解释器的代码输入和输出日志：

run_steps = client.beta.threads.runs.steps.list(
  thread_id=thread.id,
  run_id=run.id
)
{
  "object": "list",
  "data": [
    {
      "id": "step_DQfPq3JPu8hRKW0ctAraWC9s",
      "object": "assistant.run.step",
      "type": "tool_calls",
      "run_id": "run_kme4a442kme4a442",
      "thread_id": "thread_34p0sfdas0823smfv",
      "status": "completed",
      "step_details": {
        "type": "tool_calls",
        "tool_calls": [
          {
            "type": "code",
            "code": {
              "input": "# Calculating 2 + 2\nresult = 2 + 2\nresult",
              "outputs": [
                {
                  "type": "logs",
                  "logs": "4"
                }
              ]
            }
          }
        ]
      }
    }
  ]
}

知识检索

检索增强了助手模型的功能，可以从模型之外获取知识，例如专有产品信息或用户提供的文件。文件上传后，OpenAI 会自动分割文件、索引并存储嵌入，并实现向量搜索以检索相关内容回答用户查询。

启用检索

要启用检索，将检索作为工具参数传递给助手：

assistant = client.beta.assistants.create(
  instructions="You are a customer support chatbot. Use your knowledge base to best respond to customer queries.",
  model="gpt-4-1106-preview",
  tools=[{"type": "retrieval"}]
)

检索工作原理

模型根据用户消息决定何时检索内容。助手 API 自动选择两种检索技术中的一种：

  • 要么在短文档中提示文件内容，
  • 要么对较长的文件执行向量搜索。

目前，检索通过向模型调用的上下文添加所有相关内容来优化质量。我们计划引入其他检索策略，使开发者可以在检索质量和模型使用成本之间做出不同的权衡。

对上传文件进行检索

与代码解释器类似，文件可以在助手级别或线程级别上传

# Upload a file with an "assistants" purpose
file = client.files.create(
  file=open("knowledge.pdf", "rb"),
  purpose='assistants'
)
 
# Add the file to the assistant
assistant = client.beta.assistants.create(
  instructions="You are a customer support chatbot. Use your knowledge base to best respond to customer queries.",
  model="gpt-4-1106-preview",
  tools=[{"type": "retrieval"}],
  file_ids=[file.id]
)

文件也可以添加到线程中的消息。这些文件仅在这个特定线程内可访问。上传文件后，你可以在创建消息时传递这个文件的 ID：

message = client.beta.threads.messages.create(
  thread_id=thread.id,
  role="user",
  content="I can't find in the PDF manual how to turn off this device.",
  file_ids=[file.id]
)

最大文件大小为 512MB。检索支持多种文件格式，包括.pdf、.md、.docx 等等。在下面的支持文件部分可以找到更多关于文件扩展名（及其对应 MIME 类型）的详细信息。

删除文件

要从助手中移除文件，你可以从助手中删除文件的 id：

file_deletion_status = client.beta.assistants.files.delete(
  assistant_id=assistant.id,
  file_id=file.id
)

从助手中分离文件也将其从检索索引中移除。

文件引用

当代码解释器在消息中输出文件路径时，你可以使用 annotations 字段将它们转换为相应的文件下载。有关如何执行此操作的示例，请参见下面的注释部分。

{
    "id": "msg_3jyIh3DgunZSNMCOORflDyih",
    "object": "thread.message",
    ...
    "file_ids": [
      "file-oSgJAzAnnQkVB3u7yCoE9CBe"
    ],
    ...
  }

调用函数

与聊天完成 API 类似，助手 API 支持调用函数。函数调用允许你向助手描述函数，并让它智能地返回需要调用的函数及其参数。当助手在运行中调用函数时，API 将暂停执行，你可以提供函数调用的结果以继续执行。

9: 定义函数

首先，在创建助手时定义函数：

assistant = client.beta.assistants.create(
  instructions="You are a weather bot. Use the provided functions to answer questions.",
  model="gpt-4-1106-preview",
  tools=[{
      "type": "function",
    "function": {
      "name": "getCurrentWeather",
      ...
    }
  }, {
    "type": "function",
    "function": {
      "name": "getNickname",
      ...
    } 
  }]
)

读取助手调用的函数

当你启动一个触发函数的用户消息的运行时，运行将进入 requires_action 状态。模型可以一次返回一个或者多个函数调用的参数，以便于在程序中执行这些函数。同时，也提供 submit_tool_outputs：

{
  "id": "run_3HV7rrQsagiqZmYynKwEdcxS",
  "object": "thread.run",
  "assistant_id": "asst_rEEOF3OGMan2ChvEALwTQakP",
  "thread_id": "thread_dXgWKGf8Cb7md8p0wKiMDGKc",
  "status": "requires_action",
  "required_action": {
    "type": "submit_tool_outputs",
    "submit_tool_outputs": {
      "tool_calls": [
        {
          "tool_call_id": "call_Vt5AqcWr8QsRTNGv4cDIpsmA",
          "type": "function",
          "function": {
            "name": "getCurrentWeather",
            "arguments": "{\"location\":\"San Francisco\"}"
          }
        },
        {
          "tool_call_id": "call_45y0df8230430n34f8saa",
          "type": "function",
          "function": {
            "name": "getNickname",
            "arguments": "{\"location\":\"Los Angeles\"}"
          }
        }
      ]
    }
  },
...

提交函数输出

你需要提供 API 所需的函数调用输出。你可以编写代码来自动完成这一任务：

run = client.beta.threads.runs.submit_tool_outputs(
  thread_id=thread.id,
  run_id=run.id,
  tool_outputs=[
      {
        "tool_call_id": call_ids[0],
        "output": "22C",
      },
      {
        "tool_call_id": call_ids[1],
        "output": "LA",
      },
    ]
)

这些是如何利用 OpenAI 助手 API 进行文件处理和函数调用的基本步骤。

支持的文件格式

为了支持 text/ MIME 类型, 编码方式必须是： utf-8, utf-16, or ascii.

Alt text

接上页：

Alt text

助手 API（Assistants API）身份验证（Authentication）