企业官网建设流程全解析

最近在折腾RAG相关的项目，被文档解析这一步搞得头大，直到把docling这个工具放到实际流程里，整个链路才顺了不少。docling是IBM开源的一个文档转换工具，核心就是把PDF、Word、PPT、Excel这类常规办公文档，直接转成结构清晰、格式规范的Markdown和JSON。它内置了版面分析、表格识别、OCR这些AI能力，实测下来表格还原和阅读顺序重建确实让人眼前一亮，已经很久没遇到一个开源工具能把这两件事同时处理得这么顺手了。

这篇文章不打算复读官方文档，而是基于我自己从安装到批量落地、再到和RAG流程集成的一套完整实操，把它适合谁、怎么快速上手、有哪些容易踩的坑，一次讲清楚。无论你是做知识库、文档搜索、资料归档，还是单纯想把一堆扫描版PDF批量转成Markdown，这篇文章都能给你一条可以直接照做的路线。

1. Docling到底解决了什么问题

1.1 传统文档解析的那些苦日子

在遇到docling之前，我做PDF解析基本靠pdfplumber、PyPDF2、pdfminer这几个库轮换着用。这几个工具说到底是在做“按位置提取”，对排版规整的纯文本型PDF还能应付，一旦遇到扫描件、复杂表格、双栏论文、混合排版，问题就全冒出来了。最典型的是表格内容不是按行读出来，而是被切成碎片，要么夹在正文里，要么顺序乱掉，等我把数据喂给下游模型，效果自然好不了。

后来我也试过一些商用SaaS方案，识别效果确实不错，但有两个问题绕不开。一是文档内容涉及内部资料时，数据出内网这件事本身就有合规压力，很多人不敢把资料传上去。二是按页计费，大批量跑起来，成本是实打实的。docling属于本地开源的纯AI方案，模型和代码都跑在自己机器上，不用上传数据，这块顾虑直接省掉了。

这里要先说明一下，docling不是“又一个PDF转文本工具”。它的思路是把文档当成一个“视觉+结构”问题来处理——先用模型识别页面上的标题、正文、表格、图片、页眉页脚这些区块，再做阅读顺序重建，最后统一输出成带完整语义结构的文档对象。正因为这一步做到了位，后面做RAG、做结构化入库，才有好数据可用。

1.2 同赛道方案对比后，为什么留下它

我前后对比过几种主流路子。有的框架需要自己先训练模型，配置成本高得离谱；有的库快是快，但对复杂表格基本无能为力；还有一些全家桶式的文档解析平台，功能全但太笨重。docling在这堆方案里，优点比较突出：

• 开源自治，模型权重本地加载，数据不出机器；
• 表格识别是强项，内置了专门的表格结构模型，不是简单地把单元格割开；
• 输出格式覆盖Markdown、JSON、HTML，和现有工具链衔接很自然；
• 跟LLM生态集成做得早，LangChain和LlamaIndex都有对应加载器，省了自研接入的功夫。

当然docling也有自己的脾气。模型文件首次要联网下载，机器配置太低时大文档推理会比较慢，遇到一些奇葩复杂的表格样式也可能翻车。这都不是大问题，后面我会在对应章节给出具体调整方法。

2. 核心能力拆解：它凭什么能把文档读明白

2.1 版面分析与阅读顺序重建是怎么实现的

docling的第一步是版面分析。页面输入进去后，模型会先做类似“语义分割”的操作，把页面划分成不同类型的区域：标题、段落、表格、图片、代码块、页眉页脚、引用等，每个区域都带有一个坐标框。有了这些框，工具就不会再把页面当成一堆散落的字符，而是当成一组有逻辑关系的区块对象。

这一步背后是IBM训练的深度学习版面检测模型，专门针对多类型文档做了优化，和常规的OCR按行输出坐标完全是两码事。常规OCR关注的是“文字在哪”，版面分析关注的是“这堆文字在这个页面里是什么角色”。刚开始用的时候我习惯性打印了输出结果，看到它能准确区分Figure和Table、能算出物理版心区域外的东西，确实省了后续清洗的力气。

阅读顺序重建这块，是容易被忽视但影响巨大的一环。做过文档解析的人应该都遇到过，PDF内部的文本对象顺序经常和视觉阅读顺序对不上，尤其是双栏学术论文、杂志排版、表格和图片穿插的页面，按物理顺序提取出来的文字，人眼根本没法连续阅读，机器更是会被误导。docling会根据区块坐标、大小、语义特征综合推断阅读顺序。我自己拿一篇IEEE双栏论文测过，正文和引用顺序基本能对上。

