Docling实战：从PDF到结构化文档，高效接入RAG知识库

我最近在折腾RAG项目时发现一个很反直觉的现象：解析PDF的工具不缺，缺的是能把文档“结构”保留下来的解析器。docling这个开源项目最近在技术社区里讨论度很高，核心原因是它把PDF、Word、PPT、扫描件这些乱七八糟的格式，统一转换成一种带完整文档结构的中间表示，然后再导出成Markdown、HTML、JSON给下游使用。

简单说，docling解决的是“AI读文档”这件事里最脏最累的一环——不是把文字抠出来，而是告诉模型：哪块是标题、哪块是正文、表格在第几栏、阅读顺序是什么。这篇文章我就结合自己实际跑通的流程，从安装、原理、效果到RAG接入，把值得关注的经验点一次说完。适合正在做知识库、文档问答、数据清洗，或者被PDF解析折磨过的人参考。

1. 整个解析链路里，Docling补的是哪块短板

先说清楚我为什么会被这个工具吸引。过去做文档解析，PyMuPDF、pdfplumber、pypdf这些库我都用过，它们解决的问题很纯粹：把PDF里的字符、坐标、矩形框提取出来。但问题也正出在这里——它们给你的是一堆“字”和“位置”，不是“文档”。

这种“有字无文”的解析结果直接喂给LLM，会出现几个明显症状：双栏论文被读成左右穿插的乱序文本，表格内容散落成碎片，页眉页脚混进正文，标题层级完全丢失。你可以在后处理阶段写一堆规则去修，但文档版式千奇百怪，规则越写越多，最后变成维护一个永远修不完的补丁集合。

1.1 不是另一个“PDF提取库”，是文档结构还原器

docling和传统提取库最大的区别，在于它把“物理布局分析”和“语义结构重建”做成了内置能力。它先通过布局模型把页面切分成不同的区域——标题、段落、表格、图片、页眉、页脚——然后对阅读顺序进行排序，再用专门的表格结构模型把表格里的单元格关系重建出来，最后把所有信息组装进一个统一的DoclingDocument数据结构里。

这个数据结构非常关键。它不是一个简单的纯文本对象，而是带有层级关系的文档模型：有Document、有Section、有Table、有Figure、有文本块之间的父子关系，还保存了阅读顺序。也就是说，docling输出的不是“一行行字符串”，而是一棵“文档树”。

1.2 多格式输入，同一套输出结构

我比较看重的一点是它支持多格式输入。除了PDF，docling还能处理 DOCX、PPTX、XLSX、图片、HTML 这些常见格式。这意味着在搭建文档处理管道时，我可以统一用一套代码处理公司内部各种杂七杂八的文件，而不是给每种格式各写一个适配器。

尤其在实际项目里，知识库的素材来源几乎不可能只有PDF。有人扔一个Word报过来，有人发个PPT，还有人拍了几张照片，过去这些要分别走不同的解析流程，维护成本很高。docling把这些入口收敛成一个，输出还是同一个结构，这对工程化来说价值非常大。

1.3 适用人群和典型场景

从实际体验来看，下面几类人和场景最适合用docling：

• 正在做RAG知识库，发现“文档加载”这步成了瓶颈的。
• 需要批量把公司历史文档转换成Markdown/结构化数据的。
• 做文档训练数据清洗，希望保留表格和标题层级信息的人。
• 需要处理扫描件或者图片型PDF，想省去单独接OCR的功夫。
• 做多模态文档理解，想把版面、图表位置信息一起保留下来的人。

如果你只是偶尔从PDF里复制几段文字，那用pypdf甚至直接手动复制就行，没必要上这个工具。docling的价值体现在规模化和结构化上。

2. 安装与第一次运行：坑比想象少，但要有点耐心

安装本身不复杂，按照官方README操作就行。但有几点体验上的细节，值得提前说清楚，免得你第一印象被网络或依赖问题搞坏。

2.1 环境准备

