Assistants 代码解释器

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

概览

Code Interpreter 允许 Assistant 在沙盒执行环境中编写并运行 Python 代码。该工具可以处理具有不同数据和格式的文件，并生成包含数据和图表图像的文件。Code Interpreter 允许你的 Assistant 迭代运行代码，以解决具有挑战性的代码和数学问题。当你的 Assistant 编写了无法运行的代码时，它可以通过尝试运行不同的代码进行迭代，直到代码执行成功。

请在此处查看如何开始使用 Code Interpreter 的快速入门此处.

工作原理

Code Interpreter 的收费为每会话 $0.03。如果你的 Assistant 在两个不同的 Thread 中同时调用 Code Interpreter（例如，每个终端用户对应一个 Thread），则会创建两个 Code Interpreter 会话。每个会话默认处于活动状态的时间为一小时，这意味着如果用户在同一个 Thread 中与 Code Interpreter 交互长达一小时，你只需支付一个会话的费用。

启用 Code Interpreter

传入 Assistant 对象的 code_interpreter in the tools 参数以启用 Code Interpreter：

python

1
2
3
4
5
assistant = client.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-4o",
  tools=[{"type": "code_interpreter"}]
)

1
2
3
4
5
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-4o",
  tools: [{"type": "code_interpreter"}]
});

1
2
3
4
5
6
7
8
9
10
11
curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v2' \
  -d '{
    "instructions": "You are a personal math tutor. When asked a math question, write and run code to answer the question.",
    "tools": [
      { "type": "code_interpreter" }
    ],
    "model": "gpt-4o"
  }'

然后，模型会根据用户请求的性质决定在 Run 中何时调用 Code Interpreter。可以通过在 Assistant 的 instructions 中进行提示来促发此行为（例如，“编写代码来解决这个问题”）。

将文件传递给 Code Interpreter

在 Assistant 级别传递的文件可由该 Assistant 的所有 Run 访问：

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# Upload a file with an "assistants" purpose
file = client.files.create(
  file=open("mydata.csv", "rb"),
  purpose='assistants'
)

# Create an assistant using the file ID
assistant = client.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-4o",
  tools=[{"type": "code_interpreter"}],
  tool_resources={
    "code_interpreter": {
      "file_ids": [file.id]
    }
  }
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
// 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-4o",
  tools: [{"type": "code_interpreter"}],
  tool_resources: {
    "code_interpreter": {
      "file_ids": [file.id]
    }
  }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# Upload a file with an "assistants" purpose
curl https://api.openai.com/v1/files \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -F purpose="assistants" \
  -F file="@/path/to/mydata.csv"

# Create an assistant using the file ID
curl https://api.openai.com/v1/assistants \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v2' \
  -d '{
    "instructions": "You are a personal math tutor. When asked a math question, write and run code to answer the question.",
    "tools": [{"type": "code_interpreter"}],
    "model": "gpt-4o",
    "tool_resources": {
      "code_interpreter": {
        "file_ids": ["file-BK7bzQj3FfZFXr7DbL6xJwfo"]
      }
    }
  }'

也可以在 Thread 级别传递文件。这些文件只能在特定的 Thread 中访问。使用文件上传端点上传文件，然后将 File ID 作为 Message 创建请求的一部分传递：

python

