docling文档智能解析实战：从PDF到结构化Markdown的完整指南

最近公司在做文档智能解析相关的选型，核心诉求很直接：把各种格式的文档（PDF、Word、PPT、扫描件）转成结构化的Markdown或JSON，喂给我们内部的知识库和大模型应用。市面上工具不少，但要么收费，要么对中文支持不友好，要么解析出来的结构一塌糊涂。后来在GitHub上翻到IBM开源的一个项目docling，实测了一段时间，效果超出预期，这里把完整的踩坑过程和实操经验分享出来。

docling这名字可能有人不熟，但它的定位很清晰——把文档变成结构化数据，而不是单纯提取文字。项目由IBM Research开源，底层拆成了版面分析、表格结构识别、OCR、阅读顺序恢复等好几个模块，整体走的是深度学习模型+传统规则结合的路子。相比同类工具，它最大的优势是端到端跑通，一条命令或几行Python代码就能拿到高质量的结构化输出，而且完全本地运行，数据不出内网，这对很多企业场景来说是硬性要求。

这篇内容会从安装环境、核心API使用、输出格式细节、性能调优、常见问题等方面展开，包括我在实际测试中文PDF、复杂表格、扫描件时遇到的各种坑和解决办法。内容偏实操，尽量把关键参数和代码贴全，方便你直接抄作业。

1. 项目核心能力与适用场景

1.1 它到底解决什么问题

日常做文档解析，最烦人的几类场景：PDF里既有文字层又有扫描图片，表格跨页、合并单元格，双栏排版、页眉页脚混在正文里，公式、签名、印章乱入。传统方案用PyPDF2或pdfplumber只能拿到文本块和坐标，根本分不清哪段是标题、哪段是正文、哪个表格是完整的一块。

docling的价值在它对文档做了完整的结构化理解。它会先做版面分析，识别出标题、段落、表格、图片、公式这些元素，然后通过阅读顺序模型把它们按人类阅读习惯排序，最后输出成干净的Markdown或JSON。也就是说，它拿到的不是一坨文字，而是一棵有逻辑结构的文档树，这对后续接大模型做RAG、做知识抽取、做文档比对都非常关键。

我自己做过对比测试，同样一份包含多级标题、三栏表格、脚注的中文PDF，用pdfplumber提取出来是几十个乱序文本块，而docling输出的Markdown结构基本接近原排版，表格能还原成真正的Markdown表格语法，这个差距在实际项目中就是“能用”和“不能用”的区别。

1.2 支持哪些输入格式和输出格式

docling支持的输入格式比较全，日常办公场景基本覆盖了。我从官方文档和实测情况整理了下面的表：

输出格式主要是Markdown和JSON（Python里是dict对象），也支持导出为纯文本和HTML。Markdown适合给人看、适合直接进Markdown文档库；JSON适合程序化处理，比如做字段抽取、文档比对、进知识库之前的预处理。

这里有个值得专门说的点：docling只做文档解析，不做PDF生成。有些人会把它和ReportLab、WeasyPrint这类工具搞混，实际上它的定位非常纯粹，就是“读文档”，不是“写文档”。

2. 环境准备与安装

2.1 安装依赖与避坑指南

docling的安装方式官方推荐用conda建独立环境，原因很简单：它依赖的深度学习相关库比较多，放在系统环境里容易和已有包冲突。我自己在macOS和Linux服务器上都装过，Python版本建议3.10到3.12，装3.13可能会碰到某些依赖还没适配的情况，这点要先有心理准备。

conda create -n docling-env python=3.11 -y conda activate docling-env pip install docling

如果网络环境特殊，可以用国内镜像源加速：

pip install docling -i https://pypi.tuna.tsinghua.edu.cn/simple

装完之后验证一下：

python -c "from docling.document_converter import DocumentConverter; print('ok')"

能正常打印“ok”就说明装好了。这里提醒一个新手高频问题：如果你发现import报错，大概率是pydantic版本冲突。docling对pydantic的版本敏感，解决方案通常是把pydantic降到2.x的较新版本，或者升到docling要求的指定版本，具体以pip安装时提示的为准。

