企业官网建设流程全解析

做知识库和RAG项目快三年，我最大的体会是：数据清洗阶段最磨人的永远是PDF。文本内容还好说，正则和切片能凑合用，但表格一出现，之前所有解析方案基本都要推倒重来。更别提那些扫描版PDF——页面上只有一张图片，没有文本层，普通解析库直接抓瞎。所以当我第一次看到IBM开源的docling时，我的第一反应是"又一个PDF转Markdown的玩具"。但实际跑了几个测试样本之后，我把它列入了文档解析方案的第一梯队。

docling做的事情，不是简单把PDF里的字符抠出来拼接成字符串，而是一整套文档转换链路：先做版面分析，识别出标题、正文、表格、图片这些结构区域，再按阅读顺序输出成Markdown、JSON或HTML，同时可选配合OCR处理扫描件。对正在做RAG、知识库、文档结构化、数据清洗这类工作的人来说，这个工具能省掉大量自己拼模型的活儿。这篇文章我从一个实际使用者的角度，把docling的安装、核心用法、实测效果，以及踩坑过程完整分享出来，希望能帮你少走弯路。

1. 为什么我从"用库抠文本"切换到"先建模再读取"

1.1 文档解析的真相：PDF本身没有"文字流"这个概念

很多人第一接触PDF解析时会很困惑：为什么PDF明明有文字，用PyMuPDF提取出来却是乱序的？原因在于PDF存储的是绘制指令，它只记录"在哪个坐标画什么内容"，并不记录"阅读顺序"。一个双栏的论文页面，物理坐标上左栏在上、右栏在下，提取出来的文字大概率会两栏交错。

更麻烦的是表格。PDF里没有"表格"对象，只有一堆线、框和文本块。渲染引擎不同，有的表格有线框，有的只有间距，有的甚至用背景色区分单元格。你很难用一套规则把它们全部搞定。

我之前的做法是组合拳：PyMuPDF提取文本、Camelot处理带线框的表格、Tesseract处理扫描件，最后再写一堆后处理逻辑。这套方案能跑通，但维护成本非常高，每个新项目都要重新调试一轮。

1.2 常见解析方案的局限

我整理了一下团队里实际用过的几类方案，它们的优缺点很明确：

单看某一项能力，每个工具都有自己的优势，但docling的优势在于它把"版面分析、元素识别、阅读顺序、结构化导出"整合在了同一个管线里。我不需要再自己写代码把这些工具串起来，它本身就是一条完整的流水线。

1.3 模型驱动带来的本质区别

之前很多方案是"规则驱动"：通过坐标、空格、字体大小来判断结构。规则驱动的问题在于，真实文档的多样性永远超出规则设计者的预期。

docling走的是"模型驱动"路线。它内置了版面分析模型，能识别标题、正文、表格、图片等区域；表格结构识别用的是TableFormer模型，专门还原表格的行列关系；扫描件场景则可以套用OCR引擎。模型的好处是泛化能力比规则强，遇到没见过的版式，规则可能直接崩溃，模型至少能给出一个接近的结果。

我在实际测试里验证过一个最痛的场景：两栏排版的双语论文，用坐标规则解析会输出乱序文本，而docling输出的Markdown基本保持了从左上栏到右下栏的正常阅读顺序。这个差异对RAG检索效果的影响是决定性的。

2. 安装和初始化：这工具的核心成本在模型

2.1 最小的安装方式

docling的安装没有想象的那么复杂，常规情况下一条pip命令就能解决：

pip install docling

如果你的文档涉及扫描件或者图片型PDF，需要用到OCR能力，建议先把OCR相关的依赖装好：

pip install docling[ocr]

这个扩展包会带上一批OCR运行时依赖。我个人建议从一开始就装OCR版本，因为后续你大概率会碰到扫描件，临时再补装依赖还得重启进程。

2.2 首次运行的模型下载过程

这一块是新手最容易困惑的。第一次执行转换的时候，docling会去模型仓库拉取权重文件，包括版面分析模型、表格识别模型，以及OCR模型。模型文件不算小，整个下载过程可能需要几分钟，取决于你的网络状况。

