docling：RAG文档解析利器，把PDF转为结构化数据

别小看RAG流水线里的文档解析环节。项目做到后面你会发现，真正影响回答质量上限的，往往不是向量模型选得多好，而是喂给它的文本干不干净。处理PDF、Word、PPT这类日常办公文档，如果是纯文本提取，格式全丢；如果用正则硬拆，表格和标题层级完全乱套；碰到扫描件更是直接劝退。docling 这个IBM开源的文档转换工具，解决的就是这个问题：把PDF、DOCX、PPTX、XLSX等非结构化文档，转成LLM能直接吃的Markdown和JSON结构化数据，内置布局分析、表格识别、公式解析和OCR能力，非常适合接进知识库和RAG系统。这篇文章不聊虚的，直接讲清楚它能做什么、怎么快速跑通、底层原理是什么，以及我在实际项目里踩过的坑。

作为一个在RAG项目里折腾过不少文档解析方案的人，我第一次用docling的感受是：这玩意儿终于把"文档理解"和"文本提取"这两件事分开了。传统PDF库拿到的是一堆文字块和坐标，docling拿到的是完整的文档结构——标题、段落、表格、列表、图片、公式，层级关系清清楚楚。如果你正准备做知识库、文档问答或者内容抽取，先把docling用明白，后面很多事都会顺很多。

1. docling到底解决了什么问题——RAG流水线里最容易被低估的一环

1.1 被"能读PDF"掩盖的文档解析难题

很多做RAG的人一开始都有这个误区：以为PDF解析就是把文字抽出来，然后切片、向量化、存库就完事了。等真正接到企业文档才意识到，事情远没那么简单。

第一类是扫描件。现在很多合同、票据、历史纸质档案都是扫描成PDF的，里面的文字是图像而非文本层。你用常规PDF库去读，抽出来的全是空白或乱码，只能额外接OCR。第二类是复杂排版的文档。学术论文、行业报告、产品手册经常是多栏布局，文字夹着图表、公式、页眉页脚。普通工具contour出来的是一个"从左到右"的线性文本流，好好的双栏内容被硬拼成一段，语义直接错乱。第三类就是表格，尤其是跨页表格、带合并单元格的复杂表格。常见方案只能按坐标把单元格文字一个个抠出来，但行和列的关系、合并逻辑、表头信息全部丢失。

这些问题的共性在于：传统解析工具只做"字符级提取"，不做"文档级理解"。而RAG链路最需要的就是文档理解。知识库里的文档不只是文字串，它们有标题层级、有逻辑段落、有表格关系，这些结构本身就是语义的一部分。丢了结构，检索精度和回答质量都会明显下滑。

1.2 docling的定位：文档进，结构化数据出

docling的出现，本质上是把这个"理解"的环节做成了开箱即用的工具。它不是又一个PDF文本提取库，而是完整的文档结构化转换框架。

我总结了一下它的核心能力，基本覆盖了文档解析的全部痛点：

我当时看中它还有个原因：转换结果不只是给人看的Markdown，JSON输出里保留了文档的完整层级关系，包括页面、元素类型、元素内容、阅读顺序以及元素间的引用关系。这意味着后续做切片可以"按语义切"而不是"按字符数硬切"，做检索也能用上文档标签信息。这种结构化粒度，才是docling区别于 pdfplumber、PyMuPDF这些工具的核心。

从工程角度看，docling像是把"版面分析+OCR+表格识别+结构化导出"这条流水线打包好了，让你不用再自己去拼装一堆独立模型和服务。

2. 首次跑通docling：环境和Quickstart实测

2.1 安装前先搞清楚两个隐藏的"坑"

docling的安装命令很简单：pip install docling。但这里有两个容易被忽视的点，我云环境里的首次安装就差点因此翻车。

第一，依赖体积比想象中大。它会拉取PyTorch、模型相关的推理库和默认模型权重，整个安装过程下载的东西比较多。如果你是在容器或服务器里装，千万先确认磁盘余量够不够。第二，需要Python 3.10及以上版本。有些老项目的环境还停在3.8、3.9，直接装docling会报依赖解析失败，不要硬刚，升级Python或者起个新虚拟环境，省得把环境搞乱。

我个人的建议是，不要在跑业务的环境里直接装，先起一个独立的虚拟环境或者Docker容器试跑一遍再决定。docling官方也提供了镜像，如果只是临时转换一批文件，用Docker方式更省事。