建议使用 Python 3.10 以上的版本，我个人在 3.11 上跑得很稳。装一个虚拟环境是必须的，因为docling的依赖树里有torch、onnxruntime、transformers这类比较重的库，直接怼进系统Python环境容易发生版本冲突。

python -m venv venv source venv/bin/activate # Windows下为 venv\Scripts\activate pip install docling

如果你主要处理的是PDF，并且需要完整的PDF解析能力，官方还提供了带PDF增强依赖的安装方式，安装时可以按需选装：

pip install docling[pdf]

不建议一上来就装“全家桶”，除非你确认各种格式都要用。依赖越少，出问题的面越小。

2.2 第一次运行的“下载关”

docling的核心模型权重并不是安装时带在包里的，而是在第一次执行转换时自动下载到本地缓存。这就意味着，第一次跑的时候一定要保证网络畅通，否则会卡在模型加载阶段，看起来像“程序假死”。

我第一次跑的时候没心理准备，看到一个PDF文件半天没出结果，还以为是卡死了。后来翻日志才发现它正在下载布局模型和表格模型。跑完第一次之后，模型会缓存在本地，之后断网也能正常用。

建议第一次测试时用一个很小的单页PDF文件，目标只是跑通流程，别一上来就丢一个上千页的扫描件进去。

2.3 最小可用验证：一行命令从PDF到Markdown

docling自带命令行工具，安装完成之后可以直接在终端使用。先拿最简单的场景验证一下：

docling sample.pdf --to md

如果希望指定输出目录：

docling sample.pdf --output ./output_dir --to md

执行完成后，你会在输出目录里看到转换生成的Markdown文件，以及中间产生的JSON文件。那个JSON不是简单的提取结果，而是带着完整文档结构的DoclingDocument序列化结果，后面在代码里重新加载它也很有用。

我第一次跑通的时候，把一个双栏论文PDF转成Markdown，惊讶地发现阅读顺序竟然是对的——左栏从上到下读完，再切到右栏，不是左右两栏内容像拉链一样交错。这一点很多工具都做不到。

2.4 安装实战中遇到的两个坑

第一个坑是onnxruntime的版本兼容性问题。docling的模型推理依赖ONNX Runtime，如果你机器上已经装了其他版本的onnxruntime，可能会遇到模型加载时版本不匹配的报错。解决办法是尽量用干净的虚拟环境安装，让docling自己拉取匹配的版本。

第二个坑是CPU推理速度问题。纯CPU环境下，一个普通PDF页面可能需要一两秒到几秒不等，看页面复杂度。文件页数一多，总耗时就很可观。如果你只是偶尔转换几个文件，CPU完全够用；如果要接批量处理管道，建议上GPU或者对任务做并行化处理。

3. 核心概念：DoclingDocument到底在做什么

用命令行能跑通，但要在项目里真正用好docling，还是得理解它的核心数据模型。这部分看起来有点抽象，却决定了你后续怎么二次开发和接入上层框架。

3.1 从“页面”到“文档树”的转换过程

docling的处理流程可以拆成几个阶段。输入文件先经过页面栅格化或原生解析，得到页面图像和底层文本层；然后布局模型在页面图像上做目标检测，框出标题、正文、表格、图片、列表这些区域；接着表格结构模型对表格区域做单元格级的识别，重建出表格的行列结构；如果检测到扫描件或OCR标志，还会调用OCR引擎补齐文字；最后所有这些信息被汇集成一个DoclingDocument。

这个文档树才是docling的真正产品。所有下游输出，比如Markdown、HTML、纯文本、JSON，都是从这棵树上导出的。

3.2 阅读顺序为什么重要

很多人忽略阅读顺序，但这对LLM效果影响特别大。以双栏论文为例，如果按物理位置从上到下直接拼接文本，右边栏第二行的内容会很突兀地插到左边栏第一段中间，模型根本读不出“上下文”。docling的布局模型在识别区域之后，会做一次阅读顺序的排序，保证输出的文本流符合人类阅读习惯。