还有一个容易被忽略的点：docling首次运行某个模型时，会自动从Hugging Face下载模型权重到本地缓存目录。国内网络环境下这部分经常卡住，表现为程序跑起来后一直停在某个进度条不动。解决办法是提前把模型下载好，在命令行设置镜像环境变量（比如HF_ENDPOINT指向可用镜像），或者手动把模型放到缓存目录。模型路径一般在~/.cache/docling/models，不同版本可能略有差异，可以在代码里打印缓存路径确认。

2.2 模型加载机制与首次启动

docling的模型是一套组合，包括版面分析模型（Layout）、表格结构模型（TableFormer）、公式识别模型、OCR引擎。正常情况下，比如转一个普通的PDF，它会把布局模型和表格模型加载进来；如果是扫描版，还会额外加载OCR相关组件。

首次启动时模型下载时间可能比较长，这很正常。我建议第一次用docling时，先拿一个简单的PDF文件跑一遍，让它把该下载的模型都下载完，之后再跑正式文件就会快很多。这个预热步骤很值得做，可以避免在正式任务卡在“Downloading model...”半天不动。

模型加载过程中会打印一行行状态信息，有些小白用户看到一堆warning会吓到，其实大部分是无害的。比如缺少某个可选依赖，docling会提示“XX not found, using fallback”，这种情况下一般不影响核心功能。真正要关注的是“ERROR”级别日志，以及最终输出是否是空内容。

3. 核心API使用与实操

3.1 基础用法：三行代码转Markdown

docling的上手成本很低，核心就是DocumentConverter这个类。下面是最基础的一个例子：

from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("example.pdf") # 输出Markdown print(result.document.export_to_markdown()) # 输出JSON data = result.document.export_to_dict() print(data)

就这么简单。converter.convert()接收文件路径或URL，返回一个DocumentConversionResult对象，里面包含了解析后的Document对象。Document对象提供export_to_markdown()、export_to_dict()、export_to_text()等方法。

我的习惯是先把结果存成文件，方便人工检查：

from pathlib import Path result = converter.convert("example.pdf") md_content = result.document.export_to_markdown() output_path = Path("output") output_path.mkdir(exist_ok=True) (output_path / "example.md").write_text(md_content, encoding="utf-8") import json dict_data = result.document.export_to_dict() with open(output_path / "example.json", "w", encoding="utf-8") as f: json.dump(dict_data, f, ensure_ascii=False, indent=2)

这是最简单的用法，但实际项目中通常不会只转一个文件。我一般会写一个批量转换的小脚本，遍历整个目录，把PDF、Word、PPT全部转成Markdown，并保留相对路径的目录结构，方便后续统一入库。

3.2 进阶配置：控制OCR和模型行为

默认配置适合大多数场景，但如果你遇到扫描版PDF、图片文字识别不出来、或表格结构还原不完整的情况，就需要动PipelineOptions了。

from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.document_converter import DocumentConverter pipeline_options = PdfPipelineOptions() pipeline_options.do_ocr = True pipeline_options.ocr_options.ocr_engine = "easyocr" # 可选 easyocr / tesseract / rapidocr converter = DocumentConverter(pipeline_options=pipeline_options) result = converter.convert("scan.pdf")

关于OCR引擎的选型，我三个都试过，简单说说区别：

• EasyOCR：默认引擎，支持中文和英文，识别精度可以，但速度偏慢，对显存有一定要求
• Tesseract：老牌OCR，需要单独安装tesseract-ocr系统包，速度快一点，但对复杂版面识别能力稍弱，中文需要额外下载语言包
• RapidOCR：基于PaddleOCR，对中文支持好，在CPU上表现也不错，适合不想折腾GPU的环境

如果你跑的是CPU机器，可以把do_ocr先关掉试一下，对于带文字层的数字原生PDF，默认不开启OCR反而更快更准。OCR只在处理扫描件时才需要开。我踩过的坑就是拿一个原生PDF开OCR，结果识别出来的文字反而变差了，因为模型会优先用OCR结果而不是底层文本层。

还有一个很有用的参数scale，用来控制解析时对页面图像放大的倍数，对于低分辨率PDF或复杂表格，适当调大可以提升识别率：

