企业官网建设流程全解析

我上周花了整整一个下午，把一份 54 页、全是扫描图片的合同文本从 PDF 里“抢救”了出来，靠的就是 docling。不是那种复制出来就乱码、排版稀碎的文本，而是标题、段落、表格层级清清楚楚的 Markdown。说实话，折腾各种文档解析工具这么久，docling 给我的感觉是把“能用”这条线拉高了一个量级。

这篇就从一个实际用户的视角，把 docling 的实现思路、安装细节、参数选择、常见坑位一次讲透。无论你是刚接触文档解析的新手，还是准备把它接进 RAG 管线和知识库的开发者，这篇文章都能帮到你。

1. 从“能打开”到“能用”：文档解析到底难在哪

1.1 三个层级：文本提取、结构还原、语义理解

很多人觉得解析 PDF 不是啥难事，一行PyPDF2跑完就有文本了。但真要把结果拿去做知识库或者喂给大模型，你会发现提取出来的东西根本没法用。

我习惯把文档解析拆成三个层级来看：

• 第一层，纯文本提取。把 PDF 里的字符抠出来，这步确实简单。可一旦遇到双栏排版、页眉页脚、跨页表格，字符顺序就乱了，读起来像天书。
• 第二层，结构还原。告诉机器哪里是标题，哪里是正文，哪几列属于同一个表格，段落之间的阅读顺序是什么。这个层级很多工具做不到，或者做得稀烂。
• 第三层，语义理解。把文档当人一样读懂，知道标题的层级关系、表格的表头含义、参考文献的归属。这部分需要模型能力，不单纯是规则匹配。

docling 给我最大的感受，就是它没有把“解析”只停留在第一层，而是靠一套流水线把第二层甚至部分第三层工作自动化了。它输出的结果里，正文是正文，标题是标题，表格被还原成 Markdown 表格语法，阅读顺序也是对的。

1.2 为什么常规工具总在“排版”上翻车

早些年我常用的方案是PyMuPDF加正则清理。遇到结构简单的文档还挺顺利，一旦碰到以下情况就崩：

• 多栏布局：页面被纵向切成两块，文本提取顺序从左栏一直串到右栏。
• 复杂表格：合并单元格、跨页表格、表头重复，提取出来全是碎片。
• 扫描件：整页是图片，没有文本层，必须先走 OCR。

docling 的做法不是单靠某一种算法硬刚，而是用“定位排版 + 版面分析 + 可选 OCR + 组装输出”的组合拳。它把版面分析这一步做得很重，先搞清楚页面上每个区域是什么角色——标题、正文、表格还是图片——然后再决定怎么输出。这种设计思路，从根上避开了乱序问题。

2. docling 的核心架构：一条流水线如何把文档拆明白

2.1 输入与输出：它到底能吃哪些格式

docling 不是只能处理 PDF。实际项目中，文档源千奇百怪，我经常要面对 Word 文档、PPT 讲义、Excel 报表混着来的情况。docling 目前的输入格式支持得很全：

输出侧，最实用的是 Markdown 和 JSON。Markdown 适合直接丢给大模型、导入知识库；JSON 保留完整文档元素层级，适合做进一步的结构化加工。

2.2 内部的流水线设计：版面分析、表格识别、OCR 组装

docling 的内部流程大致是一条流水线，分四步走：

第一步，页面图像预处理。如果是扫描件，它会把页面图像做必要的矫正和增强，为后续模型识别做准备。

第二步，版面分析（Layout Analysis）。这是整个工具的灵魂，模型对页面做目标检测，把页面划分成若干区域：标题区域、正文区域、表格区域、图片区域、页眉页脚区域。这一步的结果直接决定后续输出的顺序和层级。

第三步，表格结构识别。针对被判定为表格的区域，单独跑表格结构模型，识别行、列、合并单元格，恢复表格内容。docling 支持不同的表格模式，我一般默认用 accurate，速度和精度比较平衡。

第四步，OCR 组装。如果文档没有文本层（典型的就是扫描件），这一步负责把图像上的文字转成可读文本，再把结果填回版面分析得到的结构里。最终导出干净的 Markdown 或 JSON。

2.3 和 PyMuPDF、Unstructured、Camelot 相比凭什么胜出

我实际对比过 PyMuPDF、Unstructured 和 Camelot，各有各的问题：

