Files API 是什么
文件接口的思路是「先上传、再引用」：把文档或数据集上传到平台换取一个 file_id，之后在批处理、微调或文件检索请求里引用这个 id，避免每次请求都重复上传大文件。上传意味着数据驻留在第三方平台，所以用途（purpose）声明、生命周期与删除策略都要在流程里写清楚。不同平台对文件大小、格式与保留时间的限制差异较大，以官方文档为准。
基本信息
| 核心流程 | 上传取 file_id → 请求中引用 → 用后删除 |
|---|---|
| 主要用途 | Batch 输入、微调数据集、检索库、文件问答 |
| 上传接口 | POST /v1/files，purpose 必填 |
| 删除接口 | DELETE /v1/files/{file_id} |
| 关键风险 | 数据驻留与残留，需配套保留策略 |
| 限制 | 大小与格式以官方文档为准 |
典型使用场景
- 批处理前置：把 JSONL 请求集上传后用 file_id 创建批任务
- 微调数据准备：上传训练与验证集，供平台启动训练任务
- 文件问答：上传受控文档，作为检索或问答的数据源
- 大文件复用：同一份数据被多次请求引用，节省重复上传时间
- 临时数据处理：任务结束即删除，避免数据长期残留在第三方
上传、引用与清理
上传、引用与清理
# 上传前先做敏感信息扫描，确认没有多余的个人数据
grep -nE "[0-9]{11}|@[a-z0-9.-]+" data.jsonl | head # 粗筛手机号与邮箱
export OPENAI_API_KEY=你的密钥
# purpose 必须与用途一致，填错会在后续调用里被校验拦下
curl -s https://api.openai.com/v1/files -H "Authorization: Bearer $OPENAI_API_KEY" -F purpose=batch -F file=@data.jsonl
# 任务结束后删除，减少数据残留与合规暴露面
curl -s -X DELETE https://api.openai.com/v1/files/FILE_ID -H "Authorization: Bearer $OPENAI_API_KEY"
# 定期列出文件脚查遗留：curl -s https://api.openai.com/v1/files -H "Authorization: Bearer $OPENAI_API_KEY"purpose 取值与用途
| purpose | 对应场景 | 易错点 |
|---|---|---|
| batch | 批处理任务的输入文件 | 用微调数据集的 purpose 上传会导致批任务校验失败 |
| fine-tune | 微调训练与验证数据 | 格式必须符合平台要求，否则训练任务拒绝启动 |
| assistants / 检索类 | 作为检索与问答数据源 | 数据会长期驻留，需配套清理策略 |
| 其他专用值 | 平台按用例划分 | 以官方文档为准，不要凭经验猜 |
上传即数据驻留：传之前完成脱敏，传之后按保留期删除；把上传环节写进数据合规台账，否则审计时无法说明数据流向。
file_id 是不透明的引用，删除后所有依赖它的批任务与训练任务都会失效，删除前先确认没有在跑的任务引用它。