代码解释器工具允许模型在沙盒环境中编写和运行 Python 代码,从而解决数据分析、编程和数学等领域中的复杂问题。你可以将其用于:
- 处理具有不同数据和格式的文件
- 生成包含数据和图形图像的文件
- 迭代地编写和运行代码以解决问题——例如,如果模型编写的代码运行失败,它可以持续重写并重新运行代码,直到成功为止
- 增强我们最新推理模型(如 o3 和 o4-mini)的视觉智能。模型可以使用此工具来裁剪、缩放、旋转以及以其他方式处理和转换图像。
以下是调用 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)虽然我们将此工具称为代码解释器(Code Interpreter),但模型将其识别为“python 工具”(python tool)。模型通常能够理解引用代码解释器工具的提示,但最明确的调用方式是在提示词中要求使用“python 工具”。
容器
代码解释器工具需要一个容器对象。容器是一个完全沙盒化的虚拟机,模型可以在其中运行 Python 代码。该容器可以包含你上传的文件,或者由模型生成的文件。
有两种创建容器的方式
- 自动模式:如上例所示,你可以在创建新的 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。 - 显式模式:在此模式下,你通过
v1/containers端点显式创建一个容器,包括你所需的memory_limit(例如"memory_limit": "4g"),并将该容器的id作为 Response 对象中工具配置里的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 或 64g。更高层级为会话提供更多 RAM,并按照代码解释器的内置工具费率计费。所选的 memory_limit 适用于该容器的整个生命周期,无论它是自动创建的还是通过容器 API 创建的。
请注意,自动模式下创建的容器也可以通过 /v1/containers 端点进行访问。
过期
我们强烈建议你将容器视为临时资源,并将与此工具使用相关的所有数据存储在你自己的系统上。过期详情如下:
- 如果容器在 20 分钟内未被使用,则会过期。一旦过期,在
v1/responses中使用该容器将会失败。你仍然可以在容器过期时查看其元数据的快照,但与该容器相关的所有数据将从我们的系统中丢弃,且不可恢复。你应该在容器处于活动状态时下载可能需要的任何文件。 - 你无法将过期状态的容器恢复为活动状态。请创建一个新容器并重新上传文件。请注意,旧容器内存中的任何状态(如 Python 对象)都将丢失。
- 任何容器操作(如检索容器、添加或删除文件)都会自动刷新容器的
last_active_at(最后活跃时间)。
使用文件
在运行代码解释器时,模型可以创建自己的文件。例如,如果你要求它构建一个绘图或创建 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"
}你可以通过调用获取容器文件内容方法来下载这些生成的成果文件。
任何模型输入中的文件都会自动上传到容器中。你无需显式地将其上传到容器。
上传和下载文件
使用创建容器文件将新文件添加到容器中。此端点接受多部分上传或带有 file_id 的 JSON 正文。使用列出容器文件查看现有容器文件,并通过检索容器文件内容下载字节数据。
处理引文
模型生成的文件和图像将作为助理消息的注释返回。container_file_citation 注释指向容器中创建的文件。它们包含 container_id、file_id 和 filename。你可以解析这些注释以显示下载链接或对文件进行其他处理。
支持的文件
| 文件格式 | 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 或 "text/xml" |
.zip | application/zip |
使用说明
| API 可用性 | 速率限制 | 备注 |
|---|---|---|
| 每个组织每分钟 100 次请求 (RPM) |