2.2 表格识别：这批工具里最能打的一环

表格识别是docling我个人最常用、也最信任的能力。它内置了一个叫TableFormer的模型，专门负责把表格还原成完整的结构信息：行列坐标、单元格内容、合并单元格、跨行跨列关系，都能给你拎出来。

我拿不同来源的PDF测过，结论比较稳定。普通规整的三线表，识别出来的Markdown表格基本直接能用；带合并单元格的表格，它也能还原出合理的层级关系，而不是把单元格挤成一团。这在很大程度上解决了“表格内容在Markdown里乱掉”的痛点。

有一点要提醒，表格识别是整个pipeline里最耗资源的部分，不是每次转换都需要开启。如果你处理的PDF主要是纯文本、纯排版，没有多少复杂表格，可以考虑在配置里把表格结构识别关掉，速度提升非常明显。至于怎么关，我在后面配置章节会讲到。

2.3 输出格式与JSON结构，不只是转个文本

docling输出JSON时，内部结构设计得挺讲究。它不是简单地把识别结果拍平，而是按document、page、maintext、tables、groups等层级组织。maintext里存放的是正文段落，tables里存放的是表格对象，每个表格对象内部又细分了单元格结构。

为什么这点重要？因为做RAG或者结构化业务时，经常需要精确到“这一段是哪一页的内容”“这个表格里的哪一行对应什么记录”。JSON结构合理，意味着你可以直接按节点筛选，把它接进自己的数据管道。

举个例子，我在做知识库索引时，不会把整篇文档一把梭地丢给embedding模型，而是会遍历JSON里的tables节点，把每张表格单独抽出来做结构化存储，正文段落按标题层级做切分。这样索引的粒度准得多，检索效果也好得多。这部分详细的落地方式，我会在第四节里配合代码一起讲。

3. 环境准备与快速上手

3.1 安装和依赖，别在这步翻车

docling的安装方式比我预想的简单，直接用pip就能装。不过有个前置条件，环境里得有Python 3.9以上，建议直接用3.10或3.11版本，有些依赖在新版本Python上踩过坑。

pip install docling

这一步会连PyTorch一起装进来。如果你的机器有NVIDIA显卡，建议提前装好对应版本的CUDA版PyTorch，再装docling，这样Docling能直接用上GPU推理，速度会快不少。我第一次装的时候没注意，默认装的是CPU版PyTorch，后面跑一个大PDF等了半天，才发现这个问题。

首次运行docling时，它会自动从模型仓库下载版面分析和表格识别模型的权重，体积大概在几百MB。公司内网环境如果没有外网权限，下载可能会失败，解决方式是提前在能联网的机器上下载模型，再把缓存目录拷贝到目标机器，具体缓存路径在HuggingFace的模型配置里能看到。这块大多数人第一次用都会卡，提前知道能省不少时间。

3.2 第一段代码：把PDF转成Markdown

安装好之后，最基础的使用方式就是转换成Markdown。我写了一个最简单的脚本：

from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("test.pdf") print(result.document.export_to_markdown())

就这么几行，PDF就被转成Markdown了。如果你想保存到文件：

from pathlib import Path from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("test.pdf") markdown_content = result.document.export_to_markdown() output_path = Path("output.md") output_path.write_text(markdown_content, encoding="utf-8")

这是最简单的用法，适合先跑通流程，看看输出效果。实际使用中，我会把原文档名和页码信息保留下来，方便后续回溯来源，这个在第四节会给出更完整的做法。

3.3 几个关键参数，理解了才能用好

docling的转换器在初始化时，可以传一组配置，常见的有这些：

from docling.document_converter import DocumentConverter from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions pipeline_options = PdfPipelineOptions() pipeline_options.do_ocr = True pipeline_options.do_table_structure = True converter = DocumentConverter(pipeline_options=pipeline_options)

这里最关键的两个配置是do_ocr和do_table_structure。

do_ocr控制是否对扫描件执行OCR识别。如果文档是图片型PDF，不打开OCR，输出就只有一堆空壳或乱码。打开后会调用OCR引擎做文字提取。Tesseract是常见选择，也可以根据系统情况配置其他引擎，需要注意的是OCR功能需要额外安装对应依赖，只pip install docling的话是不带OCR引擎的。

