RAG 系统做久了，你会发现一个很反直觉的现象：决定最终回答质量的，往往不是向量库选得多好、大模型换得多勤，而是最前面那一步——文档解析。我见过太多团队在检索层反复调参，召回率就是上不去，最后定位到根因，全是 PDF 解析出来的文本本身就是一锅粥：表格串行、标题丢失、页眉页脚混进正文、跨页段落被硬生生切断。检索再精准，喂进去的是垃圾，出来的也只能是垃圾。
IBM 开源的 Docling 就是冲着这一环来的。它做的事情说起来朴素——把各种格式的文档统一解析成结构化的、对大模型友好的中间表示，但真正用下来会发现，它解决的是 RAG 管线里最脏最累、又最容易被低估的那段活。这篇内容适合正在搭 RAG 知识库、被文档解析折磨过的工程师，也适合刚接触 RAG、想知道"为什么我的知识库答非所问"的入门者。我会从解析这一环为什么痛讲起，拆解 Docling 的设计思路，给出可复现的实操步骤，再聊聊实测中踩过的坑。
1. 为什么文档解析是 RAG 管线里最容易被低估的一环
1.1 检索效果差，八成问题出在解析而不是检索
很多人搭 RAG 的第一反应是：先选个向量数据库，再挑个 embedding 模型，然后接上大模型就完事了。文档解析这一步，随手找个库把 PDF 转成纯文本，切一切就灌进去了。等到问答效果不理想，第一反应又是去调 chunk size、换 embedding、加 rerank。折腾一圈下来提升有限，因为根子上的问题没动。
我拿一个真实场景说明。假设你有一份 50 页的产品招标文件，里面有大量表格，比如技术参数对照表、报价明细表。用最朴素的 PDF 转文本工具处理，表格会被拉平成一行一行的文字，列与列之间的关系彻底丢失。原本"参数名—数值—单位"三列的结构，变成"参数名 数值 单位 参数名 数值 单位"这样一条长串。检索时用户问"某参数的标准值是多少"，向量检索可能命中这段文本，但大模型拿到的是没有列对齐关系的乱序内容，回答要么张冠李戴，要么直接说找不到。
问题的本质是：纯文本丢失了文档的语义结构。而 RAG 的检索和生成，恰恰高度依赖结构信息。标题告诉你这段属于哪个章节，表格告诉你数据之间的对应关系，页码和段落边界告诉你内容的组织方式。这些信息一旦在解析阶段丢掉，后面任何环节都补不回来。
1.2 文档格式的碎片化让解析变成一场持久战
RAG 知识库面对的文档格式从来不是单一的。PDF、Word、PPT、Excel、HTML、Markdown，甚至扫描件图片，每种格式的解析难度都不一样。PDF 尤其麻烦，因为它本质上是一种"排版描述语言"，而不是"内容描述语言"。它只告诉你"在坐标 (x, y) 处画这几个字"，至于这几个字是标题还是正文、属于哪一列、和谁是一段，PDF 本身不关心。
这就导致一个尴尬局面：不同格式要用不同工具，每个工具的解析质量参差不齐，输出格式还各不相同。PDF 用一个库，Word 用另一个库，HTML 再换一个，最后还要写一堆胶水代码把它们统一成同一种结构。维护成本高不说，每种格式的解析质量还没法保证一致。团队里但凡有人离职，这套解析管线就成了没人敢动的黑盒。
1.3 解析质量直接决定 chunk 策略能不能落地
现在稍微讲究一点的 RAG 方案，都不会再用固定长度硬切了，而是按语义结构切分——按章节切、按段落切、表格单独成块。这种"结构感知的切分"前提是，你得先有结构。如果解析出来的就是一大坨纯文本，那结构感知切分根本无从谈起，只能退回到按字符数硬切。
按字符数硬切的后果是，一个完整的论述可能被从中间切断，前半段进了这个 chunk，后半段进了那个 chunk。检索时只命中半段，大模型拿到的上下文是残缺的，回答自然不完整。更糟的是表格被切断，一半数据在这个 chunk，一半在另一个，检索命中哪个都拼不出完整表格。
所以你看，解析不是 RAG 的前置杂活，它是整个管线的地基。地基没打好，上面盖什么都是歪的。
2. Docling 到底解决了什么问题：统一解析与结构化输出
2.1 一个工具吃掉多种格式，输出统一的文档对象
Docling 最直接的价值，是把多格式解析这件事收敛到一个工具里。它支持 PDF、DOCX、PPTX、XLSX、HTML、Markdown、AsciiDoc 以及图片等多种输入，输出的是统一的文档对象模型。这个对象模型里保留了文档的层级结构：标题层级、段落、列表、表格、图片、页码等都有对应的表示。
这意味着你不再需要为每种格式写一套解析逻辑，也不用担心不同格式输出结构不一致。整个管线里，解析这一环被标准化了。对工程团队来说，这直接降低了维护成本；对个人开发者来说，这意味着你可以把精力放在检索和生成上，而不是耗在格式适配上。
它输出的中间格式是 DoclingDocument，这是一个结构化的 JSON 表示。你可以把它理解成"文档的骨架"，里面每个元素都带着类型和层级信息。这个结构往下游走，无论是做 chunk 切分、做向量化，还是做结构化抽取，都有据可依。
2.2 版面分析让 PDF 里的表格和标题不再丢失
Docling 处理 PDF 的核心能力是版面分析（layout analysis）。它不只是按坐标把文字抠出来，而是会判断每个区域是什么类型——是标题、正文、表格还是图片。对于表格，它会尝试还原行列结构，输出成结构化的表格对象，而不是拉平的文本。
这一点对 RAG 太关键了。表格还原成结构后，你可以选择把它序列化成 Markdown 表格、HTML 表格，或者转成自然语言描述再向量化。无论哪种方式，行列对应关系都保住了。用户问表格里的数据，大模型拿到的是有结构的上下文，回答准确率完全不是一个量级。
标题识别同样重要。Docling 会识别文档里的标题层级，这样你在切分时就能按章节组织 chunk，而不是把整篇文档当成一锅粥。标题还能作为 chunk 的元数据附加上去，检索时带上"这段内容属于第三章第二节"这样的上下文，对提升回答质量很有帮助。
2.3 页码、章节、段落这些元信息为什么值钱
Docling 输出的结构里保留了页码、章节路径、段落边界这些元信息。很多人一开始觉得这些是锦上添花，用起来才发现是刚需。
举个场景：用户问"这份合同里关于违约责任的条款是怎么写的"。如果 chunk 里带着章节路径元信息，检索时就能优先命中"违约责任"章节下的内容，而不是全文里所有提到"违约"二字的地方。再比如用户问"第 12 页那个表格里的数据"，页码元信息就能帮你精确定位。
这些元信息还能用于引用溯源。RAG 系统如果能在回答里标注"该内容来自第 3 章第 12 页"，可信度会大幅提升。而要做到这一点，前提就是解析阶段把这些信息保留下来。纯文本解析是做不到的，因为页码和章节边界在转纯文本时就丢了。
3. 把 Docling 接进 RAG 管线的完整实操
3.1 环境准备与安装：避开依赖冲突的坑
Docling 是 Python 包，安装本身不复杂，但有几个依赖细节容易踩坑。基础安装用 pip 就行：
pip install docling如果你要处理 PDF，尤其是带复杂版面的 PDF，建议把相关依赖装全。Docling 底层会用到一些版面分析和 OCR 能力，这些在默认安装里可能不是全部包含的。实测下来，处理扫描件或图片型 PDF 时，OCR 组件是必须的，否则解析出来是空白。
提示：建议在独立的虚拟环境里安装 Docling，因为它依赖的一些模型和库版本比较敏感，和现有项目混装容易冲突。我一般用 venv 或 conda 单独开一个环境。
安装完成后，第一次运行会自动下载版面分析和表格识别的模型权重。这一步需要联网，且模型体积不小，建议在网络稳定的环境下完成，下载一次之后会缓存到本地，后续离线也能用。
3.2 用 Python 跑通第一个解析任务
先跑一个最小可用的例子，把一份 PDF 解析成结构化对象：
from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("sample.pdf") doc = result.document # 导出为 Markdown，方便肉眼检查结构 print(doc.export_to_markdown())这段代码做了三件事：创建转换器、解析文档、导出为 Markdown。导出成 Markdown 是为了快速验证解析质量——标题有没有识别出来、表格有没有还原、段落有没有串行，一眼就能看出来。
如果你想把结构完整保留下来，可以导出为字典格式：
doc_dict = doc.export_to_dict()这个字典里包含了文档的完整结构，每个元素都有类型标记。后续做 chunk 切分时，就基于这个结构来切，而不是基于纯文本。
3.3 从解析结果到 chunk：按结构切而不是按字数切
拿到结构化文档后，切分策略就可以升级了。核心思路是：按文档的自然结构切，而不是按固定字符数切。
一个可落地的做法是遍历文档元素，遇到标题就开一个新的 chunk 分组，把标题下的段落、列表、表格归到同一组。表格单独处理，不要和正文混在一起切。代码逻辑大致是这样：
chunks = [] current_chunk = {"heading": None, "content": []} for element in doc.iterate_items(): if element.label == "section_header": # 遇到新标题，先把上一个 chunk 收尾 if current_chunk["content"]: chunks.append(current_chunk) current_chunk = {"heading": element.text, "content": []} elif element.label == "table": # 表格单独成块，保留结构 table_md = element.export_to_markdown() chunks.append({"heading": current_chunk["heading"], "content": [table_md]}) else: current_chunk["content"].append(element.text) if current_chunk["content"]: chunks.append(current_chunk)这样切出来的每个 chunk 都带着所属章节的标题，语义完整度比硬切高得多。表格作为独立 chunk，检索命中时能拿到完整表格，不会出现半张表的情况。
3.4 表格的序列化：三种方式各有适用场景
表格怎么喂给大模型，是个值得单独说的问题。Docling 还原出表格结构后，你有三种处理方式：
| 序列化方式 | 适用场景 | 优缺点 |
|---|---|---|
| Markdown 表格 | 结构规整、行列不多的表 | 可读性好，大模型理解容易；列多时容易错位 |
| HTML 表格 | 复杂表格、合并单元格 | 结构表达能力强；token 消耗偏高 |
| 自然语言描述 | 需要语义检索的表格 | 检索友好；丢失精确数值对应关系 |
我的经验是，如果表格要参与语义检索，用自然语言描述加 Markdown 混合的方式效果最好。具体做法是：先用一句话概括表格内容（比如"下表列出了各型号产品的技术参数对比"），再附上 Markdown 表格。这样检索时既能命中语义描述，生成时又能拿到精确数据。
4. 实测中踩过的坑与性能调优
4.1 扫描件和图片型 PDF 的 OCR 处理
不是所有 PDF 都是文字型的。很多扫描件、传真件、图片导出的 PDF，里面根本没有文字层，全是图像。这种文档直接解析会得到空白结果。Docling 支持 OCR，但需要确认 OCR 组件已启用。
实测下来，OCR 的质量对最终效果影响很大。如果扫描件本身清晰度差、有倾斜、有噪点，OCR 出来的文字错误率会很高，这些错误会一路传到检索和生成环节。我的建议是，对扫描件先做预处理——纠偏、去噪、提高对比度，再交给 OCR。这一步多花点时间，后面省很多事。
另外，OCR 很吃算力。大批量处理扫描件时，CPU 跑会非常慢，有条件的话用 GPU 加速，速度能差出好几倍。
4.2 大文档解析的内存与耗时控制
处理几百页的大文档时，内存占用和耗时是两个现实问题。Docling 在解析时会加载版面分析模型，模型本身占内存，加上文档内容，峰值内存可能不低。
我的做法是分批处理。把大文档拆成若干段分别解析，或者用流式处理的方式，解析完一部分就落盘，不要全部堆在内存里。耗时方面，版面分析是主要瓶颈，纯文字页快，复杂版面页慢。如果对实时性要求高，可以考虑把解析做成异步任务，解析结果缓存起来，避免重复解析同一份文档。
注意：解析结果一定要缓存。同一份文档反复解析是纯浪费，把 DoclingDocument 序列化存下来，下次直接读缓存，能省大量时间。
4.3 解析质量的自检清单
解析完不要直接灌库，先做一轮自检。我一般会检查这几项：
- 标题层级是否完整，有没有把正文误判成标题
- 表格是否还原成结构，有没有被拉平
- 页眉页脚有没有混进正文（这是很常见的污染源）
- 跨页段落有没有被正确合并
- 特殊字符、公式、符号有没有乱码
这几项里，页眉页脚污染最容易被忽视。很多 PDF 每页都有页眉页脚，解析出来会混进正文，检索时这些重复内容会干扰结果。处理办法是在解析后做一轮过滤，把高频重复的短文本行识别为页眉页脚剔除掉。
5. Docling 在真实 RAG 场景里的价值边界
5.1 它擅长什么，不擅长什么
Docling 擅长的是结构化程度较高的文档——技术文档、合同、招标文件、研究报告这类有明确章节和表格的文档。这类文档解析出来结构清晰，对 RAG 提升明显。
它不擅长的是高度非结构化的内容，比如手写笔记、艺术排版的设计稿、极端复杂的多栏混排。这些场景下版面分析容易出错，解析质量会打折扣。遇到这类文档，可能需要人工介入或者换专门的方案。
还有一个边界是实时性。Docling 的解析不是毫秒级的，它要跑模型做版面分析，单页耗时在秒级。如果你的场景要求用户上传文档后立刻就能问答，解析这一步会成为延迟瓶颈。这种场景下，要么接受几秒的等待，要么在后台预解析。
5.2 和纯文本解析方案的对比
为了直观，我拿同一份带表格的技术文档做了对比：
| 对比项 | 纯文本解析 | Docling 结构化解析 |
|---|---|---|
| 表格还原 | 拉平成文本，列关系丢失 | 保留行列结构 |
| 标题识别 | 无，标题和正文混在一起 | 识别层级，可作元数据 |
| 页码保留 | 丢失 | 保留 |
| chunk 切分 | 只能按字数硬切 | 可按章节语义切 |
| 检索准确率 | 一般 | 明显提升 |
| 解析耗时 | 快 | 较慢，需跑模型 |
这个对比不是说纯文本解析一无是处。如果文档本身就是纯文字、没有表格和复杂版面，纯文本解析够用且更快。但只要文档里有表格、有层级结构，结构化解析的优势就体现出来了。
5.3 什么规模的 RAG 项目值得上 Docling
不是所有 RAG 项目都需要 Docling。如果你只是做个 demo，文档就几页纯文字，用轻量方案就够了。但如果你面对的是以下情况，Docling 值得投入：
- 文档里有大量表格，且表格数据需要被检索和引用
- 文档有明确的章节结构，希望按结构切分 chunk
- 需要引用溯源，回答里要标注来源页码和章节
- 文档格式多样，希望统一解析管线
- 文档量大，解析质量直接影响整体问答效果
说白了，当解析质量成为 RAG 效果的瓶颈时，就是该上结构化解析工具的时候。而 Docling 的价值，在于它把这件事开源化、标准化了，你不用自己从零造轮子。
6. 把解析这一环做扎实的几个经验
我在多个 RAG 项目里反复验证过一件事：解析环节投入的时间，回报率是最高的。检索和生成的调优，边际收益递减很快，但解析质量每提升一点，下游效果是成倍改善的。
第一个经验是，解析完一定要人工抽检。不要迷信工具的输出，随机抽几页看看解析结果，尤其是表格和标题。我遇到过表格识别把两列合并成一列的情况，如果不抽检根本发现不了，等到线上问答出错才回头查，成本高得多。
第二个经验是，chunk 的元数据要尽量丰富。除了章节标题和页码，还可以把文档名、文档类型、解析时间都带上。这些元数据在检索过滤和结果排序时都能派上用场。比如用户限定"只看技术文档"，元数据里有文档类型就能直接过滤。
第三个经验是，解析管线要可复现。同一份文档，今天解析和明天解析结果应该一致。这意味着要固定模型版本、固定参数、缓存结果。解析结果不稳定，会让整个 RAG 系统的行为变得不可预测，排查问题时会非常痛苦。
Docling 这类工具的出现，其实反映了一个趋势：RAG 的竞争正在从"模型层"往"数据层"转移。谁的文档处理得更干净、结构保留得更完整，谁的 RAG 就更靠谱。模型大家都能调用，但把脏活累活做扎实的能力，才是真正的差距所在。
