Docling：IBM 开源的文档解析引擎，把复杂 PDF 变成结构化数据

1. 这篇教程带你完成什么

从零搭一个能跑起来的 Docling 批量文档解析器：把一个装满 PDF 的目录丢进去，输出每个文件的 Markdown 正文 + 结构化 JSON，再顺手切成语义 chunk 准备喂给 RAG。全程本地跑，CPU 就行，不需要 GPU，也不需要任何云服务 key。

2. 前置条件

• Python 3.9 及以上，官方在 3.10 / 3.11 上验证最充分，3.8 会直接装不上。
• pip 23+，旧版 pip 解析 docling 的依赖树容易卡住。
• 磁盘预留 2–3 GB：模型权重（layout + TableFormer）首次运行会下载到本地缓存。
• 内存 8 GB 起步，处理上百页的 PDF 建议 16 GB，版面模型比较吃内存。
• 网络能访问 huggingface.co（或提前配好镜像），否则首次 convert 会卡住。
• Linux 服务器额外装 libgl1、libglib2.0-0，否则 opencv 导入报错。

3. 安装部署

3.1 建虚拟环境并安装

python3.11 -m venv .venv
source .venv/bin/activate          # Windows: .venvScriptsactivate
python -m pip install -U pip
pip install docling

3.2 预热模型（可选但强烈建议）

先把权重拉下来，避免第一次转换时误以为是卡死了。

docling-tools models download -o ./models
export DOCLING_ARTIFACTS_PATH=./models   # Windows: set DOCLING_ARTIFACTS_PATH=.models

3.3 验证安装

docling --version
docling --help

能看到版本号和 --to、--ocr、--table-mode 等参数就说明 CLI 起来了。

4. 第一个 Demo：批量 PDF → Markdown + JSON

第一步：准备素材。建两个目录，放一两个 PDF 进去。

mkdir -p pdfs out
cp ~/Downloads/某份报告.pdf pdfs/

第二步：先用 CLI 快速验证单个文件跑得通。这一步只是确认环境没问题，不写代码。

docling --to md --output ./out --ocr false pdfs/某份报告.pdf
ls ./out

预期输出：out/某份报告.md，打开应该能看到标题、段落和表格（Markdown 表格语法）。

第三步：写批处理脚本。核心 API 只有三行：建 Converter、convert、导出。

# convert_batch.py
from pathlib import Path
import json
from docling.document_converter import DocumentConverter

SRC, OUT = Path("pdfs"), Path("out")
OUT.mkdir(exist_ok=True)

converter = DocumentConverter()          # 复用同一个实例，别在循环里 new

for pdf in sorted(SRC.glob("*.pdf")):
    result = converter.convert(pdf)
    doc = result.document

    md = doc.export_to_markdown()
    (OUT / f"{pdf.stem}.md").write_text(md, encoding="utf-8")
    (OUT / f"{pdf.stem}.json").write_text(
        json.dumps(doc.export_to_dict(), ensure_ascii=False, indent=2),
        encoding="utf-8",
    )
    print(f"{pdf.name}: {len(doc.pages)} 页 -> {len(md)} 字符")

第四步：跑起来。

python convert_batch.py

预期输出类似 某份报告.pdf: 24 页 -> 38120 字符，out/ 下同时出现 .md 和 .json。JSON 里带阅读顺序、页码、元素类型，后续要定位引用出处就靠它。

第五步：切成 chunk，准备接 RAG。Docling 自带一个结构感知的切块器，不会把表格从中间劈开。

# chunk_demo.py
from docling.document_converter import DocumentConverter
from docling.chunking import HybridChunker

doc = DocumentConverter().convert("pdfs/某份报告.pdf").document
chunks = list(HybridChunker().chunk(doc))
print(len(chunks), chunks[0].text[:200])

预期输出：若干条 chunk 以及第一条的正文预览，每条 chunk 的 metadata 里保留了标题层级和页码。

5. 配置与调优

5.1 中文扫描件必须开 OCR 并指定语言

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions, EasyOcrOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

opts = PdfPipelineOptions()
opts.do_ocr = True
opts.ocr_options = EasyOcrOptions(lang=["ch_sim", "en"])

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=opts)}
)

纯文本 PDF 别开 OCR，慢好几倍且没有收益。

5.2 表格与图片：按需打开

opts.do_table_structure = True
opts.table_structure_options.do_cell_matching = True   # 单元格对齐更准
opts.generate_picture_images = True                    # 导出图片，供多模态用
opts.images_scale = 2.0                                # 2x 分辨率

只想快点出结果就用 CLI 的 --table-mode fast，追求表格质量用默认的 accurate。

5.3 资源控制：线程、批大小、设备

docling --to md --num-threads 8 --page-batch-size 4 --device cpu pdfs/某份报告.pdf

多页大文件把 --page-batch-size 调大能提吞吐，但内存会线性涨；显存不够或没有 GPU 时显式 --device cpu，比让程序自己探测稳。

6. 常见坑与排错

7. 下一步

• 接向量库跑通端到端 RAG：把 HybridChunker 输出的 chunk 灌进你惯用的向量库，重点验证"引用能回到原页码"，这是 Docling 相比纯文本抽取最值钱的地方。
• 换 VLM 管线处理极端版面：遇到多栏、公式、复杂表格混排的 PDF，可以切到基于视觉语言模型的 pipeline，代价是推理更慢、需要更强硬件。
• 起一个文档解析服务：用同项目的 docling-serve 把转换能力暴露成 REST 接口，前端上传、后端排队解析，就能从脚本升级成可部署的服务。