OpenAI Files API 怎么用？

官方资料（2026-10-31 核对）：Upload file reference · File inputs guide · Files lifecycle reference · File Search guide · Uploads API

Files API、文件输入和 File Search 有什么区别？

第一步：按用途上传文件

生产站点应由自己的服务端持有 API Key 并读取本地或对象存储文件。普通模型文件输入使用 user_data；不要把 API Key 或文件上传能力直接暴露给匿名浏览器。

import fs from "fs";
import OpenAI from "openai";

const openai = new OpenAI({
  apiKey: process.env.OPENAI_API_KEY
});

const file = await openai.files.create({
  file: fs.createReadStream("./document.pdf"),
  purpose: "user_data",
  expires_after: {
    anchor: "created_at",
    seconds: 604800
  }
});

console.log({
  id: file.id,
  filename: file.filename,
  bytes: file.bytes,
  expiresAt: file.expires_at
});

expires_after.seconds 当前允许 3,600 到 2,592,000 秒，即从 1 小时到 30 天。purpose=batch 默认 30 天后到期；其他用途默认持续保存到手动删除。若业务不需要长期复用，主动设置到期并在数据库记录所有者、用途和到期时间。

purpose 应该怎么选？

第二步：用 file_id 调用 Responses

得到 File 对象后，可以在 Responses 请求中加入 input_file。PDF 会同时提取文本和页面图片；Word、PowerPoint、文本和代码等非 PDF 文件通常只提取文本，内部图片和图表不会被抽取。需要保留图表视觉信息时，先转换为 PDF。

const response = await openai.responses.create({
  model: "gpt-6-astra",
  input: [{
    role: "user",
    content: [
      {
        type: "input_file",
        file_id: file.id
      },
      {
        type: "input_text",
        text: "请总结这份文件，并列出需要核实的数字。"
      }
    ]
  }]
});

console.log(response.output_text);

Responses 还支持 Base64 file_data 和外部 file_url；Chat Completions 的文件内容部分当前只支持 PDF，并且不支持外部文件 URL。非 PDF 文档优先使用 Responses，或由应用先提取文本再发送。

四组大小限制不要混淆

项目文件存储和 Vector Store 存储不是同一个概念。File Search 需要把 File 附加到 Vector Store 并等待处理完成；大知识库应使用 File Search，而不是把所有文档塞进一次 50 MB 的模型请求。

PDF、文档和表格会怎样解析？

• PDF：视觉模型会同时接收提取文本和页面图片，因此图表更完整，但 Token 用量也可能更高；Responses 可用 detail 控制页面图像细节。
• Word、PPT、文本和代码：提取文本，非 PDF 文件里的图片或图表不会进入模型上下文。
• Excel、CSV、TSV：Responses 使用表格增强流程，当前最多解析每个 Sheet 的前 1,000 行，并添加模型生成的摘要和表头元数据。
• 大规模表格分析：复杂聚合、连接和图表更适合 Hosted Shell 或应用自己的数据处理层。

文件输入会消耗模型上下文和输入 Token。PDF 同时包含文本与页面图像时更明显；上线前应结合 API Usage 指南记录文件类型、大小、页数、模型和实际 usage。

如何列出、读取、下载和删除文件？

const page = await openai.files.list({
  purpose: "user_data",
  order: "desc",
  limit: 100
});

const metadata = await openai.files.retrieve(file.id);
const content = await openai.files.content(file.id);

// 删除是有影响的写操作
const deleted = await openai.files.delete(file.id);

List 支持 after 游标、limit、order 和 purpose 过滤。File 对象里的 status 与 status_details 已标记为弃用，不要用它们判断 Vector Store 是否完成摄取；File Search 应查看 Vector Store File 或 File Batch 的处理状态。

大文件什么时候使用 Uploads API？

直接 Files 上传超过 512 MB 时，可以评估 Uploads API：先声明总字节、文件名、MIME 和 purpose，得到一个 1 小时后失效的 Upload；再把文件切成最多 64 MB 的 Parts，可并行上传；最后按正确顺序提交 part_ids 完成。完成时实际字节必须与创建时声明一致，成功后返回可复用的 File 对象。

1. POST /v1/uploads 创建 Upload，并保存 upload_id。
2. POST /v1/uploads/{upload_id}/parts 上传每个 Part。
3. 保存所有 part_id 和原始顺序，可选计算 MD5 做完整性校验。
4. POST /v1/uploads/{upload_id}/complete 提交有序 part_ids。
5. 使用返回的 upload.file.id，再次检查目标用途的大小和格式限制。

Upload 过期或不再需要时应取消；不要因为 Uploads 支持 8 GB 就假设 Responses、Batch 或 File Search 会接受同样大小。

上线前检查清单

• 上传路由只在服务端调用 OpenAI，API Key 未进入浏览器、日志或 Git。
• 验证登录、租户、文件所有者、扩展名、MIME、真实大小和业务配额。
• purpose 与目标用途一致，普通模型输入使用 user_data。
• 区分 512 MB 上传限制、50 MB 模型输入限制、200 MB Batch 限制和 8 GB Uploads 上限。
• 数据库保存 file_id、原文件名、bytes、purpose、created_at、expires_at、租户和业务引用。
• 非 PDF 文件的图表需求已评估，必要时转换 PDF。
• 大知识库使用 Vector Store/File Search，并等待摄取完成。
• List 使用游标分页；不再依赖已弃用的 File status。
• 删除前检查 Batch、微调、评测、Responses 和 Vector Store 引用。
• 文件到期、删除、失败重试、恶意文件、跨租户访问和孤儿文件清理都有测试。

常见问题

本文核对日期为 2026-10-31。文件格式、大小、存储、上传速率、模型输入和下游用途限制可能调整，上线前请再次读取官方 Files、File inputs、File Search、Batch 与 Uploads 文档。