做RAG或者数据处理这块儿，文档解析永远是绕不开的坎。PDF转文本，听着简单，真上手才发现是一个无底洞：文本层和图片混排，表格解析完像一团乱麻，双栏论文读成一条直线，扫描件更是直接劝退。我一开始用的是pypdf加pdfplumber，勉强能用，但遇到复杂版面就是灾难。后来在项目里试了IBM开源的docling，才算把这条链路走顺了。这篇东西不是官方文档复述，是我在自己的语料库项目里实际跑完之后的完整经验，包括怎么安装、怎么调参、哪些地方会翻车，以及它跟普通PDF解析库的差距到底在哪。
如果你的目标是做RAG、结构化抽数、或者把一批历史PDF转成Markdown喂给大模型，那docling值得花一晚上研究一下。下面按我实际使用的路线来聊。
1. 为什么是docling：文档解析里最被低估的"结构感知"能力
1.1 传统PDF解析的三大噩梦
先盘一下传统方案的痛点。PDF这格式本来就不是为提取数据设计的，它只负责"长得像"，不负责"语义对"。用pypdf这类库去抽文本，遇到的第一类问题是内容碎片化：PDF里的文字往往按行、按块甚至按字符存储在对象流中，直接拼接出来的结果经常是段落错乱、列序颠倒，一段话被截成七八块。
第二类问题是表格完全读不懂。pdfplumber能通过坐标把单元格内容取出来，但遇到边框不全、合并单元格、跨页表格，它就彻底歇菜。我项目里有不少带复杂表头的财务报表，pdfplumber提取出来的结果需要自己写一堆坐标逻辑去拼，极其痛苦。
第三类问题是扫描件等于盲人摸象。没有文本层的PDF必须靠OCR，而OCR只是把图像变成文字，版面结构依然丢得干干净净。标题、段落、表格、页眉页脚全混在一起，后续做语义切分时越做越脏。
1.2 docling改变了什么
docling解决的核心问题不是"多一个解析库"，而是把文档变成了一个有结构的对象。它背后的思路是用深度模型对版面做完整的布局分析，识别标题、正文、表格、图片、公式等区域，同时恢复阅读顺序，再输出成干净的Markdown或JSON。也就是说，它做的不是"提取文本"，而是"理解版面"。
docling的底层模型组合大致包括：布局检测模型（负责识别区域类型）、表格结构识别模型（负责还原单元格行列关系）、可选的OCR引擎（负责处理扫描件），还有一个阅读顺序模块。这些模型被封装成一条pipeline，用户不需要分别调用模型，直接用DocumentConverter就能拿到结果。这种"开箱即用的完整管线"设计，在同类工具里非常少见。
2. 环境安装与模型档案：最容易在第一晚崩溃的环节
2.1 安装依赖与Python版本
docling目前以Python包为主，安装命令很简单：
pip install docling但别指望一句命令就万事大吉。它依赖的库不少，比如torch、transformers、ultralytics（YOLO系列模型）、pydantic、lxml、多个OCR相关库，在干净的容器里安装通常要几分钟。我推荐在Python 3.10到3.11的环境里跑，3.12也能用，但某些老版本依赖解析可能会出冲突。
如果遇到依赖冲突（尤其是torch和numpy版本问题），更稳妥的方式是先用venv或者conda建一个独立环境，再执行安装。我自己的做法是：
conda create -n docling python=3.11 conda activate docling pip install docling2.2 模型下载与缓存
第一次运行docling转换文档时，它会自动从Hugging Face下载一组模型文件。这些模型加起来可能有好几百MB，视网络情况可能需要几分钟。弹出下载进度的是hf_hub_download，文件默认缓存在~/.cache/huggingface目录。
如果网络不稳定，我建议提前用huggingface_hub把模型拉到本地，再通过环境变量指定缓存路径，避免每次初始化都在下载上卡壳：
export HF_HOME=/data/models/docling-models注意：docling的模型ID在代码里写死，它会根据你启用哪些功能选择对应模型。按需求优先下载也会省一点时间，比如只做扫描件OCR就只需要版面模型加OCR，不需要表格结构模型。但我实际使用中还是建议全量下载，不然后面开启某功能时还要临时拉模型，很影响批处理节奏。
2.3 CPU还是GPU：实测差距
docling支持GPU加速。如果机器有CUDA环境，安装好torch的GPU版本能明显提速。我的一台机器是RTX 3090，处理一张A4扫描页（300 DPI）大约0.5秒；用CPU跑的话，同样一页大概要4到6秒。如果是批量处理几百页，这个差距是致命的。
设置方式很简单，转换时用DocumentConverter后内部会自动检测CUDA，也可以手动传入设备参数。对于小文件和偶尔转换的情况，CPU也能忍受，但凡是超过50页的文档，我强烈建议用GPU。如果没有GPU，可以把批量任务拆开，并用下面的并发思路补一点性能缺口。
3. 核心API拆解：从PDF到结构化数据的完整链路
3.1 最简调用：两行代码跑通
docling最惊艳的地方是API足够简单。先看一个最基础的例子：
from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("sample.pdf") print(result.document.export_to_markdown())就这两行，它会返回一个转换结果对象，里面包含解析出的Document对象。export_to_markdown()会把文档里的标题层级、段落、列表、表格、代码块都转换成对应的Markdown语法。对于一份结构规整的论文或说明文档，输出基本可以直接拿去用。
如果你需要的是结构化数据，可以用export_to_dict()拿到JSON，里面是完整的元素树，包含每个元素的label、bbox（坐标）、text、层级关系等。这个JSON对于写程序二次处理非常友好。
3.2 转换流程内部发生了什么
虽然API只有一行，但底层管线有好几步：
- 输入解析：读取PDF每一页的原始内容，包括文本对象、图片、字体信息。
- 版面分析：通过YOLO类检测模型识别页面上各区域的位置和类型，比如标题、正文、表格、图片、页眉、页脚、页码。
- 阅读顺序排序：把检测出的区域按照人类阅读习惯排序，避免双栏或复杂排版下读串行。
- 表格结构识别：对标记为表格的区域进行行、列、单元格合并关系识别，还原出逻辑表格。
- OCR处理：当PDF没有文本层或内容太模糊时，对图片区域进行OCR文字识别。
- 组装输出：把上述信息组合成统一的Document对象，再按Markdown/JSON/HTML等格式导出。
这个过程最值钱的就是"阅读顺序排序"和"表格结构识别"。有了这两步，Markdown输出才能保持正确的语义顺序，而不是简单的坐标排序。
3.3 输出格式与用途选型
我日常常用的三种导出方式：
| 格式 | 方法 | 适合场景 |
|---|---|---|
| Markdown | export_to_markdown() | 喂给LLM做RAG，或人工阅读 |
| JSON | export_to_dict() | 程序化检索、结构化入库 |
| HTML | export_to_html() | 保留更多版式信息，后续转PDF |
实际用下来，RAG场景优先用Markdown，因为它天然压缩了冗余格式，又保留了标题层级和表格结构，对embedding模型友好。如果要做字段级抽取（比如合同里的金额），JSON更合适，因为可以按元素类型去精确定位。
3.4 参数调节：不要只默认跑
convert()方法可以接收一些选项，常用的是DocumentConversionOptions。举个例子，扫描版PDF默认会自动启用OCR，但如果你确认某个PDF有文本层且干净，可以关闭OCR来提速。
from docling.datamodel.base_models import InputFormat, DocumentStream from docling.document_converter import DocumentConverter, DocumentConversionOptions opts = DocumentConversionOptions( do_ocr=False, # 关闭自动OCR table_mode=True, # 启用表格结构化 ) converter = DocumentConverter() # 从文件路径转换 result = converter.convert("clean_text.pdf", options=opts)table_mode这个参数很关键。开启后，表格输出才带行列关系；关闭时表格内容会退化成纯文本堆叠。如果你处理的PDF里有大量复杂表格，务必保持开启。
docling还支持从字节流读PDF，方便和Web下载、数据库存储对接：
buf = get_bytes_from_somewhere() result = converter.convert(DocumentStream(filename="demo.pdf", stream=buf), options=opts)这个流式接口极大方便了把docling塞进已有服务管道。
4. 实测：不同文档类型下docling的真实表现
4.1 扫描版PDF：OCR救场的上限
我特意找了一份20年前扫描的行业报告来测。整份PDF没有文本层，只有300 DPI的扫描图片。docling会自动调用OCR引擎识别文字，同时保留版面结构。结果让我比较意外：正文识别率很高，表格基本还原，但某些老字体和公式区域会识别成乱码。
这里有个重要经验：**docling的OCR引擎依赖Tesseract（或可选的其他OCR库），但版面检测是深度学习模型驱动，所以OCR识别率和原图质量强相关。**如果你发现OCR文字质量差，建议先用OpenCV做图像预处理（去噪、二值化、对比度增强），再喂给docling，会比直接硬识别好很多。
官方默认的OCR语言是英文，中文支持需要额外安装chi_sim语言包。对中文文档，别忘了在OCR选项里指定语言参数。
4.2 双栏学术论文与复杂表格
我拿了一篇IEEE双栏排版论文来测试。传统的pdfplumber提取出来的文本会严重串栏，段落在两栏之间左右横跳；docling的输出则基本遵循"左栏从上到下、再右栏从上到下"的顺序逻辑，段落也保持完整。
表格方面，我用了一张包含合并单元格、表头跨行的统计表。docling输出的Markdown表格行数和列数基本正确，合并单元格会被拆成空值或用占位表示，没有出现行错位。但我也遇到一个局限：如果表格内嵌了图片或复杂公式，它们会被替换成占位框，不会百分百还原成表格单元格里的内容。
4.3 和传统库的对比
我拿同一份财报PDF（数字密集型的表格）跑了三个工具：
| 工具 | 表格结构 | 阅读顺序 | 扫描件支持 | 结构化JSON |
|---|---|---|---|---|
| pdfplumber | 部分 | 坐标排序 | 无 | 无 |
| pypdf | 无 | 基本乱 | 无 | 无 |
| docling | 强 | 模型排序 | 支持 | 有 |
这个表格不是说传统库没用。pdfplumber在精细坐标提取上依然有优势，如果你要精确读取某个区域的像素级内容，它会更灵活。但如果是"整份文档转成干净的语料"，docling的完成度明显高一个档次。
5. 避坑指南：我踩过的docling坑与排查链路
5.1 模型下载失败或卡住
docling第一次运行会拉模型，由于网络原因可能导致下载卡住或失败。排查思路是：
- 判断是不是模型文件不完整：删除
~/.cache/huggingface里对应模型文件夹，重新运行。 - 检查网络代理设置，确保
HuggingFace Hub能连上。 - 如果没法直接下载，用离线方式把模型下载好后放到
HF_HOME指定目录。
另外，docling的模型版本更新较勤，升级docling包之后可能会要求重新下载新版模型，不要奇怪，这是正常现象。
5.2 OCR引擎的依赖问题
实际跑扫描件时，我遇到最多的是tesseract未安装。docling在需要OCR时如果找不到外部OCR可执行文件，可能会静默退化为空文本或抛异常。排查链路：
# 先确认系统里有没有tesseract which tesseract # 没有就安装，Ubuntu为示例 sudo apt update sudo apt install -y tesseract-ocr # 中文语言包 sudo apt install -y tesseract-ocr-chi-sim安装后重启Python进程，再跑一次转换。如果还有问题，查看docling日志里OCR引擎的具体报错。这里有一个容易忽略的点：有些docling版本把OCR封装在docalyze或者easyocr这类后端里，你需要看日志确认用的到底是Tesseract还是其他引擎，按对应后端去补依赖。
5.3 大文档的内存和耗时优化
处理一本几百页的书时，docling会一次把模型加载进内存，同时保留所有页面的解析中间结果，内存占用轻松突破4GB。优化策略我总结了几条：
- 用
DocumentConversionOptions里的一些开关，减少不必要的处理项，例如不需要图片内容时可以把图像提取关掉。 - 对大PDF按页拆分处理。docling支持
DocumentStream按页切割传输，比如用pypdf把每20页切成一个临时块，循环处理再合并Markdown。避免一次加载全本。 - 如果是GPU环境，适当调小批量大小（内部没有直接暴露，但可以通过降低图片缩放参数减少显存压力）。
我实际处理一本约600页的扫描书时，用GPU单批次全量处理直接OOM，后来按每30页切段跑，耗时从不可完成降到约8分钟，内存稳定在3GB以内。
5.4 多进程并发时的模型加载冲突
做批量任务时，我一开始图省事用multiprocessing起8个worker，每个worker初始化一个DocumentConverter。结果发现模型重复加载导致显存直接爆炸。更好的方案是：
- 每个进程只初始化一次converter，然后循环处理多个文件，不要每处理一个文件就创建一次。
- 如果单个文件也很大，优先用单进程内的流式切分，而不是多个进程同时跑。
- 如果机器没有GPU，可以用
concurrent.futures.ThreadPoolExecutor来做I/O并发，但模型推理部分是CPU密集，线程提升有限，多进程+限制并发数更可靠。
6. 工程化落地：docling与RAG/LLM流水线的实际整合
6.1 批量文档处理脚本骨架
这节是我项目里的一个脚本简化版，可以直接抄着改：
from pathlib import Path from docling.document_converter import DocumentConverter converter = DocumentConverter() def to_markdown(pdf_path: Path): result = converter.convert(str(pdf_path), options=DOCLING_OPTS) md = result.document.export_to_markdown() out_path = pdf_path.with_suffix(".md") out_path.write_text(md, encoding="utf-8") return out_path # 遍历目录下所有PDF for pdf in Path("data/pdfs").glob("*.pdf"): try: to_markdown(pdf) except Exception as e: print(f"[FAILED] {pdf}: {e}") # 记日志，发告警，具体看你项目需要加上错误捕获和日志后，这条脚本能稳定跑整夜。如果遇到个别打不开的损坏PDF不会中断其他文件的流程。
有一点要注意：**docling保存的Markdown文件编码默认UTF-8，但在Windows下写文件时需要显式指定UTF-8，不然中文会乱码。**此外，Markdown里的图片路径默认是相对路径，如果后续要把文档库迁移到别处，最好用图片内嵌或单独导出附件。
6.2 利用JSON做结构化检索
对于需要精准检索的场景，我会同时导出JSON：
doc_dict = result.document.export_to_dict()拿到这个字典后，可以根据元素的label过滤出表格或标题，甚至可以按坐标区域做二次处理。比如在一份年报里，我想抽所有表格，代码就这样写：
for element in doc_dict["elements"]: if element["label"] == "table": process_table(element)这种结构化方式比从Markdown里正则匹配表格稳定得多。因为docling显式给每个元素打了标签，RAG需要按域检索时，这个标签非常值钱。
6.3 我的配置模板
最后分享一套我目前稳定使用的配置组合（在RAG场景下）：
- 开启表格结构化：
table_mode=True - 关闭图片导出：通过选项关闭，减少中间表示体积
- 扫描件开启OCR，语言按文档类型切换
- 导出格式：同时导出Markdown和JSON，Markdown喂给embedding，JSON用于字段定位
这套组合跑了一个月，处理了上千份文档，准确率虽然谈不上100%，但整体可用性远高于之前的自研解析流程。
docling的版本迭代也比较快，我之前用的API和现在写的可能略有出入。遇到方法名或参数变化，优先看官方仓库的example目录，那里有最新的调用示例。工具毕竟是工具，真正稳妥的还是建立一套自己的验证集，每次换版本就把典型文档重跑一遍，确认输出没有劣化再上生产。