2.2 命令行十分钟上手

docling装好后自带命令行，最简单的转换命令是这样：

# 单个PDF转Markdown docling input.pdf --to md -o output_dir # 输出JSON，保留完整结构化信息 docling input.pdf --to json -o output_dir # 批量转换当前目录下所有PDF docling docs/*.pdf --to md -o output_dir

命令行跑的时候会在终端打印进度，能看到"正在分析布局""正在识别表格""正在OCR"之类的阶段性日志，方便确认它到底做了哪些事。我第一次跑完打开输出目录，里面除了target.md/target.json，还有一个pipeline_log文件，记录每次转换的用时和处理的页面数。这个细节对排查问题很有用。

如果你要处理的文档已经自带可复制文本层，转Markdown的速度会很快。但如果是扫描件，命令行会自动触发OCR流程，耗时明显变长，同时CPU占用会拉满。这时候记得调整页面数量或者用下面要讲的Python SDK做更多控制。

2.3 用Python SDK写第一个转换脚本

正式接进项目后，Python SDK是主力，命令行更适合前期体验。最基础的脚本只要几行：

from docling.document_converter import DocumentConverter converter = DocumentConverter() # 支持本地路径和URL result = converter.convert("input.pdf") # 导出为Markdown文本 markdown_output = result.document.export_to_markdown() with open("output.md", "w", encoding="utf-8") as f: f.write(markdown_output) # 导出为JSON字典，进行结构化处理 json_output = result.document.export_to_dict()

convert()返回的结果对象很实用，它既保存了转换后的Document对象，也封装了保存文件的方法。日常用得最多的是result.document.export_to_markdown()和export_to_dict()这两个接口，一个给人看，一个给程序读。

整个第一次跑通的体感是：从安装到拿到干净的Markdown，几乎没有需要手工调参的地方。我之前用PyMuPDF提取后再去拼表格、用Tesseract做OCR再自己去对坐标，整个链路繁琐且脆弱。docling把这些全收进了一个convert()调用，这也是为什么我后来在项目里逐步把解析这块全切到了它身上。

3. 文档理解的核心机制——docling比"提取文本"多做了什么

3.1 布局分析：先弄懂页面上有什么

docling的文档理解链路，第一步是页面级的版面分析，这与"直接把文字抽出来"有本质区别。它内部有一个基于大规模标注数据训练出来的布局检测模型，能够识别一页纸上的各种元素类型，比如标题、段落、表格、图片、公式、页眉页脚、目录等等。模型不是简单抠出文字块，而是给每个区域分类并预测边界框的位置。

这个步骤的价值在复杂版面中特别明显。比如学术论文的首页，标题、作者、摘要、正文、参考文献挤在一起，有的还分成双栏。普通文本提取器会按坐标顺序或者流式顺序读出文本，读出来的内容往往是错乱的。docling先完成区域检测，再按页面上的阅读顺序重新组织每个区域的文本，从而保持了标题和正文的层级关系。多栏文档的处理也因此变得可靠。

我做过一个小实验，拿一份双栏的期刊版PDF跑docling，输出的Markdown里，左栏的正文和右栏的正文是分离的两个段落，顺序不穿插，标题自动变成了一级标题格式。而用传统库提取时，两栏内容直接缝合在一起，不花大量后处理根本没法用。

3.2 表格与公式的高保真还原

版面分析搞定了"区域在哪"，表格和公式的识别则是更细一层的结构恢复。

表格结构解析是docling另一个让我觉得物超所值的地方。它用了专门的表格结构识别模型，可以推断出每行每列的边界、表头位置、合并单元格等信息，然后把单元格内容按二维结构组织起来，再导出成Markdown或HTML表格。实测来看，对于常见的三类复杂表格——跨页表格、带合并单元格的报表、嵌套表头的统计表——docling都能还原出可用的Markdown结构，不完美，比传统方案高出一大截。

公式方面，docling支持把文档里的数学公式识别并转成LaTeX表示。对理工科文献、技术文档这种场景很关键。理工科PDF里的公式如果作为纯文本抽出来，经常是乱码或者变成一些不可读的符号。docling转成LaTeX之后，在RAG检索和摘要生成这些下游任务里就能保留数学语义。