do_table_structure控制是否启用表格结构识别。如果文档里有复杂表格，一定要打开，否则表格会退化成普通文本，结构信息完全丢失。如果只是纯文本文档，可以考虑关掉，提速效果明显。

还有个选项是针对特殊文档的，比如双栏或多栏PDF，docling布局模型会自动处理，一般不需要手动干预。处理这些特殊文档时，OCR参数的设置影响很大，尤其是扫描版的双栏文档，OCR开启后效果和关闭时差距非常明显，我建议这类文档一定开启OCR后再转换。

3.4 命令行工具，不写代码也能跑

如果只是临时转几个文件，不想写Python脚本，docling还自带命令行工具，直接在终端执行：

docling test.pdf --to md --output ./output_dir

这里有一点容易踩坑，--output参数后面接的是一个输出目录，而不是文件名。我第一次跑的时候习惯性地写了一个完整文件名，结果工具把目录创建得乱七八糟。多个文件也可以一次传入：

docling file1.pdf file2.pdf --to md --output ./output_dir

命令行工具的选项和Python API基本对齐，适合快速批量转换。遇到报错时，多注意看终端日志，docling的日志输出还算详细，基本能定位到是模型下载、依赖缺失还是解析器不支持的问题。

4. 进阶实战：批量处理与RAG集成

4.1 批量转换脚本，带来源信息

实际业务里，往往是一堆PDF要处理，不太可能一个个手动转。我来分享一个我常用的批量脚本，它不只输出Markdown，还保留了原始文件名和页码信息，方便后续做溯源。

from pathlib import Path import json from docling.document_converter import DocumentConverter converter = DocumentConverter() input_dir = Path("./pdfs") output_dir = Path("./outputs") output_dir.mkdir(exist_ok=True) for pdf_file in input_dir.glob("*.pdf"): try: result = converter.convert(pdf_file) md_content = result.document.export_to_markdown() json_content = result.document.export_to_dict() md_path = output_dir / (pdf_file.stem + ".md") md_path.write_text(md_content, encoding="utf-8") json_path = output_dir / (pdf_file.stem + ".json") json_path.write_text(json.dumps(json_content, ensure_ascii=False, indent=2), encoding="utf-8") print(f"[OK] {pdf_file.name} -> {md_path.name}") except Exception as exc: print(f"[FAIL] {pdf_file.name}: {exc}")

这个脚本有几个设计点值得说明。第一，每个PDF单独放在try/except里，单个文件失败不会中断整个批量任务。第二，同时导出Markdown和JSON，Markdown方便人阅读，JSON方便程序做结构化处理。第三，使用pdf_file.stem作为输出文件基础名，保证和原始文件一一对应，后续溯源非常方便。

4.2 从JSON里抽取表格，做精确索引

批量做完之后，下一步是从JSON里抽取关键结构。我实际处理时，重点关注tables节点。大致逻辑是遍历JSON对象画出tables列表，逐个解析表格内容。

import json from pathlib import Path json_path = Path("./outputs/demo.json") data = json.loads(json_path.read_text(encoding="utf-8")) tables = data.get("tables", []) for idx, table in enumerate(tables): print(f"--- Table {idx + 1} ---") print(table.get("text", "")[:500])

docling的JSON结构在不同版本里可能有些差异，比如说tables字段的具体位置可能不同，运行之前先打印一下data.keys()看看当前版本的结构，再写解析逻辑会更稳。我在一个旧版本上就踩过这个坑，结构字段名和小版本强相关。

拿到表格文本后，我会对每张表格分别建立索引，并记录它属于哪个文件、出现在哪一页。相比整篇文档切块，这种按表格独立索引的方式在回答数据类问题时效果会好非常多。

4.3 与LangChain和LlamaIndex的生态衔接

如果你在用LangChain搭RAG链路，docling有现成的加载器。我测试过基础用法，代码如下：

from langchain_community.document_loaders import DoclingLoader loader = DoclingLoader(file_path="test.pdf") docs = loader.load()

加载出来的documents就已经按docling的解析结果切分过了，标题层级、段落结构直接保留，不需要再叠加一堆自定义切分逻辑。用LlamaIndex的话也有对应的DoclingReader，只是加载器和文档版本有关系，建议引入前先看一眼官方文档的兼容版本表，避免撞上版本冲突。

