企业官网建设流程全解析

处理PDF转Markdown这事儿，干过的人都知道有多挠头。排版乱了、表格错位、扫描件一个字都抽不出来，这些坑我全踩过。后来在项目里用上了Docling，才算是把文档解析这摊事儿理顺了不少。这工具是IBM开源的，能把PDF、Word、PPT、图片这些乱七八糟的格式，转成干干净净的Markdown和JSON，尤其是表格识别这块，比我之前用过的开源方案都稳。这篇就把我实际使用的经验、踩过的坑、还有跟RAG场景结合的心得，一次说清楚。

1. Docling是什么，为什么它值得关注

1.1 先说说文档解析这件事有多烦

做知识库、做RAG、做文档中台的人，八成都有过这种经历：手里一堆PDF，有的是文字版、有的是扫描图片、有的是Word导出的假PDF。你想把这些内容提取出来给大模型用，结果一跑脚本，出来的Text东缺一块西缺一块，表格直接变成一串乱码数字，标题层级全丢了。更气人的是，有些PDF打开看着好好的，复制出来全是乱码——因为内嵌的字体映射根本不对。

这些问题的根源在于，PDF本身是一种"排版格式"，不是"内容格式"。它只记录了每个字符画在哪个坐标，至于这个字符属于标题还是正文、属于表格第几列，PDF根本不在乎。所以想从PDF里提取结构化信息，必须靠额外的版面分析和语义理解，这就是Docling这类工具存在的意义。

1.2 Docling的核心能力，一句话讲透

Docling做的事情，说白了就是：把入口杂乱无章的文档，统一解析成结构化的中间表示，再导出成你需要的格式。它支持的输入包括PDF、DOCX、XLSX、PPTX、图片和HTML，输出支持Markdown、HTML和带丰富标注的JSON。

它最拿手的有三件事：

• 版面分析：识别出标题、正文、列表、表格、图片、页眉页脚这些区域，并且区分层级关系。
• 表格结构识别：这是它的拳头功能。能把表格里的单元格、行、列、合并单元格都拆清楚，而不是像普通OCR那样只吐出一行行没有逻辑的文字。
• OCR兜底：遇到扫描版PDF，可以自动调用OCR引擎把图片里的文字抠出来，和版面分析结果融合在一起。

相比之下，常见的PyMuPDF只能拿文本和坐标，不管语义；Unstructured功能全但配置复杂，有些高级能力还要走云端API；marker速度快，但表格稍微复杂一点就露馅。Docling在这些开源方案里，属于"识别质量"和"可定制性"平衡得比较好的。

2. 环境准备与快速上手

2.1 安装环节，先把这个跑通

Docling基于Python，依赖PyTorch和Hugging Face生态，所以在装之前建议先把Python环境搞定。官方要求Python 3.10以上，实测3.9跑不起来，别在版本上省事。

# 建议用虚拟环境，别直接往系统Python里怼 python -m venv docling-env source docling-env/bin/activate # 安装核心库 pip install docling

第一次安装会自动拉一批依赖，包括torch、transformers、torchvision这些大头。如果你在GPU机器上，强烈建议提前装好CUDA版PyTorch，再用pip install docling，否则它会装CPU版，后面跑模型慢得让你怀疑人生。

装完之后，模型文件不会立即下载。第一次执行解析任务时，Docling会自动去Hugging Face拉取版面分析模型和表格识别模型，总大小在几百MB左右，取决于你启用的组件。这一步很多人会卡住——国内网络拉不动Hugging Face。解决办法是设镜像：

export HF_ENDPOINT=https://hf-mirror.com

或者提前用huggingface-cli download把模型拉到本地缓存目录。我实际测试下来，只要设了镜像，模型下载基本能跑满带宽，不设镜像的话经常超时重试。

2.2 命令行先跑一遍，感受一下输出

安装好之后，最快的验证方式是命令行。找一份带表格、带标题的PDF，直接执行：

docling my_document.pdf --to markdown

命令跑完后，同目录下会生成一个my_document.md文件。打开看看，如果版面简单的话，效果会超过你的预期：标题层级在、段落顺序对、表格变成了规范的Markdown表格。如果内容区域识别错了，先别急着下结论，大概率是模型对一些特殊排版处理不到位，这个我后面会细说。

