issue: Docling-indexed PDFs have no page_label, so the model opens and cites the page before the right one

问题场景

用户在 Open WebUI v0.12.5 中启用 Docling（Docling Serve v1.38.2）做文档抽取，将多页 PDF 上传到知识库，并让具备原生工具调用的模型（如经 vLLM 提供的 Gemma 4 31B）使用内置工具。当提问答案位于 PDF 某页并要求模型“打开/引用该页”时，模型从检索分块拿到 page: 85 形式的元数据，随后调用 display_file(path="<file_id>", page=85)，结果打开物理第 85 页，而相关内容实际在第 86 页。

报错原文

issue: Docling-indexed PDFs have no page_label, so the model opens and cites the page before the right one

Relevant chunk metadata:
page: 85

Observed tool call:
display_file(path="<file_id>", page=85)

The relevant passage was on physical PDF page 86.

原因分析

这是页码起算规则不一致，而非 Docling 独有问题。Issue 维护者在 v0.12.5 代码中核实：各类加载器写入分块的 page 元数据均为 0 起算，例如 Docling 在 retrieval/loaders/main.py 中将 page_no - 1 写入，默认 PDF 加载器用 enumerate 索引，Mistral OCR 与 PaddleOCR-VL 同样使用 0 起算索引。能同时写出 page_label 的加载器会把它写成 1 起算的人类可读页码。

而模型侧通过 RAG_SOURCE_METADATA_KEYS=page,... 在来源块中暴露的是未转换的 0 起算 page；消费端 display_file 的参数文档与前端预览（先丢弃 ≤0 的值，再限制在 [1, pageCount]）均按 1 起算处理。两个界面使用同名 page 却语义不同，模型自然倾向“同名同值”直接传递，导致整体偏移一页；首页 page: 0 还会被前端归一化直接丢弃。Docling 的分块未生成 page_label，使模型缺少可用的 1 起算字段，进一步放大了该问题。

环境排查

• 确认 Open WebUI 版本（报告为 v0.12.5）以及是否在 dev 分支复现。
• 确认文档抽取引擎及版本（Docling Serve v1.38.2），或检查是否使用默认 PDF、Mistral OCR、PaddleOCR-VL 等加载器。
• 检查 RAG_SOURCE_METADATA_KEYS 的取值，是否包含 page，是否缺少 page_label。
• 确认触发工具的模型是否支持原生工具调用，并检查实际产生的 display_file 参数。
• 核对报错页相邻的检索分块元数据（page 与实际物理页码是否相差 1）。

解决步骤

1. 先复核偏移规律：查看打开页与目标页是否固定相差 1，并检查分块元数据中 page 的数值，确认是 0 起算偏移而非文档本身缺页。
2. 可优先尝试：将环境变量改为 RAG_SOURCE_METADATA_KEYS=page,page_label,file_id，让来源标注携带 1 起算的 page_label，重启 Open WebUI 后重新测试。
3. 若使用 Docling，由于该版本不写 page_label，需升级到包含 #33616 修复的版本，并对已用 Docling 索引的文件重建索引，否则旧分块仍没有标签。
4. 不建议长期依赖系统提示词让模型“加 1”；报告中已验证该做法在观测案例中仍失效。
5. 如需从代码层面统一，可关注 Issue 维护者提出的方向（在工具参数文档中说明 0 起算差异、入库时统一为 1 起算、或为工具增加显式 0 起算参数）；其中入库统一方案需要对已有向量库重新索引。该 Issue 已在 dev 分支处理。

验证方法

重新提问并要求模型展示答案所在页，检查来源块与工具调用参数：打开页应与答案所在物理页一致（如目标为第 86 页则打开第 86 页），且 PDF 首页不再因 page: 0 被丢弃。若来源中已出现 page_label 且标注页正确，说明缓解措施生效。

参考来源

open-webui/open-webui #33603

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。