注：本译文仅作参考，请以原始文档为准：https://platform.openai.com/docs/assistants/

Assistant API 使您能够在自己的应用中创建 AI 助理。这样的助理根据指令运作，能够结合模型、工具和知识库来解答用户的问题。目前，Assistant API 支持三种 工具：代码解释器（Code Interpreter）、信息检索（Retrieval）和函数调用（Function calling）。我们未来的计划是推出更多由 OpenAI 创建的工具，并让您能在我们的平台上使用您自己的工具。

从宏观角度看，集成 Assistant API 通常包括以下步骤：

1. 通过制定定制指令和选择一个模型，在 API 中创建一个 Assistant。如果需要，还可以启用代码解释器、信息检索和函数调用等工具。
2. 用户开始交谈时，创建一个 对话线程。
3. 用户提出问题时，向对话线程中添加 消息。
4. 对对话线程执行 运行 动作，以激活 Assistant 的响应。这一过程会自动调用相关的工具。

目前，Assistant API 处于 beta 测试阶段，我们正在不断扩展其功能。欢迎您在我们的 开发者论坛 分享反馈！

这份入门指南将带领您了解创建并运行一个使用代码解释器工具的 Assistant 的关键步骤。

第 1 步：创建 Assistant

一个 Assistant 是可以配置响应用户消息的实体，配置项包括：

• 指令：定义 Assistant 和模型的行为或反应方式
• 模型：您可以选择任何 GPT-3.5 或 GPT-4 模型，包括经过微调的模型。信息检索工具需要使用 gpt-3.5-turbo-1106 和 gpt-4-1106-preview 模型。
• 工具：API 目前支持由 OpenAI 构建和托管的代码解释器和信息检索工具。
• 功能：API 允许您自定义函数签名，这与我们的 函数调用 特性相似。

例如，在本例中，我们将创建一个启用了代码解释器工具的个人数学辅导 Assistant：

调用 Assistant API 时，您需要传递 Beta 版头信息。如果您使用 OpenAI 官方的 Python 和 Node.js SDKs，系统会自动处理这一信息。

OpenAI-Beta: assistants=v1

const assistant = await openai.beta.assistants.create({
  name: "Math Tutor",
  instructions:
    "You are a personal math tutor. Write and run code to answer math questions.",
  tools: [{ type: "code_interpreter" }],
  model: "gpt-4-1106-preview",
});

步骤 2：创建 Thread

Thread 就像是一场会话。我们建议在用户开始交流时就为每位用户创建一个 Thread。在这个 Thread 里，您可以通过创建消息（Messages）来添加用户特定的情境和文件。

const thread = await openai.beta.threads.create();

Thread 没有容量上限。您可以向其中添加无限多的消息。API 会采取合适的优化措施，比如截断，来确保请求在最大上下文窗口内处理。

步骤 3：向 Thread 添加消息

消息（Message）包含用户的文本内容，用户还可以选择上传任何 文件。目前我们还不支持图像文件，但计划在接下来的几个月内开始支持。

const message = await openai.beta.threads.messages.create(thread.id, {
  role: "user",
  content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
});

如果你现在查看 Thread 中的消息列表，你会看到新消息已经被添加进 Thread 中。

{
  "object": "list",
  "data": [
    {
      "created_at": 1696995451,
      "id": "msg_4rb1Skx3XgQZEe4PHVRFQhr0",
      "object": "thread.message",
      "thread_id": "thread_34p0sfdas0823smfv",
      "role": "user",
      "content": [{
        "type": "text",
        "text": {
          "value": "I need to solve the equation `3x + 11 = 14`. Can you help me?",
          "annotations": []
        }
          }],
        ...
    }
  ]
}

步骤 4：启动 Assistant

要让 Assistant 对用户的消息做出反应，您需要创建一个 运行实例（Run）。这会让 Assistant 阅读整个 Thread，并决定是调用工具还是直接使用模型来以最合适的方式回答用户的问题。在运行过程中，Assistant 会添加标记为 role="assistant" 的消息到 Thread 中。

在创建运行实例时，您也可以给 Assistant 额外的指令：

const run = await openai.beta.threads.runs.create(thread.id, {
  assistant_id: assistant.id,
  instructions:
    "Please address the user as Jane Doe. The user has a premium account.",
});

步骤 5：展示 Assistant 的回复

这会创建一个处于 queued 状态的运行实例。您可以定期查询运行实例的 状态，看它是否已经完成。

const run = await openai.beta.threads.runs.retrieve(thread.id, run.id);

一旦运行实例完成，您就可以查看 Assistant 添加到 Thread 中的消息了。

const messages = await openai.beta.threads.messages.list(thread.id);

