最近测试了好几个文档解析开源项目最后留在工作流里的是Docling。这个工具能直接把PDF、Word、PPT、扫描件转换成Markdown和JSON而且对版面结构的还原做得相当细。在RAG、知识库构建、文档预处理这块它解决了我的一个长期痛点——以前用PyPDF或pdfplumber提取的文本经常是乱的标题层级丢失、表格错位、多栏混排更是家常便饭。Docling的优势在于它不是简单抽文本而是把文档版面、阅读顺序、表格结构、甚至公式都一并识别出来输出成干净的结构化数据。这篇文章我从实际使用角度拆一下它的核心能力、安装配置、代码实操、踩坑记录以及跟其他同类方案的对比给准备接文档预处理的朋友提供一个可以“抄作业”的参考。1. 项目核心定位与整体设计思路1.1 它到底解决什么问题先说说我为什么需要这类工具。做知识库的人都有体会喂给LLM的文档质量直接决定RAG效果。过去我处理PDF一般走这样的流程先抽文本pdfplumber或PyMuPDF再做正则清洗然后手动处理标题、列表、表格碰到扫描件还得先接OCR。这套流程的问题是文档一旦稍复杂一点就全线崩盘——双栏的PDF抽出来文本顺序是乱的表格变成了空格堆叠的无意义字符碰到带图片的说明文档图片信息完全丢失。整个环节消耗大量人工而且容易出错。Docling的思路不太一样。它会先对页面做完整的版面分析识别出标题、正文、表格、图片、公式这些区域理解它们之间的相对位置和阅读顺序然后再按照这种感知到的结构输出Markdown或JSON。也就是说它给文档重建了一套结构模型而不是简单地把字符拎出来。这种做法的好处是后续无论是向量化切片、按需检索、还是整篇喂给LLM文档的语义结构都在。1.2 为什么选Docling而不是其他方案有实力的同类方案我基本都试过了。PyMuPDF适合轻量文本抽取但版面分析能力弱LayoutLMv2这类模型方案效果好但部署复杂需要单独训练或下载大模型PaddleOCR专注中文OCR但文档结构还原并不擅长开源的Marker我曾在项目里用过几个月速度和效果都不错但商业许可限制比较严格。Docling相比之下有几个让我比较看重的点自带深度学习的版面分析模型DocLayNet能识别标题、正文、表格、图片等区域不依赖Adobe的API这类在线服务离线可用。表格结构由TableFormer模型专门处理能重建复杂表格的行列、合并单元格信息这一点非常关键。输出模型层做得干净支持Markdown和JSONJSON里保留阅读顺序和层级关系方便接后续逻辑。项目本身是MIT许可整合到商业项目里没有法律包袱。我在实际试用之后发现它的表格识别能力在开源方案里属于第一梯队比单纯用视觉模型去推理稳定得多。这是最吸引我的地方——表格往往是企业文档里信息密度最高的区域。1.3 核心模块组成Docling的工作流程可以拆成几个环节。PDF输入后先做解析PDF解析器页面图像进入版面分析模型识别区域语义角色和阅读顺序表格区域交给表格结构模型重建行列逻辑普通文本区域执行OCR增强如果需要最终由文档组装器把所有结果按统一数据模型拼接并输出两种格式。整体体感更像一条工业流水线而不是一个简单的文本提取脚本。有一点值得强调Docling的“文档图”概念。所有解析出的元素标题、段落、表格、图片、公式都带语义标签并且记录了元素之间的语义关系比如标题和正文之间的归属关系。这意味着你拿到的不是扁平markdown而是一棵结构树。对RAG切片来说能基于这一层做结构化感知的切片策略而不是傻傻地按字符数切。2. 安装与基础环境准备2.1 环境要求与依赖说明安装之前先说环境。Docling基于Python建议Python 3.10以上版本我用的是3.11。它依赖PyTorch深度学习模型推理、HuggingFace Transformers模型管理和OpenCV图像处理。这些依赖体积都不小建议在虚拟环境里装别直接污染系统环境。一个重要提示如果你不在安装前指定PyTorch的版本pip会根据你机器的CUDA情况自动拉一个默认版本。实测某些环境下pip会自动装CPU版或额外拉一个巨大的CUDA依赖导致安装时间飙升。我建议先单独安装PyTorch选好适合自己的版本。2.2 安装的两种方式和注意事项这里给出我实测过的两种安装方式看你自己的偏好。首先是直接pip安装适合想快速体验的人pip install docling这种方式安装特别省事一次性把核心依赖都装上安装完就能用。但如果你机器上已经有了一个PyTorch环境安装时最好注意一下版本冲突问题。第二种方式是从源码安装适合需要二次开发的人git clone https://github.com/docling-project/docling.git cd docling pip install -e .源码安装的好处是你可以修改源码并调试尤其是如果你要使用Docling暂未开放的内部接口或者想研究模型的调用细节源码就是最好的文档。缺点是安装时间稍长而且你需要自己处理依赖关系。我第一次折腾源码安装时也是小踩了几个坑比如某些依赖需要先单独装好torch、onnxruntime不然到最后会发现因为缺少某个包导致整体安装失败。2.3 模型文件的下载和缓存首次运行Docling时会自动从HuggingFace下载模型权重。如果你在的网络环境无法直连需要提前给HF_ENDPOINT设置一个可用的镜像站或者在项目代码里用local_files_only模式并手动把模型文件放到缓存目录。模型文件缓存默认在~/.cache/docling/modelsLinux环境Windows则在用户的.cache目录下。主要模型包括doclaynet版面分析模型负责识别页面的区域类型和阅读顺序。tableformer表格结构重建模型负责还原表格的行列和单元格关系。OCR相关模型当页面文本层缺失时使用。如果网络状况不够好建议提前下载好这几个模型再离线使用。我自己的做法是在部署Docling的机器上设置HF_HOME环境变量指向已挂载的磁盘然后在有网的前提下提前把模型跑一遍让缓存完整后切换到离线模式后续运行不再需要网络。3. 核心功能拆解从PDF到结构化Markdown3.1 基础用法一条命令完成PDF转换先来一个最简单的例子。给你设置一个真实的测试环境我用一份某互联网公司的公开财报PDF作为输入里面包含复杂的多栏排版、数据表格、图表文档约20页包含标题层级、目录和页脚。在Python中进行如下操作from docling.document_converter import DocumentConverter converter DocumentConverter() result converter.convert(test.pdf) print(result.document.export_to_markdown())运行完这段代码后在控制台会输出一大段带有结构标记的Markdown文本。这段代码的核心逻辑就是实例化一个转换器调用convert方法获取Document对象然后通过export_to_markdown()方法导出结果。在转换大型文档时处理速度是很多人关心的点。我的测试中一个包含28页、带大量图片表格的PDF在CPU环境下纯解析文本加版面分析大约需要30秒如果启用完整OCR则需要3分钟左右。如果你的服务器有NVIDIA GPU时间会压缩到一个可接受的范围。3.2 处理扫描版PDF和图片型文档很多PDF扫描件在数字化过程中没有生成文本层直接读取会得到一片空白。传统的做法是配合OCR软件先识别再导入到文档处理流程中。Docling对这种场景的支持是自动检测到页面缺少文本层后会触发OCR环节。from docling.datamodel.pipeline_options import PdfPipelineOptions pipeline_options PdfPipelineOptions() pipeline_options.do_ocr True pipeline_options.ocr_options.lang [en, zh] # 识别中英文混合文本 converter DocumentConverter(pipeline_optionspipeline_options) result converter.convert(scan_test.pdf)上面这段代码里我设置了OCR语言为英文加中文并列支持多语言混合文档识别。实际测试中它对印刷体中英文混排的扫描件识别效果不错表头、图表标注、甚至脚注都能够识别成可检索的文本。它内置的OCR引擎是EasyOCR如果想换用Tesseract可以通过ocr_options调整引擎类型。需要注意的是OCR是一个比较吃计算资源的操作。同一份扫描文档纯文本层提取只需要几秒OCR识别要花几分钟而且CPU占用率会明显升高。生产环境下建议做任务队列不要同步阻塞请求。3.3 表格识别能力实测表格识别是Docling产品的核心竞争力之一我重点测试了这份含大量报表的财报PDF。它通过TableFormer模型实现了表格重建最终输出到Markdown时表格会以标准管道符|格式呈现在输出中。下面是我从输出中抽取的一个真实表结构简化处理版| 项目 | 2023年度 | 2022年度 | 变动比例 | |------------------|----------------|----------------|------------| | 营业收入 | 12,586.30 | 9,870.12 | 17.72% | | 营业成本 | 8,210.42 | 6,510.03 | 15.39% | | 研发费用 | 1,982.34 | 1,256.44 | 11.86% | | 经营活动现金流 | 2,356.02 | 1,898.75 | -11.20% |这个表格在原PDF中是一个跨页的大型三线表包含合并单元格、表头多行嵌套。Docling基本上把它还原成了可以作为结构化数据分析的格式在保留原始信息方面表现很不错。处理复杂表格时有几点经验值得特别说明跨页表格Docling能将跨页表格的每个子部分拆开识别然后在输出中通过表格标题关联。但其处理的逻辑可能和我们预期不同经常会将每页上的表格分拆成多个表格而不是合并为一个。想拼接的时候可以通过表格的id以及页面信息进行关联再做二次合并。合并单元格识别时往往保留第一个有内容的单元格其他的会以空字符串或None形式表示。处理数据时需要注意对这类情况进行填充通常根据表格结构信息推断应该是和上述单元格内容一致。数字格式原始PDF里带逗号分隔的数字在转换后仍然保持原样如1,234.56。如果要批量做数值计算需要考虑先去掉分隔符这步在数据清洗环节作为小坑处理。3.4 阅读顺序Reading Order的处理技巧阅读顺序是很多文档解析工具不擅长的地方。以双栏PDF为例如果文本抽取算法按坐标从左到右截取那么文档会交叉呈现首行、第二行和第三列最终导致阅读顺序混乱。Docling通过版面分析给出的区域排序来解决此问题。它会评估所有区域的空间坐标、语义角色、类型研判出合理的阅读顺序。实测结果表明大部分双栏和三栏排版可以做到和原PDF阅读顺序一致的输出。这里举一个实际处理案例一份学术期刊PDF双栏排版非常严格包含摘要、引言、图注、参考文献等。通过result.document.export_to_markdown()输出的Markdown段落顺序与人类阅读顺序一致摘要先出现随后是正文左栏到右栏图注紧跟图片。没有出现左栏读一行跳右栏的错误。如果你在处理特殊排版例如报纸式的多米尼克骨牌布局时发现阅读顺序依旧不准确可以手动调整一些版面分析参数或者用Docling的JSON输出结构中每页的区域坐标信息重新做排序映射。这个工作稍微繁琐一些但比修改底层模型要可控。4. 实战操作用Docling构建RAG预处理流程4.1 一个完整的文档转换-to-JSON示例在实际RAG项目中我通常需要的不只是Markdown还需要结构化JSON来分块和向量化。Docling的JSON输出不只是文本的容器还保留了每个元素的坐标、层级、语义角色、阅读顺序、双向链接等丰富信息。看一个示例代码演示完整保存JSONfrom docling.document_converter import DocumentConverter from pathlib import Path converter DocumentConverter() result converter.convert(sample.pdf) doc result.document # 输出为JSON文件 output_dir Path(output) output_dir.mkdir(exist_okTrue) doc.save_as_json(output_dir / sample.json) # 导出Markdown with open(output_dir / sample.md, w, encodingutf-8) as f: f.write(doc.export_to_markdown())运行这段代码后输出目录会包含一个sample.json和一个sample.md。其中JSON文件的组织方式比较冗长根节点包含name、origin、furnishings等字段但不要被这些复杂的键名吓倒。在Docling的JSON数据模型里常用的字段如下text元素文本内容。label元素的语义角色值可能为title、paragraph、table、picture、page_header、page_foot等。prov来源信息包含页面号、页面尺寸等。parent当前元素对应的父级元素索引用于恢复层级树。在遍历JSON时一个常见需求是只取标题和正文文本忽略页眉页脚和页码信息。from docling.datamodel.base_models import TableCell import json with open(output/sample.json, r, encodingutf-8) as f: content json.load(f) for element in content[furnishings]: label element.get(label) text element.get(text) if label in [title, paragraph, table] and text: print(f[{label}] {text[:80]})这个代码可以过滤出需要的内容片段按需写入你的向量数据库中。实践中发现如果不加这个过滤页眉页脚和页码这些噪声信息可能会进入向量索引干扰语义检索的准确性。4.2 遇到大文档时的批处理和资源管理现实生产里系统要处理的PDF文件一般都有几十甚至上百页一次性加载庞大的文档会让内存飙升甚至导致OOM。解决的方法之一是分批处理。Docling的DocumentConverter没有直接提供批次ID控制接口但我们可以通过批量提交文件给转换器并设置合理的并发和分块策略来缓解。一个实用的批量处理代码from docling.document_converter import DocumentConverter from pathlib import Path converter DocumentConverter() pdf_files list(Path(./pdfs).glob(*.pdf)) batch_size 4 for i in range(0, len(pdf_files), batch_size): batch pdf_files[i:ibatch_size] for pdf_file in batch: result converter.convert(pdf_file) md result.document.export_to_markdown() output_file Path(./output) / (pdf_file.stem .md) output_file.write_text(md, encodingutf-8)以上代码中pdf_files首先被glob实例化为一个可迭代集合然后按每批4份进行转换。如果你的文档数量很大建议将结果直接写入磁盘保持数据的流动而非堆积。对于内存敏感型任务还可以手动关闭不需要的处理步骤如不需要图片提取时可以关闭图像渲染不需要OCR时设置do_ocrFalse来显著减少内存占用。这是我踩过多次坑后的实际经验默认配置覆盖能力最强但对机器性能的消耗也比较大。4.3 自定义输出只导出需要的部分有时你需要的不是整篇文档的Markdown而是某个特定标题下的内容。比如我在处理招标文件时只需要“技术方案”和“报价单”两个章节。Docling虽然不提供按标题直接截取文本的API但利用结构判断可以快速定位上下文。第3.4节里提到的JSON层级结构此时很有用。我们可以遍历根元素的子节点按label为标题的元素判断文本是否匹配目标关键词若匹配则把该标题对应的内容块及之后的段落一直聚合到下一个同等级标题之前。这种做法的稳定性已经过高频项目的实战验证。在复杂长文档中提取特定章节总体可靠只是在部分情况下遇到编号格式不一致如“1.技术方案”和“第1章 技术方案”并存时需要调整关键词匹配逻辑把匹配条件放宽成包含关系而非等值比较。5. 常见问题和排查技巧实录5.1 PDF加密和扫描件无法解析的解决方案我最初在使用时报过几次错大多是PDF加密或扫描件问题。对于密码保护的PDFDocling不会自动破解密码。可以在构造DocumentConverter或转换前用过第三方库解开限制。如果是复制、打印受限的PDF建议先用qpdf --decrypt这样的工具解除约束再交给Docling。扫描件的处理方法在前面已经提过需要在PdfPipelineOptions里显式将do_ocr设置为True否则它会返回空文本。实际使用中这个开关经常被忽略然后大家以为是不够“智能”而无效其实只是配置没开。5.2 表格识别结果错位的三个常见原因表格识别失败先别怀疑模型能力优先排查这三个点单元格边框极淡或没有边框TableFormer对没有明显边框线的表格识别鲁棒性会下降通常会输出完整行列但把内容嵌入相邻单元格形成错位。此时可以在扫描或生成PDF时尝试保留表格线或在后期把原始表格转成图片再输给Docling做OCR重建。单元格过大且内容空原表格在版面上是独立区域但Docling可能将其识别为图片。遇到这种情况检查输出的Markdown里是否出现了很多的![]()占位符且内容为空。解决办法是调整版面分析时的阈值或者把图片区域裁剪出来单独做OCR。合并单元格多且行列复杂能还原结构但部分单元格值是空的。可以根据JSON里的row_span、col_span属性在Post-processing阶段补全数据。5.3 依赖版本和安装时的坑依赖安装阶段有几个高频问题值得记录一是报libGL.so.1缺失。这是OpenCV的经典问题在Linux服务器尤其是精简版Docker镜像上几乎必现。解决方法是apt-get update apt-get install -y libgl1 libglib2.0-0 libsm6 libxext6 libxrender-dev二是transformers版本不兼容。Docling对新版本transformers适配有滞后如果你之前已经装过新版的transformers运行时会报一些奇怪的属性错误。最好按照项目要求的版本上限安装不要一味追求新版。三是模型下载卡住。如果网络不佳转换过程会一直卡在“Downloading model”阶段。建议提前下好模型释放到离线目录然后把转换器配置改成离线模式。5.4 和其他开源文档解析方案的横向对比Docling、Marker、PaddleOCR和Unstructured是几个开源方案里的常见选择我在这段时间里都试过从体验和结果上有个大致对比方案核心优势主要短板适合场景Docling表格还原极强JSON结构完整MIT许可模型体积较大OBJ模型复杂企业文档RAG、知识库、表格密集型文档Marker转换速度快文本精准表格能力一般商业许可不友好快速批处理、一般文档转MDPaddleOCR中文识别效果出色OCR能力强大版面结构感知弱布局还原不够纯中文扫描件、票据识别Unstructured数据清洗能力丰富支持多格式依赖在线API部分功能需要快速上手清洗数据的团队选型时不要只盯着“谁的效果更好”要结合团队对数据格式的需求、部署能力、许可合规、二次开发程度来决定。如果你做的是需要深度定制的企业服务Docling的模型层和JSON模型提供了更大的发挥空间。6. 进阶用法跟LangChain和深度学习流水线的集线6.1 Docling作为LangChain文档加载器LangChain生态里已经有Docling的集成通过langchain-docling包可以直接把转换结果加载成LangChain的Document对象。这个方法省去了中间文件写入的步骤from langchain_docling.loader import DoclingLoader from langchain_docling.loader import DoclingLoaderConfig config DoclingLoaderConfig(chunkingTrue, max_chunk_size1024) loader DoclingLoader( file_pathsample.pdf, configconfig ) docs loader.load()加载结果中的每个Document对象都带统一的文档层级标记item_type你可以根据它来过滤title、table、paragraph等元素。这样处理后切片策略可以根据元素类型做精细化调整——比如标题不能被截断表格必须完整存入一条向量正文可以按长度切分。6.2 在LLM分析表格场景里直接使用Docling输出另一个让我觉得好用的是在做财务文档问答时Docling输出的表格Markdown可以直接喂给LLM。比如对表格进行“营收增长幅度”、“利润率变化”这类分析LLM能基于结构化Markdown直接推理不需要额外做很多文本转换。相比让模型从长文本里“找数据”这种方法准确率高得多也不容易产生幻觉。在RAG的召回环节里我还会把表格转换成自然的描述文本如“2023年营业收入为12586.30万元同比2022年增长17.72%”存入知识库作为额外字段这样在向量检索的时候更灵活。Docs直接输出的Markdown表格向量化后有时因为格式字符影响召回精度因此可以在索引写入前使用Prompt对原文重新生成描述性段落。6.3 嵌入到Docker服务中的部署参考生产部署时我使用一个简单的FastAPI应用包装Docling以REST接口提供文件上传、转换、下载功能。为避免每次请求重新加载多GB模型非常影响延迟和内存我使用单例模式将DocumentConverter在进程内复用。启动时间重建模型约5-10秒每次转换的小文件在CPU上通常1秒以内完成整体表现稳定。个人经验在实际落地Docling的过程中我最大的体会是文档解析工具在使用过程中不要太“完美主义”。永远会有一些特变复杂的表格、极其奇怪的排版无法一次还原成功利用好它的结构化JSON输出做好后处理和修正闭环比追求一键完美转换更现实。它真正解放的是人工读取和手工标记文档结构的时间而不是彻底消灭所有格式转化的工程问题。如果你正在做企业知识库、合规文档分析或者智能客服问答Docling值得花一两天时间好好测试我相信你会得到和自己以前手工预处理方案完全不同的结构化体验。
