企业官网建设流程全解析

做文档解析这几年，我越来越觉得“PDF转Markdown”这件事被严重低估了。看起来不就是把字体、段落抽出来重新排一遍吗？真做过的都知道，一张带合并单元格的财报表格就够你折腾一下午，更别提扫描件、双栏论文、带页眉页脚的招股书——传统工具抽出来的文本经常是乱的，表格直接散架，图片注释全部丢失。我最近跑通了 IBM 开源的docling，才意识到这类问题本可以有更体面的解法。它不只是一个转换器，而是一套能把 PDF、Word、PPT、图片等杂乱文档解析成结构化 JSON / Markdown 的本地化方案，尤其适合做 RAG 知识库、文档治理和自动化归档。这篇文章就把我从安装到实战的全过程、踩过的坑和调优经验完整写出来，希望能给同样在折腾文档解析的朋友省点时间。

1. 文档转换为什么这么难？先聊聊 Docling 要解决的问题

1.1 PDF 不是“开放格式”，而是“排版快照”

很多人第一次接触 PDF 解析时会很困惑：为什么 PDF 明明“看起来”有段落、有标题、有表格，程序读出来却是一堆无规则的字符流？原因在于 PDF 本质上不是一个“文档格式”，而是一个“排版快照”。它记录的并不是“这里是一个一级标题”“这里是一个三行四列的表”，而是“在坐标 (x, y) 处用某种字体绘制这些字符”。字体、位置、颜色、嵌入的图片，才是 PDF 真正知道的东西。

这意味着，任何工具想把 PDF 转成 Markdown，都必须自己承担一项额外的任务：做版面分析（Layout Analysis），也就是根据字符的坐标、字体大小、间距等线索，重新推断出文档的语义结构。这和人眼看文档的过程完全不同，人眼有先验知识，机器只能靠模型来猜。传统工具往往只做了“抽取字符 + 简单排序”这一层，所以输出结果一遇到复杂版面就崩。

1.2 传统转换工具的三个致命伤

我在实践中用过不少文档解析方案，总结下来问题集中在三个点：

• 表格结构丢失：最头疼的。页面上明明是一个有 5 列、带跨行合并的表格，抽取出来却变成了一坨挤在一起的纯文本，列对应关系全靠肉眼去猜。
• 阅读顺序错乱：双栏论文最常见。左边的第二段还没读完，右边的第一段已经插进来了。普通工具按坐标从左到右、从上到下硬排，结果段落完全对不上。
• 扫描件无能为力：只要是图片型 PDF，传统文本抽取工具输出的就是空白。必须先经过 OCR（光学字符识别），再做版面分析，很多轻量工具在这一步直接放弃。

这三个问题叠加在一起，导致一个很尴尬的现状：你花了大把时间做文档预处理，真正用在内容消费和知识检索上的时间反而被压缩了。Docling 吸引我的第一个点，就是它把这几个能力都集成到了一个框架里，不需要再东拼西凑。

1.3 谁适合用 Docling

如果你属于下面任何一类，Docling 大概率值得你花一个下午跑通：

• 做 RAG（检索增强生成）和知识库的人，需要把大量 PDF 转成结构化文本再切片入向量库。
• 处理财务报表、合同、论文、政府公开文件等复杂版式文档的从业者。
• 想摆脱云端 API、在本地或者内网环境里完成文档解析的团队，数据不出内网这一点在不少行业是硬性要求。
• 需要把 Word、PPT、扫描件统一走同一条解析管道的场景。

2. Docling 的核心能力拆解：它到底比你想象中的转换器强在哪

2.1 版面分析与阅读顺序还原

Docling 的底层是用深度学习模型做文档版面分析（Document Layout Analysis，DLA）的。它不是按字符坐标做简单排序，而是先识别出页面里的每一个区域分别是什么类型——标题、正文、表格、图片、页眉、页脚、公式——再根据这些区域的空间关系和排版规则，还原出合理的阅读顺序。

这带来的体验差异是很明显的。我拿一份标准双栏学术论文测试过，Docling 转换后的 Markdown 能基本按“标题 → 摘要 → 左栏正文 → 右栏正文 → 结论”的逻辑输出，而不是把两栏文本交叉混在一起。页眉页脚也会被识别为独立元素，不会混进正文中间。这种层次化输出正是 LangChain、LlamaIndex 这类框架做切片时最想要的——你可以顺着 Docling 输出的标题层级去切块，而不是用固定字符数去暴力截断。

2.2 表格识别：这是和普通转换器最大的分水岭