pipeline_options.scale = 3.0 # 默认通常是2.0，调大更精细但更慢

3.3 命令行方式快速转换

除了写Python代码，docling也提供了命令行工具。和Python调用等价，但胜在简单直接，适合快速验证。

docling example.pdf --to md -o ./output_dir

这条命令会把example.pdf转成Markdown，输出到指定目录。同样支持JSON：

docling example.pdf --to json -o ./output_dir

命令行工具在写自动化脚本或批量处理时很实用。比如Linux下用for循环批量转：

for f in *.pdf; do docling "$f" --to md -o ./output_dir done

不过命令行可以调的参数相对有限，如果你需要细致控制OCR引擎、分辨率、加速卡等配置，还是推荐用Python脚本。

3.4 GPU加速配置

docling支持用GPU加速，如果你的机器有NVIDIA显卡且装好了CUDA环境，可以在PipelineOptions里指定设备：

from docling.datamodel.pipeline_options import AcceleratorOptions, AcceleratorDevice pipeline_options = PdfPipelineOptions() pipeline_options.accelerator_options = AcceleratorOptions(device=AcceleratorDevice.CUDA)

至于CUDA版本的坑，我只提醒两点：一是PyTorch的CUDA版本必须和现有驱动匹配，二是用conda安装的PyTorch大概率自带CUDA运行库，可以直接用，但需要确认安装的是GPU版本而不是CPU版本。跑之前可以用nvidia-smi看驱动，再用python -c "import torch; print(torch.cuda.is_available())"验证PyTorch能不能调到GPU。

我在实际测试中，GPU加速对OCR类任务的提速非常明显，但对版面分析这类模型只能说略有帮助。如果你的主要瓶颈在表格识别，GPU的意义没有想象中那么大。

4. 常见问题与排查经验

4.1 转换结果乱码或文字缺失

这是遇到最多的问题，但原因却各不相同，不同场景的排查路径差别很大。我整理了最常见的三类：

第一，扫描版PDF没开OCR。这类PDF本质是图片，默认模式下解析出的文本为空，转换结果自然“看不懂”。解决办法是显式开启do_ocr=True，并配置好OCR引擎。

第二，模型下载不完整或缓存损坏。把~/.cache/docling/models目录删掉重跑一次，让docling重新下载。

第三，字体或特殊字符支持问题。这个比较难查，比如某些PDF嵌入了特殊编码的字体，提取出来的文字可能是乱码。这种情况下试试把页面渲染成图片再用OCR，虽然慢一点但往往能救回来。

4.2 表格识别结果不理想

docling的表格识别功能在同类工具里算强的，但遇到复杂表格还是会出问题。比如合并单元格很多的大表、跨页表格这种，TableFormer模型的输出偶尔会丢失部分行列或者把表格拆成多块。

我从自己的测试经验出发，给几个实用建议。首选方法是调整scale参数，把页面放大倍数提高，模型看到的细节更多，识别率会明显提升。其次是尽量保证PDF分辨率足够高，如果源文件本身就是模糊扫描件，可以先做图像增强再转PDF。最后是做好人工复核机制，对每张表格输出一个置信度标识，低于阈值就进入人工审查队列，这个在知识库生产流程中很有必要。

4.3 大文件转换内存溢出

一份几百页的PDF，尤其带图片和扫描件，很容易让内存飙升。docling内部会把模型加载进显存/内存，同时保留整篇文档的结构数据，规模一大就可能OOM（内存溢出）。

我的处理方案是按页拆分转换，比如用PyPDF2先把PDF按每10页切片，再逐个转换，转完合并Markdown：

from pypdf import PdfReader, PdfWriter reader = PdfReader("big.pdf") page_size = 10 for start in range(0, len(reader.pages), page_size): writer = PdfWriter() for page in reader.pages[start:start + page_size]: writer.add_page(page) with open(f"chunk_{start}.pdf", "wb") as f: writer.write(f)

这样内存占用会稳定很多。当然，如果你每页都转成图片做OCR，速度肯定会受影响，这是资源与效率的取舍。

