Docling 总览:统一文档解析器

30 秒导读: Docling 是一个 Python SDK + CLI,把 PDF、Word、PPT、Excel、HTML、 Markdown、图片、音频、邮件、各种 XML 等几十种格式,统一解析成一个叫 DoclingDocument 的结构化文档对象,再导出成 Markdown / JSON / HTML 等,专门喂给 RAG / 生成式 AI 流程。你只要写 DocumentConverter().convert(x).document.export_to_markdown()。

本章是这组文档的门厅:只讲「这是什么、大概怎么转、各部件在哪、该读哪一章」, 不深入实现。任何一个机制的细节都指向 01–05 章。

1. 这是什么(零基础也能懂)

一句话定义: Docling 是一个「文档 → 统一结构」的转换器。喂给它一个文件(本地路径、 URL 或内存字节流),它吐回一个统一的、可导出的文档对象。

解决什么问题 / 给谁用: 假设你在搭一个 RAG 问答系统,知识库里混着 PDF 合同、Word 报告、PPT、扫描件、网页存档。每种格式的解析库都不一样、输出结构也不一样,你不想为每种格式写一套抽取 + 清洗 + 切块的代码。Docling 把这件事统一掉:不管进来的是什么格式,出去的都是同一种 DoclingDocument, 下游只需面对一种数据结构。依据 README.md:29-31「What is Docling」段。

它能做什么(功能,依据 README.md:33-47 Features):

能力	说明
多格式解析	PDF / DOCX / PPTX / XLSX / HTML / EPUB / 图片 / 音频(ASR) / 邮件 / LaTeX / 各类 XML 等
PDF 深度理解	版面布局、阅读顺序、表格结构、代码、公式、图片分类
统一表示	一个 `DoclingDocument` 承载所有格式的解析结果
多种导出	Markdown、HTML、JSON(无损)、DocTags、WebVTT 等
面向 AI 集成	LangChain / LlamaIndex / Haystack 等,以及分块器(chunking)
本地可离线	敏感数据 / 隔离网络环境可完全本地运行

用起来什么样(最小示例):

Python(推荐,README.md:93-100):

from docling.document_converter import DocumentConverter

source = "https://arxiv.org/pdf/2408.09869"   # 本地路径或 URL 都行
converter = DocumentConverter()
result = converter.convert(source)
print(result.document.export_to_markdown())    # 输出:"## Docling Technical Report[...]"

命令行(README.md:79-88;入口 pyproject.toml:70-71 docling = "docling.cli.main:app"):

docling https://arxiv.org/pdf/2206.01062          # 生成同名 .md
docling --pipeline vlm --vlm-model granite_docling https://arxiv.org/pdf/2206.01062

一句话直觉 / 类比: 把 Docling 当成文档界的万能翻译插座—— 左边插进任意「插头形状」(格式),右边永远输出同一种「标准电流」(DoclingDocument)。中间那套「识别插头 → 选对适配器 → 转成标准电流」的机制,就是这组文档要讲的东西。

注:docling/__init__.py 是空文件(0 字节),包不在顶层 re-export 符号; 对外主入口是 docling.document_converter.DocumentConverter,CLI 入口是 docling.cli.main:app。

2. 顶层全景(一次 convert 怎么转)

2.1 主线一张图

一次 convert() 的数据流,从左到右、命中即走下一格:

  source                                                         DoclingDocument
(路径/URL/流)                                                      + 导出字符串
    │                                                                   ▲
    ▼                                                                   │
┌─────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐   ┌──────────┐ │
│①识别格式 │──▶│②选后端+  │──▶│③后端读   │──▶│④流水线   │──▶│⑤组装+    │─┘
│InputFormat│  │ 流水线   │   │ 原始字节 │   │ 产出内容 │   │ 富化+导出│
└─────────┘   │FormatOption│  │ backend/ │   │ pipeline/│   │datamodel/│
              └──────────┘   └──────────┘   └──────────┘   └──────────┘
   猜MIME/后缀   查分派表并    把文件变成     两种走法:      读顺序/标题层级
   (第01章)     缓存流水线    可处理形态     直出 或        /图片富化,
                (第01章)      (第02章)      分页识别        然后 export
                                            (第03/04章)     (第05章)

怎么读这张图: ①②是「分派」(决定用谁),③④是「干活」(真正解析), ⑤是「收尾」(拼成文档并导出)。四种箭头都是同一次 convert() 内顺序发生。

2.2 部件一句话职责

部件	干什么	在哪(相对克隆根)
`DocumentConverter`	对外唯一入口,编排整条链	`docling/document_converter.py:274`
格式识别	由后缀 / MIME / 内容猜 `InputFormat`	`docling/datamodel/document.py:741` `_guess_format`
`FormatOption`	把「格式」映射到「后端类 + 流水线类」	`docling/document_converter.py:90`、`236` `_get_default_option`
backend(后端)	把原始字节读成可处理形态	`docling/backend/`
pipeline(流水线)	把后端产物加工成 `DoclingDocument`	`docling/pipeline/`
models/stages	PDF 识别用的各阶段模型(布局/OCR/表格…)	`docling/models/stages/`
datamodel	`DoclingDocument`、`ConversionResult`、各种 options	`docling/datamodel/`
chunking	把 `DoclingDocument` 切块喂 RAG	`docling/chunking/`

