English
主导航

旧版 API

代码解释器

允许模型编写并运行 Python 以解决问题。

代码解释器工具允许模型在沙盒环境中编写并运行 Python 代码,以解决数据分析、编程和数学等领域的复杂问题。适用于:

  • 处理具有多种数据和格式的文件
  • 生成包含数据和图表图像的文件
  • 迭代编写并运行代码来解决问题——例如,编写代码运行失败的模型可以不断重写并运行该代码,直到成功为止
  • 提升我们最新推理模型(如 o3 and o4-mini)的视觉智能。模型可以使用此工具来裁剪、缩放、旋转,以及进行其他图像处理和变换操作。

以下是一个调用 Responses API 并包含代码解释器工具调用的示例:

使用 Responses API 与代码解释器
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
from openai import OpenAI

client = OpenAI()

instructions = """
You are a personal math tutor. When asked a math question,
write and run code using the python tool to answer the question.
"""

resp = client.responses.create(
    model="gpt-4.1",
    tools=[
        {
            "type": "code_interpreter",
            "container": {"type": "auto", "memory_limit": "4g"}
        }
    ],
    instructions=instructions,
    input="I need to solve the equation 3x + 11 = 14. Can you help me?",
)

print(resp.output)

虽然我们称其为代码解释器工具,但模型将其识别为“python tool”。模型通常能理解提及代码解释器工具的提示,但是,调用此工具最明确的方式是在提示中要求使用“python tool”。

容器

代码解释器工具需要一个 容器对象。容器是一个完全沙盒化的虚拟机,模型可以在其中运行 Python 代码。该容器可以包含您上传的文件或其生成的文件。

创建容器有两种方式:

  1. 自动模式:如上例所示,您可以在创建新 Response 对象时通过在工具配置中传入 "container": { "type": "auto", "memory_limit": "4g", "file_ids": ["file-1", "file-2"] } 属性来完成。这会自动创建一个新容器,或复用模型上下文中由先前 code_interpreter_call 项使用过的活动容器。省略 memory_limit 将保持容器的默认 1 GB 规格。查找此 API 请求输出中的 code_interpreter_call 项,以找到生成或使用的 container_id 生成或使用的。
  2. 显式模式:在这里,您通过 创建容器 使用 v1/containers 端点(包括您所需的 memory_limit ,例如 "memory_limit": "4g"),并在 Response 对象的工具配置中分配其 id 作为 container 值。例如:
使用显式容器创建
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
from openai import OpenAI
client = OpenAI()

container = client.containers.create(name="test-container", memory_limit="4g")

response = client.responses.create(
    model="gpt-4.1",
    tools=[{
        "type": "code_interpreter",
        "container": container.id
    }],
    tool_choice="required",
    input="use the python tool to calculate what is 4 * 3.82. and then find its square root and then find the square root of that result"
)

print(response.output_text)

你可以选择 1g (默认), 4g, 16g, or 64g。更高级别提供更高的会话 RAM,并按 内置工具费率 的代码解释器。所选 memory_limit 适用于该容器的整个生命周期,无论它是自动创建的还是通过 containers API 创建的。

请注意,使用自动模式创建的容器也可以通过 /v1/containers endpoint.

过期时间

我们强烈建议您将容器视为临时的,并将与使用此工具相关的所有数据存储在您自己的系统中。过期详情:

  • 如果容器在 20 分钟内未被使用,它就会过期。发生这种情况时,在以下操作中使用该容器 v1/responses 将会失败。您仍然可以在容器过期时查看其元数据的快照,但与该容器关联的所有数据将从我们的系统中被丢弃且无法恢复。您应该在容器处于活动状态时,从容器中下载您可能需要的任何文件。
  • 您无法将容器从已过期状态恢复为活动状态。相反,请创建一个新容器并再次上传文件。请注意,旧容器内存中的任何状态(如 Python 对象)都将丢失。
  • 任何容器操作,例如检索容器,或者向容器中添加或删除文件,都会自动刷新该容器的 last_active_at time.

处理文件

在运行 Code Interpreter 时,模型可以创建自己的文件。例如,如果您要求它绘制图表或创建 CSV,它会直接在您的容器上创建这些图像。在这种情况下,它会在其下一条 annotations 消息中引用这些文件。以下是一个示例:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
{
  "id": "msg_682d514e268c8191a89c38ea318446200f2610a7ec781a4f",
  "content": [
    {
      "annotations": [
        {
          "file_id": "cfile_682d514b2e00819184b9b07e13557f82",
          "index": null,
          "type": "container_file_citation",
          "container_id": "cntr_682d513bb0c48191b10bd4f8b0b3312200e64562acc2e0af",
          "end_index": 0,
          "filename": "cfile_682d514b2e00819184b9b07e13557f82.png",
          "start_index": 0
        }
      ],
      "text": "Here is the histogram of the RGB channels for the uploaded image. Each curve represents the distribution of pixel intensities for the red, green, and blue channels. Peaks toward the high end of the intensity scale (right-hand side) suggest a lot of brightness and strong warm tones, matching the orange and light background in the image. If you want a different style of histogram (e.g., overall intensity, or quantized color groups), let me know!",
      "type": "output_text",
      "logprobs": []
    }
  ],
  "role": "assistant",
  "status": "completed",
  "type": "message"
}

你可以通过调用 获取容器文件内容 method.

任意 模型输入中的文件 会自动上传到容器。您无需显式地将其上传到容器。

上传和下载文件

使用以下方式向您的容器添加新文件: 创建容器文件。此端点接受分段上传或带有以下内容的 JSON 请求体: file_id。使用以下命令列出现有容器文件: 列出容器文件 and download bytes from 获取容器文件内容.

处理引用

模型生成的文件和图像会作为注释 (annotation) 返回在助手的消息中。 container_file_citation 。注释指向在容器中创建的文件。它们包含 container_id, file_id,且 filename。您可以解析这些注释以显示下载链接或对文件进行其他处理。

支持的文件

文件格式MIME 类型
.ctext/x-c
.cstext/x-csharp
.cpptext/x-c++
.csvtext/csv
.docapplication/msword
.docxapplication/vnd.openxmlformats-officedocument.wordprocessingml.document
.htmltext/html
.javatext/x-java
.jsonapplication/json
.mdtext/markdown
.pdfapplication/pdf
.phptext/x-php
.pptxapplication/vnd.openxmlformats-officedocument.presentationml.presentation
.pytext/x-python
.pytext/x-script.python
.rbtext/x-ruby
.textext/x-tex
.txttext/plain
.csstext/css
.jstext/javascript
.shapplication/x-sh
.tsapplication/typescript
.csvapplication/csv
.jpegimage/jpeg
.jpgimage/jpeg
.gifimage/gif
.pklapplication/octet-stream
.pngimage/png
.tarapplication/x-tar
.xlsxapplication/vnd.openxmlformats-officedocument.spreadsheetml.sheet
.xmlapplication/xml or "text/xml"
.zipapplication/zip

使用说明

API 可用性速率限制备注
每个组织 100 RPM

定价
ZDR 和数据驻留