实测下来，对于版面规整的双栏论文，它的阅读顺序恢复效果相当不错。对于分栏复杂的报纸杂志，偶尔还是会排序错乱，但总体正确率已经可以接受。

3.3 代码里怎么使用

命令行只是入口，更灵活的方式是在Python代码里直接用DocumentConverter：

from docling.document_converter import DocumentConverter source = "sample.pdf" converter = DocumentConverter() result = converter.convert(source) document = result.document # 导出成各种格式 markdown_text = document.export_to_markdown() html_text = document.export_to_html() plain_text = document.export_to_text() json_data = document.export_to_dict()

这里能看到docling的工程设计思路：内部统一用DoclingDocument，对外暴露多种导出方法，方便你对接不同的下游系统。比如做RAG时，你可以选择导出成Markdown，利用它的标题层级语义；做全文检索时，可以导出成纯文本，去掉格式噪音；做数据交换时，直接导出成JSON，保留完整结构。

DoclingDocument的层级结构还可以让你有选择地提取内容。比如只想要某个章节的文本，或者只想要表格数据，可以自己遍历文档树，而不是拿到一整块Markdown再去正则捞。

3.4 模型背后的一点背景

docling的布局模型是基于DocLayNet等数据集训练的，DocLayNet本身是一个大规模文档版面标注数据集，覆盖论文、报告、说明书等多种文档类型。这也是为什么它对学术论文、技术文档这类规整版面表现特别好——训练数据里这类样本多。

理解这一点很有用：当你拿到的文档类型和它的训练数据分布偏离较大时（比如古旧书籍、手写笔记、特殊设计感杂志），就不要期待它有很高的识别准确率。工具再强，也有能力边界。

4. 实际效果：三份典型文档跑下来的对比

光看文档和模型说明，不如亲手跑几份典型文档。我拿自己手头的三份文件做了个粗测：一份单栏技术报告PDF，一份双栏学术论文PDF，一份带复杂表格的扫描版报表。这里不是严谨的评测，只是一些直观感受。

4.1 单栏技术报告：基本不用操心

单栏文档是最理想的场景。docling对标题层级的识别很到位，一级标题、二级标题、正文段落、代码块都基本正确，导出的Markdown可以直接用。表格也能重建出完整的行列结构，在Markdown里显示为标准管道表格。这一档属于“开箱即用”。

4.2 双栏学术论文：阅读顺序是最大亮点

双栏PDF过去是重灾区。我用一份两栏排版、带图表和参考文献的论文做了测试，docling输出的阅读顺序基本正确：先完整读取左栏内容，再切到右栏，没有出现左右穿插的情况。标题、摘要、段落层级也能对上。表格部分有个别跨页表格被拆成两个表格的情况，但语义上没有严重问题。

这一档的表现已经超过不少商业工具的免费解析效果了，重点是不花钱、本地跑、数据不出内网。

4.3 扫描版报表：能救急，但得人工核对

扫描版PDF没有原生文本层，必须依赖OCR。docling支持自动OCR，但在表格特别复杂的扫描件上，它的单元格识别会出现移位或合并错误。比如一行原本是[项目] [金额] [备注]，识别出来可能漏掉某一列的内容，或者把相邻单元格的内容串起来。

我用一份清晰度一般的扫描报表测试，整体文字能识别出来，但表格结构完整性只能算“七成可用”。这份文档如果直接进RAG，可能会导致问答时引用错误的单元格数据。

4.4 三类文档的感受总结

从表格可以看出，docling最顺手的地方是“电子版PDF的结构重建”，最需要留意的是“扫描件里的复杂表格”。这不是说扫描件不能用，而是要有预期管理：扫描件走完docling之后，最好设计一个人工复核环节，或者在构建知识库时对来源做标注，让下游对这部分内容的可信度有感知。

5. 接入RAG的正确方式：Loader、Exporter和分块器