2.3 主线走一遍(高层,不进代码)

你调 convert(source),它内部转成批量的 convert_all([source]) (document_converter.py:402、467)。
输入被包成 _DocumentConversionInput,其 docs() 逐个猜格式、按格式 查出该用哪个后端,产出 InputDocument(datamodel/document.py:599 docs)。
转换器按格式取一条流水线(带缓存),调用 pipeline.execute(in_doc) (document_converter.py:663 _get_pipeline、714 _execute_pipeline)。
流水线内部固定四步:_build_document → _assemble_document → _enrich_document → _determine_status(pipeline/base_pipeline.py:69 execute)。
结果是一个 ConversionResult,里面挂着 .document(即 DoclingDocument)、 .pages、.status、.confidence(datamodel/document.py:372 ConversionAssets)。
你对 .document 调 export_to_markdown() 等导出,或交给 chunking 切块。

3. 两条主路径(整份文档的骨架分歧)

Docling 的核心设计是:同一个入口,底下有两条截然不同的处理路径。选哪条, 完全由「格式 → FormatOption」这张分派表决定(document_converter.py:236)。读懂这两条路径的对比,就读懂了 Docling 的一半。

3.1 路径 A —— 声明式直出(结构已在源文件里)

像 Word / PPT / Excel / Markdown / HTML / CSV 这些格式,结构信息本来就写在文件里 (标题、段落、表格都是显式标签),不需要「识别」,后端能直接吐出 DoclingDocument。

流水线:SimplePipeline(pipeline/simple_pipeline.py:16)
后端:DeclarativeDocumentBackend(backend/abstract_backend.py:66), 它有个 convert() 方法一步产出文档。
干活方式:SimplePipeline._build_document 就一句 conv_res.document = backend.convert()(simple_pipeline.py:40)——没有分页、没有模型。

3.2 路径 B —— 分页识别(结构要靠模型认出来)

像 PDF / 图片 / 扫描件,文件里只有像素或字形坐标,没有"这是标题/这是表格"的语义。必须逐页跑一串识别模型(布局检测、OCR、表格结构、阅读顺序)才能重建结构。

流水线:StandardPdfPipeline(pipeline/standard_pdf_pipeline.py:567)—— 一个多线程分阶段流水线。
后端:PdfDocumentBackend(分页后端,backend/abstract_backend.py:54 PaginatedDocumentBackend 的子类),能按页取字节。
干活方式:逐页流经 preprocess → ocr → layout → table → assemble 五个线程化阶段 (standard_pdf_pipeline.py:685-733)。

3.3 两条路径对比

维度	路径 A 声明式直出	路径 B 分页识别
典型格式	DOCX / PPTX / XLSX / MD / HTML / CSV / EPUB / 邮件 / XML	PDF / IMAGE / METS_GBS
流水线	`SimplePipeline`	`StandardPdfPipeline`
后端基类	`DeclarativeDocumentBackend`	`PaginatedDocumentBackend` / `PdfDocumentBackend`
结构从哪来	源文件里已有显式结构	靠识别模型从像素/坐标重建
是否分页	否,整份直出	是,逐页处理
是否跑 ML 模型	否(构建阶段)	是(布局/OCR/表格/阅读顺序)
是否多线程	否	是(有界队列 + 背压)
详见	第 02 / 03 章	第 03 / 04 章

两条路径最终汇合于同一处:都产出 ConversionResult.document(DoclingDocument), 再统一走富化(第 05 章)和导出。这正是「统一文档解析器」名字的由来。

4. 巧妙之处清单(只点题,细节留各章)

这里只列出 Docling 值得带走的几个设计,每条一句话点破妙在哪,实现细节见对应章节。

① 三级分派 + 按 options 哈希缓存流水线。 格式识别、格式→(后端+流水线)映射、流水线实例三层解耦;流水线以 (pipeline_cls, options_hash) 为键缓存,重复转换同类文档复用同一实例、不重复加载重模型 (document_converter.py:663-690 _get_pipeline、375 _get_pipeline_options_hash)。→ 第 01 章。

② 后端与流水线正交。 「怎么读字节」(后端)和「怎么加工」(流水线)是两个独立维度,靠 FormatOption 自由组合(document_converter.py:90)。→ 第 02 / 03 章。

③ 线程化分阶段 PDF 流水线。 StandardPdfPipeline 每个阶段一个 worker 线程,阶段间用有界队列连接;队列满时生产者阻塞(背压),close() 逐级传播实现确定性收尾;每次 execute 用独立 run_id 隔离并发调用(standard_pdf_pipeline.py:149 ThreadedQueue、216 ThreadedPipelineStage、573 run 序号、846-863 文档级超时)。→ 第 04 章。

