企业官网建设流程全解析

1. 为什么文档解析是 RAG 管线里最容易被低估的一环

做过 RAG 项目的人大概都有过这种体验：模型选型纠结了半天，向量库对比了一轮又一轮，检索策略从朴素向量检索一路升级到混合检索加重排序，结果上线之后回答质量还是不稳定。排查到最后，问题往往不在检索层，也不在生成层，而是卡在最前面那一步——文档解析。

我自己的项目里就踩过这个坑。早期做企业知识库问答，PDF 丢进去直接按固定长度切块，切出来的东西惨不忍睹：表格被拦腰截断，标题和正文混在一起，页眉页脚重复出现在每个块里，跨页的段落被硬生生拆成两半。检索的时候命中率低得可怜，用户问一个表格里的数据，召回的却是一堆无关的页眉文字。后来花了大量时间做后处理，效果也就那样。

这就是 RAG 管线里最痛的一环：文档解析的质量直接决定了后续所有环节的天花板。检索再强，也救不回一堆语义破碎的文本块。而现实中的文档格式又极其复杂——PDF、Word、PPT、Excel、扫描件、HTML，每种格式的解析难度都不一样，PDF 尤其麻烦，因为它本质上是一种"排版描述"而非"结构描述"，文字在 PDF 里的存储顺序和人类阅读顺序经常对不上。

IBM 开源的Docling就是冲着这个问题来的。它的定位很明确：把各种格式的文档统一解析成结构化的、适合 RAG 使用的中间表示，输出包含页码、章节层级、段落、表格结构、阅读顺序等信息的结构化文本。换句话说，它试图把"文档解析"这一环从各家自己造轮子，变成一个可以统一处理的标准件。

这篇文章我会从实际使用的角度，把 Docling 的能力边界、核心原理、实操流程、参数调优和踩坑经验完整拆一遍。不管你是刚接触 RAG 的新手，还是已经被文档解析折磨过的老手，应该都能从中找到能直接抄作业的部分。

2. Docling 到底解决了什么问题：核心能力与设计思路拆解

2.1 传统文档解析方案的三种路线及其局限

在聊 Docling 之前，先理一下目前主流的文档解析方案，这样你才能理解它为什么值得关注。

第一种是基于规则和坐标的解析，典型代表是各种 PDF 文本提取库。它们的工作原理是读取 PDF 内部的文字对象和坐标信息，然后按位置排序输出。这种方案速度快、依赖少，但遇到多栏排版、复杂表格、图文混排就歇菜了。因为 PDF 里文字对象的存储顺序和视觉阅读顺序没有必然关系，纯靠坐标排序经常会把两栏的内容交错在一起。

第二种是基于深度学习的版面分析，用目标检测模型识别页面上的标题、正文、表格、图片等区域，再按区域提取内容。这种方案对复杂版面的适应性好很多，但需要针对不同文档类型调优，而且模型推理有额外的算力和时间成本。

第三种是基于多模态大模型的端到端解析，直接把页面图像丢给视觉语言模型，让它输出结构化的 Markdown 或 JSON。效果上限高，但成本也高，而且大模型偶尔会"幻觉"，把原文没有的内容编进去，这在需要精确引用的场景里是致命的。

Docling 的思路是把这几条路线组合起来：底层用版面分析模型做区域识别和阅读顺序判断，表格用专门的表格识别模型处理结构，文字提取则结合 PDF 原生文本层和 OCR，最后统一输出成结构化的文档对象。它不是单纯依赖某一种技术，而是根据文档类型和内容特征动态选择最合适的处理路径。

2.2 统一中间表示：DoclingDocument 的设计哲学

Docling 最核心的设计是它的输出格式——DoclingDocument。这不是简单的 Markdown 字符串，而是一个带有完整层级关系的文档对象模型。

它记录的信息包括：文档的标题层级（一级标题、二级标题……）、每个文本块的类型（正文、标题、列表项、代码块、公式）、表格的完整结构（行列、合并单元格、表头）、图片的位置和说明文字、每个元素的页码和边界框坐标、以及最重要的——阅读顺序。