表格是文档解析里公认的硬骨头，Docling 在这块下了重注。它集成了 IBM 自己的 TableFormer 模型，专门做表格结构识别。TableFormer 不只能识别出表格的边界和行列，还能识别出单元格的合并关系、表头区域、跨行跨列结构，并且把这些信息转化为一个完整的 HTML 表格结构。

实测下来，对于常见的财务表格、对比表格、调研表格，Docling 基本能做到“可以直接用”。比如一份包含两级表头、有合并单元格的季度营收表，输出成 Markdown 后列的对应关系依然是完整的。这一点极其实用，因为大多数传统 PDF 抽取工具遇到合并单元格就直接把列打散，你后续做数据分析还得手工重排，反而比自己手打还慢。

2.3 OCR 能力：扫描件和拍照件也能救回来

Docling 的输入并不局限于“文本型 PDF”。对于扫描版的 PDF 和图片，它会自动调用 OCR 引擎做文字识别，再做版面分析。换句话说，一份纸质合同扫描件，你丢给 Docling，它依然能输出结构化的 Markdown 和 JSON。

需要说明的是，OCR 这一块是“可选增强”，不是每一次转换都会默认触发。Docling 内置了 OCR 模块，内置模型对英文等拉丁字符体系支持比较成熟；对中文文档，官方也在持续优化，实测简体中文识别率在正常排版下已经可用，但复杂字体、低分辨率扫描件上，还是需要和专门的 OCR 工具配合。关于中文处理的细节，后面避坑部分我单独讲。

2.4 输出格式与等级体系

Docling 支持把文档输出为 Markdown、HTML、纯文本、JSON 等格式。牛的地方在于，它的 JSON 不是“扁平化的文本+坐标”，而是包含了完整的文档层级结构：标题、段落、表格、图片、引用关系都被组织成一棵文档树。你可以从 JSON 里精准定位“这篇文章的第三张表是哪张”，而不是靠正则表达式去猜。

这里要提一个关键概念：Docling 内部有一个统一的文档表示对象——DoclingDocument。不管输入是 PDF、DOCX、PPTX 还是图片，它都会先解析成这个统一的文档对象，再从这个对象导出为各种输出格式。这就意味着，你可以写出“一套解析代码，同时处理多类文件”的逻辑，而不需要为每种格式单独实现一套转换逻辑。这一点对自动化管线来说价值巨大。

3. 从零开始跑通 Docling：环境准备与完整安装手册

3.1 环境要求与依赖梳理

Docling 依赖 PyTorch 和 HuggingFace 生态，所以它不是一个“装完就跑”的轻量库。我的建议是：务必用虚拟环境安装，不要直接装进系统 Python 或者常用的项目环境里，依赖冲突会让你怀疑人生。

我当前的推荐环境如下：

• Python 3.10 / 3.11 均可，3.9 也能跑但部分依赖可能要降级
• 建议创建独立的 conda 或 venv 环境
• 磁盘预留至少 5GB 以上，用于模型缓存和依赖库
• 内存 8GB 以上，复杂文档转换时对内存有要求

创建环境并安装：

conda create -n docling-test python=3.11 conda activate docling-test pip install docling

安装过程会自动拉入 PyTorch、transformers、opencv-python-headless、pandas 等一系列依赖，时间会比较长，属于正常现象。装完后可以用下面的命令验证版本：

python -c "from docling.document_converter import DocumentConverter; print('docling ok')"

3.2 安装过程中容易翻车的地方

我在安装时遇到的最大问题就是依赖冲突。尤其是项目里已经有其他版本 PyTorch 或 torchvision的情况下，强制安装 docling 会触发 pip 的依赖解析失败，或者更隐蔽的版本兼容问题。我踩过一次很深刻的坑：在已有的 PyTorch 环境里直接pip install docling，安装倒是成功了，但一运行就报RuntimeError: The detected CUDA version ... mismatches，后来查出来是 transform 库要求的 torchvision 版本和环境中已有的不一致，导致模型加载阶段直接崩溃。

排查链路给各位参考：

1. 看完整报错信息，不要只看最后一行，重点看是哪个 import 语句触发的。
2. pip check检查依赖完整性，这个命令能直接列出哪些包的依赖版本不满足。
3. 确认 PyTorch 版本是否是 Docling 兼容的版本。Docling 官方对 PyTorch 2.x 支持良好，1.x 则很可能不兼容。
4. 如果项目本身已经依赖固定版本的 PyTorch，就别在同一个环境里装 Docling，给 Docling 单独开一个环境最省事。