• PyMuPDF：文本坐标定位准，但本身不做语义版面分析，你拿到的还是一堆带坐标的碎片。
• Camelot：专攻表格提取，表格效果不错，但它只管表格，表格以外的内容不处理。
• Unstructured：思路和 docling 接近，但安装依赖太重，不同版本间行为差异大，维护成本偏高。

docling 的定位更综合，一条命令能把版面分析、表格提取、OCR 通通跑完，输出格式还统一。对小团队和独立开发者来说，这套“开箱即用”的体验省掉了很多组装轮子的时间。

3. 实操：从安装到输出第一份结构化文档

3.1 环境准备与安装步骤

docling 依赖深度学习运行时，需要 Python 3.10 及以上，建议用干净的虚拟环境装。我踩过坑，直接 pip 装到全局环境里，结果和已有的 torch 版本冲突，折腾了一下午。

python -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install docling

首次跑会下载模型权重，依赖网络，下载后本地会做缓存。如果你在断网环境部署，需要提前把模型权重导出，把缓存目录一起打包带过去，否则离线跑会卡在“连接超时”上。

我自己是 MacBook Air（M2，16GB 内存），CPU 推理速度可以接受，解析一份 20 页的扫描 PDF 大概需要 1 到 2 分钟。如果手上有 NVIDIA GPU，可以用 GPU 加速，速度提升非常明显。

3.2 最简用法：3 行 Python 把 PDF 转成 Markdown

安装好后，最省事的写法是直接调用 CLI：

docling mydoc.pdf --to md

这会生成mydoc.md文件，全过程控制台会打印进度。

想用 Python API 集成到自己的工程里，核心代码也不复杂：

from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("mydoc.pdf") # 导出 Markdown markdown_output = result.document.export_to_markdown() with open("mydoc.md", "w", encoding="utf-8") as f: f.write(markdown_output)

就这么几行，扫描 PDF 也能处理，因为 docling 会自动判断文档里有没有文本层，没有就启用 OCR。

如果你要批量处理目录里的全部 PDF：

from pathlib import Path from docling.document_converter import DocumentConverter converter = DocumentConverter() pdf_dir = Path("./pdfs") for pdf_path in pdf_dir.glob("*.pdf"): result = converter.convert(pdf_path) md_path = Path("./outputs") / f"{pdf_path.stem}.md" md_path.parent.mkdir(parents=True, exist_ok=True) md_path.write_text(result.document.export_to_markdown(), encoding="utf-8")

这段代码里需要注意mkdir(parents=True, exist_ok=True)一定不能省，否则第一次运行目录不存在时会直接报错。

3.3 关键的几个参数：OCR、表格模式、页面范围

docling 的参数设计整体比较克制，但有几个参数影响很大。

第一个是 OCR 开关。纯文本型 PDF，比如直接从 Word 导出的文档，建议关掉 OCR，速度更快，输出也干净。扫描件则必须开启 OCR，否则什么文字都提取不出来。你可以按文档类型手动指定：

# 强制关闭 OCR，适合数字原生的 PDF result = converter.convert("digital.pdf", ocr=False) # 强制开启 OCR，适合扫描件 result = converter.convert("scan.pdf", ocr=True)

第二个是表格模式。docling 支持table_mode参数，accuracy 模式下模型更细致地还原表格结构和合并关系，速度慢一些；fast 模式更快但复杂表格可能丢结构。面对财务报告里那些跨列表格，我一般用 accurate，普通的技术文档用 fast 就够。

第三个是页码范围。如果一份几百页的合同你只需要前 10 页做测试，没必要全量跑一遍：

from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions pipeline_options = PdfPipelineOptions() pipeline_options.page_limits = (0, 10) result = converter.convert("long_doc.pdf", pipeline_options=pipeline_options)

注意这里页码是 0-based 区间，表示从第 1 页到第 10 页。当时我第一次用，传了(1, 10)，结果跳过了第一页，耽误了几分钟才反应过来。

4. 进阶：在 RAG 管线和知识库中用好 docling

4.1 为什么 RAG 管线需要一个像样的解析层

近一年大家都在搭 RAG，最常见的问题就是：

文档切成乱七八糟的 chunk，喂给向量库之后，召回的结果前言不搭后语，LLM 回答的各种幻觉满天飞。根本原因不是 Embedding 模型不行，而是最开始的文档结构化这一步没做好。