为什么这个中间表示很重要？因为 RAG 的切块策略需要依赖这些信息。举个例子，如果你知道某个段落属于"第三章第二节"，切块的时候就可以把章节标题作为上下文拼进块里，检索时用户问"第三章讲了什么"，命中率会高很多。再比如表格，如果解析出来的是结构化的行列数据，你就可以把表格转成自然语言描述或者按行切块，而不是把整个表格当成一坨文字。

提示：DoclingDocument 可以序列化为 JSON，这意味着你可以在解析和切块之间插入自己的处理逻辑，比如按章节聚合、按语义合并、过滤页眉页脚等。这个灵活性是纯 Markdown 输出方案给不了的。

2.3 支持的格式与典型应用场景

Docling 目前支持的输入格式覆盖了绝大多数企业文档场景：

典型应用场景我归纳了几类。企业知识库是最常见的，把制度文件、产品手册、技术文档统一解析后入库，支撑内部问答。合同和招标文件处理是另一个高频场景，这类文档的特点是结构严谨、条款编号清晰、表格多，Docling 的层级识别能力在这里很吃香。学术论文和研究报告也适合，因为需要保留公式、图表和引用关系。财务报告和年报则考验表格解析能力，资产负债表、利润表这类复杂表格能不能准确还原结构，直接决定后续分析的可行性。

3. 核心细节解析：Docling 的技术栈与关键参数

3.1 版面分析与阅读顺序判断的工作原理

Docling 的版面分析基于深度学习模型，它把每一页文档图像切成若干区域，给每个区域打上标签——正文、标题、表格、图片、页眉、页脚、页码等。这个过程类似给页面做"语义分割"。

阅读顺序的判断是难点。对于单栏文档，从上到下、从左到右基本没问题。但双栏、三栏、甚至图文环绕的排版，就需要模型理解人类的阅读习惯。Docling 的做法是结合区域的位置关系和类型信息，构建一个阅读顺序图，然后用图算法推导出合理的顺序。比如它知道标题后面应该跟正文，表格应该作为一个整体处理，页眉页脚应该被识别出来而不是混进正文。

这里有个实操细节值得注意：页眉页脚的识别准确率直接影响切块质量。如果页眉没被正确识别，它会在每一页的文本块里重复出现，检索时造成大量噪声。Docling 默认会尝试识别并标记这些元素，但不同文档的页眉样式差异很大，有时候需要手动后处理过滤。

3.2 表格识别：从图像到结构化数据

表格是文档解析里最难的部分，没有之一。PDF 里的表格可能是有边框的、无边框的、跨页的、嵌套的，甚至是用空格对齐的"伪表格"。

Docling 的表格处理分两步。第一步是表格检测，在版面分析阶段定位表格区域。第二步是表格结构识别，判断这个区域里哪些是行、哪些是列、哪些单元格合并了、表头是哪一行。这一步用的是专门的表格识别模型，输出的是类似 HTML 表格的结构。

实测下来，对于有明确边框的规则表格，识别准确率很高。对于无边框表格，模型会依赖文字对齐关系来推断列边界，准确率会下降一些。跨页表格是最麻烦的，Docling 会尝试把连续两页的表格合并，但如果中间隔了其他内容，就可能断成两个表。

注意：表格解析结果建议人工抽检。我一般会随机抽 10% 的表格，对比原文和解析结果，确认行列对应关系没错。特别是财务数据类的表格，一个单元格错位就可能导致后续分析全盘皆错。

3.3 OCR 引擎的选择与配置

对于扫描件或者没有文本层的 PDF，Docling 需要走 OCR 路径。它默认集成了 OCR 引擎，但也支持切换不同的后端。

OCR 的质量取决于几个因素：图像分辨率、文字清晰度、语言类型、字体复杂度。我的经验是，扫描件至少保证 300 DPI，低于这个值识别错误率会明显上升。中文文档建议选择对中文优化过的 OCR 模型，英文文档用通用模型即可。

配置上有个容易忽略的点：OCR 语言设置。如果文档是中英混排，只设置中文可能导致英文识别错误，反之亦然。Docling 支持多语言配置，中英混排场景建议同时启用两种语言。

3.4 关键参数速查与调优建议

Docling 的参数不算多，但有几个直接影响解析质量和速度，我整理成表格方便对照：