3.3 模型文件初识：Docling 为什么第一次运行很慢

第一次执行转换时，你会看到终端里刷屏似地下载模型文件，界面还会卡住一段时间，这是正常现象。Docling 的版面分析模型和 TableFormer 表格识别模型合计有数百 MB，首次使用会下载到本地模型缓存目录，后续再跑就直接读取缓存，速度会快很多。

这里有一个实用经验：如果你所在团队的服务器网络下载模型比较困难，可以在一个有良好网络环境的本机先把模型跑热（即成功转换过一次文档），然后把缓存目录整个打包传到服务器上。缓存目录通常在~/.cache/huggingface（如果设置了HF_HOME则取决于该环境变量），直接拷贝过去，服务器上就不用再重新下载了。这个技巧在我处理离线服务器需求时非常管用。

4. 命令行上手：一条命令把 PDF 变成 Markdown 和 JSON

4.1 基础命令与参数解读

Docling 安装后会自带一个命令行工具docling。最基础的使用方式极其简单：

docling input.pdf

默认情况下，Docling 会在当前目录生成两个文件：input.md和input.json。input.md是转换后的 Markdown，适合人类阅读和直接投喂给后续处理流程；input.json是完整结构化的文档树，适合做数据分析和程序化处理。

常用参数我整理成了表格，方便查阅：

我经常用的组合是：

docling input.pdf --to md --to json --output ./output --table-mode accurate

这样一条命令同时产出 Markdown 和 JSON 两份结果，表格识别用最高精度模式。复杂版式的文档建议用accurate，处理速度会慢一些，但表格和版面结果更稳。

4.2 批量处理与目录输出

单文件处理只是开胃菜，实际业务里更多是需要批量处理几百份文档。Docling 的命令行支持直接传入目录，也可以一次列出多个文件：

docling ./docs_dir --output ./output_all

传入目录时，Docling 会遍历目录里的支持类型文档（PDF、DOCX、PPTX、图片等）并逐份转换。实测下来，几十份文档这种量级完全没问题；如果是上千份大规模文档，我建议还是走 Python API 做并发控制，而不是单纯靠命令行，因为命令行默认是串行处理的，速度上不去。

4.3 输出结果的关系与用途

对刚开始用 Docling 的朋友，我建议从 JSON 入手而不是直接看 Markdown。原因很简单：Markdown 是给人看的，JSON 是给程序用的。Docling 的 JSON 里每一项内容都带有类型标签、位置信息和层级关系，比如某个文本块是正文还是标题，某张表有多少行列，文档里的图片在什么位置等等。

举个例子，当你需要把 100 份合同里的“合同编号”和“签约金额”抽取出来做结构化入库时，如果只依赖 Markdown，你还需要自己写正则去匹配；但如果直接分析 JSON，你可以在文档树里精准定位到“合同信息表格”节点，然后按行列索引直接取值。这一步差异，决定了你的解析流程是“一套能复用的程序”，还是“每次都在做一次性文本清洗”。所以我强烈建议，在动手写下游代码之前，先花点时间打开一个 JSON 文件，熟悉一下 Docling 的结果结构。

5. 用 Python API 构建可定制的文档解析流水线

5.1 核心类与调用流程

命令行适合快速验证和临时任务，但做自动化工具、批量任务和服务集成时，一定得用 Python API。Docling 的使用逻辑围绕DocumentConverter这个核心类展开。它理解起来非常简单：你给它一个文件路径，它返回一个转换结果；从结果里取.document属性，就得到了一个完整的DoclingDocument对象；再从这个对象导出任意格式。

基础调用：

from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("input.pdf") document = result.document # 导出 Markdown md_text = document.export_to_markdown() # 导出 JSON 字符串 json_str = document.export_to_dict() # 或 export_to_json()

5.2 一个完整的 PDF 转结构化 JSON 示例

下面是我在项目里实际用过的处理流程，做了简化但保持了完整可运行性。它实现了：读取一个 PDF，导出 Markdown 和 JSON，同时把文档里的文本块按类型统计数量，方便快速了解文档构成。