除了Markdown，还可以导JSON：

docling my_document.pdf --to json

JSON里包含每个文本块的内容、坐标、层级、类型标签，这些信息是做精细后处理的关键素材，后面接入RAG时你会体会到它的价值。

2.3 Python API引入项目，了解一下核心对象

命令行只是验证用的，真正干活还得靠Python API。核心用法非常简洁：

from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("my_document.pdf") # 输出Markdown print(result.document.export_to_markdown()) # 输出JSON print(result.document.export_to_dict())

DocumentConverter是门面类，接收文件路径或URL，返回ConvertResult对象。这个对象内部是一个结构完整的文档模型，包含了页面、区域、表格、文本块、OCR结果等所有信息。你可以在导出前做各种定制，比如只保留正文去掉页眉页脚、把表格导出成特定格式等。

3. 核心能力拆解：表格、版面、OCR是怎么协作的

3.1 表格识别为什么难，TableFormer做了什么事

做文档解析的人都知道，表格是重灾区。PDF里的表格，本质上就是一些线条加上一堆文字坐标，没有行列关系、没有单元格归属、更没有表头语义。如果解析器只按坐标排序输出，结果就是文字串行，表格逻辑彻底丢掉——这是很多简单PDF提取工具的通病。

Docling解决这个问题靠的是TableFormer模型，这是一个专门为表格结构识别训练的深度学习模型。它做的事情可以拆成几步：

• 第一步，检测页面里的表格区域在哪里，把表格区域从整页内容中切出来。
• 第二步，识别表格内部的结构，包括每个单元格的边界、行和列的划分、单元格之间的跨行跨列关系。
• 第三步，把单元格内容和结构信息映射起来，生成一个完整的表格对象。

实际使用中，TableFormer对格式规整的表格识别准确率很可观，像财务表格、实验数据表、简单的合并单元格，都能处理得像模像样。但如果表格里有多层嵌套表头、单元格大幅合并、内容跨页，效果就会打折扣。遇到这种极端情况，我一般会结合后处理逻辑，或者干脆手动介入微调。

3.2 版面分析模型：让文档恢复"阅读顺序"

表格识别是Docling的亮点，但一个文档里除了表格还有大量其他内容——标题、段落、列表、图片、公式、页眉页脚。Docling用的是基于DocLayNet数据集训练的版面分析模型，它能给每个内容块打上标签，比如"标题""正文""表格""图片""公式"。

这个能力最直接的收益是：恢复正确的阅读顺序。PDF可以做到视觉上排版正确，但内容逻辑顺序往往支离破碎。版面分析模型通过理解页面的布局结构，把视觉区域按照人类阅读习惯重新排列，导出的Markdown段落顺序和原始文档一致，而不是PDF内部的物理对象顺序。

我实际处理过一个两栏排版的学术PDF，用简单工具提取时，左栏和右栏的内容会交叉串在一起。Docling的版面分析能识别出这是两栏结构，然后按先左后右、从上到下的顺序组织内容，读起来就跟看原版论文一样。

3.3 OCR什么时候启用，以及怎么选引擎

Docling的OCR机制是"按需触发"的。它先尝试从PDF中提取文本层，如果发现某一页没有文本层（典型的就是扫描件、图片型PDF），就会自动启用OCR。注意它触发OCR的粒度是"页"级别的，这意味着一个文档里既有文字页又有扫描页，它能分别处理而不互相干扰。

OCR引擎可以配置，默认支持EasyOCR和Tesseract，也能接一些其他引擎。我在实际项目中主要用EasyOCR，识别准确率比Tesseract高一些，但速度慢而且更吃显存或内存。如果机器配置一般，处理纯中文扫描件时可以试试RapidOCR，这个引擎对中文的支持不错并且轻量一些。

配置OCR引擎的示例：

from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import PdfPipelineOptions from docling.document_converter import DocumentConverter pipeline_options = PdfPipelineOptions() pipeline_options.do_ocr = True pipeline_options.ocr_options.engine = "easyocr" pipeline_options.ocr_options.lang = ["ch", "en"] converter = DocumentConverter(pipeline_options=pipeline_options)