命令行玩明白了，接下来就是正经工程问题：怎么把docling接进RAG流程。官方其实给了一条很顺的路，我把它拆开讲一下。

5.1 核心思路：让向量库拿到“有结构的文本”

RAG的检索效果很大程度取决于索引进向量库的文本质量。固定长度切分最容易实现，但经常把一句完整的话或者一个表格切成两半，导致检索到的片段语义不完整。docling的价值在于，它保留了标题层级和表格结构，你可以基于文档结构做“智能切分”。

最简单的方式是直接把转换结果导出成Markdown或纯文本，再用LangChain或LlamaIndex自身的文本分割器处理。这种方式能用，但没有发挥docling的全部价值。

5.2 LangChain接入示例

docling官方提供了LangChain的Loader封装：

from docling.langchain.docloader import DoclingLoader loader = DoclingLoader(file_path="sample.pdf") docs = loader.load() for doc in docs: print(doc.page_content[:200])

这个Loader把PDF直接转成LangChain的Document对象，page_content里是带结构的信息。之后再接RecursiveCharacterTextSplitter或者MarkdownHeaderTextSplitter都很方便。如果文档本身带有标题层级，用MarkdownHeaderTextSplitter能按章节边界切分，比纯按字符数硬切合理得多。

5.3 LlamaIndex接入示例

在LlamaIndex里我习惯直接通过export_to_markdown()把文档转成文本，再交给LlamaIndex处理：

from docling.document_converter import DocumentConverter from llama_index.core import Document as LlamaDocument converter = DocumentConverter() result = converter.convert("sample.pdf") dl_doc = result.document llama_doc = LlamaDocument( text=dl_doc.export_to_markdown(), metadata={"source": "sample.pdf"} )

这种方式的好处是，你能完全控制是把Markdown还是纯文本送入索引。比如某个场景里你只关心正文内容，不想把页眉页脚也索引进去，那可以先对DoclingDocument做内容过滤，再导出成文本。

5.4 用HybridChunker按文档层级分块

如果你不想自己写切分逻辑，docling还提供了一个名为HybridChunker的分块器，严格按照文档结构进行智能分块。它综合了文档标题层级和文本语义边界，能在“段落完整”和“块长度可控”之间找到平衡。

from docling.chunking import HybridChunker chunker = HybridChunker(max_tokens=512) chunks = list(chunker.chunk(dl_doc)) for chunk in chunks: print(chunk.text) print("---")

个人实际体验是，用HybridChunker分出来的块，比固定字符数切出来的块更适合RAG检索。因为每个块在语义上更完整，基本对应一个完整的小节或一个表格段落，检索结果不会出现“问了上半句、索引到下半句”的尴尬情况。当然，max_tokens要根据你的向量模型和Embedding窗口大小来调，别一口吃太满。

5.5 文档元数据和溯源

接入RAG时还有一个容易被忽略的点：元数据。docling转换出的文档对象带有来源页面、文件路径等信息，在构建向量索引时把这些信息作为metadata写入，后续做引用溯源会省很多事。比如用户问一个数据相关的问题，系统检索到某个表格块后，能直接定位到来源PDF的哪一页，这对企业知识库场景几乎是刚需。

6. 项目里用Docling要记住的几件实操事

工具好用，但不代表可以无脑冲。下面这些经验是我实际部署时才慢慢意识到的，分享出来希望你少走弯路。

6.1 模型缓存与离线环境处理

第一次运行会下载模型权重，这在联网环境没问题，但在内网部署或离线机器上就麻烦了。我的做法是在一台联网机器上先把模型跑起来，让权重缓存到~/.cache/docling目录下，然后把这个目录整体拷贝到离线环境，并设置对应的缓存路径。这样离线机器也能正常调用。

注意模型版本升级后，缓存目录里的权重可能被覆盖或新增。建议在升级docling版本后，重新跑一遍模型缓存预处理，避免新旧版本模型混用。

6.2 吞吐量瓶颈与并发策略