最后，将这些消息展示给用户！在这个运行实例中，Assistant 向 Thread 中增加了两条新消息。

您还可以查询这个运行实例的 运行步骤（Run Steps），如果您希望了解或展示 Assistant 及其工具是如何运作的。

---

了解 Assistant 是如何工作的

OpenAI 的 Assistant API 是为开发者量身打造的，目的是帮助他们创建可以执行多种任务的智能 AI Assistant。

这一 API 目前还在测试阶段，我们正不断优化并拓展它的功能。欢迎在我们的开发者论坛中为我们提供宝贵意见！

1. Assistant 能够调用 OpenAI 提供的各种**模型**，根据具体指令来调整它们的个性和功能。
2. Assistant 可以同时连接多个工具。这包括 OpenAI 提供的工具——比如代码解释器和知识检索，也包括您自己开发或托管的工具（通过函数调用实现）。
3. Assistant 还能使用持久化的线程（Threads）。线程通过保存对话历史来简化 AI 应用的开发，并且能在对话变得过于冗长时进行智能截断，以适应模型处理的上下文长度。您只需创建一个线程，并随着用户互动，不断向里面添加消息即可。
4. Assistant 还能处理多种格式的**文件**，这既可以在创建它们时进行，也可以在 Assistant 与用户的互动过程中进行。使用工具时，Assistant 还能创建文件（如图像、电子表格等），并在它们生成的消息中提及这些文件。

对象解读

打造智能 Assistant

为了确保智能 Assistant 的性能最佳和兼容性最高，我们推荐结合 Assistant API 使用 OpenAI 的 最新模型。

只需指定一个 model 就可以轻松开始创建你的智能 Assistant。当然，你还可以通过以下方式来进一步定制它的功能：

1. 利用 instructions 参数来塑造 Assistant 的性格并明确其任务目标，这有点类似于在聊天完成 API 中设置系统消息。
2. 通过 tools 参数，你可以让 Assistant 接入多达 128 种工具。无论是使用 OpenAI 提供的 code_interpreter、retrieval 这类工具，还是通过 function 功能调用第三方工具，都能为 Assistant 增添更多能力。
3. file_ids 参数能让工具如 code_interpreter 和 retrieval 访问文件。文件需通过 File 上传端点上传，并且要设置 purpose 为 assistants 才能与 API 协同工作。

比如说，你想创建一个能够根据 .csv 文件生成数据可视化的 Assistant，你需要先上传该文件。

const file = await openai.files.create({
  file: fs.createReadStream("mydata.csv"),
  purpose: "assistants",
});

接着，你就可以利用这个已上传的文件来创建你的 Assistant 了。

const assistant = await openai.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-4-1106-preview",
  tools: [{ type: "code_interpreter" }],
  file_ids: [file.id],
});

每个 Assistant 最多可以关联 20 个文件，单个文件的大小上限为 512 MB。另外，你的组织上传的文件总容量不得超过 100GB。如果需要更多存储空间，可以通过我们的 帮助中心 提出申请。

另外，你还可以通过 AssistantFile 对象来管理 Assistant 与文件之间的关系，比如创建、解除关联或查看详情。要注意的是，解除 AssistantFile 的关联并不会删除文件本身，它只是移除了文件与 Assistant 的链接。如果你需要删除某个文件，应该使用文件 删除 功能。

线程与消息的管理

线程和消息是 Assistant 和用户进行对话的场所。线程里可以存储无数条消息，而当消息数量超出模型的处理范围时，系统会智能地进行删减，确保内容能够适配。以下是如何创建一个包含初步消息列表的线程：

const thread = await openai.beta.threads.create({
  messages: [
    {
      role: "user",
      content: "Create 3 data visualizations based on the trends in this file.",
      file_ids: [file.id],
    },
  ],
});

消息可以是文本、图片或文件形式。当前，用户生成的消息还不支持包含图片文件，但我们计划不久的将来加入这项功能。

消息附注

Assistant 生成的消息中可能会包含在对象的 content 数组内的 annotations 注解。这些注解提供了关于如何对消息文本进行标注的信息。

注解主要有两种类型：

1. file_citation：文件引用注解由 retrieval 工具生成，它们指向 Assistant 上传并应用于生成回应的特定文件中的具体引文。
2. file_path：文件路径注解则由 code_interpreter 工具生成，包括对该工具产生的文件的引用。

当消息对象中包含注解时，您将在文本中看到一些模型生成的、难以辨认的字符串，您需要用注解来替换这些字符串。这些字符串可能会呈现为 【13†source】 或 sandbox:/mnt/data/file.csv 的形式。下面是一个用注解替代这些字符串的 Python 代码示例。

# 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)

运行与步骤

