codecamp

OpenAI 文件与产物

文件与已发布产物

文件位于智能体执行环境中。产物(artifact)是从 OpenAI 托管环境发布的文件副本,环境过期后仍可下载。

环境 如何取回文件
self_hosted 使用提供商的文件 API 或已挂载文件系统。
openai_hosted /workspace/outputs 下的文件使用会话 Artifacts API。
none 没有环境文件系统,从会话项目读取输出。

上传文件

OpenAI 托管环境在创建会话时,通过 environment.files 提供输入文件,并为每个文件选择 /workspace 下的目标位置。

可使用 type: "file_id" 引用 Files API返回的 file_id,或使用 type: "inline" 提供 Base64 编码 data;两种方式都必须有 path。

环境连接后补充文件,使用环境 Files API。

处理上传错误

创建会话或附加文件时,文件检查可能返回 HTTP 429,错误码为 files_api_rate_limit_exceeded。响应与恢复方法见 Files API 速率限制。

HTTP 400 使用 error.param 和 error.message 定位需修正的输入。例如目标不在 /workspace 下时:

来源示例 1(json):

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_request_error",
    "message": "path must be an absolute POSIX path inside /workspace",
    "param": "path"
  }
}

参数路径与请求结构一致。下表的 i 为文件索引,首个文件从 0 开始:

请求 error.param 示例
添加一个环境文件 path、data 或 file_id
创建会话或预热环境 environment.files[i].data
创建或更新环境模板 files[i].data

使用有效 Base64、文件 ID 和 /workspace 下的绝对路径,并检查文件限制。路径经过符号链接、目标已存在或路径组件过长,都可能返回 HTTP 400。

安装文件时遇到意外错误会返回 HTTP 500。重试前,先检查目标是否已经创建,再遵循暂时性失败重试指南。

取回文件

从自有环境取回

让智能体把输出写入已知路径。轮次结束后通过提供商或自己的基础设施取回文件,在环境过期或删除前存入应用存储。

自托管环境的文件不会通过 Artifacts API 发布,包括 /workspace/outputs 下的文件。提供商专属访问方式见沙箱提供商。

从 OpenAI 托管环境取回

让智能体把文件保存到 /workspace/outputs,例如 /workspace/outputs/report.pdf。轮次完成时,OpenAI 把输出发布为不可变产物。

向以下函数传入 API 客户端、会话 ID、已完成轮次 ID、产物路径和本地目标路径。函数先列出产物,再下载轮次与路径均匹配的文件:

来源示例 2(python):

## [中文] 示例 2:从 OpenAI 托管环境取回。
## [中文] 逐页查找 turn_id 和 path 同时匹配的产物,通过 SDK 流式写入目标文件;本片段未显式检查本地目标是否已存在,应用需按需处理覆盖。
## Pass the saved session ID, completed turn ID, artifact path, and local destination.
def download_artifact(client, session_id, turn_id, path, destination):
    for artifact in client.beta.agents.sessions.artifacts.list(session_id):
        if artifact.turn_id != turn_id or artifact.path != path:
            continue
        with client.beta.agents.sessions.artifacts.with_streaming_response.content(
            artifact.id, session_id=session_id
        ) as response:
            response.stream_to_file(destination)
        return
    raise FileNotFoundError(f"No artifact for {path!r} in turn {turn_id}")

请求与响应字段见列出产物、读取元数据和下载内容。

下载多个文件

每个请求只下载一个产物,没有批量下载端点。下载多个文件时,先列出产物,再逐一请求 content。希望只下载一次,可以让智能体在 /workspace/outputs 下将结果打成 ZIP,再把压缩包作为单个产物下载。

文件生命周期

已发布产物在环境过期后仍存在。删除会话前,下载需要长期保存的内容。

此 API 不能上传或编辑产物。要发布新版本,让智能体修改环境内文件并完成另一个轮次,以轮次 ID 和路径区分版本。

不再需要发布副本时可删除产物,这不会删除环境内的原文件。

文件限制

操作 限制
创建会话时包含文件 每次请求50个文件
内联上传 每文件5 MiB,按Base64编码前大小计算
单个创建请求的内联上传总量 10 MiB,按Base64编码前大小计算
从Files API复制文件 每文件50 MiB
已发布产物 每文件200 MiB
一次共同发布的输出 总计500 MiB
OpenAI 配置智能体
OpenAI 沙箱生命周期
温馨提示
下载编程狮App,免费阅读超1000+编程语言教程
取消
确定
目录

其他能力与进阶指南

Embeddings 接口参考

审计日志接口参考

关闭

MIP.setData({ 'pageTheme' : getCookie('pageTheme') || {'day':true, 'night':false}, 'pageFontSize' : getCookie('pageFontSize') || 20 }); MIP.watch('pageTheme', function(newValue){ setCookie('pageTheme', JSON.stringify(newValue)) }); MIP.watch('pageFontSize', function(newValue){ setCookie('pageFontSize', newValue) }); function setCookie(name, value){ var days = 1; var exp = new Date(); exp.setTime(exp.getTime() + days*24*60*60*1000); document.cookie = name + '=' + value + ';expires=' + exp.toUTCString(); } function getCookie(name){ var reg = new RegExp('(^| )' + name + '=([^;]*)(;|$)'); return document.cookie.match(reg) ? JSON.parse(document.cookie.match(reg)[2]) : null; }