1. 为什么 RAG 的瓶颈从来不在模型而在文档解析做过 RAG 项目的人大概都有过这种体验向量库搭好了检索链路跑通了大模型也接上了Demo 演示时效果惊艳可一旦换成真实业务文档回答质量立刻断崖式下跌。很多人第一反应是去调 embedding 模型、换 rerank 策略、加 query 改写折腾一圈发现提升有限。问题往往不在检索和生成而在最前面那一环——文档解析。RAG 的本质是先把知识喂给模型再让模型基于知识回答。这里的喂字决定了整个系统的上限。如果解析出来的文本是乱的章节标题和正文混在一起表格被拆成一行行散字页码、页眉、页脚全被当成正文塞进向量库那么后面无论用多强的模型检索出来的都是垃圾。业内有个说法叫 garbage in, garbage out在 RAG 里体现得淋漓尽致。我接触过的 RAG 项目里文档解析环节吃掉的时间经常占到整个项目的一半以上。PDF 有扫描版和文本版之分Word 有各种嵌套样式PPT 里全是文本框Excel 的合并单元格能把结构彻底打乱更别提合同、招标文件、实施方案这类格式极其复杂的文档。传统做法是针对每种格式写一套解析脚本PDF 用 PyPDF2 或 pdfplumberWord 用 python-docxPPT 用 python-pptx然后自己写规则去清洗、分块、补元数据。这套方案能跑但维护成本极高格式一变就得改代码而且很难保证跨格式的一致性。IBM 开源的 Docling 就是冲着这个痛点来的。它的定位很明确用一个统一的工具把各种格式的文档解析成结构化的、带语义信息的统一表示直接对接下游的 RAG 和 Agent 流程。标题里说的最痛的一环指的就是文档解析这个又脏又累但又绕不开的环节。Docling 想做的是让开发者不用再为每种格式单独造轮子把精力放回检索和生成这些更有价值的地方。这篇文章我会从实际使用角度出发把 Docling 的设计思路、核心能力、实操流程、踩坑经验完整拆一遍。不管你是刚接触 RAG 的新手还是已经被文档解析折磨过的老手应该都能从中找到能直接抄作业的部分。2. Docling 到底解决了什么问题从格式地狱到统一表示2.1 传统文档解析的三层困境要理解 Docling 的价值得先看清楚传统方案到底卡在哪。我把这些年踩过的坑归纳成三层。第一层是格式适配的困境。PDF、DOCX、PPTX、XLSX、HTML、Markdown、图片每种格式的解析逻辑完全不同。PDF 最麻烦它本质上是一种打印描述语言只告诉你每个字符画在页面的哪个坐标不告诉你哪段是标题、哪段是正文、表格的边界在哪。文本版 PDF 还能靠坐标和字体大小猜结构扫描版 PDF 就得先走 OCROCR 出来的文本又丢掉了版面信息。DOCX 虽然内部是 XML结构相对清晰但样式嵌套、文本框、页眉页脚的处理依然琐碎。PPTX 更极端内容全在文本框里阅读顺序都得自己推断。第二层是结构丢失的困境。就算把文本提取出来了章节层级、段落边界、表格结构、图片位置这些信息往往也丢了。而 RAG 恰恰需要这些信息来做分块和元数据标注。一个没有章节信息的合同你很难按条款切分一个表格被拍平成文本模型根本理解不了行列关系。很多团队最后只能退而求其次按固定字数硬切效果自然好不了。第三层是维护成本的困境。每种格式一套代码每个业务方一套规则文档格式稍微一变解析结果就崩。更麻烦的是这些解析脚本往往散落在项目各处没有统一的接口和输出格式下游的检索、分块、入库逻辑得为每种格式写适配层。项目一大这块就成了技术债的重灾区。2.2 Docling 的统一抽象思路Docling 的核心思路是把文档抽象成一个统一的中间表示我习惯叫它文档对象模型。不管你喂进去的是 PDF 还是 DOCX解析完都输出同一种结构一个文档对象里面包含页面、文本块、表格、图片、章节层级、阅读顺序、坐标信息等。下游的 RAG 流程只需要面对这一种结构不用再关心原始格式。这个抽象带来的直接好处是解耦。解析归解析分块归分块检索归检索每一层职责清晰。你想换解析器只要输出格式一致下游不用动你想改分块策略也不用回头去改解析代码。这种分层设计在工程上非常重要尤其是当项目从 Demo 走向生产时可维护性往往比一时的效果更关键。Docling 的另一个设计重点是保留语义结构。它不只是把文字抠出来还会识别标题层级、列表、表格、代码块、公式这些元素并给每个元素打上类型标签。这些标签在后续分块时极其有用。比如你可以按章节切分把标题作为该块的元数据表格单独成块保留其结构化表示图片可以走多模态模型生成描述。这些能力靠传统脚本拼凑也能实现但工作量和一致性完全不是一个量级。2.3 和同类工具的定位差异市面上做文档解析的工具不少比如 Marker、Unstructured、PyMuPDF 等各有侧重。Marker 在 PDF 转 Markdown 上做得很好尤其是学术论文这类排版规整的文档转换质量很高。Unstructured 覆盖面广支持格式多但结构化程度和一致性参差不齐。PyMuPDF 更偏底层适合做定制化处理但需要自己写大量逻辑。Docling 的差异化在于它把面向 RAG 的结构化解析作为一等目标。它输出的不只是文本而是带层级、带类型、带坐标的结构化文档并且原生支持导出成 Markdown、JSON 等下游友好的格式。它还内置了对表格结构的识别和还原这对合同、财报、招标文件这类表格密集的文档非常关键。另外Docling 对阅读顺序的处理比较讲究多栏排版、图文混排的文档也能给出合理的顺序这一点在真实业务文档里比想象中重要。需要说明的是没有哪个工具是万能的。Docling 在复杂版面和结构化输出上优势明显但如果你的场景只是简单的纯文本 PDF用更轻量的方案可能更划算。工具选型永远要结合具体场景后面我会专门讲怎么判断。3. 核心能力拆解Docling 凭什么能统一处理3.1 多格式统一入口与解析管线Docling 最直观的能力是提供了一个统一的入口来接收各种格式。你不需要为 PDF 和 DOCX 写两套调用代码它内部会根据文件类型自动路由到对应的解析器。这个设计看起来简单但背后需要把不同格式的解析结果归一化到同一套数据结构工作量不小。它的解析管线大致分几个阶段。先是格式识别和预处理比如 PDF 会先判断是文本版还是扫描版扫描版会触发 OCR 流程。然后是版面分析识别页面上的文本区域、表格区域、图片区域并推断阅读顺序。接着是元素识别把文本区域进一步细分为标题、正文、列表、代码块等。最后是结构组装把页面级的元素按阅读顺序和层级关系组装成文档级的结构。这个管线里版面分析和阅读顺序推断是最难的部分也是决定解析质量的关键。多栏排版的 PDF如果阅读顺序搞错提取出来的文本就是左右栏交错完全没法读。Docling 用了基于视觉和布局的模型来做这件事比纯规则的方法鲁棒性高不少。当然模型也不是万能的遇到特别奇葩的版面还是可能出错这点后面会讲怎么排查。3.2 表格识别与结构化还原表格是 RAG 文档解析里最容易被低估的难点。很多人以为表格就是一堆文字提取出来就行但实际上表格的价值在于行列关系。一个财务表格如果丢掉了行列对应关系提取出来的数字就是一堆无意义的字符串模型根本没法用。Docling 对表格的处理分两步。第一步是检测表格区域判断页面上哪块是表格。第二步是识别表格结构包括表头、行、列、合并单元格等并还原成结构化的表示。它输出的表格不是简单的文本而是保留了单元格坐标和行列关系的结构可以导出成 Markdown 表格或 HTML 表格也可以导出成 JSON 供程序处理。这个能力在合同和招标文件场景里价值巨大。这类文档里经常有报价表、参数表、评分表如果表格结构丢了RAG 系统就没法准确回答第三项参数是多少这类问题。我实测下来Docling 对规整表格的还原准确率相当高对合并单元格和跨页表格也有一定处理能力但复杂表格还是需要人工校验。3.3 阅读顺序与层级结构还原阅读顺序这件事没踩过坑的人意识不到它的重要性。我见过太多项目PDF 解析出来的文本顺序是乱的标题跑到正文后面脚注混进段落中间结果分块时把不相关的内容切到一起检索自然不准。Docling 在阅读顺序上做了不少工作。它会根据元素的坐标、字体大小、排版特征来推断合理的阅读顺序尽量还原人类阅读时的顺序。对于多栏文档它会先判断栏的边界再按栏内顺序读取。对于图文混排它会判断图片和周围文本的关系把图片放在合理的位置。层级结构还原同样关键。Docling 会识别标题的层级比如一级标题、二级标题、三级标题并在输出中保留这个层级关系。这个信息在分块时可以直接用比如按一级标题切分大块按二级标题切分小块标题文本作为块的元数据。这样检索出来的块自带上下文模型回答时也更容易定位。3.4 元数据与坐标信息的保留Docling 输出的每个元素都带元数据包括页码、坐标、元素类型、层级等。这些信息在 RAG 里有很多用途。页码可以用来做引用溯源用户问这个结论出自哪一页系统能直接给出页码。坐标可以用来做高亮在前端展示原文时把相关段落标出来。元素类型可以用来做过滤比如检索时排除页眉页脚。坐标信息在跨页表格和跨页段落的重组上也很有用。有些文档的表格跨了两页如果只看单页表格是断的。有了坐标和页码就能判断这两部分属于同一个表格做合并处理。这类细节在 Demo 阶段往往被忽略但到了生产环境用户对准确性的要求会高很多这些元数据就是提升体验的关键。4. 实操流程从安装到跑通第一条 RAG 管线4.1 环境准备与安装Docling 是 Python 包安装本身不复杂但有几个依赖需要注意。我建议用独立的虚拟环境避免和现有项目的依赖冲突。Python 版本建议 3.10 以上太低可能遇到兼容性问题。python -m venv docling-env source docling-env/bin/activate # Windows 用 docling-env\Scripts\activate pip install docling如果你需要处理扫描版 PDF还得装 OCR 相关的依赖。Docling 支持多种 OCR 后端具体装哪个看你的场景。一般来说装完基础包后第一次跑扫描版 PDF 时它会提示你缺什么按提示补装即可。提示Docling 首次运行时会下载一些模型文件体积不小建议在网络稳定的环境下操作并预留足够的磁盘空间。如果公司网络有限制提前把模型缓存目录配好。安装完成后可以用一个简单脚本验证是否正常from docling.document_converter import DocumentConverter converter DocumentConverter() result converter.convert(test.pdf) print(result.document.export_to_markdown())能正常输出 Markdown 就说明环境没问题。如果报错大概率是依赖缺失或模型下载失败按报错信息逐个排查。4.2 单文档解析与输出格式选择Docling 的输出格式有好几种选哪种取决于下游怎么用。Markdown 适合人看也适合直接喂给大模型结构清晰、可读性好。JSON 适合程序处理保留了完整的结构和元数据方便做分块和入库。HTML 适合前端展示能保留更多排版信息。我一般的做法是解析阶段导出 JSON保留完整结构分块阶段基于 JSON 做逻辑切分入库时把块文本和元数据一起存进向量库需要展示原文时再导出 Markdown 或 HTML。这样各环节各取所需不会因为格式转换丢信息。from docling.document_converter import DocumentConverter converter DocumentConverter() result converter.convert(contract.pdf) doc result.document # 导出 Markdown适合快速查看 markdown_text doc.export_to_markdown() # 导出 JSON适合程序处理 json_data doc.export_to_dict() # 遍历文档元素查看结构 for item in doc.iterate_items(): print(item.label, item.text[:50] if hasattr(item, text) else )遍历元素这个操作很实用能帮你快速了解文档被解析成了什么结构哪些元素被识别成了标题哪些是表格阅读顺序对不对。调试解析效果时这一步基本是必做的。4.3 分块策略与元数据注入解析只是第一步怎么分块直接决定 RAG 的效果。Docling 输出的结构化信息在这里派上大用场。我的经验是分块要尽量尊重文档的语义边界而不是机械地按字数切。具体做法是优先按标题层级切分一级标题下如果内容太长再按二级标题切段落作为最小单位不要把一段话从中间切断表格单独成块保留其结构化表示图片如果有描述也单独成块。每个块要带上元数据包括所属章节、页码、元素类型等。def chunk_by_structure(doc, max_chars800): chunks [] current_chunk {text: , meta: {}} for item in doc.iterate_items(): text getattr(item, text, ) label getattr(item, label, text) # 标题作为分块边界 if label.startswith(heading): if current_chunk[text]: chunks.append(current_chunk) current_chunk { text: text \n, meta: {section: text, type: heading} } else: current_chunk[text] text \n if len(current_chunk[text]) max_chars: chunks.append(current_chunk) current_chunk {text: , meta: current_chunk[meta]} if current_chunk[text]: chunks.append(current_chunk) return chunks这段代码是简化版实际用的时候还要处理表格、图片、页码等。核心思路就是利用 Docling 提供的结构信息让分块贴合文档本身的逻辑。这样切出来的块语义完整度高检索时命中率明显更好。4.4 接入向量库与检索验证分块完成后接下来就是常规的 RAG 流程生成 embedding、存入向量库、检索、拼 prompt、调模型。这部分和用其他解析工具没本质区别重点在于验证解析和分块的质量。我习惯做一个简单的验证准备一批问题跑检索看召回的块是否包含答案。如果召回不准先别急着调 embedding回头看看解析和分块有没有问题。很多时候问题出在源头比如表格没解析好、阅读顺序错了、分块把答案切断了。把解析质量提上去检索效果往往自然就好了。# 伪代码示意具体用你选的向量库和 embedding 模型 from your_vector_db import VectorDB from your_embedding import embed db VectorDB() for chunk in chunks: vector embed(chunk[text]) db.insert(vector, chunk[text], chunk[meta]) query 合同第三条约定的付款周期是多久 results db.search(embed(query), top_k5) for r in results: print(r[meta].get(section), r[text][:100])验证时重点关注两件事一是召回的块是否来自正确的章节二是块内是否包含完整答案。如果答案被切断说明分块粒度需要调整如果召回了错误章节说明解析的层级或阅读顺序有问题。这个排查思路能帮你快速定位瓶颈。5. 踩坑实录那些文档里不会写的经验5.1 扫描版 PDF 的 OCR 陷阱扫描版 PDF 是文档解析里最麻烦的一类。Docling 支持 OCR但 OCR 本身就有准确率问题尤其是中文文档、手写体、低质量扫描件。我踩过的坑包括OCR 把数字识别错导致财务数据全错把表格线识别成文字混进正文把页眉页脚也 OCR 进去污染内容。应对办法有几个。一是尽量拿到原始电子版扫描版是最后的选择。二是 OCR 后做校验尤其是数字和关键字段可以用规则或人工抽查。三是配置 OCR 时排除页眉页脚区域减少噪声。四是对于特别重要的文档OCR 结果要人工过一遍别全信自动流程。注意OCR 的准确率和你用的引擎、语言设置、图像质量都有关。中文文档建议明确指定中文语言包否则识别率会明显下降。5.2 复杂表格的还原失败Docling 对规整表格处理得很好但遇到复杂表格还是可能翻车。我遇到过的情况包括合并单元格识别错误导致行列错位跨页表格没合并变成两个断表表格里嵌套表格结构彻底乱掉无边框表格被当成普通文本。排查这类问题第一步是看 Docling 输出的表格结构确认它识别成了几行几列单元格内容对不对。如果结构错了可以尝试调整解析参数或者对这类表格做特殊处理比如单独提取后用规则修复。如果表格特别复杂实在修不好可以考虑把表格转成图片走多模态模型理解虽然成本高但准确率有保障。5.3 阅读顺序错乱的定位方法阅读顺序错乱的表现是提取出来的文本读起来不通顺段落之间跳跃标题和正文错位。定位方法是把解析结果和原文对照看哪些部分的顺序不对。常见原因是多栏排版、图文混排、脚注尾注干扰。Docling 的阅读顺序推断基于版面分析大部分情况没问题但遇到特别规整的多栏学术论文或者排版很花的宣传册还是可能出错。如果发现某类文档普遍顺序错乱可以看看是否有配置项能调整或者考虑对这类文档单独处理。实在不行导出时按坐标自己重排也是一种办法虽然麻烦但可控。5.4 大文档的性能与内存问题几百页的 PDF 解析起来很吃内存尤其是开了 OCR 之后。我遇到过解析到一半内存爆掉的情况也遇到过解析一个几百页文档要十几分钟的情况。这在批量处理时很要命。优化思路有几个。一是分批处理把大文档拆成小段分别解析再合并结果。二是关掉不必要的功能比如不需要 OCR 就别开。三是控制并发别一次性解析太多文档。四是如果只是做 RAG可以考虑只解析需要的章节不用全文解析。这些手段能显著降低资源消耗。5.5 常见问题速查表问题现象可能原因排查方向解决思路文本顺序错乱多栏排版、图文混排对照原文看错位位置调整版面分析参数或按坐标重排表格结构错误合并单元格、跨页表格检查表格行列和单元格内容单独处理复杂表格或转图片走多模态OCR 识别错误图像质量差、语言设置错抽查关键字段指定语言包人工校验关键数据解析速度慢文档大、开了 OCR看解析耗时分布分批处理关闭不必要功能内存溢出文档过大、并发过高监控内存占用减小批次降低并发页眉页脚混入正文未排除页眉页脚区域检查正文开头结尾配置排除区域或后处理过滤标题层级识别错字体样式不规整检查标题元素标签后处理修正层级或自定义规则这张表是我在实际项目中总结的覆盖了大部分常见问题。遇到问题时按表排查能省不少时间。6. 从解析到 Agentic RAGDocling 在完整链路中的位置6.1 解析质量如何影响下游检索很多人低估了解析质量对检索的影响。我做过对比实验同一批文档一份用粗糙的固定字数切分一份用 Docling 的结构化分块其他环节完全一样。结果结构化分块的检索命中率明显更高尤其是在需要定位具体条款、具体参数的问题上差距更大。原因不难理解。固定字数切分会把不相关的内容切到一起也会把相关内容切断。检索时向量匹配的是整个块块里噪声多了匹配精度就下降。结构化分块让每个块语义更纯粹向量表示更聚焦检索自然更准。而且结构化分块带的元数据还能支持按章节过滤、按类型过滤进一步提升精度。6.2 结构化输出对 Agent 流程的价值现在 RAG 往 Agentic RAG 方向走Agent 会自己规划、调用工具、多轮检索。这种场景下文档的结构化程度更重要。Agent 需要知道文档有哪些章节、每个章节讲什么、表格里有哪些字段才能做出合理的检索决策。Docling 输出的结构化文档可以直接转成 Agent 能理解的形式。比如把章节树喂给 Agent让它知道该去哪个章节找答案把表格结构喂给 Agent让它知道有哪些字段可以查。这种结构化的上下文比一堆平铺的文本块有用得多。我实测下来给 Agent 提供结构化文档信息后它的检索决策明显更合理无效检索少了很多。6.3 和 LangChain、LlamaIndex 等框架的配合Docling 本身不绑定任何 RAG 框架它的输出可以对接 LangChain、LlamaIndex 等主流框架。常见的做法是把 Docling 解析出的结构化文档转成框架的 Document 对象带上元数据然后走框架的分块、embedding、检索流程。这种配合方式的好处是灵活。你可以用 Docling 做解析用 LangChain 做编排用你喜欢的向量库做存储各取所长。需要注意的是框架自带的分块器往往不理解 Docling 的结构信息直接用可能浪费了结构化数据。我的建议是要么用 Docling 的结构信息自己做分块要么把结构信息转成框架能识别的元数据让框架的分块器利用起来。6.4 本地知识库场景的落地建议本地知识库是 Docling 很适合的场景。很多团队想把内部文档做成问答系统但文档格式杂、结构乱解析这关就卡住了。Docling 能统一处理多种格式输出结构化结果大大降低了落地难度。落地时我建议分几步走。先小范围试点选一批有代表性的文档跑通解析到检索的完整链路验证效果。然后根据试点结果调整分块策略和检索参数。接着扩大范围处理更多格式的文档补齐异常处理。最后做工程化把解析、分块、入库做成流水线支持增量更新。这个过程里解析质量的监控很重要要能及时发现哪类文档解析出了问题。7. 工具选型什么场景该用 Docling什么场景不该用7.1 适合 Docling 的典型场景Docling 最适合的场景是文档格式多样、结构复杂、对结构化要求高的 RAG 项目。具体来说合同、招标文件、实施方案、财报、技术手册这类文档格式复杂、表格多、层级深用 Docling 能省很多事。多格式混合的场景也适合比如一个知识库里有 PDF、Word、PPT 各种格式用 Docling 统一处理比每种格式单独写脚本划算。另一个适合的场景是快速验证。想快速搭个 RAG Demo不想在解析上花太多时间Docling 开箱即用能快速跑通链路。等验证完价值再考虑要不要针对特定场景做优化。7.2 可能不需要 Docling 的情况如果你的文档格式单一、结构简单比如全是纯文本 PDF或者全是格式规整的 Markdown用更轻量的方案可能更划算。Docling 的模型和依赖有一定开销简单场景用它有点杀鸡用牛刀。如果对解析速度要求极高比如要实时解析用户上传的文档Docling 的模型推理可能成为瓶颈。这种场景可能需要更轻量的解析方案或者做异步处理。另外如果团队已经有成熟的解析方案且效果满足需求也没必要为了新工具而迁移除非现有方案确实遇到了瓶颈。7.3 选型对比参考维度DoclingMarkerUnstructuredPyMuPDF格式覆盖广PDF/Office/HTML 等主要 PDF很广主要 PDF结构化程度高保留层级和表格中高偏 Markdown中格式间不一致低需自己处理表格处理强结构化还原中中弱阅读顺序较好好学术文档一般需自己处理上手难度低低中中高适合场景复杂文档 RAG学术 PDF 转换多格式粗解析定制化处理这张表是个人使用感受具体选型还要结合你的文档特点和团队情况。我的建议是如果拿不准先用 Docling 跑一批真实文档看看效果再决定要不要深入。8. 我个人的一些实操体会用 Docling 这段时间最大的感受是文档解析这件事值得认真对待。很多团队在 RAG 上投入大量精力调模型、调检索却忽略了最前面的解析环节结果事倍功半。把解析做扎实后面的环节会顺很多。另一个体会是没有银弹。Docling 很强但不是所有文档都能完美解析。复杂表格、扫描件、特殊排版还是需要人工介入或特殊处理。做 RAG 项目要有解析质量需要持续监控和优化的心理准备别指望一次配置就一劳永逸。最后分享一个小技巧建一个解析质量评估集选一批有代表性的文档人工标注正确答案每次调整解析或分块策略后跑一遍评估集看效果变化。这个习惯能帮你避免感觉变好了但实际没提升的情况让优化有据可依。文档解析的优化是个长期活有评估集在手方向会清晰很多。