import json from pathlib import Path from docling.document_converter import DocumentConverter def convert_pdf_to_structured(input_path: str, output_dir: str = "./output"): input_path = Path(input_path) output_dir = Path(output_dir) output_dir.mkdir(parents=True, exist_ok=True) converter = DocumentConverter() result = converter.convert(str(input_path)) document = result.document # 导出 Markdown md_text = document.export_to_markdown() (output_dir / f"{input_path.stem}.md").write_text(md_text, encoding="utf-8") # 导出 JSON doc_dict = document.export_to_dict() (output_dir / f"{input_path.stem}.json").write_text( json.dumps(doc_dict, ensure_ascii=False, indent=2), encoding="utf-8" ) # 统计文档结构信息 texts = document.texts tables = document.tables pictures = document.pictures print(f"文档 {input_path.name} 转换完成") print(f"文本块数量: {len(texts)}") print(f"表格数量: {len(tables)}") print(f"图片数量: {len(pictures)}") return document if __name__ == "__main__": convert_pdf_to_structured("report.pdf")

document.texts、document.tables、document.pictures返回的是文档树各类型节点。你可以遍历这些节点拿到更细的信息，比如每个表格的单元格内容、每张图片的页码等，这一层精细控制是命令行做不到的。

5.3 从文档到知识的落地方案：切分、元数据与下游应用

在对接 RAG 知识库时，我一般采取这样的策略：先用 Docling 把每份 PDF 转成 JSON，然后写一个遍历脚本，按“标题节点”把文本块组织成多个章节块。这样切出来每一个 chunk 本身就自带标题上下文，比随机切 500 个字符再靠向量召回效率高得多。

对于表格，我倾向于单独处理：把每个表格单独抽出来，转成字典或 DataFrame 存进数据库，同时给表格生成一段文字摘要作为索引。为什么这么做？因为基于向量的检索在召回表格时，效果经常不尽如人意——表格是二维结构，转成纯文本会丢失列之间的关系。让表格走“结构化存储 + 文字摘要召回”的方式，准确性会比把它拍扁成字符串高很多。

元数据这一层也很重要。Docling 转换结果里有页码信息，我建议你把它一直保留到向量库的 metadata 里。用户提问时命中了某一段内容，系统能直接告诉用户“这个信息在第 12 页”，这个体验在问答产品里是加分项，而且实现成本极低——只需要在写入向量库时多存一个页码字段而已。

6. 实测中的教训与排查链路：这些坑我替你踩过了

6.1 依赖冲突与 Python 版本地狱的完整排查过程

前面提到过，Docling 安装最常见的坑就是依赖冲突。但我第一次踩的时候并不只是“安装失败”这么简单。当时的情况是：pip install docling顺利完成，一执行转换就报错，报错信息指向torchvision某个函数不存在。我首先怀疑是版本问题，于是按网上的建议升级torchvision，结果又导致 PyTorch 版本不匹配，运行直接报 CUDA 相关的初始化错误。折腾了大半天，最终决定回到初衷——不要在一个已有 PyTorch 环境里硬塞 Docling。

排查思路整理成清单，供各位参考：

1. 报错优先看 traceback 的源头，Docling 报错经常是层层封装过的，真正的依赖问题在最后几行更常见。
2. 用干净环境重装，而不是反复升级降级原有环境的包。虚拟环境是廉价的重试成本，不值得在冲突环境里做针线活。
3. 如果公司网络下载依赖特别慢，配置好 pip 的全局镜像源，能节省大量时间。
4. 下载模型失败时，优先检查 503、超时这类异常。模型下载是走 HuggingFace 官方源，遇到网络不稳时重试或者离线部署模型缓存，是最稳妥的解法。

6.2 表格识别不准时的调试思路

虽然 Docling 的表格识别已经很强，但它并不是万能的。我遇到过几种失败场景：复杂表头嵌套（多级合并且跨栏跨页）、无边框表格、以及表格中嵌入图片的混合内容。出现识别不准时，不要急着认定工具不行，按下面的顺序排查会高效一些：

• 先确认 PDF 本身是文本型还是扫描型。扫描型表格必须走 OCR，OCR 的识别质量直接决定了表格结构识别的好坏。
• 再看表格是不是跨页的。跨页表格是当前几乎所有表格识别模型的弱项，Docling 虽然比多数方案好，但仍不能保证跨页表格的合并关系完全正确。
• 最后考虑调整--table-mode为accurate，如果文档页数较多，意味着处理时间会成倍增长，但表格结构通常会更稳定。

另外有一个实用技巧：如果表格特别重要，我会把 Docling 转换后的 Markdown 表格再交给专门的表格解析工具（比如 Excel 或者 pandas 的read_html）做二次校验，核对单元格数量是否符合预期。这不能自动化解决所有问题，但能帮你发现哪些表格被识别坏了，及时介入手工修正。

6.3 中文与混合语言文档的处理细节