当您从线程中获取了所有必需的上下文信息后，您可以选择一个 Assistant 来执行这个线程。

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

通常，执行操作会默认使用 Assistant 对象中预设的 model 和 tools 配置，但您在创建执行操作时可以自定义这些配置以获得更大的灵活性：

const run = await openai.beta.threads.runs.create(thread.id, {
  assistant_id: assistant.id,
  model: "gpt-4-1106-preview",
  instructions: "additional instructions",
  tools: [{ type: "code_interpreter" }, { type: "retrieval" }],
});

注意：在创建执行操作期间，与 Assistant 相关联的 file_ids 是无法被替换的。您必须通过 modify Assistant 接口来修改它们。

执行生命周期

执行对象有多种可能的状态。

轮询更新

为了及时了解你的 Run 最新状态，你需要不时地检查 获取 Run 对象。每次获取对象时，都可以查看 Run 的最新状态，从而判断你的应用下一步该做什么。我们计划很快会引入流媒体支持功能，以便简化这一流程。

Thread 锁定

当 Run 正在 in_progress 中且尚未结束时，Thread 会被锁定。这表示：

• 无法向对话线程添加新内容。
• 对话线程上无法启动新的执行过程。

执行步骤

执行步骤的各状态与执行状态的含义是一致的。

执行步骤对象中大部分重要信息都包含在 step_details 字段里。执行步骤的详细信息有两种类型：

1. message_creation：当助理创建了对话线程中的消息时，这种类型的执行步骤就会被生成。
2. tool_calls：当助理调用了某个工具时，这种类型的执行步骤就会被生成。关于此的更多细节，请参阅 工具 指南的相关章节。

限制

在此测试版中，有几个已知的局限性，我们希望在接下来的几周和几个月里进行解决。当我们增加额外的功能支持时，会在这个页面上发布变更日志。

• 支持连续输出功能（包括消息和执行步骤）。
• 支持通知功能，以便在无需轮询的情况下分享对象的状态更新。
• 支持将 DALL·E 作为工具。
• 支持用户创建包含图像的消息。

工具

提供给助理使用 OpenAI 托管的工具，比如代码解释器和知识检索，或者您可以使用函数调用来构建自己的工具。

Assistant API 目前正处于 测试 阶段，我们正致力于增加更多功能。您可以在我们的 开发者论坛 中提供您的反馈！

代码解释器

代码解释器让 Assistant API 能够在一个沙箱环境中编写和运行 Python 代码。该工具能处理各种数据和格式的文件，并且能够生成包含数据和图形图像的文件。代码解释器允许您的助理通过迭代执行代码来解决复杂的编程和数学难题。如果助理编写的代码不能成功运行，它可以通过尝试不同的代码进行迭代，直到找到能够成功执行的代码。

启用代码解释器

在助理对象的 tools 参数中传递 code_interpreter，以便启用代码解释器：

const assistant = await openai.beta.assistants.create({
  instructions:
    "You are a personal math tutor. When asked a math question, write and run code to answer the question.",
  model: "gpt-4-1106-preview",
  tools: [{ type: "code_interpreter" }],
});

模型会根据用户的请求内容来决定在何时调用代码解释器。您可以通过在助理的 instructions 中加入提示（比如，“编写代码解决这个问题”）来引导这种行为。

代码解释器的文件处理

代码解释器能够处理并分析文件数据。这一功能尤其有用，比如当您需要向 Assistant 传输大批量数据，或是让用户上传文件以供分析时。

在 Assistant 级别上传的文件，可以被所有启用该 Assistant 的运行任务访问到：

// Upload a file with an "assistants" purpose
const file = await openai.files.create({
  file: fs.createReadStream("mydata.csv"),
  purpose: "assistants",
});

// Create an assistant using the file ID
const assistant = await openai.beta.assistants.create({
  instructions:
    "You are a personal math tutor. When asked a math question, write and run code to answer the question.",
  model: "gpt-4-1106-preview",
  tools: [{ type: "code_interpreter" }],
  file_ids: [file.id],
});

同样，文件可以在单独的线程级别进行传递。这样的文件只能在指定的线程里被访问。您可以通过 文件上传 接口来上传文件，并在创建消息请求时传递文件 ID：

const thread = await openai.beta.threads.create({
  messages: [
    {
      role: "user",
      content: "I need to solve the equation `3x + 11 = 14`. Can you help me?",
      file_ids: [file.id],
    },
  ],
});

文件的最大容量限制为 512 MB。代码解释器支持包括 .csv、.pdf、.json 在内的多种文件格式。关于支持的文件扩展名和相应 MIME 类型的更多详细信息，请参阅下文的 支持的文件 部分。

读取代码解释器生成的图像与文件