调优的核心思路是在精度和速度之间找平衡。全量解析一份几百页的 PDF，如果开启所有高精度选项，可能要几分钟甚至更久。我的做法是先用 fast 模式跑一遍看整体质量，对质量不达标的文档再单独用 accurate 模式重跑。

4. 实操过程：从安装到接入 RAG 管线的完整流程

4.1 环境准备与安装

Docling 是 Python 包，安装本身不复杂，但有几个依赖需要注意。

# 基础安装 pip install docling # 如果需要处理 PDF 的深度学习模型，首次运行会自动下载模型权重 # 建议提前设置好模型缓存目录，避免占满系统盘 export DOCLING_ARTIFACTS_PATH=/your/cache/path

首次运行时会下载版面分析和表格识别的模型权重，大小在几百 MB 到 1 GB 之间。如果网络环境不稳定，建议提前下载好放到缓存目录。模型下载完成后会缓存在本地，后续运行不再重复下载。

Python 版本建议 3.9 以上，低于这个版本可能遇到依赖冲突。如果项目里已经有其他深度学习框架，注意检查版本兼容性，特别是 PyTorch 的版本。

4.2 单文档解析：最小可用示例

先看一个最简单的例子，把一份 PDF 解析成 Markdown 和结构化 JSON：

from docling.document_converter import DocumentConverter # 初始化转换器 converter = DocumentConverter() # 解析文档 result = converter.convert("your_document.pdf") # 导出为 Markdown markdown_output = result.document.export_to_markdown() # 导出为结构化字典 dict_output = result.document.export_to_dict() # 保存结果 with open("output.md", "w", encoding="utf-8") as f: f.write(markdown_output)

这段代码跑通之后，你会得到两个东西：一份人类可读的 Markdown，和一份机器可处理的 JSON。Markdown 适合快速预览解析质量，JSON 才是接入 RAG 管线的关键。

4.3 批量处理与性能优化

实际项目里不可能一次只处理一个文档。批量处理的时候，性能优化就很重要了。

from docling.document_converter import DocumentConverter from pathlib import Path from concurrent.futures import ThreadPoolExecutor converter = DocumentConverter() pdf_files = list(Path("./docs").glob("*.pdf")) def process_file(pdf_path): try: result = converter.convert(str(pdf_path)) return { "file": pdf_path.name, "markdown": result.document.export_to_markdown(), "dict": result.document.export_to_dict() } except Exception as e: return {"file": pdf_path.name, "error": str(e)} # 控制并发数，避免内存溢出 with ThreadPoolExecutor(max_workers=4) as executor: results = list(executor.map(process_file, pdf_files))

并发数不是越高越好。Docling 的模型推理会占用较多内存，并发太高容易 OOM。我的经验是按可用内存来定，每并发大约需要 1-2 GB 内存，8 GB 内存的机器开到 4 并发比较稳妥。

4.4 从解析结果到 RAG 切块：关键处理逻辑

解析只是第一步，怎么把 DoclingDocument 变成适合检索的文本块才是重点。这里分享我的切块策略。

第一，按章节层级聚合。利用 Docling 输出的标题层级信息，把同一章节下的内容聚合在一起。如果章节太长，再在章节内部按段落切分。这样每个块都带有明确的章节上下文。

第二，表格单独处理。表格不要和正文混在一起切。我的做法是把表格转成两种形式：一种是保留结构的 Markdown 表格，另一种是逐行的自然语言描述。检索时两种都入库，提高命中率。

第三，过滤噪声元素。页眉、页脚、页码这些元素在解析结果里是有标记的，切块前直接过滤掉。

def build_chunks(doc_dict, max_chunk_size=800): chunks = [] current_section = "" current_text = "" for item in doc_dict.get("texts", []): # 过滤页眉页脚 if item.get("label") in ["page_header", "page_footer", "page_number"]: continue # 标题作为章节上下文 if item.get("label") == "section_header": if current_text: chunks.append({ "section": current_section, "text": current_text }) current_section = item.get("text", "") current_text = "" else: current_text += item.get("text", "") + "\n" # 超长时切分 if len(current_text) > max_chunk_size: chunks.append({ "section": current_section, "text": current_text }) current_text = "" if current_text: chunks.append({"section": current_section, "text": current_text}) return chunks

