上周帮一个做知识库的朋友处理了几十份混合来源的PDF——有扫描件、有Word导出的、还有带复杂三线表的论文。他原来的流程是先OCR再手动贴进语料库结果排版乱、表格断、引用堆在一起光是清洗就花了两天。后来我直接上了docling一个晚上把全部文档转成结构化Markdown和JSON表格结构、标题层级、段落顺序基本不用二次修。朋友问这东西跟普通的PDF转文本有啥区别我说区别大了去了今天就把docling从原理到实操完整拆一遍。Docling是一个开源的文档转换与解析工具由IBM发布核心目标是把PDF包括扫描件、Word、PPT等文档变成机器能读懂的结构化数据而不是一坨纯文本。它最大的价值在于不是简单抽文字而是把版面、表格、阅读顺序、章节层级都重建出来直接对接RAG、知识库、文档比对、内容审核等下游任务。适合做文档解析、知识库构建、大模型语料预处理的人也适合不想再看OCR乱码文本的普通用户。1. Docling是个什么项目为什么文档解析这么难1.1 文档解析的真实痛点PDF像是电子纸先说清楚一个问题PDF在绝大多数人眼里是文档但在技术层面它更像是一张电子纸。PDF只规定了每个字符、每条线段出现在页面哪个坐标完全不告诉你这是一级标题这是表格第三行第二列这一段属于上一节的注释。早期做文档解析基本靠两类土办法。一类是直接用正则表达式抽文本碰上多栏排版、页眉页脚、跨页表格就全线崩溃另一类是调现成的OCR库识别扫描件但OCR出来的是纯文本流没有顺序、没有层级长文档根本没法用。我见过最离谱的一次有人拿Tesseract处理一份双栏论文结果左右两栏的文字在输出里交错混在了一起逻辑完全断裂。Docling要解决的就是这个问题它把PDF转文本升级成PDF转结构化文档对象。转换结果里每一段有它的类型标题、正文、表格、列表、引用、页眉页脚等表格有完整的行列结构标题之间有父子关系阅读顺序也是按人类实际阅读习惯重排后的而不是物理位置从上到下硬读。1.2 Docling在文档处理生态里的定位现在市面上做文档解析的工具不算少docling的独特点在于它的组合拳思路。它不是纯规则引擎也不是纯深度学习黑盒而是把一个完整的解析流水线拆成多个独立模型和模块分别处理布局分析识别页面的版面结构区分正文、标题、图片、表格、页眉页脚、页码等区域。表格结构识别自动重建表格的行、列、合并单元格、表头层级这是它最出名的能力基于TableFormer架构。OCR处理扫描件或没有文本层的PDF可插拔设计支持EasyOCR等引擎。阅读顺序重建把识别出的各个区域按逻辑顺序排序而不是简单按坐标。元数据抽取识别文档标题、作者、日期等关键信息。这些能力最终输出为统一的Docling文档表示Docling Document格式再按需导出为Markdown、JSON、HTML等。换言之docling给下游应用提供的是结构化输入而不是一堆文本让你自己再洗一遍。这个定位让它很适合嵌入RAG知识库的预处理环节。很多团队用LangChain或LlamaIndex做文档问答第一步Embedding之前文档清洗质量直接决定了召回效果。拿docling转出来的Markdown丢给Embedding模型比塞原始PDF文本要靠谱得多。2. 核心能力与技术管线拆解2.1 从PDF到结构化JSON一次转换发生了什么用docling处理一份PDF内部其实跑了一整条流水线。我按实际执行顺序拆给你看格式解析首先判断输入文档类型。PDF走PDF解析器Word、PPT、图片等各有对应解析器。这一步会先尝试提取文本层如果有文本就直接用没有就标记为需要OCR。布局分析对每一页做版面理解输出若干区域框每个框标注类型文字、标题、表格、图片、公式等和位置。这一环节由布局模型完成docling基于定制的LayoutModel。表格识别对于被标记为表格的区域进入TableFormer模型做精细的行列结构识别。它不只是画框而是重建出表格的语义结构包括单元格跨度、表头、内容对齐。OCR对扫描页或文本缺失区域执行OCR。docling支持可插拔的OCR引擎默认选项针对常见场景做了优化。阅读顺序排序把版面分析得到的区域按人类阅读逻辑排序。这里的重点是处理多栏布局、图表标题归属、脚注与正文关系等。组装为Docling Document把上述结果整合成带层级、带类型、带元数据的文档对象。这套流程走完之后你手里的就不再是页面图像文字而是一个结构完整的文档数据模型。从数据模型导出Markdown时标题会变成#、##层级表格会变成规范的管道表语法引用区域可以保留或丢弃。2.2 表格识别的看家本领TableFormer坦白讲我用过不少PDF转Markdown工具绝大多数在表格面前都是灾难。普通工具能把表格文字抽出来就算不错但行列关系一乱表格数据基本不能用于后续统计或入库。Docling的表格处理核心是TableFormer这是IBM开源的一个Transformer架构模型专门做表格结构识别。它的输入是表格区域的图像或对应布局特征输出是完整的HTML表格结构或类似表示。它能理解合并单元格横向合并、纵向合并都有处理能还原表头层级能判断哪些文本属于同一行、同一列。这给下游带来的好处非常实际转出的Markdown表格是正经表格粘贴进Notion、飞书或者数据库行列不歪数字不错位。我在测试中拿一份带多层表头的季度财报PDF跑过表头2023-Q1/Q2/Q3/Q4与营收/利润的嵌套关系转出来之后依然清晰。这一点对金融、科研、政务类文档特别重要。2.3 两种PDF处理模式怎么选PDF Mining与PDF MLDocling针对PDF文件提供了两套处理逻辑理解它们的区别能帮你避免很多坑对比项PDF Mining模式PDF ML模式处理方式完整流水线布局表格OCR重排基于PDF预训练文档模型直接推断表格识别走TableFormer结构还原能力强依赖模型内部分析复杂表格容易简化适用场景复杂版式、扫描件、强表格文档数字原生PDF、结构相对简单的文档速度相对慢更快资源占用更高更低简单说PDF ML模式适合干净的PDF——比如论文、报告这类排版规整的电子版追求速度时可以用。如果你的文档有大量复杂表格、扫描痕迹、多栏混排果断用PDF Mining模式。默认配置下docling会根据文档情况自动选择但手动干预时要知道这个区别。提示实际使用中如果是数字原生PDF且以文字段落为主PDF ML模式能节省不少时间但只要涉及表格或扫描页建议切回PDF Mining模式保结构完整比省那几秒钟重要得多。3. 本地跑通安装、命令行与Python API实操笔记3.1 环境准备与依赖安装Docling基于Python生态建议用Python 3.11及以上版本装起来省心很多。创建虚拟环境是基本操作别图省事直接装全局后面依赖冲突会让你怀疑人生。python -m venv docling-venv source docling-venv/bin/activate # Windows下用 docling-venv\Scripts\activate pip install docling装完之后可以顺手验证一下版本docling --version首次运行时会自动下载布局、表格等深度学习模型的权重文件模型默认从Hugging Face拉取所以第一次转换会等一会儿。这个属于正常现象不是卡死了耐心等就好。如果你在的网络访问Hugging Face比较慢可以提前配置镜像源或者设置本地缓存目录但这是环境问题跟docling本身无关。有些系统还需要额外的系统级依赖。比如在macOS上文件类型检测可能会用到libmagic建议直接用Homebrew装brew install libmagicLinux环境Debian/Ubuntu一般需要poppler-utils来辅助PDF解析sudo apt install poppler-utils3.2 Python API三行代码把PDF变成MarkdownDocling的Python接口设计得相当简洁。最基础的用法如下from docling.document_converter import DocumentConverter source example.pdf # 本地文件路径或URL都行 converter DocumentConverter() result converter.convert(source) # 导出为Markdown markdown result.document.export_to_markdown() with open(example.md, w, encodingutf-8) as f: f.write(markdown) # 导出为JSON json_output result.document.export_to_dict()如果你从没跑过docking这一套看到这个API可能会觉得就这么简单对就这么简单。DocumentConverter会按文档类型自动选择处理流程PDF走PDF流水线Word走Word解析图片走OCR。你不用自己判断文件类型也不用手工选择模型。想控制细节的话可以传入格式选项。比如你想关闭表格识别以提升速度或者反过来强制开启OCR这样配置from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions pipeline_options PdfPipelineOptions() pipeline_options.do_ocr False # 关闭OCR pipeline_options.do_table_structure True # 开启表格识别 converter DocumentConverter( format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) } ) result converter.convert(example.pdf)这里想提醒一个细节do_ocr False只对已有文本层的PDF有效。如果PDF本身是扫描件关闭OCR会导致后续处理拿不到文字输出可能是一片空。实务上的建议是先判断PDF是否包含文本层再决定OCR开关。你可以用PyPDF2或pdfplumber预扫一遍也可以直接开着OCR让docling自己判断。3.3 命令行用法与批量处理的取舍不写代码的时候docling也提供了命令行工具适合快速处理单个文档或批量导出。基本用法docling mydoc.pdf --to md --output ./out把当前目录下所有PDF批量转成Markdowndocling ./pdfs/*.pdf --to md --output ./out命令行工具的参数不算多常用的几个列出来参数说明--to导出格式md、json、html等--output输出目录--from指定输入格式不写则自动识别--pdf-backend选择PDF处理模式对应前面讲的Mining/ML--ocr开关OCR--table开关表格识别批量处理时我建议用Python API写个循环而不是命令行因为命令行每个文件都要重新初始化模型大量小文件时会有效率浪费。Python这边可以复用同一个converter实例模型只加载一次文档逐个喂进来吞吐量高不少。4. 进阶玩法chunking、切片、多模态与批量编排4.1 为什么RAG场景需要docling-chunking现在做RAG检索增强生成的人越来越多但很多人只顾着调Embedding模型忽视了文档切分这一层的质量。传统的按字符数切分比如每500字切一段会把表格腰斩、把标题和正文拆散、把连续的表格数据劈成两半最终导致召回内容语义不完整。Docling官方提供了一个配套组件docling-chunking专门基于Docling文档的结构化信息做语义化切块。安装方式pip install docling-chunking使用方式也很简单把前面转换得到的文档对象喂给切分器from docling.chunking import HybridChunker chunker HybridChunker( tokenizerBAAI/bge-small-en-v1.5, # 指定分词器按token数控制块大小 max_tokens512, overlap64 ) chunks chunker.chunk(result.document)这里的关键点是切分器不是按字符硬切而是按语义边界断句——优先保持一个段落、一个表格、一个列表项完整。一个128行的表格传统切分法可能切成四段每段都缺头少尾docling-chunking会把整个表格作为一个语义单位保留下来需要时再决定是否跨块引用。实测中这类切分方式对表格密集型文档的检索效果提升非常明显。4.2 自定义OCR与关键参数配置Docling的OCR模块是可插拔的。默认情况下文档若包含扫描页会自动调度OCR引擎。如果你的扫描质量很差、或者文档中英文混杂比例极高可以考虑调整OCR参数。比如显式指定OCR引擎时可以用类似方式from docling.datamodel.pipeline_options import EasyOcrOptions model_options EasyOcrOptions( lang[en, zh], # 根据自己的文档语言配置 use_gpuTrue ) pipeline_options.ocr_options model_options不需要每个参数都去调默认值但有两个值得注意。一个是语言列表lang要按真实文档内容配置中文扫描件不配zhOCR效果会很感人一个是GPU开关大批量处理时GPU加速能把效率拉高一个量级代价是显存占用。一般来说超过几千页的批量处理任务建议上GPU实例CPU硬扛太浪费时间了。其他值得调的参数包括pipeline_options.do_code_extraction是否单独识别代码块对技术文档有用pipeline_options.do_formula_extraction是否识别公式科研场景建议打开4.3 实测效果与精度评估参考虽然docling在多数常见PDF上表现不错但不是万能的。我拿不同类型文档做了个粗略的横向测试结果供参考文档类型布局重建表格还原文字抽取整体可用度数字原生PDF论文/报告优秀优秀优秀直接可用Word导出的PDF良好良好优秀基本可用扫描版PDF清晰良好良好良好需少量校对扫描版PDF模糊/歪斜一般一般一般建议先预处理手写批注混合文档一般一般较差不建议使用最理想的使用场景是文本层清晰版面规整表格结构化的数字原生PDF这种文档转出来几乎可以闭眼用。扫描件只要清晰度有保证OCR和表格也能做得不错但真遇到模糊、倾斜、手写混排的文档任何工具都救不了先把图像质量拉起来再说。5. 我踩过的坑和排查思路5.1 首次运行卡在模型下载OnlineMode与离线缓存很多第一次用docling的人都会碰到这种情况代码跑起来终端停在某个位置不动仿佛死机了。其实大概率是在下载模型权重docling的版面模型和表格模型默认从Hugging Face仓库拉取首次下载可能要下载几百MB到1GB不等的文件。我第一次跑的时候等了快十分钟一度以为是网络出了问题后来把日志级别调到INFO才看清是在下载模型。解决思路很简单提前手动把模型权重下载好配置本地缓存或者设置好网络代理让下载通道畅通取决于你的实际网络环境。另外docling支持离线模式如果你已经在某台机器上下载过模型可以把缓存目录拷贝到离线机器设置环境变量指向它之后就不需要联网了。5.2 内存与CPU占用过高批量处理时的性能调优Docling虽然功能强但跑起来也不算轻量。在我测试的机器上8核CPU、16GB内存处理一份30页的扫描版PDF内存占用一度冲到3GB以上CPU全部打满。这是正常现象因为布局模型、表格模型、OCR引擎都要吃资源但如果你有批量处理需求就得提前做性能规划。我调试后的几个优化手段实测有效控制并发数不要一次性把十几份PDF丢进进程池docling内部已经有并行逻辑外层再加太多并发会导致内存翻倍。关闭不需要的模块如果文档确定没有表格把do_table_structure关掉能省下TableFormer的算力开销。分页处理超长文档可以按页切分后分批转换避免单页过大的内存峰值。用GPU跑模型有条件就上GPU显存够的话在PdfPipelineOptions里不开CPU回退即可。5.3 处理复杂表格时的常见问题与规避办法用docling处理表格整体体验已经比市面上大多数工具好但也碰到过几次翻车场景列几个最常见的问题一表格被识别为普通段落。这种情况多发生在表格没有明显边框线、纯靠空格对齐的文档里。规避办法是让docling优先用PDF Mining模式不要用PDF ML模式因为ML模式对细粒度表格的理解相对粗糙。问题二合并单元格错位。跨多行的单元格偶发错位尤其是在复杂表头嵌套场景。这个坦白说没有完全规避的办法我实际操作中的做法是转完Markdown后对表格列数一致性做一次自动化校验不一致的地方标记出来人工复查。问题三OCR文字串进表格单元格。扫描件场景下偶尔OCR会把相邻单元格的内容串行。这个问题根源在OCR精度不在表格模型。我的经验是先把扫描件做一次图像预处理提升对比度、去噪点再喂给docling串行率能下降不少。5.4 版本迭代带来的行为变化Docling迭代速度不慢版本升级后某些API和默认行为可能变化。比如早期版本中options.do_ocr默认是False后来一版改成了根据PDF文本层状态自动决定。如果你参考的是网上老教程的配置代码在新版本上可能行为完全不同。我的建议是上线前固定版本把docling版本号写进依赖文件升级后至少跑一遍核心用例的回归验证重点看表格和OCR行为有没有变化。这个坑我踩过一次升级后一批文档的表格输出格式变了直接影响了知识库入库的质量回头排查才发现是版本行为变化导致的。写在最后的个人体会Docling不是银弹它解决的是把文档变成结构化数据这个环节的问题但文档清洗、质量校验、语料审核这些工程活还是得自己上。我目前的知识库处理流程是docling转Markdown和JSON → 脚本校验表格完整性 → docling-chunking做语义切块 → Embedding入库。这套流程跑了好几个月最大的感受是真正省时间的点不是省掉了写代码而是省掉了反复清洗脏文本的时间。如果你的文档解析需求集中在PDF、扫描件、Word混合场景值得花一下午把docling完整跑一遍比起在文本乱泥潭里挣扎这个投入太划算了。 
长河君 · 2026/9/26 14:33:01 · 阅读 1.2k Docling实战：从PDF到结构化数据的文档解析与知识库预处理指南
上周帮一个做知识库的朋友处理了几十份混合来源的PDF——有扫描件、有Word导出的、还有带复杂三线表的论文。他原来的流程是先OCR再手动贴进语料库结果排版乱、表格断、引用堆在一起光是清洗就花了两天。后来我直接上了docling一个晚上把全部文档转成结构化Markdown和JSON表格结构、标题层级、段落顺序基本不用二次修。朋友问这东西跟普通的PDF转文本有啥区别我说区别大了去了今天就把docling从原理到实操完整拆一遍。Docling是一个开源的文档转换与解析工具由IBM发布核心目标是把PDF包括扫描件、Word、PPT等文档变成机器能读懂的结构化数据而不是一坨纯文本。它最大的价值在于不是简单抽文字而是把版面、表格、阅读顺序、章节层级都重建出来直接对接RAG、知识库、文档比对、内容审核等下游任务。适合做文档解析、知识库构建、大模型语料预处理的人也适合不想再看OCR乱码文本的普通用户。1. Docling是个什么项目为什么文档解析这么难1.1 文档解析的真实痛点PDF像是电子纸先说清楚一个问题PDF在绝大多数人眼里是文档但在技术层面它更像是一张电子纸。PDF只规定了每个字符、每条线段出现在页面哪个坐标完全不告诉你这是一级标题这是表格第三行第二列这一段属于上一节的注释。早期做文档解析基本靠两类土办法。一类是直接用正则表达式抽文本碰上多栏排版、页眉页脚、跨页表格就全线崩溃另一类是调现成的OCR库识别扫描件但OCR出来的是纯文本流没有顺序、没有层级长文档根本没法用。我见过最离谱的一次有人拿Tesseract处理一份双栏论文结果左右两栏的文字在输出里交错混在了一起逻辑完全断裂。Docling要解决的就是这个问题它把PDF转文本升级成PDF转结构化文档对象。转换结果里每一段有它的类型标题、正文、表格、列表、引用、页眉页脚等表格有完整的行列结构标题之间有父子关系阅读顺序也是按人类实际阅读习惯重排后的而不是物理位置从上到下硬读。1.2 Docling在文档处理生态里的定位现在市面上做文档解析的工具不算少docling的独特点在于它的组合拳思路。它不是纯规则引擎也不是纯深度学习黑盒而是把一个完整的解析流水线拆成多个独立模型和模块分别处理布局分析识别页面的版面结构区分正文、标题、图片、表格、页眉页脚、页码等区域。表格结构识别自动重建表格的行、列、合并单元格、表头层级这是它最出名的能力基于TableFormer架构。OCR处理扫描件或没有文本层的PDF可插拔设计支持EasyOCR等引擎。阅读顺序重建把识别出的各个区域按逻辑顺序排序而不是简单按坐标。元数据抽取识别文档标题、作者、日期等关键信息。这些能力最终输出为统一的Docling文档表示Docling Document格式再按需导出为Markdown、JSON、HTML等。换言之docling给下游应用提供的是结构化输入而不是一堆文本让你自己再洗一遍。这个定位让它很适合嵌入RAG知识库的预处理环节。很多团队用LangChain或LlamaIndex做文档问答第一步Embedding之前文档清洗质量直接决定了召回效果。拿docling转出来的Markdown丢给Embedding模型比塞原始PDF文本要靠谱得多。2. 核心能力与技术管线拆解2.1 从PDF到结构化JSON一次转换发生了什么用docling处理一份PDF内部其实跑了一整条流水线。我按实际执行顺序拆给你看格式解析首先判断输入文档类型。PDF走PDF解析器Word、PPT、图片等各有对应解析器。这一步会先尝试提取文本层如果有文本就直接用没有就标记为需要OCR。布局分析对每一页做版面理解输出若干区域框每个框标注类型文字、标题、表格、图片、公式等和位置。这一环节由布局模型完成docling基于定制的LayoutModel。表格识别对于被标记为表格的区域进入TableFormer模型做精细的行列结构识别。它不只是画框而是重建出表格的语义结构包括单元格跨度、表头、内容对齐。OCR对扫描页或文本缺失区域执行OCR。docling支持可插拔的OCR引擎默认选项针对常见场景做了优化。阅读顺序排序把版面分析得到的区域按人类阅读逻辑排序。这里的重点是处理多栏布局、图表标题归属、脚注与正文关系等。组装为Docling Document把上述结果整合成带层级、带类型、带元数据的文档对象。这套流程走完之后你手里的就不再是页面图像文字而是一个结构完整的文档数据模型。从数据模型导出Markdown时标题会变成#、##层级表格会变成规范的管道表语法引用区域可以保留或丢弃。2.2 表格识别的看家本领TableFormer坦白讲我用过不少PDF转Markdown工具绝大多数在表格面前都是灾难。普通工具能把表格文字抽出来就算不错但行列关系一乱表格数据基本不能用于后续统计或入库。Docling的表格处理核心是TableFormer这是IBM开源的一个Transformer架构模型专门做表格结构识别。它的输入是表格区域的图像或对应布局特征输出是完整的HTML表格结构或类似表示。它能理解合并单元格横向合并、纵向合并都有处理能还原表头层级能判断哪些文本属于同一行、同一列。这给下游带来的好处非常实际转出的Markdown表格是正经表格粘贴进Notion、飞书或者数据库行列不歪数字不错位。我在测试中拿一份带多层表头的季度财报PDF跑过表头2023-Q1/Q2/Q3/Q4与营收/利润的嵌套关系转出来之后依然清晰。这一点对金融、科研、政务类文档特别重要。2.3 两种PDF处理模式怎么选PDF Mining与PDF MLDocling针对PDF文件提供了两套处理逻辑理解它们的区别能帮你避免很多坑对比项PDF Mining模式PDF ML模式处理方式完整流水线布局表格OCR重排基于PDF预训练文档模型直接推断表格识别走TableFormer结构还原能力强依赖模型内部分析复杂表格容易简化适用场景复杂版式、扫描件、强表格文档数字原生PDF、结构相对简单的文档速度相对慢更快资源占用更高更低简单说PDF ML模式适合干净的PDF——比如论文、报告这类排版规整的电子版追求速度时可以用。如果你的文档有大量复杂表格、扫描痕迹、多栏混排果断用PDF Mining模式。默认配置下docling会根据文档情况自动选择但手动干预时要知道这个区别。提示实际使用中如果是数字原生PDF且以文字段落为主PDF ML模式能节省不少时间但只要涉及表格或扫描页建议切回PDF Mining模式保结构完整比省那几秒钟重要得多。3. 本地跑通安装、命令行与Python API实操笔记3.1 环境准备与依赖安装Docling基于Python生态建议用Python 3.11及以上版本装起来省心很多。创建虚拟环境是基本操作别图省事直接装全局后面依赖冲突会让你怀疑人生。python -m venv docling-venv source docling-venv/bin/activate # Windows下用 docling-venv\Scripts\activate pip install docling装完之后可以顺手验证一下版本docling --version首次运行时会自动下载布局、表格等深度学习模型的权重文件模型默认从Hugging Face拉取所以第一次转换会等一会儿。这个属于正常现象不是卡死了耐心等就好。如果你在的网络访问Hugging Face比较慢可以提前配置镜像源或者设置本地缓存目录但这是环境问题跟docling本身无关。有些系统还需要额外的系统级依赖。比如在macOS上文件类型检测可能会用到libmagic建议直接用Homebrew装brew install libmagicLinux环境Debian/Ubuntu一般需要poppler-utils来辅助PDF解析sudo apt install poppler-utils3.2 Python API三行代码把PDF变成MarkdownDocling的Python接口设计得相当简洁。最基础的用法如下from docling.document_converter import DocumentConverter source example.pdf # 本地文件路径或URL都行 converter DocumentConverter() result converter.convert(source) # 导出为Markdown markdown result.document.export_to_markdown() with open(example.md, w, encodingutf-8) as f: f.write(markdown) # 导出为JSON json_output result.document.export_to_dict()如果你从没跑过docking这一套看到这个API可能会觉得就这么简单对就这么简单。DocumentConverter会按文档类型自动选择处理流程PDF走PDF流水线Word走Word解析图片走OCR。你不用自己判断文件类型也不用手工选择模型。想控制细节的话可以传入格式选项。比如你想关闭表格识别以提升速度或者反过来强制开启OCR这样配置from docling.document_converter import DocumentConverter, PdfFormatOption from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions pipeline_options PdfPipelineOptions() pipeline_options.do_ocr False # 关闭OCR pipeline_options.do_table_structure True # 开启表格识别 converter DocumentConverter( format_options{ InputFormat.PDF: PdfFormatOption(pipeline_optionspipeline_options) } ) result converter.convert(example.pdf)这里想提醒一个细节do_ocr False只对已有文本层的PDF有效。如果PDF本身是扫描件关闭OCR会导致后续处理拿不到文字输出可能是一片空。实务上的建议是先判断PDF是否包含文本层再决定OCR开关。你可以用PyPDF2或pdfplumber预扫一遍也可以直接开着OCR让docling自己判断。3.3 命令行用法与批量处理的取舍不写代码的时候docling也提供了命令行工具适合快速处理单个文档或批量导出。基本用法docling mydoc.pdf --to md --output ./out把当前目录下所有PDF批量转成Markdowndocling ./pdfs/*.pdf --to md --output ./out命令行工具的参数不算多常用的几个列出来参数说明--to导出格式md、json、html等--output输出目录--from指定输入格式不写则自动识别--pdf-backend选择PDF处理模式对应前面讲的Mining/ML--ocr开关OCR--table开关表格识别批量处理时我建议用Python API写个循环而不是命令行因为命令行每个文件都要重新初始化模型大量小文件时会有效率浪费。Python这边可以复用同一个converter实例模型只加载一次文档逐个喂进来吞吐量高不少。4. 进阶玩法chunking、切片、多模态与批量编排4.1 为什么RAG场景需要docling-chunking现在做RAG检索增强生成的人越来越多但很多人只顾着调Embedding模型忽视了文档切分这一层的质量。传统的按字符数切分比如每500字切一段会把表格腰斩、把标题和正文拆散、把连续的表格数据劈成两半最终导致召回内容语义不完整。Docling官方提供了一个配套组件docling-chunking专门基于Docling文档的结构化信息做语义化切块。安装方式pip install docling-chunking使用方式也很简单把前面转换得到的文档对象喂给切分器from docling.chunking import HybridChunker chunker HybridChunker( tokenizerBAAI/bge-small-en-v1.5, # 指定分词器按token数控制块大小 max_tokens512, overlap64 ) chunks chunker.chunk(result.document)这里的关键点是切分器不是按字符硬切而是按语义边界断句——优先保持一个段落、一个表格、一个列表项完整。一个128行的表格传统切分法可能切成四段每段都缺头少尾docling-chunking会把整个表格作为一个语义单位保留下来需要时再决定是否跨块引用。实测中这类切分方式对表格密集型文档的检索效果提升非常明显。4.2 自定义OCR与关键参数配置Docling的OCR模块是可插拔的。默认情况下文档若包含扫描页会自动调度OCR引擎。如果你的扫描质量很差、或者文档中英文混杂比例极高可以考虑调整OCR参数。比如显式指定OCR引擎时可以用类似方式from docling.datamodel.pipeline_options import EasyOcrOptions model_options EasyOcrOptions( lang[en, zh], # 根据自己的文档语言配置 use_gpuTrue ) pipeline_options.ocr_options model_options不需要每个参数都去调默认值但有两个值得注意。一个是语言列表lang要按真实文档内容配置中文扫描件不配zhOCR效果会很感人一个是GPU开关大批量处理时GPU加速能把效率拉高一个量级代价是显存占用。一般来说超过几千页的批量处理任务建议上GPU实例CPU硬扛太浪费时间了。其他值得调的参数包括pipeline_options.do_code_extraction是否单独识别代码块对技术文档有用pipeline_options.do_formula_extraction是否识别公式科研场景建议打开4.3 实测效果与精度评估参考虽然docling在多数常见PDF上表现不错但不是万能的。我拿不同类型文档做了个粗略的横向测试结果供参考文档类型布局重建表格还原文字抽取整体可用度数字原生PDF论文/报告优秀优秀优秀直接可用Word导出的PDF良好良好优秀基本可用扫描版PDF清晰良好良好良好需少量校对扫描版PDF模糊/歪斜一般一般一般建议先预处理手写批注混合文档一般一般较差不建议使用最理想的使用场景是文本层清晰版面规整表格结构化的数字原生PDF这种文档转出来几乎可以闭眼用。扫描件只要清晰度有保证OCR和表格也能做得不错但真遇到模糊、倾斜、手写混排的文档任何工具都救不了先把图像质量拉起来再说。5. 我踩过的坑和排查思路5.1 首次运行卡在模型下载OnlineMode与离线缓存很多第一次用docling的人都会碰到这种情况代码跑起来终端停在某个位置不动仿佛死机了。其实大概率是在下载模型权重docling的版面模型和表格模型默认从Hugging Face仓库拉取首次下载可能要下载几百MB到1GB不等的文件。我第一次跑的时候等了快十分钟一度以为是网络出了问题后来把日志级别调到INFO才看清是在下载模型。解决思路很简单提前手动把模型权重下载好配置本地缓存或者设置好网络代理让下载通道畅通取决于你的实际网络环境。另外docling支持离线模式如果你已经在某台机器上下载过模型可以把缓存目录拷贝到离线机器设置环境变量指向它之后就不需要联网了。5.2 内存与CPU占用过高批量处理时的性能调优Docling虽然功能强但跑起来也不算轻量。在我测试的机器上8核CPU、16GB内存处理一份30页的扫描版PDF内存占用一度冲到3GB以上CPU全部打满。这是正常现象因为布局模型、表格模型、OCR引擎都要吃资源但如果你有批量处理需求就得提前做性能规划。我调试后的几个优化手段实测有效控制并发数不要一次性把十几份PDF丢进进程池docling内部已经有并行逻辑外层再加太多并发会导致内存翻倍。关闭不需要的模块如果文档确定没有表格把do_table_structure关掉能省下TableFormer的算力开销。分页处理超长文档可以按页切分后分批转换避免单页过大的内存峰值。用GPU跑模型有条件就上GPU显存够的话在PdfPipelineOptions里不开CPU回退即可。5.3 处理复杂表格时的常见问题与规避办法用docling处理表格整体体验已经比市面上大多数工具好但也碰到过几次翻车场景列几个最常见的问题一表格被识别为普通段落。这种情况多发生在表格没有明显边框线、纯靠空格对齐的文档里。规避办法是让docling优先用PDF Mining模式不要用PDF ML模式因为ML模式对细粒度表格的理解相对粗糙。问题二合并单元格错位。跨多行的单元格偶发错位尤其是在复杂表头嵌套场景。这个坦白说没有完全规避的办法我实际操作中的做法是转完Markdown后对表格列数一致性做一次自动化校验不一致的地方标记出来人工复查。问题三OCR文字串进表格单元格。扫描件场景下偶尔OCR会把相邻单元格的内容串行。这个问题根源在OCR精度不在表格模型。我的经验是先把扫描件做一次图像预处理提升对比度、去噪点再喂给docling串行率能下降不少。5.4 版本迭代带来的行为变化Docling迭代速度不慢版本升级后某些API和默认行为可能变化。比如早期版本中options.do_ocr默认是False后来一版改成了根据PDF文本层状态自动决定。如果你参考的是网上老教程的配置代码在新版本上可能行为完全不同。我的建议是上线前固定版本把docling版本号写进依赖文件升级后至少跑一遍核心用例的回归验证重点看表格和OCR行为有没有变化。这个坑我踩过一次升级后一批文档的表格输出格式变了直接影响了知识库入库的质量回头排查才发现是版本行为变化导致的。写在最后的个人体会Docling不是银弹它解决的是把文档变成结构化数据这个环节的问题但文档清洗、质量校验、语料审核这些工程活还是得自己上。我目前的知识库处理流程是docling转Markdown和JSON → 脚本校验表格完整性 → docling-chunking做语义切块 → Embedding入库。这套流程跑了好几个月最大的感受是真正省时间的点不是省掉了写代码而是省掉了反复清洗脏文本的时间。如果你的文档解析需求集中在PDF、扫描件、Word混合场景值得花一下午把docling完整跑一遍比起在文本乱泥潭里挣扎这个投入太划算了。