3.3 从页面到文档图：结构化输出的组装逻辑

docling最终产出的JSON不是简单罗列文字块，而是一棵完整的分层文档树。在它的数据模型里，一篇文章由pages组成，每个page包含若干elements，每个element都有type属性和具体内容，比如"title""paragraph""table""picture""formula"，并且通过relations维护元素之间的关系。同时每个element会带上bbox坐标和页码信息，方便后续按位置做精细处理。

这种结构化的好处在于：你完全可以写一个后处理逻辑，只抽取"标题"元素来生成文档目录；或者把"表格"元素单独提取出来写入数据库；或者把"公式"和"段落"分开处理后再按段落切块进入向量库。传统方案里这些都要靠判断字体大小、文本模式各种hack才能实现，docling直接把这些结构化信息摆在你面前。

一句话总结：docling做的是"文档结构化"，而不只是"文档转文本"。结构化的数据是下游各种AI应用最好的中间表示。

4. 把docling接进RAG流程：完整示例与工程要点

4.1 最小化的文档入库脚本

接进RAG的核心需求，是把文档切分成适合检索的块，然后向量化召回、增量或全量更新。最粗糙的分块方式是按固定字符数硬切，但这样大概率会把一个完整的列表、一个段落或者一张表格的语义切碎。docling给的Markdown至少保留了标题层级和表格结构，就可以在这个基础上做更合理的切片。

我项目里的一个基础转换入库脚本大概是这样的思路：

import json from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("annual_report.pdf") doc = result.document # 导出结构化JSON data = doc.export_to_dict() with open("structure.json", "w", encoding="utf-8") as f: json.dump(data, f, ensure_ascii=False, indent=2) # 按元素类型提取文本段 chunks = [] for page in data.get("pages", []): for elem in page.get("elements", []): if elem.get("type") in ("paragraph", "title", "table", "list"): # 从doc.get_element_text(elem)等方法取对应文本 text = doc.get_element_text(elem) if text and text.strip(): chunks.append({ "page_no": page.get("page_no"), "type": elem.get("type"), "text": text.strip() }) # 后续就可以将chunks交给embedding模型向量化 for chunk in chunks: print(f"[{chunk['type']}] {chunk['text'][:50]}...")

这段代码里，我按元素类型筛选后逐个提取文本，而不是一次性把整篇文档的字符串拿回来再切块。好处很明显：文本本身就是语义完整的片段，无需担心硬切切断句子或表格。你可以根据自己的业务需要，把表格转成Markdown格式再进向量库，也可以把公式文本单独保存。

4.2 结构化信息在RAG里的价值

实际做RAG的时候，很多检索不准确的问题不是模型差，而是片段质量差。具体到场景里：

• 用户问"去年营收数据"时，如果表格被切碎了，表格表头和单元格内容分散到不同的块，召回率会很低
• 用户问"报告的核心结论"时，如果标题、正文、结论混在一个超长切片里，向量表达会"稀释"核心含义
• 用户问"某个专业术语的定义"时，如果术语在图表里、公式里，传统文本解析完全漏掉

docling因为输出了元素级结构，切片时可以按语义粒度来。文档被切出的块通常能保持语义独立，比如一个段落是一块、一个表格是一块、一个带有子列表的区域是一块。这种块的向量表达比"第N页第500个字符到第850个字符"干净得多。再加一条：如果后续你想做分块路由、元素类型属性过滤，比如只检索表格区域，docling的JSON结构也能直接支撑，省去额外造轮子的成本。

5. 实测中的性能表现与踩坑记录

5.1 三种典型文档的耗时与识别效果

为了让你对docling的能力边界有个直观认识，我在实际环境里做了一组测试。机器配置是普通的CPU服务器，2核4GB，文档分别为：一份30页的电子版PDF报告（带文本层）、一份10页的老式扫描合同（纯图像）、一份8页的学术论文文章（含公式和复杂表格）。

整体上，在CPU环境下，docling的转换速度不算快。如果你想批量处理几十上百份文档，需要预留充足时间。但如果只是日常知识库的增量更新，一天处理几十份文档完全够用。有GPU环境下配置得当会明显提速，这个后面讲进阶时再说。

5.2 我踩过的几个坑及对策

在真正把docling用起来的这段时间，我也踩了不少坑，这里挑几个有共性的分享出来。