我当时第一次跑转换脚本，看到终端半天没输出，第一反应是"程序卡住了"。后来打开日志才发现它在后台静默下载模型。这里给你一个建议：

提示：新环境上第一次跑docling之前，最好是先跑一个极小的PDF文件，让它把模型权重完整下载到本地缓存。确认模型就位之后再做批量转换，否则批量脚本一开始可能大量时间花在等模型下载上。

模型下载完成之后会缓存在本地，同一个环境里后续再跑就不会重复下载了，这个不用担心。

2.3 依赖与版本：锁版本比追新更重要

docling的版本迭代节奏相当快，我印象中API在不同小版本之间都可能出现调整。比如配置类的导入路径、PdfPipelineOptions的字段，不同版本写法不一样。如果你是在团队协作项目里使用docling，强烈建议在requirements.txt里锁定版本号，别用不带版本限制的裸安装。

我踩过一个比较痛的版本坑：代码在1.x下跑得好好的，某次环境重建时装了最新版，结果一些导入路径直接失效，转换结果的数据结构也发生了变化。后面我会专门讲这个坑的排查过程。这里先记住一句话：docling的API是快速演进状态，生产环境必须锁版本。

另外，Python环境建议用3.10以上，旧版Python在个别依赖上容易碰到二进制轮子缺失的问题。如果是在虚拟环境里安装，基本不会污染系统环境，踩坑概率小很多。

3. 一次完整的PDF到Markdown转换拆解

3.1 十行代码跑通核心流程

不绕弯子，直接给最简示例。这是我从PDF到Markdown的最小可运行代码：

from docling.document_converter import DocumentConverter source = "sample_report.pdf" converter = DocumentConverter() result = converter.convert(source) doc = result.document with open("sample_report.md", "w", encoding="utf-8") as f: f.write(doc.export_to_markdown()) with open("sample_report.json", "w", encoding="utf-8") as f: import json f.write(json.dumps(doc.export_to_dict(), ensure_ascii=False, indent=2))

跑完之后你会得到两个文件：一个Markdown版本方便人和模型直接读，一个JSON版本保留文档的结构化信息。

这里有个小细节：converter.convert()的入参可以是本地文件路径，也可以直接传HTTP链接，docling会自动下载并解析。我平时会用这个能力快速抓取网页上的PDF报告做测试。

3.2 管线里究竟发生了什么

一个看似简单的convert调用，背后实际做了一堆事情：

• 页面栅格化：把PDF页面转成图像供模型识别
• 版面分析：识别标题、段落、表格、图片、页眉页脚等区域
• 表格结构识别：对表格区域进行行列检测，还原单元格归属
• 文本归属：把OCR或原生文本按照版面区域归类
• 阅读顺序还原：按照视觉顺序整理出正确的文档流
• 结构化导出：生成Markdown、JSON或者HTML

这些步骤在管线内部是串联执行的，每一步的输出都影响下一步的输入。理解这个链路对你的调参很有帮助。比如扫描件识别不准，问题可能出在OCR环节；表格行列错位，问题可能出在表格结构识别环节。你知道是哪一环出了问题，才能针对性地调整配置。

3.3 一个我常用的批量转换脚本

单文件转换演示完，实际工作里更常见的是批量处理目录里的PDF。我使用的批量脚本大概是这个思路：

import json import time from pathlib import Path from docling.document_converter import DocumentConverter converter = DocumentConverter() input_dir = Path("./pdfs") output_dir = Path("./outputs") output_dir.mkdir(exist_ok=True) failed = [] total_start = time.time() for pdf in sorted(input_dir.glob("*.pdf")): try: start = time.time() result = converter.convert(str(pdf)) doc = result.document (output_dir / f"{pdf.stem}.md").write_text( doc.export_to_markdown(), encoding="utf-8" ) (output_dir / f"{pdf.stem}.json").write_text( json.dumps(doc.export_to_dict(), ensure_ascii=False, indent=2), encoding="utf-8", ) print(f"OK {pdf.name} {time.time() - start:.1f}s") except Exception as exc: failed.append(pdf.name) print(f"FAIL {pdf.name} {str(exc)[:80]}") print(f"完成，共{len(failed)}个失败: {failed}") print(f"总耗时 {time.time() - total_start:.1f}s")

