快速结论:在 RAGFlow 的 Go 解析链路中,当 PDF 走 OpenDataLoader(opendataloader_apiserver 或租户 OpenDataLoader 模型引用)解析时,解析结果只保留文本、类型和表格单元格,丢弃了服务返回的元素几何信息,因此切片结果没有 positions / _pdf_positions,引用无法在源 PDF 上高亮,也没有预览裁剪区域。优先确认解析输出项是否缺少这些位置字段。
适用环境:RAGFlow 源码提交 4e240ab24(分支 fix/paddleocr-pdf-highlights,基于 upstream/main 合并 3c79c1958);Go 摄取后端;PDF 解析族;OpenDataLoader(opendataloader_apiserver / OPENDATALOADER_APISERVER,或租户 OpenDataLoader 模型引用)。Issue 未提供操作系统、Python、CUDA、显卡等信息,且报告者说明这是通过源码检查发现的,不涉及已发布镜像。
最快修复方案:升级到包含 PR #21450 的主线版本。该 PR 在 Go 的 OpenDataLoader PDF 路径上把 bbox 转换为屏幕空间位置,并为所有 item 类型输出 positions / _pdf_positions。
注意事项:修复应保持“只返回位置”的约定,不要为了补位置而把图片内容内联进解析结果——Issue 指出图片是刻意排除在解析结果之外的,以控制解析阶段的内存峰值,chunker 和 VLM 按需从源 PDF 裁剪。另外,同一路径缺少大纲(outline 被硬编码为空数组)是另一个问题(#21221),本次修复不包括它。
问题场景
用户在 RAGFlow 中配置 OpenDataLoader(opendataloader_apiserver 或租户 OpenDataLoader 模型引用)并摄取 PDF,走后端 Go 的 OpenDataLoader PDF 解析路径。解析完成后检查输出,发现每个 item 带有 text / doc_type_kwd / layout,但没有 positions / _pdf_positions。结果是引用无法定位并高亮源 PDF 页面区域。
报错原文
[Bug]: OpenDataLoader PDF parsing drops page positions returned by the service
The Go OpenDataLoader PDF path drops the page positions that the service returns.
... the emitted items are built from those fields alone — no `positions` / `_pdf_positions` is ever produced, so citations cannot highlight the source PDF and there is no preview crop region.
原因分析
Issue 明确指出 Go 侧解析代码只读取每个元素的 type、content、text、html / html_content 和 cells 字段,输出项完全由这些字段构建,从未生成位置信息。而 OpenDataLoader 服务本身会返回元素的几何信息(bounding box),Python 侧 deepdoc/parser/opendataloader_parser.py 中的 _bbox_from_element 已能读取 bounding box / bounding_box / bbox 并转换为 RAGFlow 位置标签。也就是说,服务端数据是完整的,缺口在 Go 解析器没有消费这些字段,属于解析链路与 Python 实现不一致。
环境排查
- 确认 RAGFlow 源码版本:是否包含
4e240ab24附近或更早的提交,且是否已合入 #21450。 - 确认 PDF 解析使用的连接方式:
opendataloader_apiserver/OPDATALOADER_APISERVER(原文为OPENDATALOADER_APISERVER),或租户 OpenDataLoader 模型引用。 - 确认解析由 Go 摄取后端执行,而不是 Python
deepdoc解析器;Python 路径已具备 bbox 转换能力,可作对照。 - 查看 OpenDataLoader 服务响应中是否包含 per-element bounding box,以确认数据源正常、问题在 Go 侧消费环节。
- Issue 未提供 OS、Python、CUDA、显卡或依赖版本,相关项目无需强行核对。
解决步骤
- 先按 Issue 的复现方式在代码层面确认缺口:配置 OpenDataLoader 后摄取一个 PDF,检查解析输出的 item 是否只有
text/doc_type_kwd/layout而没有positions/_pdf_positions。 - 将服务响应与解析输出对比,确认服务返回了每个元素的 bounding box,而 Go 解析器没有读取它。
- 升级到包含 #21450 的主线版本(该 PR 将 bbox 转换为屏幕空间位置,并为所有 item 类型补上
positions/_pdf_positions)。 - 若自行修改代码,可优先尝试参照 Python 侧
_bbox_from_element的字段读取逻辑(bounding box/bounding_box/bbox),输出 1-based 的[page, left, right, top, bottom]位置。此步骤为基于 Issue 的推断,修改后需自行验证。 - 保持现有元素类型映射和表格
cells读取逻辑不变;不要通过内联图片负载来补偿位置缺失。
验证方法
重新摄取同一 PDF 后检查解析输出:各类型 item 均应带有 positions / _pdf_positions,且位置为 1-based,格式与 Python 路径一致;引用应能在源 PDF 上高亮,并具备可用的预览裁剪区域。同时确认解析结果中仍未内联图片负载,解析阶段内存峰值未被抬高。
参考来源
AI 工具推荐
想把多个 AI 模型放在一个入口?
GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型,适合写作、绘图、视频和日常 AI 工作流。
推广链接:通过此链接购买,我可能获得佣金,不影响你的价格。
这个方案解决了吗?
可以继续搜索完整报错,或查看同一工具的其他排查指南。
![[Bug]: aiohttp_openai drops `service_tier` from chat completion responses](https://www.chat-gpts.plus/wp-content/uploads/2026/10/47258-28448113-768x403.jpg)
![[Bug]: /v1/images/edits with no `image` part returns 500 with a raw Python TypeError instead of 400](https://www.chat-gpts.plus/wp-content/uploads/2026/10/42185-37908672-768x403.jpg)