代码解释器还能输出文件，例如制作图形图表、CSV 和 PDF 文件。生成的文件主要有两类：

1. 图像文件
2. 数据文件（比如，由 Assistant 生成的 csv 文件）

当代码解释器生成图像时，您可以在 Assistant 消息响应中的 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"
      }
    }
  ]
  # ...
}

您可以通过文件 API 将文件 ID 传递出去，以下载文件内容：

const file = await openai.files.retrieveContent(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"
            }
          }
          // ...
        ]
      }
    }
  ]
}

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

通过查看调用了代码解释器的运行步骤，您可以审查代码解释器的 input 和 outputs 日志：

const runSteps = await openai.beta.threads.runs.steps.list(thread.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"
                }
                //...
              ]
            }
          }
        ]
      }
    }
  ]
}

---

知识检索功能

检索功能能够让 Assistant 访问模型之外的知识源，比如用户提供的专有产品信息或文档。文件一经上传并传至 Assistant，OpenAI 就会自动对您的文件进行分块处理、索引和储存嵌入，进而实现向量搜索，以便检索出对用户询问有关联的内容。

启用检索功能

在 Assistant 的 tools 参数中加入 retrieval 即可启用检索功能：

const assistant = await openai.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" }],
});

它的工作原理

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

1. 对于短文档，它可以直接在提示中加入文件内容，
2. 对于较长的文档，则执行向量搜索。

当前的检索功能通过将所有相关内容加入到模型调用的上下文中，来优化响应质量。我们计划推出更多检索策略，以便开发者可以根据检索质量和模型使用成本之间的不同需求，做出合适的选择。

如何上传文件供后续查询使用

就像代码解释器一样，你可以在整个 Assistant 程序或在特定的对话线程中上传文件。

// Upload a file with an "assistants" purpose
const file = await openai.files.create({
  file: fs.createReadStream("knowledge.pdf"),
  purpose: "assistants",
});

// Add the file to the assistant
const assistant = await openai.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 来引用这个文件了：

const message = await openai.beta.threads.messages.create(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 类型，可以查看下面的 Supported files 部分。

如何删除文件

如果需要从 Assistant 程序中删除文件，您可以将文件与 Assistant 程序解除关联：

const fileDeletionStatus = await openai.beta.assistants.files.del(
  assistant.id,
  file.id
);

这样做不仅会将文件与 Assistant 程序解除关联，同时也会从检索索引中删除该文件。

File citations

当代码解释器在消息中输出文件路径时，您可以使用 annotations 字段来将路径转换为文件下载链接。具体如何操作，可以参考 Annotations section。

{
    "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"
              }
            }
          ]
        }
      }
    ],
    "file_ids": [
      "file-oSgJAzAnnQkVB3u7yCoE9CBe"
    ],
        ...
  },

---

函数调用的工作方式

这与 Chat Completions API 类似，Assistants API 也支持函数调用功能。函数调用允许您告诉 Assistant 您的函数是什么，它能够智能地返回需要调用哪些函数以及它们的参数。在执行 Run 时，如果需要调用函数，Assistants API 会暂停执行，这时您就可以输入函数调用的结果，以便继续执行 Run。

如何定义函数

首先，在您创建 Assistant 时，您需要定义您的函数：

const assistant = await openai.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",
        description: "Get the weather in location",
        parameters: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "The city and state e.g. San Francisco, CA",
            },
            unit: { type: "string", enum: ["c", "f"] },
          },
          required: ["location"],
        },
      },
    },
    {
      type: "function",
      function: {
        name: "getNickname",
        description: "Get the nickname of a city",
        parameters: {
          type: "object",
          properties: {
            location: {
              type: "string",
              description: "The city and state e.g. San Francisco, CA",
            },
          },
          required: ["location"],
        },
      },
    },
  ],
});

如何读取 Assistant 所调用的函数

当您启动一个包含了触发函数的用户消息的 Run 时，Run 将会进入 requires_action 状态。模型能够通过 parallel function calling 功能同时提供多个函数调用选项：

{
  "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\"}"
          }
        }
      ]
    }
  },
...

如何提交函数的输出

您可以通过调用的函数返回输出结果来完成 Run。在提交时，需传递 tool_call_id，按照 required_action 对象中的说明与每次函数调用相对应。

const run = await openai.beta.threads.runs.submitToolOutputs(
  thread.id,
  run.id,
  {
    tool_outputs: [
      {
        tool_call_id: callIds[0],
        output: "22C",
      },
      {
        tool_call_id: callIds[1],
        output: "LA",
      },
    ],
  }
);

提交函数的输出之后，Run 将会进入 queued 状态，并继续执行下去。

Supported files

For text/ MIME types, the encoding must be one of utf-8, utf-16, or ascii.