第一个坑是内存占用。docling一次转换多个大PDF时，如果不做任何控制，内存可能涨得很快，因为多个文档的解析结果会同时驻留在内存里。我的对策是循环逐文件转换，每次转换后立即导出结果并释放对象引用，避免一个脚本里累积太多大文档。

import gc paths = ["a.pdf", "b.pdf", "c.pdf"] for path in paths: result = converter.convert(path) # 保存markdown/json... del result gc.collect()

第二个坑是扫描件OCR在纯CPU环境下真的慢。10页扫描件直接跑了非常久，而且cpu几乎满载。如果您的扫描件分PDF超过几十页，强烈建议拆分页码分批处理，或者在docling初始化时显式控制是否启用OCR的配置开关，给部分已有文本层的扫描件关了OCR反而更快。

第三个坑是表格识别不是万能的。简单表格、标准三线表，docling十识别效果非常好；但如果表格有多层嵌套表头、斜线表头、合并区域非常复杂的格式，输出Markdown还是会偶尔串行或漏掉某个单元格。这是我目前使用中碰到最多的问题。对策也很实在：对重要表格，宁可让它输出成结构化JSON再人工核验，也别直接信任第一个Markdown输出。

经验之谈：docling适合做"90%场景的自动化和标准化"，剩下10%的复杂文档仍需人工介入。它的意义在于大幅压缩了人工处理范围和成本，而不是彻底消灭人工。

5.3 什么时候不要用docling

工具都有边界，docling不是所有场景的最优解。如果文档本身就是简单电子版PDF，只有纯文本段落，用PyMuPDF这类轻量库提取反而更快捷，几秒钟就能跑完一大本。如果是需要做大规模实时文档OCR的在线服务，docling的推理链路相对重，你更应该考虑专门OCR服务配合后处理。docling最合适的场景是"离线批量处理+追求文档结构完整性"，比如构建企业知识库、处理历史归档文档、做文档预处理流水线。

6. 进阶：模型替换、GPU加速与更多输出格式

6.1 用GPU和并发提高批量处理性能

docling在CPU上能跑，但体验只能算"够用"。如果你在本地有支持CUDA的NVIDIA GPU，建议让docling跑在GPU上，注意在环境中确认torch的CUDA版本匹配，否则代码无法利用GPU加速。启用GPU后，版面分析、OCR和表格识别都有明显提速，批量处理几十页文档的时间会从"漫长"变成"可接受"。

除了GPU，docling也支持多线程/多进程并发。批量转换时，机器内存、CPU核心数允许的前提下，适当增加并发数能大幅提升吞吐。但要注意并发数也不是越大越好——文档解析本身是计算密集型任务，并发太高容易内存飙升。我一般建议在CPU环境先把并发设为2，观察内存再往上加；GPU环境则可以放开一些。

6.2 用配置项控制OCR与表格解析行为

docling有一个统一的配置入口，可以在构建DocumentConverter时传入不同的参数，按文档需求做细粒度调节。举例来说，如果你在处理混合型PDF，有些页面有文本层、有些是扫描的，你可能希望对无文本层的页面启用OCR；如果你在写论文场景里，希望公式识别更积极，可以调整公式相关的配置；如果遇到表格识别卡顿，也可以关闭一些耗时的增强项，优先保证速度和基本结构。

我建议在实际项目里先拿一份代表性文档跑出默认结果，根据产物质量再定制配置。不要一上来就调一堆参数，那样很难定位是哪一项影响效果。配置项的意义在于让docling适配你的文档集，而不是为了"看起来更专业"。

6.3 和其他解析工具放在一起，怎么选

最后把自己项目里的工具选型体验做个梳理，给大家一个直观对照：

选型时唯一的标准就是"你的下游需要什么"。如果你的下游只是把文档内容抓出来做个全文搜索，那docling属于杀鸡用牛刀；如果你的下游是LLM应用，需要干净、语义完整、结构分明的文本，那docling目前是性价比非常高的选择。

从我个人的实际体验来说，docling目前还不能做到"所有文档一次转换完美"，但它已经把文档解析这个原本需要手工搓大量规则和模型的环节，变成了一个相当规范的工程组件。对做RAG和知识库的人来说，尽早把这类工具沉淀到自己的数据流水线里，后面迭代会轻松很多。