返回博客

上传一个 200MB 的 PDF,进度条为什么能实时更新

入库跑在 Celery Worker 里,API 进程和前端不在同一进程。有谷用 DB 存权威进度、Redis Stream 跨进程广播、SSE 推给浏览器,断线还能按 seq 补发。

上传一份 200MB 的扫描 PDF 进知识库,解析、OCR、版面检测、切块、向量化——跑下来可能要几分钟。

如果前端只能「上传完转圈等最终结果」,用户不知道是在排队、卡在 OCR 还是已经失败;刷新页面后进度归零,更不知道要不要重传。

有谷大脑的入库进度是实时可见、可恢复、跨 API 副本一致的——因为 Worker、API、浏览器是三套进程,进度不能靠内存里的回调传递。

RAG 入库进度:Worker 写 DB → Redis Stream → API SSE → 浏览器。

为什么进度推送比想象中麻烦

RAG 入库是重活,放在 Celery Worker 里异步跑:PDF 转图片、调外部 RAG 服务、写向量库。API 进程只负责接上传、建任务、查状态——Worker 里发生的任何事,API 进程默认不知道。

多副本部署时更复杂:用户连的是 API 实例 A,进度事件在 Worker 里产生,若只写 Worker 内存,实例 B 上的 SSE 连接收不到任何东西。

早期常见做法的问题:

做法问题
前端轮询 GET /status延迟高、空转请求多、阶段粒度粗
Worker 直接 HTTP 回调前端前端地址不可达、无法鉴权
Redis pub/sub 广播订阅者离线丢消息,无历史
进度只存 Worker 内存进程重启进度丢失

需要的是:权威持久化 + 实时推送 + 断线补发。

三层设计

PostgreSQL — 真相源

每条进度事件落库:文档 ID、阶段(queued / parsing / chunking / embedding / indexing / done / error)、序号 seq、时间戳、可选详情 JSON。SSE 断线、Stream 丢消息,都可以按 seq 从 DB 重放补齐。

Redis Stream — 跨进程实时通道

Worker 写入 DB 后,向该知识库的 Stream 发布事件。所有 API 副本的 SSE handler 对同一 Stream 做 XREAD——天然支持 Worker→API 跨进程和多副本,不需要 API 里再跑独立订阅循环。

Stream 发布失败不影响入库主流程:DB 已是权威源,最坏情况是 SSE 稍晚才追上,不会丢最终状态。

SSE — 浏览器长连接

前端对 /api/.../rag-progress 建立 EventSource,收到 JSON 事件后更新进度条和阶段文案。Run 结束或 error 后关闭连接。

典型阶段用户看到什么

一份复杂 PDF 入库,用户可能依次看到:

  1. 排队中 — Celery 队列拥堵,任务尚未被 Worker 领取
  2. 解析中 — PDF 分页、版面检测、OCR 或格式专用解析(Excel 走另一路径)
  3. 切块中 — 语义 chunk 生成,合同/代码等走专用策略
  4. 嵌入中 — 调用 embedding 服务,批量写向量
  5. 写入中 — RAG 服务索引落盘
  6. 完成 — 可检索;或 失败 — 展示错误原因,允许重试

大视频、长音频转写阶段更多,但原则相同:让用户知道系统在工作,而不是卡死。

断线重连与 seq

SSE 连接可能因网络切换、笔记本合盖而断开。重连时客户端带上最后收到的 seq,服务端从 DB(或 Stream 历史)补发遗漏事件,再续上实时流——用户看到的进度条不会从 0% 跳回空白。

event id 校验防止重复渲染:同一 seq 的事件只应用一次,避免 UI 抖动。

和外部 RAG 服务的配合

向量索引在外部 yogu-rag-server 完成。Worker 调 RAG API ingest 时,RAG 侧也会回调 webhook 上报细粒度进度;后端合并进同一套 DocumentRagProgress 模型,再广播到 Stream。

这样无论瓶颈在本地解析还是远端 embedding,用户看到的都是一条连续时间线——而不是「我们这边完了,那边还在转圈」的两个独立 UI。

工程取舍

DB 优先于 Stream。 Stream 是实时加速层,不是唯一存储。运维可以重建 Stream,不能丢 DB 里的进度历史。

Webhook 鉴权。 RAG 服务回调带 HMAC 签名,防止伪造进度事件。

进度与业务状态分离。 「计算中」不等于「用户可见」——失败要显式 error 态,不能 silent fail 停在 99%。

不阻塞上传响应。 上传接口快速返回 document id,进度异步推——和网页收藏「先保存 URL、后台抓取」同一产品节奏。

在体验链里的意义

入库进度是信任 UI:用户敢传大文件、敢批量导入,是因为看得见 pipeline 在走。它连接:

  • 上传 / 收藏 — 任务入队
  • 格式专用解析 — 各 blog 篇描述的 chunk 质量
  • 问答 — 索引完成后 Agent 才能检到

RAG 质量取决于 chunk;用户愿不愿意等,取决于进度是否诚实。把重活放在 Worker、把状态放在 DB、把实时性放在 Stream+SSE,是让两者同时成立的基础设施。