脚本关键点就两个：转换结果分别保底输出两份文件，一份Markdown一份JSON；失败文件单独记录，不会因为单个文件报错导致整个批处理中断。实际跑几百个文件的时候，最后能直接看到失败清单，再单独处理那些刺头文档。

4. 表格、扫描件、多栏版面：真实文档里的硬骨头

4.1 表格识别：从"丢线框"到TableFormer

表格是文档解析里公认的难点，docling在这块用的是TableFormer模型。这个模型的主要任务是还原表格的行列结构，把单元格和行列的关系真正建立起来。

我拿一份真实的财报PDF试过，表格有合并单元格、跨行项目，输出结果基本能还原出正确的行列关系。转换成Markdown后的效果类似这样：

| 项目 | 本期发生额 | 上期发生额 | | --- | ---: | ---: | | 营业收入 | 1,286.53 | 1,104.29 | | 营业成本 | 1,046.72 | 893.45 |

如果是用坐标规则去猜表格，遇到这种左对齐右对齐不一致的报表，出来的结果基本没法看。

不过也别神化TableFormer。我测下来，表格识别对原始PDF的渲染质量很敏感。如果表格线框比较淡、或者单元格间距混乱，识别出来就可能有行列错位。遇到这种情况，建议先确认原始PDF的分辨率是否足够，必要时先把PDF转成300DPI的高质量版本再喂给docling。

4.2 扫描版PDF：OCR的接入与语言配置

扫描件是传统解析方案最头疼的题型，docling通过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 = True pipeline_options.ocr_options.lang = ["en"] # 按需扩展语言代码 converter = DocumentConverter( format_options={ InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options) } ) result = converter.convert("scanned_report.pdf")

不同版本之间配置方式可能略有出入，但思路是一样的：打开OCR开关，指定语言。

这里特别提醒一句：语言代码不是随便写的，不同OCR引擎的代号规则不一样。比如EasyOCR中文是ch_sim，Tesseract中文是chi_sim。配置之前先确认你用的OCR引擎是哪家，再查对应语言代码，不然语言设置不生效，识别结果还是乱码。

4.3 多栏版面与页眉页脚处理

学术论文、行业报告里双栏甚至三栏排版非常常见。如果解析工具不识别栏结构，输出的文字会完全错乱。

docling的版面分析模型会识别栏位，并且按阅读顺序输出。我用一篇双栏英文论文测试，输出的Markdown段落顺序和人工阅读顺序基本一致，左栏读完才进入右栏。这个体验不是所有解析工具都能做到的。

页眉页脚这块需要留意一下。docling可以把页眉页脚识别为独立区域，但在Markdown导出里，页眉页脚有时候会混入正文。如果你的知识库只需要正文内容，建议在后处理阶段根据JSON的位置信息把页眉页脚排除掉，不要直接拿Markdown的完整文本去喂RAG。

5. 输出JSON到底好在哪：给RAG喂数据的正确姿势

5.1 DoclingDocument的数据结构

很多工具提供Markdown导出就完了，docling额外的价值在于保留了完整的文档结构化信息。通过export_to_dict()导出的JSON，内部组织成了一个文档对象树，包含文本块、表格、图片等元素，并且记录了两层关系。

文本块不只是字符串，还带有在页面中的区域信息；表格块里除了识别出的文本，还有行列网格信息；图片则保留引用位置。这一点对于做精细化的数据处理特别有用。

具体字段在不同版本里会有演进，我建议你拿到一份PDF跑一下，把输出的JSON打印出来看几个节点，比看文档理解的更快。

5.2 Markdown适合给人看，JSON适合给程序用

我平时对这两份输出文件的使用方式完全不同：

• Markdown：用来快速人工核对内容是否正确，也适合直接粘贴给LLM做问答
• JSON：用来做精确的切块、过滤、坐标追踪

