Parse PDFs for RAG Locally with Docling: Rich Tables, No Cloud Upload

在本地使用 Docling 解析 PDF 以实现 RAG：丰富表格，无需上传云端 | Towards Data Science

LLM 应用

在本地使用 Docling 解析 PDF 以实现 RAG：丰富表格，无需上传云端

企业文档智能 [Vol.1 #5ter] – 表格单元格、OCR、标题、小标题：云端级别的结构，运行在您自己的机器上。无需密钥，无需按页计费，数据不出楼

石凯赞

2026 年 6 月 13 日

19 分钟阅读

分享

照片由 Ricardo Olvera 提供，来源：Pexels。

本文是企业文档智能系列文章的解析指南，该系列文章通过四个模块构建企业 RAG 系统。第 5 篇文章（文档解析）使用 PyMuPDF（fitz）构建了解析器。本指南保持相同的目标和相同的关系表，但将引擎替换为 Docling，这是一个更丰富的软件包，能够恢复 fitz 无法识别的表格单元格、OCR 和标题，并且完全在您的本地机器上运行。为什么最后这一点很重要，我们从这里开始。

本文的位置：它扩展了第 5 篇（文档解析），在第 II 部分（四个模块）中，使用了不同的解析引擎 – 图片由作者提供

目前市面上最丰富的解析器能够读取表格、扫描内容以及嵌入在图表中的文本。但它还需要将文档发送到其他人的云端。

对于很多企业工作来说，这并不现实。您桌面上的保险合同、医疗记录、并购数据室、已签署的雇佣协议。法律部门不会允许这些字节离开大楼，更不用说跨越边界进入其他人的云端。如果合规性阻止了上传，世界上最丰富的解析器也毫无用处。

Docling 是另一个解决方案。它是 IBM Research 的开源文档解析器（MIT 许可，项目 GitHub 上的 LICENSE 文件中已声明）：布局检测、OCR、阅读顺序以及 TableFormer（IBM 的深度学习模型，能够检测表格结构（行、列、标题）而无需正则表达式）。所有这些都可以通过 pip 安装。它在您的本地机器上运行。第一次调用会将模型下载到本地缓存；之后的所有调用都是离线进行的。无需 API 密钥，无需按页收费，文档永远不会离开主机。

输出结果与 fitz 和 Azure 一样，是相同的关系表。下游管道不会关心是哪个引擎生成的字典。检索、生成、注释都会读取行。它们永远不会读取 PDF。

相同的表格，Docling 丰富了其中的一半，所有操作都在您的本地机器上 – 图片由作者提供

1. 云端是限制，而非能力

第 5 篇补充文章提出了更丰富的解析需求。保留表格的列。对扫描页面进行 OCR。从图表中恢复文本。即使 PDF 没有书签，也能识别标题。这些论点在这里没有变化。发生变化的是计算发生的位置。

Azure DI 是一个托管的云服务。您发送它字节，它会返回结构。对于一篇公开的 arXiv 论文，这没有问题。但对于填充真实企业档案的文档，这通常不是可行的解决方案：

• 保密性：保险政策、健康记录、NDA 下的合同、任何包含个人数据的文档。将它们发送到第三方 API 是一个需要法律部门批准的数据处理事件，而且通常不会批准。

• 数据驻留：在许多行业中，“数据保留在该地区”是一个合同条款。如果云解析器位于错误的地区，这将违反合同。

• 隔离环境：某些网络根本没有出站互联网连接。在这些网络中，云调用不是慢，而是不可能。

• 规模成本：每页几美分对千页来说微不足道，但对一千万页来说却是一个真正的费用项。

该功能是相同的；区别在于文档是否跨越到计费的云端，还是留在主机上 – 图片由作者提供

Docling 以同样的方式回答这四个问题：模型在文档已经存在的地方运行。权衡从金钱和信任转移到计算和设置。你支付的是 CPU 秒数和一次性的模型下载费用，而不是按页收费和合规性审查。对于一个机密的语料库，这就是你想要的权衡。

本文的其余部分与第 5 bis 篇文章的结构相同，因为合同是相同的。在细节上，Docling 与 Azure 的不同之处会被明确指出。

2. 同样的合同，本地运行

一次调用，与 fitz 解析器相同的表格，结构相同，全部来自一个本地的 Docling 转换。Docling SDK 调用本身很简短：构建一个 DocumentConverter，传入一个路径，然后读取一个 DoclingDocument。第一次调用会将布局和 TableFormer 权重下载到本地缓存；之后的每次调用都离线进行。

from docling.document_converter import DocumentConverter

converter = DocumentConverter()                   # 懒加载：此时不加载模型
result = converter.convert("data/paper/1706.03762v7.pdf")
doc = result.document                             # 一个 DoclingDocument

# 一个 DoclingDocument 提供的内容
doc.export_to_markdown()  # 整个文档的 Markdown 格式
doc.tables                # TableItem 列表（每个都携带 .data.table_cells）
doc.pictures              # PictureItem 列表（边界框 + 可选的 OCR / 分类）
doc.texts                 # TextItem 列表，标签为标题 / 小节标题 / 段落 / 公式 / 图片说明

该 DoclingDocument 是本文中所有构建者读取的内容。parse_pdf_docling 包装了上面的调用，并将文档转换为与其他引擎返回的相同表格字典，因此下游模块无需知道哪个引擎运行即可读取输出。以下是调用包装器的方式。

out = parse_pdf_docling("data/contracts/MyContract.pdf")

out["line_df"]         # 文本项 + 表格单元格 + 复选框
out["page_df"]         # 每页一行
out["image_df"]        # 图片，OCR 文本 + 分类
out["toc_df"]          # 从布局标签重建
out["object_registry"] # 通过标签检测到的图片说明
out["cross_ref_df"]    # 正文提及（正则表达式）
out["span_df"]         # 空（没有子行排版）
out["parsing_summary"] # 文档级别的综合字典

parse_pdf_docling 是 parse_pdf 的本地双胞胎：相同的调用方式，相同的表格字典输出，因此每个下游模块都可以读取它，而无需知道哪个引擎运行。正文内容值得一看，因为它展示了系列中每个引擎遵循的结构：一次转换，然后每个表格一个小型构建器，并重用与引擎无关的构建器来处理只需要 line_df 的表格。

def parse_pdf_docling(pdf_path):
    doc = convert_pdf(pdf_path)                  # 一次 Docling 转换，共享使用
    line_df  = docling_pdf_to_line_df(pdf_path, doc=doc)   # 文本 + 表格单元格
    image_df = build_image_df_docling(doc)                 # 图片 + OCR 文本
    toc_df   = build_toc_df_docling(doc)                   # 标题 / 节标题
    object_registry = build_object_registry_docling(doc)   # 图注标签
    page_df      = build_page_df(line_df)        # 重用 fitz 构建器（仅使用 line_df）
    cross_ref_df = build_cross_ref_df(line_df)   # 重用 fitz 构建器（仅使用 line_df）
    return {"line_df": line_df, "image_df": image_df, "toc_df": toc_df,
            "object_registry": object_registry, "page_df": page_df,
            "cross_ref_df": cross_ref_df, "span_df": pd.DataFrame(),
            "parsing_summary": parsing_summary}

从上到下阅读：一次 convert_pdf 运行模型一次，然后每个表格有一个小构建器（每个构建器都读取那个共享的 doc），而仅需要 line_df、page_df 和 cross_ref_df 的两个表格，是由原生解析器使用的同一个 fitz 构建器生成的。最后的字典是每个引擎返回的合同。

这些表格与 parse_pdf 相对应，使用 Docling 在 15 页的 Attention 论文上运行的真实形状 – 图片由作者提供

这个一次转换运行的内容。将 Docling 归类为“OCR”是诱人的。但 Docling 并不是 OCR；OCR 是它内部的一个可选阶段。convert() 首先运行一个布局模型（它找到区域、表格、图表、标题、正文及其阅读顺序），然后在每个检测到的表格上运行 TableFormer（行、列和标题的网格），只有在页面是扫描件且没有文本层时，才会运行 OCR 引擎来读取像素。对于原生数字 PDF，OCR 阶段完全被跳过：单元格文本来自原生文本层。因此，表格的 markdown 是 TableFormer 的结构，填充了单元格文本，这些文本在原生 PDF 上从未经过 OCR 处理。你选择的 OCR 引擎（EasyOCR、PaddleOCR、Tesseract、RapidOCR）只影响扫描像素的处理，而表格本身的品质调节旋钮是 TableFormer 的模式（快速 vs 准确），而不是 OCR 后端。

Docling 是一个管道，而不是 OCR 包装器：布局和 TableFormer 处理结构；OCR 仅读取扫描像素 – 图片由作者提供

3. 每个表格获得的内容

为了在你可以验证的内容上展示这一点，我们在 Attention Is All You Need 论文（Vaswani 等人，2017；arXiv 非独占分发许可，在 arXiv 摘要页面上声明）上运行了 Docling，这是该系列中使用的一篇公共 arXiv PDF。十五页，原生数字，没有原生书签，四个真实表格，六个图表，五个显示公式。这是一篇文档，其中 fitz 在散文部分表现良好，但丢失了表格和节结构。插入你自己的 PDF，同样的构建器会运行；下面的数字是 Docling 在这篇文档上返回的结果。

3.1. line_df 获得表格单元格行、图表文本、复选框

Docling 的 TableFormer 模型将每个表格检测为一个具有行和列索引以及标题标志的单元格网格。我们将这个网格展平为 markdown 行，使表格像其他内容一样存在于 line_df 中，每行一个表格行，在标题后有一个 | --- | 分隔符。论文中的表 1（一个 5 行 4 列的复杂性比较）返回为 six line_df 行：五条数据行加上标题后跟随的 | --- | 分隔符。

表格扁平化本身过程简短，但值得一看，因为它就是整个技巧所在：先创建一个空的行数乘以列数的网格，将每个 TableFormer 单元格放入其对应的（行，列）位置，然后将每一行合并成一条 Markdown 格式的一行。

def table_to_markdown_rows(table):
    n_rows, n_cols = table.data.num_rows, table.data.num_cols
    grid = [[""] * n_cols for _ in range(n_rows)]
    header = set()
    for cell in table.data.table_cells:      # the cells TableFormer found
        row, col = cell.start_row_offset_idx, cell.start_col_offset_idx
        grid[row][col] = cell.text.strip()
        if cell.column_header:
            header.add(row)
    h = min(header) if header else 0
    rows = ["| " + " | ".join(grid[h]) + " |",           # header row
            "| " + " | ".join(["---"] * n_cols) + " |"]   # separator
    rows += ["| " + " | ".join(grid[r]) + " |"            # data rows
             for r in range(n_rows) if r != h]
    return rows      # one markdown line per source row -> one line_df row each

每个源行都会变成 line_df 中的一行；列结构包含在 Markdown 文本中。这些就是 Docling 为表 1 生成的真实行 – 图片由作者提供。

我们选择将单元格保留在 line_df 中，而不是添加一个单独的表格单元格表。这样下游的每个模块都可以读取一个 DataFrame；段落行和表格行在输出时看起来是一样的。代价是：每个单元格的查询需要一个 Markdown 解析步骤。对于 RAG 问题，这没有问题。检索器在行文本中匹配关键词，模型直接读取 Markdown。这与 Azure 构建器的选择是一致的，因此下游的分块器会将 fitz、Azure 和 Docling 的表格行视为相同。

还有两个额外的来源向 line_df 提供数据。Docling 在图像区域中找到的文本会以普通文本行的形式出现（通过布局 + OCR 恢复），因此在图表中渲染的标签可以被搜索到。复选框项会变成单字符行，选中时为 [x]，未选中时为 [ ]，因此复选框表单字段可以被查询。在《Attention》论文中，当四个表格被展平后，行数从原始文本的行数增加到 560 行。

3.2. image_df 增加了 ocr_text 和一个分类列

同一行，新增两列。对于每个检测到的图片，我们收集所有其边界框至少有 50% 位于图像区域内的文本项，并将它们合并为 ocr_text。第 3 页的架构图和第 4 页的两个注意力图在其图像内部带有标签，这些标签会出现在 ocr_text 中并可以被检索。

《Attention》论文中的图表，其内部标签已暴露 – 图片由作者提供

新增的第二列是分类。Docling 提供了一个可选的图片分类器，用于标记每个图像（如图表类型、标志等）。当启用分类器时，标签会出现在分类列中；当未启用时，该列保留以保持结构一致，但内容为空。Azure 没有类似功能，因此这是 Docling 超越 Azure 的一个地方。对于由 fitz 生成的 image_df，该列根本不存在；fitz 返回的是 width_px / height_px / image_hash，并且从不进行图像的 OCR。

3.3. toc_df 从布局标签中重新构建

《Attention》论文没有原生的书签。使用 fitz 的 build_toc_df 来处理它，你会得到一个空表，这在企业环境中很常见：Word 导出、扫描件、任何没有使用 LaTeX 和 hyperref 设置的文档。这种情况下，生成过程会丢失章节结构。

Docling 直接为每个标题添加标签：

• 用于文档标题的 title item，当检测到标题时

• 为每个章节标题添加一个 section_header item（在本文中，Docling 即使将标题也标记为章节标题）

构建器会遍历这两个标签，分配一个级别，并组装一个 TOC，其 start_page、end_page、start_y 和 breadcrumb 列与 fitz 路径相同。计算 end_page 的回溯过程与 fitz 和 Azure 的过程相同；只是行的来源不同。

在 Attention 论文上，它恢复了 28 个标题，而 fitz 没有恢复任何标题。这个数字并没有被夸大：Docling 为每个章节标题都标记了一次，包括 Method 和 Results 的子章节，这对这篇论文是正确的。对于一个具有较短、更密集章节的文档，数量会更低。

从布局标签中在没有原生书签的 PDF 上恢复的 28 个标题 – 图片由作者提供

层次的深度取决于文档。当 Docling 的布局模型分配了不同的标题级别时，你会得到一个真正的多级树；在这篇论文中，它将标题标记为单个级别，因此重建的 TOC 主要是扁平的。不管怎样，它都是一个可用的章节索引，而 fitz 会给出什么都没有。Azure 也通过其自己的角色标签执行了同样的技巧；两者相当，Docling 在本地运行。

3.4. object_registry 获取标题标签检测

Fitz 通过以行开头的正则表达式检测标题，例如 ^Figure \d+\b、^Table \d+\b。它会错过 Fig. 2 和多行换行，还会在以 “Figure 2 shows…” 开头的正文句子上产生误判。

Docling 在布局分析期间将标题块标记为标题标签。我们直接读取标签，不需要正则表达式来查找标题。(object_type, object_id) 与 cross_ref_df 的连接键仍然通过 fitz 和 Azure 构建器使用的相同正则表达式从标题文本中提取，因此无论使用哪种引擎，连接都是一样的。在 Attention 论文中，这将所有九个标题（Figure 1 到 5，Table 1 到 4）放入 object_registry。优势在于召回率：Docling 能够捕捉到 fitz 的行开头正则表达式会遗漏的标题。

3.5. parsing_summary 增加了 Docling 特有的统计信息

三个计数进入文档级别的合成字典中：

• n_tables_detected：TableFormer 检测到的表格数量（在 Attention 论文中为 4）。

• n_pictures：布局模型识别出的图片数量（为 6）。

• n_formulas：Docling 标记为公式的显示公式数量（为 5）。

这些使得路由变得简单。一个文档如果 n_tables_detected = 18，看起来像一份合同，其中表格结构很重要。一个文档如果 n_formulas 数量达到数十，那是一篇以数学为主的文章，你可能需要一个公式感知的下游步骤。一个文档如果 n_pictures = 0，那么是纯文本；没有理由扫描图片以查找内部文本。

3.6. page_df 和 cross_ref_df：保持不变

两个表格保持相同的结构。page_df 和 cross_ref_df 仅从 line_df 构建，因此生成 line_df 的引擎无关紧要。一个实现，三种引擎，没有漂移。

在 Docling 下，span_df 为空，与 Azure 下的情况完全相同。布局模型不会暴露子行的排版（如按单词加粗或斜体）。当你需要用于标题检测或术语强调的 span 时，对于该文档请继续使用 fitz。这些引擎可以相互补充。

4. parsing_method 列：自适应解析的来源

每行表格来自 parse_pdf_docling 的都会带有 parsing_method == "docling"。每行表格来自 parse_pdf 的会带有 "fitz"；来自 parse_pdf_azure_layout 的会带有 "azure_layout"。相同的列，相同的名字，每个引擎都如此。关键点在于下游处理。

使用 fitz 解析的合同，表格页面再次使用 Docling 解析；两个引擎通过 parsing_method 列在 line_df 中共存 – 图片由作者提供

这就是自适应解析（文章 10）所使用的机制。默认情况下使用 fitz。那些在预解析检查中失败的页面（如没有提取出任何行的表格区域、图像密集但文字稀少的页面、质量低的 OCR 层）将被更强大的引擎重新解析。使用 Docling 进行重新解析是本地的，因此即使文档无法上传到云端，它仍然可用。重新解析的行将替换或追加到原始 line_df 行中，而 parsing_method 列则保留了追踪信息。

该列使下游的三种模式成为可能：

• 去重：当同一页经历了两次解析时，通过显式的优先级映射，保留更强大引擎的行，而不是 fitz 的行。

• 审计：带有 parsing_method == "docling" 的行告诉你，它是通过模型生成的，而不是简单的文本提取；答案的置信度加权可以利用这一点。

• 路由统计：哪些页面需要走重型路径，以及它们耗时多久。

5. 成本、延迟和设置

运行 Docling 是免费的，但运营它并不免费。有三件事需要考虑。

延迟：在 CPU 上，一个页面通过完整的 Docling 流程（布局 + TableFormer + OCR）大约需要 1 到 5 秒，具体时间取决于页面的复杂程度。在笔记本电脑的 CPU 上，开启 OCR 的 15 页《注意力》论文解析时间不到几分钟。使用 GPU 可以显著缩短这个时间。fitz 解析相同的文档只需不到一秒。因此，路由规则与 Azure 一致：首先使用 fitz 解析，仅在 fitz 处理效果不佳的页面上升级到 Docling。与 Azure 的区别在于，升级到 Docling 的成本是 CPU 时间，而不是金钱或网络往返时间。

设置：第一次转换会将布局和 TableFormer 模型（数百 MB）下载到本地缓存，而 Docling 的安装会引入 PyTorch，体积较大。需要预算用于磁盘空间和一次性下载。之后就可以离线使用。在隔离网络环境中，你可以提前将模型缓存部署好；运行时不需要连接到外部网络。

计算成本，而非每页费用：没有每页收费。成本取决于你运行它的机器。对于每年处理一千万页的机密数据，拥有本地计算资源通常比每页的云费用更便宜，而且当数据完全不能离开时，这是唯一的选择。

这些数字会随着硬件和 Docling 的版本而变化。重要的是其趋势：fitz 几乎是免费且即时的；Docling 需要几秒的本地计算时间和一次性的设置；Azure 每页收费数美分，并需要连接到你必须信任的云端。

6. 何时调用哪个引擎

默认使用 fitz。当有明确信号表明 fitz 不够时，升级到重型引擎，并根据文档允许上传的位置选择引擎。

• fitz：默认情况下，每页都使用。适用于生来就是数字的 PDF，具有可选择的文本和简单的布局。免费、即时、离线。

• Docling：当 fitz 处理失败（如表格、扫描件、图表文字、没有书签）且文档是机密的或环境是隔离的。本地运行，使用时免费，数据不会离开机器。如果你更倾向于拥有计算资源而不是按页付费，这也是默认选择。

• Azure DI：当 fitz 无法处理且将文档发送到云端是可以接受的，并且你更倾向于使用托管服务而不是自行运行模型时。按页计费，无需维护任何基础设施，部署速度最快。

触发升级的信号与 Article 5 bis 中列出的一致：检测到一个没有类似行结构的表格区域、一个图像密集但文本稀疏的页面、OCR 质量评分较低，或一个没有原生目录但需要段落上下文的文档。Article 10 构建了读取这些信号的调度器。parsing_method 列让每个下游阶段知道哪个引擎处理了哪一行。

7. 结论

无论使用哪种引擎，相同的关联表结构。在 Azure 和 Docling 之间，能力行几乎势均力敌；决定性的行是操作层面的。Azure 将文档发送到云端并按页计费。Docling 在本地保留文档，仅按计算资源计费。Fitz 两者都不做，成本为零。

对企业 RAG 至关重要的每种能力，以及计算运行的位置、速度和成本 – 图片由作者提供

8. 参考资料和进一步阅读

Docling 在 IBM Research 技术报告（Auer 等，2024）中进行了描述，该报告描述了布局流水线、TableFormer 单元检测模型以及阅读顺序步骤。Docling 继承的单元级表格提取方法有其自身的研究背景（Smock 等，2022，PubTables-1M / Table Transformer）。与本文相关的交叉阅读是 Article 5bis（Azure DI），它提供了来自付费云服务的相同表格合同：相同的能力，不同的操作配置。

与文章方向一致：

• Auer 等，《Docling 技术报告》，IBM Research 2024（arXiv:2408.09869）。本文使用的本地布局流水线的参考架构：布局检测、TableFormer、阅读顺序、统一文档表示。

• Smock、Pesala、Abraham，《PubTables-1M / Table Transformer（TATR）》，CVPR 2022（arXiv:2110.00061）。Docling 和 Azure 都采用的单元级表格提取方法背后的研究背景。

不同角度、不同背景：

• Microsoft，Azure AI 文档智能。布局模型。与 Article 5bis 相同的级联的付费云服务等价物。相同的表格合同；以云端上传和按页计费换取本地计算。当运营团队更倾向于使用托管服务而不是本地托管模型权重时，这是正确的选择。

问题很少是“哪个解析器最好”，而是“这个文档被允许做什么，这个页面需要什么”。一个干净的纯文本数字页面：fitz。一份公开报告中的表格页面：如果你想要托管服务，选择 Azure；如果你想要本地处理，选择 Docling。Article 10 连接了按页面做出决策的调度器。

系列中更早的部分：

• 文档智能：系列简介。系列构建的内容，一块一块，以及构建顺序。

• 从 PDF 到高亮答案的基线企业 RAG。四块砖的端到端流水线：PDF 输入，高亮答案输出。

• 嵌入不是魔法：RAG 检索的可预测失败模式。嵌入相似性在哪些地方胜出（同义词、拼写错误、改写），在哪些地方可预测地失败（未知术语、否定、术语与答案的相关性），以及如何无论如何使用它。

• 重排序器也不是魔法：交叉编码器层是否值得付出延迟成本。交叉编码器相对于双编码器嵌入添加了什么，经过测量，以及何时值得付出延迟成本。

• RAG 并不是机器学习，而机器学习工具包解决的是错误的问题。为什么块大小调整和微调优化的是错误的目标；应根据问题类型进行路由。

• 从正则表达式到视觉模型：哪种 RAG 技术适用于哪种问题。两个轴：文档复杂度和问题控制，用于为每种情况选择合适的技术。

• 我们在生产环境中持续看到的 10 个常见 RAG 错误。十个生产环境中的错误，按砖块逐一组织，并附有每个错误的修复方法。

• 超越 extract_text：驱动 RAG 质量的 PDF 的两个层次。解析砖块的第一部分：文档的性质、信号和摘要。

• 停止从 PDF 返回扁平文本：RAG 所需的关系结构（链接即将发布）。解析砖块的第二部分：每个下游砖块读取的关系表。

• 当 PyMuPDF 无法识别表格时：使用 Azure Layout 解析 PDF 以进行 RAG（链接即将发布）。Azure Layout 提供的相同表格：原生表格单元格、OCR 和段落角色。

撰写者

查看 Kezhan Shi 的所有文章

文档处理

,

大语言模型

解析

PDF

分享本文

• 在 Facebook 上分享

• 在 LinkedIn 上分享

• 在 X 上分享

Towards Data Science 是一个社区出版物。提交你的见解，以触达全球受众，并通过 TDS 作者支付计划获得收益。

更新 href 为你的实际投稿链接

为 TDS 写作

✦ 结束 CTA ✦