注意lang参数只对EasyOCR这种可配置引擎生效，而且语言代码要用ISO 639-1风格。识别中文扫描件时，如果把语言设成纯英文，中文部分会全部丢失，这个坑我踩过，输出一堆空字符还以为是模型坏了。

4. 中文文档实战：从乱码到结构化，我趟过的路

4.1 文字型中文PDF，处理起来比想象中顺利

对于本身带有文本层的中文PDF，Docling处理起来基本没有障碍。这些PDF里的文字内容可以正常提取，字体编码问题Docling做了兼容，不会出现那种复制出来全是"锟斤拷"的乱码。

我测试过一份从排版软件导出的中文技术手册，内含多级标题、段落、带边框表格。Docling导出的Markdown里，标题层级完整，表格内容分列清晰，中文标点也没有丢失。这一点比很多老牌PDF解析库要强，它们面对CJK字体经常在字符映射上翻车。

不过有一类特殊情况要提醒：如果PDF里的中文是通过特殊字形嵌入的，比如某些设计软件把文字描边变成了曲线，那本质上这些内容已经变成了"图片"，没有文本层，只能靠OCR硬啃，效果取决于扫描质量和字体清晰度。这不是Docling能单独解决的，换成任何工具都一样。

4.2 中文扫描件的OCR，质量波动比你想的大

中文扫描件的识别难度跟字体、分辨率、版面复杂度强相关。实测下来，300DPI、印刷体、黑白分明的扫描件，用EasyOCR的识别效果最好，基本能到可用水平。但如果是带底纹、低对比度的扫描件，或者用了宋体小号字，错误率会明显上升，尤其是数字和标点容易混。

有一招能显著提升OCR质量：预处理图片。Docling本身不做图像增强，但你可以先把PDF页面转成图片，做灰度化、对比度拉伸、降噪之后，再交给Docling识别。像我用过OpenCV做自适应阈值和二值化，处理后的识别错误率比原图直接识别能降低不少。

实测下来，中文扫描件处理链路是：

• 先用pdf2image把页面转成PNG，分辨率设到300DPI以上。
• 用OpenCV做灰度化和二值化预处理。
• 把处理后的图片交给Docling识别。

这套流程处理老旧的中文书籍扫描件，比直接喂原始PDF的识别结果明显更稳。

4.3 竖排文本、复杂公式这几个老顽固

中文文档里有些特殊版面，是目前所有开源解析器都没完全啃下来的：

• 竖排文本：古籍、老报纸里的竖排中文，Docling做不到正确的阅读顺序，会按从左到右的方式硬读，结果就是整段内容顺序错乱。
• 复杂数学公式：含有大量上下标、积分符号、根号嵌套的公式，Docling不会自动转成LaTeX，导出Markdown时公式会以图片形式或者混乱文本形式保留。
• 页眉页脚与正文的边界：中文书籍页眉经常放章节名，Docling有时候会误判为正文内容，导致提取结果里重复出现章节标题。

遇到这三类内容，我的经验是：别指望全自动，要么在项目里做后处理规则，要么用支持这些场景的专业工具配合。Docling强在通用场景，特殊场景需要你用手头的工程能力去补。

5. 把Docling接入RAG与知识库，这才是重头戏

5.1 RAG效果不稳，很多时候是解析这一步先烂了

做RAG的人常有一个困惑：同一个知识库，换个文档加进去，问答效果突然就崩了。排查到最后，往往不是Embedding模型的问题，也不是Prompt写得不对，而是源文档解析出的文本太脏——表格内容串行、标题层级丢失、扫描件文字缺失。大模型拿到的上下文本身就是坏数据，再怎么调优都白搭。

因此，RAG的第一步不是选向量库，而是把文档解析这关过了。Docling在这个链路里的定位，就是作为"文档清洗路由器"。

• 它对输入做版面分析，输出带语义标签的内容块。
• 它对表格做结构识别，输出关联行列关系的结构化数据。
• 它把整个过程的结果统一成Markdown和JSON，方便下游按需取用。

我现在的RAG流程基本是：上传文档 → Docling解析 → 按标题切分chunk → 过滤掉页眉页脚 → 表格块单独处理 → Embedding入库。这套流程跑稳定之后，问答效果再也不受文档格式拖累了。

5.2 利用JSON输出，按需截取你要的块