举个例子，在RAG场景里，你可能希望"表格单独作为一个chunk，不跟段落混在一起"。如果用坐标提取的纯文本，你根本没法判断一段内容是表格还是正文。但用docling的JSON，每个元素自带类型标签，你直接按类型过滤，表格和非表格轻松分离。

5.3 基于输出做分块的实践思路

实际做RAG文档处理时，我的分块策略依赖于docling输出里的结构信息。基本思路是：

• 按标题层级切分正文段落，每个小节作为一个语义单元
• 表格单独抽取，作为一个独立的chunk，便于检索命中后以结构化形式传给LLM
• 图片先不参与文本检索，但保留引用关系，便于答案生成时辅助定位

这样处理后，检索的召回率和回答的准确性会比"无脑按字符数切块"明显更好。顺带一提，LangChain、LlamaIndex里都有对应的docling加载器，可以直接把docling的输出接进现有的检索管线，省得自己写适配代码。

6. 实操中踩过的坑和排查链路

6.1 模型下载不完整导致的诡异报错

有一次批量转换脚本在某个环境上报错，错误信息指向模型加载阶段，但日志里看不出是哪个模型。排查链路是这样走的：

先单独转换一个最简单的单页PDF，确认问题稳定复现。然后检查本地模型缓存目录，发现模型文件大小比预期小。清理缓存后重新跑了一次极简转换，这次日志显示完整下载了整个权重，后续转换恢复正常。

这个案例说明：遇到模型加载相关报错，先怀疑缓存不完整。删掉缓存目录重新下载通常能解决。

6.2 版本升级后API不兼容的完整排查过程

这是让我印象最深的坑。某次环境重建后安装了新版docling，原来的代码在导入阶段就报错。错误信息显示找不到某个模块。我的排查过程是：

1. 先看报错堆栈，确认是导入路径失效
2. 打印出已安装版本的版本号
3. 对比当前代码里的导入语句和官方示例里的写法
4. 在项目的GitHub Releases页面核对迁移说明

最终确认是新版重构了文档数据模型，旧的导入路径不再存在。解决办法是调整代码适配新版API，同时把依赖版本锁死。从那之后，我再也没有在未锁版本的环境里跑过docling批量任务。

6.3 大文档转换巨慢：判断瓶颈是模型加载还是推理

300页的PDF跑了好几分钟，这是正常的，但如果你判断不出卡在哪一步，就会很焦虑。我的排查方法是：

第一次转换后，立刻用同一个文件再转一次。如果第二次明显变快，说明第一次大部分时间花在模型加载上，这是正常的。如果两次耗时差不多，说明瓶颈在逐页推理，这时候需要考虑硬件能力，或者降低文档复杂度。

使用GPU机器的读者会有明显体感提升，尤其在表格识别环节，GPU和CPU的耗时差距可能达到数倍。如果是周期性的批量任务，建议优先安排有GPU的机器跑docling。

6.4 OCR语言没生效：不报错但输出乱码

有次处理一批中文扫描合同，设置看起来没问题，程序也不报错，但输出的文本全是乱码。排查链路是这样的：

先确认OCR开关确实打开了，发现配置没生效，输出没有走OCR路径。然后检查语言设置，发现当前OCR引擎不认zh这种写法，需要具体引擎的语言代码。最后查阅对应引擎的文档，换成中文对应的语言代码后重新转换，问题解决。

这条经验也是我前面强调的：OCR引擎的语言代码要按引擎各自的规则写，不能想当然填一个通用代码。

最后分享一点个人体会。如果你正在做知识库或RAG相关的文档清洗，我的建议是先用二十份覆盖不同难度的文档做小样本验证，覆盖普通文本、表格、扫描件、多栏版式这几类，确认docling在你的业务场景下表现稳定，再大规模铺开。它不是什么银弹，但作为一条文档解析的主干管道，能帮你省掉大量自己拼接工具的零碎工作。遇到识别不理想的情况，结合JSON输出做后处理修正，基本能处理掉绝大多数业务文档。