④ enrichment 二次富化。 主结构建好后,再对特定元素(图片描述、图片分类、代码/公式、图表抽取)跑第二轮增补模型(base_pipeline.py:111 _enrich_document、177 富化模型列表; PDF 额外加 CodeFormulaVlmModel,standard_pdf_pipeline.py:631)。→ 第 05 章。

⑤ 失败不中断批处理 + 结构化错误。 单个文档解析失败(格式不符、URL 取不到、超时、某页解析崩)不会拖垮整批;失败被记成 ErrorItem 挂在 ConversionResult.errors,状态区分 SUCCESS / PARTIAL_SUCCESS / FAILURE / SKIPPED(base_models.py:85 ConversionStatus、document_converter.py:692 _process_document)。→ 第 01 / 05 章。

5. 全局代码地图(导航索引)

一张表把你/agent 直接送进源码。符号名比行号抗漂移,优先用符号名 grep 定位。

主题	文件路径	符号名
对外入口、编排	`docling/document_converter.py`	`DocumentConverter`、`convert`、`convert_all`、`convert_string`
格式→后端+流水线分派表	`docling/document_converter.py`	`FormatOption`、`_get_default_option`、`PdfFormatOption`、`WordFormatOption`
流水线缓存	`docling/document_converter.py`	`_get_pipeline`、`_get_pipeline_options_hash`
输入迭代 / 格式识别	`docling/datamodel/document.py`	`_DocumentConversionInput.docs`、`_guess_format`
支持的输入格式	`docling/datamodel/base_models.py`	`InputFormat`、`FormatToExtensions`、`FormatToMimeType`
转换状态 / 组件类型	`docling/datamodel/base_models.py`	`ConversionStatus`、`DoclingComponentType`、`FailureCategory`
后端基类(三种)	`docling/backend/abstract_backend.py`	`AbstractDocumentBackend`、`DeclarativeDocumentBackend`、`PaginatedDocumentBackend`
各格式后端实现	`docling/backend/`	`MsWordDocumentBackend`、`HTMLDocumentBackend`、`DoclingParseDocumentBackend`、`PdfDocumentBackend`
流水线骨架(四步)	`docling/pipeline/base_pipeline.py`	`BasePipeline.execute`、`_enrich_document`、`ConvertPipeline`、`PaginatedPipeline`
声明式流水线	`docling/pipeline/simple_pipeline.py`	`SimplePipeline`
多线程 PDF 流水线	`docling/pipeline/standard_pdf_pipeline.py`	`StandardPdfPipeline`、`ThreadedQueue`、`ThreadedPipelineStage`、`RunContext`
PDF 识别各阶段模型	`docling/models/stages/`	`PagePreprocessingModel`、`LayoutModel`、`PageAssembleModel`、`ReadingOrderModel`
结果 / 数据模型	`docling/datamodel/document.py`	`ConversionResult`、`ConversionAssets`、`InputDocument`
面向 RAG 的分块	`docling/chunking/__init__.py`	`HybridChunker`、`HierarchicalChunker`(re-export 自 `docling_core`)
CLI 入口	`docling/cli/main.py`	`app`、`convert`

6. 阅读地图(建议顺序)

由浅入深,顺着一次 convert() 的数据流往下钻:

01-entry-dispatch.md —— 入口与三级分派: convert 如何变成 convert_all → _convert → _process_document,格式怎么被猜出来, FormatOption 分派表,以及流水线的哈希缓存。先读这章建立主干。
02-backends.md —— 后端层:三种后端基类、声明式后端如何一步 convert() 直出、分页后端如何按页取字节。
03-pipelines.md —— 流水线层:BasePipeline 的四步骨架, SimplePipeline 直出 vs StandardPdfPipeline 的多线程分阶段架构对比。
04-pdf-recognition-stages.md —— PDF 识别流水线: preprocess / ocr / layout / table / assemble 五个阶段各自的模型与线程化细节。
05-datamodel-output-rag.md —— 数据模型、enrichment 二次富化、DoclingDocument 的导出与面向 RAG 的分块。

只想「用」不想「懂」的,读完 §1 + §2 即可上手;要改 Docling 或排查解析问题, 按上面顺序读完 01–05。

1. 这是什么(零基础也能懂)​

2. 顶层全景(一次 convert 怎么转)​

2.1 主线一张图​

2.2 部件一句话职责​

2.3 主线走一遍(高层,不进代码)​

3. 两条主路径(整份文档的骨架分歧)​

3.1 路径 A —— 声明式直出(结构已在源文件里)​

3.2 路径 B —— 分页识别(结构要靠模型认出来)​

3.3 两条路径对比​

4. 巧妙之处清单(只点题,细节留各章)​

5. 全局代码地图(导航索引)​

6. 阅读地图(建议顺序)​