Docling导出JSON的价值，很多人在初用时没体会到。JSON里包含了所有内容块的坐标、层级和类型信息，这意味着你可以做很多精细操作：

• 按label字段过滤：只保留"标题"和"正文"类型的内容块，丢掉"页眉""页脚""页码"。
• 按坐标区域裁剪：如果文档是多栏布局，你可以按坐标把每一栏内容单独提出来。
• 按表格对象提取：直接把JSON里的表格对象转成DataFrame，批量入库。

下面是我在项目里用过的一个过滤函数，简单改改就能用：

from docling.document_converter import DocumentConverter converter = DocumentConverter() result = converter.convert("report.pdf") doc_dict = result.document.export_to_dict() # 过滤掉页眉页脚，只保留正文和标题 kept_texts = [] for element in doc_dict["texts"]: label = element["label"] if label in ["title", "text"]: kept_texts.append(element["text"])

这一步看起来不起眼，但对RAG效果的影响是决定性的。页眉页脚如果不清理，Embedding检索时经常匹配到重复的章节标题，拉低检索精度。

5.3 表格进了RAG之后，问答效果实测提升明显

表格数据在RAG场景里最尴尬：纯文本提取的表格，每一行被拆成碎片，大模型回答问题时要靠"猜"才能拼出完整语义。Docling把表格以Markdown形式还原之后，大模型对表格内容的推理能力会提高一个档次。

举个例子，我处理过一份设备参数表PDF，包含多列参数和备注说明。旧方案提取出来的内容，问"某型号的功率是多少"经常答错或答非所问。用Docling解析后，表格在Context里是一张结构完整的Markdown表格，大模型能准确对照行和列得出结论。

如果你的知识库有大量表格类文档，Docling带来的收益比任何Prompt调优都直观。

6. 常见问题与排查技巧实录

6.1 一张表讲清楚高频问题

6.2 模型下载慢、失败，怎么彻底解决

文档解析类工具都要吃模型，Docling第一次跑会自动从Hugging Face下载几个模型文件，总大小大约在几百MB级别。网络环境差的时候，下载经常失败，而且失败后重试也可能卡在缓存文件上。

我的做法是：找一个网络好的环境，手动把模型下载好，再传到目标机器。

# 先在有网机器上执行一次，模型会缓存到本地 python -c "from docling.document_converter import DocumentConverter; DocumentConverter().convert('test.pdf')" # 找到缓存目录 # Linux: ~/.cache/huggingface/hub # 把整个hub目录拷贝到目标机器的同样位置

这招在离线环境、内网环境非常实用。共享挂载盘也行，只要模型文件存在，Docling会直接复用缓存，不再触发下载。

6.3 处理大文档时内存爆掉，两个自救技巧

处理几百页的大PDF，尤其是带OCR的扫描件，内存占用会非常夸张，16G内存的机器都可能不够。这是因为Docling默认会把整个文档的解析结果全部放在内存里，再一次性导出。

自救方案有两个。第一个是启用并发安全模式并控制批量大小：

converter = DocumentConverter() # 分别处理每一页，而不是一次性convert整个文档

第二个是拆分子文档，把大PDF先按页拆分，再逐个解析，最后合并结果。拆分可以用PyPDF2或pypdf这个库，几十行代码搞定。虽然麻烦一点，但能避免内存爆掉导致整个任务白跑。

6.4 我发现的一个小技巧：结合FastAPI做异步解析服务

在团队协作场景里，Docling经常要部署成内部服务。这时候直接把DocumentConverter当单例用就行，它内部有线程池管理并发请求。性能上GPU算力是关键瓶颈，我用一台8G显存的GPU机器部署过，并发处理普通PDF文档，速度快到可以接受，比单线程逐个处理强很多。

7. 最后的实操心得

做文档解析这几年，我最大的体会是：别指望有什么工具能一劳永逸。Docling是同类开源方案里综合能力比较突出的，但也不是万能的。处理规范排版的中英文文档、复杂表格、扫描件，它能帮你解决九成问题；剩下那一成，要么靠预处理，要么靠后处理规则去兜底。关键是把它放对位置——它解决的是"从文档里准确提取结构信息"这个问题，而不是"理解文档语义"那个问题。想明白边界，踩坑的概率就能小很多。