1
2
3
4
5
6
7
8
9
10
11
12
13
14
thread = client.beta.threads.create(
  messages=[
    {
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",
      "attachments": [
        {
          "file_id": file.id,
          "tools": [{"type": "code_interpreter"}]
        }
      ]
    }
  ]
)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
const thread = await openai.beta.threads.create({
  messages: [
    {
      "role": "user",
      "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",
      "attachments": [
        {
          file_id: file.id,
          tools: [{type: "code_interpreter"}]
        }
      ]
    }
  ]
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl https://api.openai.com/v1/threads/thread_abc123/messages \
  -u :$OPENAI_API_KEY \
  -H 'Content-Type: application/json' \
  -H 'OpenAI-Beta: assistants=v2' \
  -d '{
    "role": "user",
    "content": "I need to solve the equation `3x + 11 = 14`. Can you help me?",
    "attachments": [
      {
        "file_id": "file-ACq8OjcLQm2eIG0BvRM4z5qX",
        "tools": [{"type": "code_interpreter"}]
      }
    ]
  }'

文件大小上限为 512 MB。Code Interpreter 支持多种文件格式，包括 .csv, .pdf, .json 等等。有关支持的文件扩展名（及其相应的 MIME 类型）的更多详细信息，请参见下面的支持的文件部分。

读取 Code Interpreter 生成的图像和文件

API 中的 Code Interpreter 还会输出文件，例如生成图像图表、CSV 和 PDF。生成的文件有两种类型：

图像
数据文件（例如 Assistant 生成的包含数据的 csv 文件）

当 Code Interpreter 生成图像时，你可以在 Assistant Message 响应的 file_id 字段中查找并下载此文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{
	"id": "msg_abc123",
	"object": "thread.message",
	"created_at": 1698964262,
	"thread_id": "thread_abc123",
	"role": "assistant",
	"content": [
    {
      "type": "image_file",
      "image_file": {
        "file_id": "file-abc123"
      }
    }
  ]
  # ...
}

随后可以通过将文件 ID 传递给 Files API 来下载该文件内容：

python

1
2
3
4
5
6
7
8
9
from openai import OpenAI

client = OpenAI()

image_data = client.files.content("file-abc123")
image_data_bytes = image_data.read()

with open("./my-image.png", "wb") as file:
    file.write(image_data_bytes)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI();

async function main() {
  const response = await openai.files.content("file-abc123");

  // Extract the binary data from the Response object
  const image_data = await response.arrayBuffer();

  // Convert the binary data to a Buffer
  const image_data_buffer = Buffer.from(image_data);

  // Save the image to a specific location
  fs.writeFileSync("./my-image.png", image_data_buffer);
}

main();

1
2
3
curl https://api.openai.com/v1/files/file-abc123/content \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  --output image.png

当 Code Interpreter 引用文件路径（例如，“下载此 csv 文件”）时，文件路径将以注释的形式列出。你可以将这些注释转换为链接以下载该文件：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
{
  "id": "msg_abc123",
  "object": "thread.message",
  "created_at": 1699073585,
  "thread_id": "thread_abc123",
  "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-abc123"
            }
          }
          ...

Code Interpreter 的输入和输出日志

通过列出调用 Code Interpreter 的 Run 的步骤，你可以检查 Code Interpreter 的代码 input and outputs 日志：

python

1
2
3
4
run_steps = client.beta.threads.runs.steps.list(
  thread_id=thread.id,
  run_id=run.id
)

1
2
3
4
const runSteps = await openai.beta.threads.runs.steps.list(
  thread.id,
  run.id
);

1
2
3
curl https://api.openai.com/v1/threads/thread_abc123/runs/RUN_ID/steps \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "OpenAI-Beta: assistants=v2" \

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "object": "list",
  "data": [
    {
      "id": "step_abc123",
      "object": "thread.run.step",
      "type": "tool_calls",
      "run_id": "run_abc123",
      "thread_id": "thread_abc123",
      "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"
                }
						...
 }

支持的文件

文件格式	MIME 类型
`.c`	`text/x-c`
`.cs`	`text/x-csharp`
`.cpp`	`text/x-c++`
`.csv`	`text/csv`
`.doc`	`application/msword`
`.docx`	`application/vnd.openxmlformats-officedocument.wordprocessingml.document`
`.html`	`text/html`
`.java`	`text/x-java`
`.json`	`application/json`
`.md`	`text/markdown`
`.pdf`	`application/pdf`
`.php`	`text/x-php`
`.pptx`	`application/vnd.openxmlformats-officedocument.presentationml.presentation`
`.py`	`text/x-python`
`.py`	`text/x-script.python`
`.rb`	`text/x-ruby`
`.tex`	`text/x-tex`
`.txt`	`text/plain`
`.css`	`text/css`
`.js`	`text/javascript`
`.sh`	`application/x-sh`
`.ts`	`application/typescript`
`.csv`	`application/csv`
`.jpeg`	`image/jpeg`
`.jpg`	`image/jpeg`
`.gif`	`image/gif`
`.pkl`	`application/octet-stream`
`.png`	`image/png`
`.tar`	`application/x-tar`
`.xlsx`	`application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`
`.xml`	`application/xml or "text/xml"`
`.zip`	`application/zip`

推荐

入门

核心概念

Apps SDK

工具

运行与扩展

评估

实时与音频

模型优化

专业模型

正式上线

旧版 API

资源

入门指南

使用 Codex

配置

管理

自动化

学习

发布

核心概念

规划

构建

部署

转化应用

指南

资源

指南

文件上传

API

衡量

广告主 API

API 参考

最新

主题

主题

贡献

分类

主题

项目

活动

概览

工作原理

启用 Code Interpreter

将文件传递给 Code Interpreter

读取 Code Interpreter 生成的图像和文件

Code Interpreter 的输入和输出日志

支持的文件