docling 的价值在于，你拿到的不是一堆按空格切开的文本碎片，而是有结构含义的内容块。标题、段落、表格是分开的，可以直接按语义边界切 chunk。

一个典型的处理流程是：

from docling.document_converter import DocumentConverter from langchain_text_splitters import MarkdownTextSplitter converter = DocumentConverter() result = converter.convert("handbook.pdf") md_content = result.document.export_to_markdown() splitter = MarkdownTextSplitter(chunk_size=800, chunk_overlap=100) chunks = splitter.split_text(md_content)

这样切出来的 chunk 天然保留了 Markdown 结构，喂给向量库时语义更完整，召回效果也要比纯字符切分稳得多。

4.2 从 JSON 输出中提取结构化数据

有些业务场景不需要阅读，而是要把文档里的字段抽出来入库。docling 的 JSON 输出保留的是标准化的文档树结构，层级清晰。

import json result = converter.convert("report.pdf") doc_json = result.document.export_to_dict() # 快速遍历所有文本块 for text_item in doc_json["texts"]: label = text_item["label"] # title / paragraph / table_caption 等 text = text_item["text"] # 按 label 过滤，做业务处理

这个label字段是版面分析的产物。比如你想只提取所有标题，就按label == "title"过滤。再比如你想单独处理表格，可以遍历doc_json["tables"]，每个表格元素自带行列信息和单元格文本，方便入库。

4.3 实测：文档解析链路中的效果与性能

我拿三份不同来源的文档做过一次小规模测试，数据如下：

这份测试结果说明：对数字原生的 PDF，docling 的解析速度和准确率都很理想；扫描件因为绕不过 OCR 这一关，耗时明显更长，表格的还原效果也会受扫描质量影响。如果你手头有大量低分辨率扫描件，建议先用图像增强工具预处理一遍，再去跑 docling，效果会好很多。

5. 使用过程中最常见的 6 个问题与排查方案

5.1 安装后跑不起来，报缺依赖

这个高频问题基本发生在 torch 版本冲突上。解决方案是先创建新的虚拟环境再装。如果你已经装了 CPU 版 torch，后面又需要 GPU 版，最好先卸载再重装，避免两个版本并存导致模拟器加载混乱。

5.2 中文扫描件的 OCR 效果差

docling 默认的 OCR 引擎对中文支持不如对英文好。我的实操经验是，先用 PIL 把扫描图像做增强处理，再调用 docling。如果还不行，可以考虑换用专门的 PaddleOCR 处理图片层文字，再和 docling 的版面结果做对齐。过程麻烦一点，但针对中文扫描合同的效果是实打实的提升。

5.3 大文档内存占用过高

一次解析几百页的 PDF，内存能飙到很高。我的经验是分页处理，比如每次只解析 50 页，写回结果后释放进程。也可以改用流式思路，把大文件拆成小段，再用section级别的解析去拼接。

5.4 表格跨页被拆碎

跨页表格是 docling 目前也无法完美解决的问题。常见应对办法是：在版面分析后，根据表格内容相似度和标题连续性做后处理合并。我自己写了一个简单脚本，把相邻两页里表头一致的表格碎片拼起来，准确率提升不少。

5.5 输出 Markdown 中图片丢失

如果原文里的图片很重要，你需要在 pipeline 里开启图片导出，否则 Markdown 只保留图片占位符。具体配置可以查官方文档的图片导出参数，设置输出目录后，图片会被存为独立文件并在 Markdown 里引用。

5.6 重复执行模型权重重复下载

模型权重默认缓存在用户目录下。我有一次清了缓存，结果所有文档重新下载一遍权重。如果是在内网环境，建议把权重文件拷贝到共享路径，然后用环境变量指定缓存目录，避免每台机器重复下载。

写在最后的个人体会

我用 docling 时间不算长，但它是目前我遇到的、最接近“开箱即用”这四个字的文档解析工具。它的学习成本不高，核心思路却比很多传统方案先进：不是死板地按字符串处理，而是把文档当作文本和版面的综合体来理解。对想做 RAG、知识库和文档中台的同学，docling 是一个很值得放进技术栈的选择。

还有个细节想多说一句：如果你打算把 docling 接入正式业务，前期花点时间做文档分类很有必要。数字原生 PDF、扫描件、Excel 表格这三类文档，用同一套参数跑出来的效果差异很大。先分类，再分别调参，反而比一股脑全自动处理省事得多。这套思路，放在任何一个文档解析工具上都适用。