中文文档的处理是很多人关心的。Docling 底层模型是在多种语言上训练过的，对简体中文、繁体中文的文本型 PDF 解析，版面分析能力基本可用。但这里要分两种情况：

• 文本型中文 PDF：直接读取内嵌文本，不需要 OCR，识别的准确率高，主要瓶颈是版面结构是否复杂。中文论文、报告的双栏排版，Docling 的表现是可以接受的水平。
• 扫描版中文 PDF：必须走 OCR 流程。Docling 内置的 OCR 对中文支持需要时间来验证，如果你处理的扫描件多、质量又差，我建议把 Docling 作为版面分析框架，配合更专业的中文 OCR 引擎（比如 PaddleOCR）来补充识别文本，再合并做后处理。

混合语言文档（中英混排、中文正文+英文参考文献）说实话是目前最麻烦的场景之一。实测下来，Docling 的版面分析在大部分情况下能正确切分中英文段落块，但偶尔会出现英文和中文文本块被合在一起或者切开的情况。我的处理经验是：对于混排文档，在导出 JSON 后不要直接用最大文本块，而是遍历细粒度的文本节点，结合字体信息（Docling JSON 中有字体相关字段）做二次分段，效果更可控。

6.4 Docling 与 Pdfplumber、PyMuPDF 的横向对比

市面上常用方案我基本都上手试过，这里给一个主观但真实的横向对比：

Pdfplumber 和 PyMuPDF 不是不能用，但在复杂版式文档面前，它们把大量工作量转移到了开发者身上。你需要自己写规则判断标题层级、自己拼装表格、自己处理顺序错乱。Docling 的价值在于把这一层“脏活”内置了，你只需要在后处理阶段做校队和业务适配。云 API 效果也许更好，但对于数据敏感的行业和离线环境来说，本地开源的 Docling 是更稳的选择。

注意：Docling 处理复杂文档时，内存开销明显高于 PyMuPDF。建议在处理大批量文档时，用子进程隔离转换任务，避免单个大 PDF 把内存打爆导致整个服务重启。

7. 实战场景延伸：把 Docling 接进 RAG 知识库管道

7.1 文档解析在 RAG 管线中的位置

RAG（检索增强生成）系统的效果瓶颈，往往不在大模型，而在“喂给大模型的内容质量”。你给模型一份乱七八糟、结构残缺的文档碎片，再好的模型也提炼不出可靠答案。文档解析就是 RAG 管线的第一步，也是最容易被低估的一步。

用 Docling 替代传统的“PDF 文本抽取”之后，最直接的改变是：切分策略从“按字符数硬切”升级为“按文档结构切”。以标题为锚点，把每个二级标题下的内容作为一个语义完整的大块，再根据长度做细切。这样切出来的 chunk 上下文完整度高，向量检索的召回准确率会明显提升。表格单独建索引，也是这个整体思路的一部分。

7.2 用 Docling 结果喂给 RAG 的推荐做法

我最推荐的做法是三步走：

1. 全量转换：把知识库里的 PDF、Word、PPT 统一用 Docling 转成 JSON 和 Markdown，落盘保存。
2. 结构切分：写脚本读取 JSON，按文档树结构切出正文块和表格块，正文块保留标题路径作为 metadata，表格块提取列名和摘要。
3. 向量入库：把正文块和表格块分别向量化写入向量库。检索时优先查正文块，相关度不高时再查表格摘要索引。

就这样一套流程，看起来简单，但真正跑通之后，你的知识库系统会从“什么都能往外吐但什么都是碎片”变成“能精准定位到某个标题下的某段内容和某张表”。这种体验的差异，用过 RAG 的人一对比就知道差距在哪。

另外一个细节是：切分后的块要保留来源文件路径和页码。前端展示时能直接回链到原 PDF 的对应页，用户信任感会大不一样。

我自己已经把这个方案应用到了内部文档库和合规文档归档两个场景。说实话，第一次看到几十页的扫描版合同被转成带完整表格结构、带标题层级的 Markdown 时，我还是有点激动的。这种“哦，原来文档解析可以做到这个程度”的感觉，比之前用正则表达式硬拆 PDF 文本时舒服太多了。

最后分享一个小经验：不要一上来就把所有文档都喂给 Docling。先在几十份有代表性的样本上跑通流程，用人工抽检评估版面分析和表格还原是否符合业务要求，再决定是否批量铺开。工具再强大，也需要针对你自己的文档来做验收标准，这一条，不管用哪个解析框架都成立。