4.4 一个很实用的批量重试机制

实际跑数据的时候，经常遇到几百个文件里有几个转换失败，失败原因五花八门，有的是文件损坏，有的是格式太特殊。我写了一个带重试和错误记录的逻辑：

import time import traceback from pathlib import Path from docling.document_converter import DocumentConverter converter = DocumentConverter() fail_list = [] def convert_file(path: Path, retry: int = 3): for attempt in range(retry): try: result = converter.convert(str(path)) md = result.document.export_to_markdown() output_path = Path("output") / path.with_suffix(".md").name output_path.write_text(md, encoding="utf-8") return True except Exception as e: print(f"第{attempt + 1}次尝试失败: {path} - {e}") time.sleep(2) fail_list.append(str(path)) return False pdf_files = list(Path("input").glob("*.pdf")) for pdf_file in pdf_files: convert_file(pdf_file) print("转换失败列表:") for f in fail_list: print(f)

这个脚本是我在日常处理批量文件时一直在用的模板，加了重试机制、错误隔离和失败清单，稳很多。有些问题文件重试一次就能过，节省了不少人工盯watching的时间。

5. docling在项目中的定位与扩展建议

5.1 它在RAG管线里扮演什么角色

如果你在做大模型知识库相关项目，docling非常适合放在文档预处理阶段。整个RAG管线通常是从文档入库开始，再到切片、向量化、存储、检索，最后是生成回答。docling处理的是最前面这一段，把非结构化的PDF格式转换成结构化的Markdown。

把Markdown喂给切片器，和把纯文本喂给切片器，切片质量完全不在一个档次。Markdown里天然保留了标题层级、表格结构和列表关系，切片时可以按照标题切分，表格可以保持完整，这样检索时命中内容的上下文质量高很多。docling官方文档里也提供了和Chunking链路衔接的示例，用的DoclingDocumentChunking方法，可以让我自定义切片策略。

我目前的落地场景是政企客户的知识库，积累了大量PDF格式的制度文件、技术手册、验收报告。这些文档来源各异，有印刷扫描件、有系统导出的原生PDF、有办公软件转换出来的假PDF。docling是我目前测过的所有开源方案里，对这种混合来源支持最稳的。

5.2 和其他文档解析工具的对比

为了帮大家做选型，我把几个主流方案拉出来对比过。商业方案Like LlamaParse确实能在解析效果上更强，但价格不便宜，而且通常需要把文档传到对方服务器，这在很多企业数据安全规范下是行不通的。docling免费、开源、本地跑，产品路线上更稳。

同类开源工具里，MarkItDown或者unstructured也常被拿来和docling比较。我的体感是：对于版式简单、文字型PDF，几款工具差距不大；但对于包含复杂表格、双栏排版、图片文字混排的文档，docling的结构化完整度明显胜出。这样差异主要来自TableFormer模型和版面分析这一整套专门的深度学习pipeline。当然，这个优势也带来一个代价——模型体积大，第一次部署要下载几百MB文件，运行时对CPU或内存消耗也比轻量工具高。

5.3 后续扩展方向

docling项目本身还在快速迭代中，社区也比较活跃。我个人判断它后续会在几个方向继续演进：一是支持更多语言和更复杂版面的模型优化，二是增加更多文档类型的解析能力，三是和更多RAG框架做深度集成。

如果你要在自己的项目里引入docling，我建议先花半天时间把官方仓库里的examples跑一遍，包括PDF转Markdown、批量处理、OCR配置这几个典型场景。跑通之后再结合你的业务格式，做一个格式适配层，让docling解析结果能直接对接已有的下游系统。

最后分享一个我在部署时踩过的小经验：docling长时间运行后偶尔会有内存泄漏的现象（也可能是某个模型库的问题），长时间批量处理时会越来越慢。我的对策是在批处理脚本里设置每处理N个文件就重启一次转换进程，或者用subprocess方式调用命令行工具，批处理完再自动退出。虽然粗犷，但确实有效。总的来说，docling是个值得投入的工具，尤其在你需要完全掌控文档解析链路、又不想被商业SaaS绑定的场景下，它的价值会体现得非常明显。