这段逻辑的核心是让每个块都携带章节信息。检索时，即使块内的文字没有直接提到章节名，章节信息也能作为上下文帮助模型理解。

4.5 接入向量库与检索链路

切好的块接下来要入库。这里不展开讲向量库选型，重点说 Docling 的输出怎么和检索链路配合。

每个块建议存储这些字段：块文本、章节路径、页码、来源文件名、块类型（正文/表格/列表）。检索的时候，除了向量相似度，还可以用章节路径做过滤，比如用户明确问"第三章的内容"，就可以限定只在第三章的块里检索。

页码信息在需要引用来源的场景特别有用。用户问"这个数据出自哪里"，你可以直接返回文件名和页码，可信度比单纯给一段文字高得多。

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

5.1 解析质量问题的排查思路

解析质量出问题，排查要按顺序来，不要一上来就怀疑模型。

第一步，确认文档本身有没有文本层。用 PDF 阅读器试着选中文字，如果能选中，说明有文本层，OCR 应该关闭；如果选不中，说明是扫描件，必须开 OCR。这个判断错了，后面全白搭。

第二步，检查页面图像质量。扫描件如果分辨率太低、倾斜、有噪点，OCR 识别率会断崖式下降。这种情况建议先做图像预处理——去噪、纠偏、提高对比度，再喂给 Docling。

第三步，看版面分析结果。把解析出的区域可视化出来，看看标题、正文、表格的框选是否准确。如果框选错了，说明版面分析模型不适应这类文档，可能需要换模型或者调整参数。

第四步，检查阅读顺序。如果解析出的文字顺序混乱，多半是阅读顺序判断出了问题，这在多栏排版里比较常见。

5.2 高频问题速查表

5.3 几个我踩过的坑

坑一：以为解析一次就一劳永逸。文档会更新，解析结果也会过时。我的做法是给每个文档记录解析时间和版本，文档更新后重新解析，并且对比新旧解析结果的差异，避免因为解析器升级导致内容突变。

坑二：忽略了解析结果的存储成本。DoclingDocument 的 JSON 包含大量坐标和结构信息，体积可能是原始文本的好几倍。如果文档量大，存储成本要提前算进去。我的做法是只保留切块需要的字段，坐标信息在切块后就可以丢弃。

坑三：切块参数一刀切。不同类型的文档，最优切块大小不一样。技术文档段落长，块可以大一些；FAQ 类文档段落短，块要小一些。我后来改成按文档类型配置不同的切块参数，检索效果明显改善。

坑四：没有建立解析质量的评估机制。早期全靠人工抽检，效率低还容易漏。后来我建了一个简单的评估集，包含各种典型文档和对应的关键信息点，每次调整解析参数后自动跑一遍，看关键信息点的召回率有没有下降。这个机制帮我避免了好几次"优化"反而变差的情况。

提示：解析质量评估集不需要很大，20-30 份覆盖主要文档类型的样本就够用。关键是每次改动后都要跑，形成基线对比。

6. 关于 Docling 在 RAG 管线中的定位，我的几点实际体会

用了一段时间 Docling 之后，我对它在 RAG 管线里的定位有了比较清晰的认识。它不是万能的，但在"统一处理多种格式文档并输出结构化结果"这件事上，确实省了我很多自己造轮子的时间。

它最适合的场景是文档格式多样、结构相对规范、对解析质量有要求但预算有限的项目。如果你的文档全是干净的 Markdown，那用不上它；如果你的文档是极其复杂的扫描件且要求 100% 准确，那可能还需要配合人工校对。

我个人的建议是，把 Docling 当成 RAG 管线里的一个标准组件来用，但不要指望它解决所有问题。解析之后的后处理、切块策略、检索优化，每一环都还有大量工作要做。文档解析只是把地基打好了，上面的楼怎么盖，还是取决于你对业务场景的理解。

最后分享一个实用的小技巧：先用 Docling 把文档解析成 Markdown，人工快速浏览一遍。这一步花不了多少时间，但能让你对文档的实际结构心里有数，后续设计切块策略和检索方案时会少走很多弯路。很多时候，问题不是出在工具上，而是出在我们对文档本身的理解不够。