我自己在这条链路上最爽的一点，是彻底告别了“先转文本再正则硬切表格”的土办法。以前为了把表格数据捞出来，要写一堆正则匹配，效果还很脆。现在docling把表格结构化这件事下沉到了解析阶段，后面的切分、清洗就变得很轻松。

4.4 CPU和GPU的选择建议

资源充足的场景，建议用GPU跑。docling在推理阶段的耗时大头在版面模型和表格模型，模型本身不算小，GPU加速收益非常明显。没GPU的机器也能跑，小文档没问题，但处理上百页的大文档时，建议分批转，不然内存和CPU压力都很大。

另外，如果文档本身是扫描版且有很多页，建议先开OCR再跑版面分析。不要想着关掉OCR来省事，扫描版文本层是空的，不做OCR，后面的版面分析再准也拿不到文字内容。

5. 常见问题与避坑实录

5.1 安装与首次运行报错

docling最常见的安装报错是缺依赖。比如系统里没有libmagic，或者版本较老的Python缺少某些编译工具。遇到这类问题，建议直接看报错的包名，用pip或系统包管理器补上。Windows环境下更推荐用Windows Terminal配合WSL来跑，很多依赖问题能少一半。

另一个很常见的问题是首次运行模型下载失败。公司网络的代理策略经常拦截HuggingFace的下载请求，导致docling卡在下载阶段。解决思路是先找到模型缓存目录和下载地址，在能联网的机器上下载好，再拷贝到目标机器的对应目录。整体不复杂，但第一次碰到时容易慌乱。

5.2 扫描件和中文文档的处理

扫描版PDF如果不开启OCR，转换出来的Markdown几乎是空壳。很多人在这一步以为工具坏了，其实只是没加OCR配置。开了OCR之后，文字层能正确识别。处理中文文档时，OCR引擎要有对应的语言包，否则识别率会很难看。如果是中文扫描件，一定要确认OCR引擎和语言包配置齐全。

我测试的混合排版文档，比如中文报告中夹杂英文表格，整体识别率还是不错的。不过任何OCR方案都不能保证100%准确，对于识别质量要求极高的场景，建议抽查输出结果，重点看数字、人名、英文缩写这些容易出错的内容。

5.3 表格结构异常和阅读顺序错误

表格结构异常主要集中在两种情况。一种是图片型表格，纯图片组成的表格，如果不开OCR，模型拿不到像素里的文字内容，结构再对也是空表。另一种是特殊样式的表格，比如跨页表格、存在大量合并单元格的表格，docling偶尔会把结构识别得不够理想。遇到这两种情况，我通常的处理方式是把表格单独切出来，在转换后手动微调Markdown，必要时再配合图片原图，做人工修正。

阅读顺序错误不算高频，但版本更新后偶有Regression。之前我把docling升级到一个小版本后，发现某个双栏文件的输出顺序乱了，排查半天才发现是版本问题，回退之后恢复正常。建议在正式接入生产环境前，固定一个经过完整测试的版本号，不要频繁跟着更新，毕竟开源项目的版本节奏快，接口和模型都在持续迭代。

5.4 性能调优的实操建议

如果你要处理大量文档，建议先把测试集跑一遍，统计每类文档的耗时和瓶颈。纯文本PDF和扫描版PDF的耗时差距往往是数量级的，这两类文档最好分开处理、单独调参。

我实际使用中会把大文档拆分后再转。比如一本300页的书，一次性转换会有比较长的时间消耗和资源占用，按章拆成更小的PDF文件再并行跑，总耗时反而更可控。docling本身支持batch推理，但设计上还是偏向单文档转换，真正的高并发场景，建议自己起多进程任务，每批处理固定数量的文件，避免资源争抢。

最后再分享两个我常用的低成本技巧。一个是转换完成后写一份摘要日志，记录每个文件的输出路径、耗时和是否成功，方便排查问题；另一个是定期清理日志和多份PDF解码后的临时文件，磁盘占用其实不小，积累久了也挺占空间的。

这套流程我用了快半年，从最开始的单个文件测试，到跑完上千份内部资料，docling目前在我这里已经成了文档解析环节的标准组件。它不一定适合所有场景，但只要你的需求是“把PDF变成干净、有结构、能直接用数据”，它大概率能帮你省下大量手工清洗的时间。如果你在落地过程中发现文档里的表格总是处理不好，优先排查的肯定不是模型能力，而是有没有在pipeline里把表格结构识别和OCR正确打开。