> **TL;DR 速览**
> 
> -   **它做什么**：把 AI 啃不动的文件（**PDF / DOCX / PPTX / XLSX / HTML / EPUB / LaTeX / 扫描图 / 音视频 / 邮件 / ODF / XBRL**）转成**保住结构的 Markdown 或无损 JSON**
> -   **差别不在"抠文字"**：重点是保住**版面、阅读顺序、表格结构、公式、代码块、图像分类**——这些东西决定了下游切块切得好不好
> -   **体量与热度**：**★6.7 万**、**MIT**、**9-18 发布 v2.129（一周内连发三个版本）**、未关 issue **900+**
> -   **三种用法**：命令行一行转换 / Python API / **VLM 管线（GraniteDocling 258M）**
> -   **三种部署形态**：本地执行（可断网）、`docling-serve` 服务化、**MCP server 接给 Agent**
> -   **一条容易踩的授权坑**：**代码是 MIT，但它引用的各个模型有自己的授权**——商用前要逐个确认

![07_docling_document_parsing.jpg](https://developer.qcloudimg.com/http-save/yehe-12721511/89bcda4296397363d286f1192f6c46c1.jpg)

docling 在 9 月 18 日发布 v2.129，一周内连发了三个版本。它的定位一句话能说清：**把各种难搞的文档格式，转成保住结构的 Markdown 或无损 JSON**。项目起源于 IBM Research Zurich 的 AI for knowledge 团队，现在托管在 LF AI & Data 基金会下，仓库在 `docling-project` 组织，星标 6.7 万。

对做 RAG 的人来说，它的价值不在"能读 PDF"，而在**它认真对待了"结构"这件事**。这篇文章拆它的格式清单、表示层、部署形态和授权口径。

## 一、解析这一环为什么决定了下游上限

先把这一环的位置说清楚。

一个 RAG 系统里，文档解析是**最上游**的一步。它的产物会被切块、被向量化、被检索、最终被喂进模型。**上游丢掉的结构，下游一步都补不回来。**

具体丢的是什么？

**标题层级丢了**，切块就不知道章节边界在哪，只能按固定字数硬切。硬切的后果是**一个块里横跨两个不相干章节**，检索出来的内容自然对不上问题。

**表格结构丢了**，表格会被抽成一串按阅读顺序排列的数字。模型读到的是"2024 2025 收入 120 340 成本 80 210"，**它能看见数字，但看不出哪个是行、哪个是列。**

**阅读顺序丢了**，双栏排版会被抽成"左栏第一行、右栏第一行、左栏第二行……"这种交错文本。模型读起来是乱的，但**你从文本上看不出它乱了**——这是最隐蔽的一类失败。

**公式丢了**，会变成一堆乱码符号。**代码块丢了**，缩进和换行被吃掉，代码就不成立了。

**这四类的共同点是：解析失败的产物看起来像正常文本。** 你不会收到报错，只会收到一个质量下降的检索结果，然后把锅算在切片策略或者 embedding 模型上。**这就是为什么解析这一环值得单独用一个工具来管。**

## 二、支持的格式清单

这份清单值得完整看一遍，因为它决定了你能不能用它统一处理存量文档：

**办公文档**：PDF、DOCX、PPTX、XLSX、HTML、EPUB、Apple Pages（**容器两代都支持：Pages 5+ 和 iWork '09**）、**ODF 三件套（`.odt` / `.ods` / `.odp`）**

**纯文本类**：`.txt` / `.text`，以及 **Markdown 的超集 `.qmd` / `.Rmd`**

**图像**：PNG、TIFF、JPEG 等

**音视频**：WAV、MP3（音频）；**MP4 / AVI / MOV / MKV / WebM（视频，带 ASR 转写和关键帧抽取）**

**邮件**：`.eml`、`.msg`

**专业格式**：LaTeX、DocLang、**XBRL（财报）**、**USPTO（专利）**、**JATS（期刊文章）**、Box Notes、WebVTT

**输出格式**：Markdown、HTML、WebVTT、DocLang、DocTags、**无损 JSON**

**这份清单里三个不太常见但很实用的能力：**

**视频解析。** 抽 ASR 转写加代表性关键帧——这等于把"会议录像"也纳入了可检索范围。这类内容以前在 RAG 里基本是盲区。

**XBRL 与 USPTO。** 这两个是**行业专用格式**，说明这个项目不只服务通用文档。做财报或专利用例的话，这类格式一般都找不到好用的解析器。

**图表理解。** 柱状图、饼图、折线图会被转成**表格或代码**，并附上描述。这一条直接解决了"PDF 里的图画不进 RAG"这个老问题。

## 三、DoclingDocument：为什么"统一表示"才是关键

这是整个架构里最重要的一个设计决定。

docling 的流程是：**各种格式 → 统一的 `DoclingDocument` 表示 → 各种输出格式**。

**这个中间层的价值在于"把 N 种输入和 M 种输出解耦"。** 如果没有它，每加一种输入格式都要为每种输出单独写一遍转换；有了它，新增格式只需要产出一个 DoclingDocument，新增输出只需要写一个导出器。

**对使用者的实际好处有三个：**

**第一，不同来源的文档能进同一个下游管线。** 一份 PDF、一份 PPTX、一封邮件，转出来是同一个结构对象。你的切块逻辑只需要写一遍。

**第二，结构信息是显式字段，不是从文本里猜的。** 标题层级、表格、公式、图片都是有类型的对象，而不是"长得像标题的一行字"。这意味着**你可以对结构做过滤**——比如只取正文段落、跳过页眉页脚、表格单独走一条处理链。

**第三，可以导出无损 JSON。** 这一条值得单独强调：**Markdown 是有损的**（表格能表达，但版面坐标、图片位置这些信息会丢）。如果你需要保留更多信息，走 JSON 导出，把 Markdown 当"给人看的版本"，JSON 当"给程序用的版本"。**把这两个用途分开，能省掉后面很多返工。**

## 四、高级 PDF 理解具体做了什么

PDF 是这套东西里最难的一环，所以单独列一下它声称处理的能力：

-   **版面分析**（哪里是正文、哪里是侧栏、哪里是页眉页脚）
-   **阅读顺序**（多栏排版下的正确顺序）
-   **表格结构**（行、列、合并单元格）
-   **代码块**（保住缩进与换行）
-   **公式**
-   **图像分类**（把图片按类型区分，而不是一律当"一张图"）
-   **扫描件的 OCR**

**其中"阅读顺序"是最容易被低估的一项。** 它是前面说的那种"失败了也看不出来"的能力：文本内容全都在，只是顺序错了。**验证方法很土但有效——拿一份双栏排版的 PDF 转一遍，看转出来的 Markdown 是不是左栏读完再读右栏。** 这一步花两分钟，能筛掉一大批解析器。

**扫描件走的是另一条路径：OCR。** 这个能力是内置的，但要意识到 OCR 出来的文本**天然带识别错误**，而且**版面结构比原生 PDF 更难还原**。对扫描件占比高的存量文档，建议单独统计一下错误率，别和原生 PDF 的平均质量混着算。

## 五、三种部署形态

docling 有三条部署路径，对应三种不同的使用场景：

**形态一：本地执行。** 官方明确提到支持**敏感数据和断网（air-gapped）环境**。这是它的一个重要卖点——文档解析往往要处理内部材料，能把这一步留在本机，省掉一轮数据外发的合规评估。

**形态二：服务化（`docling-serve`）。** 跑成 API 服务，多个应用共用。适合"一批文档要给好几个系统用"的情况，避免每个系统各装一份、各调一遍。

**形态三：MCP server。** 把解析能力**直接接给 Agent**。这是最近比较新的用法——Agent 在需要读文件时自己调解析工具，而不是由人在外面先转好再喂给它。

**选择依据很简单：** 一次性脚本用本地；有多个消费方用服务化；要跟 Agent 联动用 MCP。


## 六、上手路径

**第一步，装。**

```bash
pip install docling
```

注意版本要求：**Python 3.9 的支持在 `docling 2.70.0` 被移除了，需要 3.10 或更高。** 官方支持 macOS、Linux、Windows，**x86\_64 和 arm64 都有**。

**第二步，命令行先跑通。**

```bash
docling https://arxiv.org/pdf/2206.01062
```

**在当前目录生成一个 `.md` 文件**，里面是保住结构的文档内容。这一步的作用是快速确认"这个格式我处理得了"。

**第三步，换 VLM 管线试一次。**

```bash
docling --pipeline vlm --vlm-model granite_docling https://arxiv.org/pdf/2206.01062
```

这条路径用的是视觉语言模型（默认 `granite_docling`，参数量 258M）。**什么时候该用它：** 当常规解析在复杂版面上失败时——比如混排、手写体、或结构异常的扫描件。VLM 路线通常更贵，所以是**兜底手段而不是默认手段**。建议的用法是**先用常规管线跑一遍，对失败的那部分文档再走 VLM**。

**第四步，接进代码。**

```python
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())
```

**这段代码的结构值得留意：转换器和文档对象是分开的。** 转换器可以复用（不用每份文档重新初始化），文档对象则持有结构，可以走不同的导出方式。**这个分层决定了你能不能做批处理**——批量转换时复用转换器，比每份文档新建一个快得多。

**第五步，按你的框架接。**

官方给了即插即用的集成：**LangChain、LlamaIndex、Crew AI、Haystack**。这四个覆盖了主流的 RAG 和 Agent 框架。

**第六步，做一次质量基线。** 用你自己的文档跑一批，重点看三件事：**表格有没有被抽成结构、双栏文档的阅读顺序对不对、扫描件的识别错误率是多少。** 这三个数字才是决定你要不要用它替换现有解析器的依据。

## 七、授权口径与维护状态

**先说那个容易踩的坑。**

**docling 的代码库是 MIT 许可，但它引用的各个模型有自己的授权**——官方把这个区别写在许可证章节里，并提示"请参考各原始包里的模型许可"。

**这两件事必须分开对待：**

-   **只用它的解析逻辑和格式转换** → 走 MIT，限制很少
-   **用到 VLM 管线或 OCR 相关的模型** → 那些模型的授权是独立的，**商用前要逐个确认**

**把"代码 MIT"直接理解成"整个项目可以随便商用"，是一个真实的合规风险。** 遇到这类"代码许可 + 模型许可分离"的项目，都要养成分别查的习惯。

**再说维护状态，这部分得两边看。**

**正面信号**：**一周内连发三个版本**（当前 v2.129）、托管在 **LF AI & Data 基金会**下、有 **OpenSSF Best Practices 徽章**、技术报告挂在 arXiv（编号 2408.09869）。**"进入基金会"这个动作对长期使用是个加分项**——它降低了单一公司撤资的风险。

**需要留意的一面**：**未关 issue 有 900+。** 对这个体量的项目，这个数字本身说明不了太多——**活跃项目和停止维护的项目都会积压 issue**。真正该看的是**近期的 issue 里，属于"解析结果错误"的比例高不高**，以及**新版本是不是还在修这类问题**。如果三个版本连发里有两三个都在修解析正确性，那是健康的信号。

**口径上再补一句：** 它现在的仓库在 `docling-project` 组织下，**不要把它写成"某个公司的仓库"**。起源是 IBM Research Zurich 的团队，这个说法是准确的。

## 八、什么时候该用它

**该用的信号：** 你的文档里**表格、公式、双栏排版、扫描件**占比不低；你需要**把结构往下游传**而不只是拿到文本；你要处理**音视频或行业专用格式**（XBRL / 专利 / 期刊）；你有**断网或数据不出本机**的要求。

**不太需要的信号：** 你的文档全是干净的单栏纯文本；你只需要"把文字抠出来"；你的下游本来就是按固定字数硬切、不依赖结构。**这些情况下用它会引入不必要的复杂度。**

**最后给一个具体建议：拿一份双栏 PDF 转一遍，看阅读顺序对不对。** 这是验证解析器质量成本最低的一个动作，而且它检验的正是那种"看起来正常、实际已经错了"的失败模式。

它做什么：把 AI 啃不动的文件（PDF  DOCX  PPTX  XLSX  HTML  EPUB  LaTeX  扫描图  音视频  邮件  ODF / XBRL）转成保住结构的 Markdown 或无损 JSON

RAG 的上游那一环：把 PDF 转成有结构的 Markdown

人工智能

开发工具

后端

Docling文档解析工具可将PDF、DOCX等20+格式转为保留结构Markdown或无损JSON，核心优势在于版面分析、阅读顺序、表格公式识别。支持本地部署、服务化及MCP，代码MIT许可但模型授权需单独确认。适合复杂文档处理，7天内连发3版，已集成LangChain等主流框架。

Agent 框架

代码解释

敏感数据

LlamaIndex

LangChain

Windows

容器

Python

Agent

Linux

JSON

2026上云采购 | AI焕新·智启新局

apigw

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

RAG 的上游那一环：把 PDF 转成有结构的 Markdown-腾讯云开发者社区-腾讯云

RAG 的上游那一环：把 PDF 转成有结构的 Markdown

RAG 的上游那一环：把 PDF 转成有结构的 Markdown

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