纯CPU模式下，一个PDF文件的解析时间可能在几秒到几十秒之间，具体取决于页数、分辨率和版面复杂度。如果要做批量转换，单进程串行跑几百份文件会非常痛苦。

实测下来，用多进程对文件列表做并行处理，吞吐量几乎可以线性提升。要注意每个进程都会加载一份模型，内存占用会成倍上涨。我遇到过8个进程直接吃满32G内存的情况。要根据机器配置控制并发数，别贪多。

如果你的机器有NVIDIA GPU，可以看看docling的GPU支持选项，推理速度提升非常明显。尤其是在表格识别和OCR阶段，GPU的优势会放大。

6.3 表格跨页问题要人工兜底

跨页表格是个老大难问题。docling对表格结构的识别能力已经很强，但遇到一个表格从第2页底部延伸到第3页顶部的情况，输出时可能会被拆分成两个独立表格。这两个表格在语义上本是一个整体，拆分之后，后续做表格问答或数据抽取就可能丢失一部分上下文。

我在实测中就遇到过这类情况，目前没有特别完美的自动解决方案。一个可行的兜底策略是：在文档后处理阶段，检测相邻表格的“表头是否一致”，如果一致，就尝试把它们合并，或者至少在元数据里标记“该表格可能在PDF中被跨页拆分”，让下游有感知。

6.4 识别复杂公式和图内文字时降低预期

docling对普通排版和表格很强，但公式识别并不是它的主打强项。数学公式转换成的Markdown/纯文本，往往达不到LaTeX那种精度，尤其是扫描版里的复杂公式，错漏很难避免。图内文字也一样，如果信息是以图片形式放在PDF里的，docling不一定会主动OCR图片里的文字（取决于OCR配置）。所以如果你的文档里公式密集、图表文字是关键信息，建议搭配专业的公式识别工具或者人工校对。

6.5 版本升级请谨慎：API变化比想象中快

这个我一定要说：docling的版本迭代速度不慢，API设计和模块结构在早期阶段有过调整。可能你网上看到的一段示例代码，在最新版本里就已经不能直接运行了，比如导入路径变了、函数名改了、输出目录结构变了。

我的习惯是在requirements.txt里锁定版本号，不要用“最新版”这类模糊策略。项目上线前把docling版本钉死，之后要升级，也得先在测试环境里完整跑一遍回归用例，确认输出格式没有变化之后再上生产。

6.6 处理失败任务要有重试机制

批量解析时一定会碰到个别文件转换失败。可能是PDF本身加密、页面损坏、模型推理超时，也可能是资源竞争导致内存不足。我在批量管道里加了失败重试机制：某个文件解析失败后，先记录下来，间隔几秒重试一次，连续失败三次才标记为“待人工处理”。

千万不要因为一个坏文件中断整个批量任务。docling单个文件解析失败通常不会影响整个进程，但批量逻辑里不做异常捕获，一个文件的报错就可能让整批任务停摆。

6.7 用缓存结果避免重复计算

文档内容不变的话，解析结果其实是固定的。我建议在批量处理时将解析后的JSON或Markdown落盘保存，下次相同的文件路径结合文件哈希命中缓存就直接读取，不用重新跑模型。这个优化对高频更新的知识库非常实用，尤其当文件总量上来之后，能省掉大量重复计算时间。

根据我个人的部署经验，一套稳健的docling处理管道应该是：文件路径去重 + 哈希缓存 + 多进程并发 + 失败重试 + 人工校验出口。把这几个环节做扎实，批量解析管道才算真正可交付。

项目从原型走到上线，最容易被忽视的永远是那些边缘情况：跨页表格、扫描件噪音、模型缓存、版本锁定。docling本身已经把“结构还原”这件事做到了很好的水平，剩下的工程化工作，更多是围绕它做好前置判断和后置兜底。我的体感是，它解决了我RAG链路里最头疼的结构解析问题，省下的时间足够我更好地打磨检索和生成端。