Back to blog

上传 2GB 的视频进知识库,为什么不能一次 POST

大文件、弱网、刷新页面——一次上传必然翻车。有谷用 5MB 分片、Redis 记进度、MinIO 服务端合并,支持断点续传和多副本共享状态。

拖一个 2GB 的培训视频进知识库,进度条走到 73% 时 Wi-Fi 抖了一下,浏览器报错,一切归零——要不要重来?

如果上传接口是「整文件 multipart POST」,答案是只能重来。TCP 断一次,前面的字节全部作废;API 多副本部署时,进度存在某台机器的内存里,换一台实例就查不到;用户刷新页面,前端 state 清空,服务端也不知道传到哪一片了。

有谷大脑对大文件走分片上传协议:init 注册 → 并发传 5MB 分片 → progress 查已传索引 → merge 服务端合并成完整对象,再触发RAG 入库。

分片上传四步:init → chunks → progress → merge,Redis + MinIO 支撑断点续传。

四步协议,每步都可重试

步骤作用重试语义
init注册文件名、总大小,返回 uploadId、单片大小、总片数每次 init 生成新 uploadId
chunk上传第 N 片,Body 为 raw Blob同一 index 可覆盖上传
progress返回 uploadedChunks[]只读,用于续传
merge校验齐全后服务端合并已合并则直接返回结果

前端把文件切成 file.slice(start, end),多 worker 共抢一个待上传队列——谁空闲谁取下一片,快的 worker 自动多传几片,避免「第 0 片分给慢 worker、最后一片拖全局」的负载不均。

Body 直接发 Blob,不走 multipart 包一层——省 boundary 解析,也避免浏览器二次缓冲整片数据。

为什么是 5MB

单片大小不是越小越好:

  • 对象存储 multipart 合并要求除最后一片外,分片 ≥ 5MB(S3 兼容协议的硬约束)
  • 网关请求体上限通常配置在 5~10MB
  • 弱网重传成本:100MB 切成 20×5MB,丢一片只重传 5MB;切成 5×20MB,丢一片代价大得多

服务端对单片 Body 做大小上限截断,防止恶意超大请求 OOM。

Redis + MinIO:状态不能放进程内存

上传进度、已传分片索引、uploadId 与用户映射存在 Redis;分片字节存在 MinIO(或 S3 兼容存储)。API 进程无状态,横向扩容时任意副本都能接 progress 和 chunk 请求。

merge 在服务端用 compose 把分片拼成最终对象,前端 never 持有完整 GB 级文件在内存里——对用户是「选文件 → 看进度 → 完成」,对浏览器是流式切片上传。

断点续传怎么工作

用户刷新页面或网络恢复后:

  1. 前端保留或恢复 uploadId(localStorage / 会话)
  2. 调 progress 拿到 uploadedChunks
  3. 只上传缺失的 index
  4. 齐全后 merge

merge 幂等:已合并成功的 uploadId 再次 merge 直接返回文档信息,不会重复入库。

和入库进度的衔接

merge 完成后创建 document 记录,异步投递 Celery 入库任务——解析、切块、向量化可能再跑几分钟。SSE 进度推送的是入库阶段,和上传阶段分开:上传条满 ≠ 可检索,但用户至少知道文件已安全落盘。

大 PDF、长视频、批量 ZIP 都走同一条分片通路;小文件仍可走简单上传,减少协议开销。

和扫码上传的关系

有些场景是「文件在手机、工作在 PC」——手机拍照、PC 写文档。扫码上传是另一条通路:PC 展示二维码,手机 HTTP 上传,PC 通过 WebSocket 收「已完成」通知。字节流仍走 HTTP,WebSocket 只传信令,和分片上传共享 Redis + 对象存储基建,但不必把文件经 WS 传一遍。

工程上几个坑

过期清理 — uploadId 在 Redis 里设 TTL, abandoned 的分片定期回收,避免 MinIO 堆垃圾。

鉴权 — 每片 upload 校验 user_uuid 与 init 时一致,不能猜 uploadId 替别人传。

merge 前校验 — 缺片拒绝 merge,并返回缺哪些 index,前端继续补传。

入库与上传解耦 — merge 成功但入库失败,文档状态应显式 error,允许重试 ingest 而不重传 GB 文件(对象已在 MinIO)。

在知识库产品里的意义

网页收藏解决「轻、频」;分片上传解决「大、稳」。企业知识库里的培训录像、录音、打包资料,往往才是单次体积最大的资产——上传链路不可靠,后面的版面检测、Excel 解析再精也轮不到跑。

把大文件上传做成可续传、可扩容、可观测的基础设施,是知识库从「能传小 PDF」到「能接企业资产」的分水岭。