docling 详细介绍：开源项目架构、功能与实践指南

项目快照：docling-project/docling，约 64,859 个 Star，4,622 个 Fork；最新推送时间 2026-08-15T10:13:09Z。本文基于仓库公开资料撰写。

项目地址：https://github.com/docling-project/docling · https://docling-project.github.io/docling

docling 从代码、运行环境到实践流程的项目封面 — docling 的项目能力与实践流程示意。

项目速览（TL;DR）

Docling 是一个以 Python 编写的文档解析与转换项目，目标是把多种来源、不同格式的文档转换为统一的文档表示，并为生成式人工智能（Generative AI，简称 GenAI）应用提供可处理的数据。仓库默认分支为 main，许可证为 MIT。

根据提供的 GitHub 仓库元信息，项目拥有 64859 个 Star 和 4622 个 Fork。README 将其概括为“Get your documents ready for gen AI”，核心路径是：输入 PDF、Office 文档、网页、图片、音频或其他受支持格式，经过解析、版面理解、光学字符识别（Optical Character Recognition，OCR）或模型处理后，导出为 Markdown、HTML、JSON、DocTags、WebVTT 等格式。

项目类型：文档解析、结构化转换和生成式人工智能数据准备工具。
主要语言：Python。
代码许可证：MIT。
默认分支：main。
运行方式：命令行工具（Command-Line Interface，CLI）、Python 软件开发工具包（Software Development Kit，SDK）、API 服务和模型上下文协议（Model Context Protocol，MCP）服务器。
最低 Python 版本：根据 README，docling 2.70.0 起不再支持 Python 3.9，安装环境应使用 Python 3.10 或更高版本。

定位与目标用户

Docling 解决的不是单一文件格式读取问题，而是“多格式文档如何稳定进入下游检索、分析和生成式人工智能流程”的数据准备问题。它把格式解析、页面版面理解、表格结构识别、OCR 和统一导出放在同一个处理链路中。

项目资料显示，Docling 面向需要处理异构文档集合的开发团队、研究人员以及构建代理式人工智能（Agentic AI）应用的工程团队。由于项目提供本地执行能力，因此涉及敏感文档或隔离网络的场景可以把重点放在本地部署、模型文件管理和输出审计上；具体合规结论仍取决于部署组织的政策和数据分类。

文档知识库团队：需要把 PDF、DOCX、PPTX、XLSX、HTML 和图片统一转换后再进行检索增强生成（Retrieval-Augmented Generation，RAG）。
企业内容处理团队：需要保留表格、标题、阅读顺序、代码或公式等结构信息。
人工智能应用开发团队：需要通过 LangChain、LlamaIndex、Crew AI、Haystack、MCP 或 API 服务接入文档转换能力。
研究与数据处理团队：需要以统一的 DoclingDocument 表示承接不同来源的文档内容。

核心功能

Docling 的核心能力可以分为输入格式适配、文档理解、统一表示、结构化输出以及应用集成五个层面。每种能力都对应不同的输入、处理组件和输出路径，不能仅把它理解为简单的文件扩展名转换器。

多格式输入解析

README 列出的输入包括 PDF、DOCX、PPTX、XLSX、HTML、EPUB、WAV、MP3、WebVTT、Box Notes、EML、MSG、PNG、TIFF、JPEG、LaTeX、DocLang、纯文本以及更多格式。部分格式支持由可选依赖提供，例如 PDF 使用 pypdfium2 和 docling-parse 相关依赖，Office 文档分别使用 python-docx、python-pptx 和 openpyxl。

输入源可以是本地路径，也可以是 URL。README 的 Python 示例把字符串形式的 URL 传给 DocumentConverter.convert；解析器根据输入内容和格式支持选择对应处理路径，随后将结果放入统一文档对象，而不是要求调用方分别处理每一种文件类型。

PDF 版面与结构理解

PDF 处理不仅关注页面中的字符，还包含页面版面、阅读顺序、表格结构、代码、公式和图像分类等信息。对于扫描 PDF 和图片，README 明确提供 OCR 支持；OCR 引擎通过可选依赖启用，例如 rapidocr、easyocr、tesserocr 或平台相关的 ocrmac。

这类处理的输入是页面图像或 PDF 页面内容，输出则是包含文本和结构信息的统一文档表示。实际识别效果与文档质量、语言、模型、OCR 引擎和运行环境有关；仓库资料没有提供统一的准确率、延迟或吞吐量基准，因此部署评估应使用目标文档集自行验证。

统一文档表示与多种导出

DoclingDocument 是项目用于承接解析结果的统一表示格式。Python 示例中的 result.document.export_to_markdown() 表明，调用方可以先获得结构化文档对象，再选择导出方法，而不是在解析阶段绑定某一种最终输出格式。

README 列出的导出格式包括 Markdown、HTML、WebVTT、DocLang、DocTags 和无损 JSON。Markdown 适合进入文本处理链路，HTML 可用于保留部分文档结构，JSON 则适合被程序继续消费；具体字段结构和各导出方法的完整接口，应以官方文档和当前版本代码为准。

图表、音频与视频处理

项目资料列出图表理解能力，支持柱状图、饼图和折线图，并可将图表转换为表格或代码，同时增加详细描述。该能力的输入是包含图表的文档内容，输出可能包含表格、代码或描述性内容；资料没有给出每类图表的完整识别规则或稳定性指标。

音频支持通过自动语音识别（Automatic Speech Recognition，ASR）模型处理 WAV 和 MP3。视频解析支持 MP4、AVI、MOV、MKV 和 WebM，README 将其描述为生成 ASR 转录和代表性关键帧；pyproject.toml 中的视频可选依赖还包括说话人区分、音频读取、机器学习和音频特征处理组件。

生成式人工智能生态集成

README 列出 LangChain、LlamaIndex、Crew AI 和 Haystack 集成，也提供 MCP 服务器和 API 服务（docling-serve）。这些集成的共同点是把文档转换结果暴露给下游代理、检索或服务调用链，而不是改变文档本身的原始内容。

项目还支持视觉语言模型（Vision-Language Model，VLM），README 以 GraniteDocling 为例，并给出 CLI 的 VLM 管道命令。VLM 相关依赖位于 models-vlm-inline 可选依赖组，实际模型下载、模型许可证和硬件要求需要分别核对模型原始仓库及 Docling 文档。

系统架构与关键模块

从 pyproject.toml 的依赖分组可以确认，Docling 采用模块化可选依赖设计：基础 SDK 与 CLI 位于核心包路径，格式支持、OCR、模型、分块和服务客户端按功能拆分。这样做的直接结果是，部署者可以根据输入格式和处理链路安装对应能力，而不必把所有可选功能都视为基础依赖。

处理链路

输入发现：从本地路径或 URL 获取文档，并依据文件类型选择处理器。
格式解析：使用相应格式依赖读取 PDF、Office、网页、电子邮件、XML、音视频或文本内容。
内容理解：对 PDF 进行版面、阅读顺序、表格、代码、公式和图像等处理；扫描件和图片可以接入 OCR。
模型处理：根据管道配置使用本地模型、远程模型或 VLM。README 的 CLI 示例使用 --pipeline vlm 和 --vlm-model granite_docling。
统一承接：将结果放入 DoclingDocument。
结果输出：通过 Markdown、HTML、JSON、DocTags、DocLang 或 WebVTT 等形式交给下游系统。

依赖分层

基础依赖包括 pydantic、docling-core、pydantic-settings、filetype、requests、certifi、pluggy 和 tqdm。转换核心还依赖 numpy、pillow、rtree 和 scipy；模型本地执行则由 torch、torchvision、docling-ibm-models、accelerate 和 huggingface_hub 等可选依赖支持。

项目包名在所给 pyproject.toml 中为 docling-slim，而 README 的安装命令使用 pip install docling。这两个名称来自资料中的不同上下文：README 展示的是用户安装入口，pyproject.toml 展示的是当前文件对应的模块化包配置；安装时应以官方发布页面和最新 README 为准。

依赖与运行环境

官方 README 声明 Docling 可运行于 macOS、Linux 和 Windows，并支持 x86_64 与 arm64 架构。Python 3.9 支持已在 docling 2.70.0 中移除，所给 pyproject.toml 进一步声明运行时要求为 >=3.10,<4.0。

Python 版本之外，实际环境还受选定格式、OCR 引擎和模型依赖影响。例如，GPU 或 CPU 的 PyTorch 安装方式会影响模型执行；Dockerfile 明确使用 CPU 版本的 PyTorch 安装源，并设置了模型缓存相关环境变量。仓库资料未提供统一的 CPU、GPU、内存或磁盘最低规格。

可选依赖组的使用原则

format-pdf：包含 PDF 处理相关依赖。
format-office：组合 DOCX、PPTX 和 XLSX 支持。
format-web：组合 HTML 与 Markdown 支持。
format-audio 与 format-video：分别覆盖音频转录和视频处理。
feat-ocr-rapidocr、feat-ocr-easyocr 等：选择 OCR 引擎。
models-local、models-remote、models-vlm-inline：选择本地模型、远程模型或 VLM 处理方式。
feat-chunking：提供面向 RAG 应用的文档分块能力。
cli 与 service-client：分别补充 CLI 和服务客户端相关依赖。

快速开始：安装、运行与验证

最小闭环可以分成安装、转换和验证三步。以下示例只使用 README 明确给出的安装命令、CLI 命令和 Python API，适合在本地或测试环境中验证基础解析流程。

第一步：安装

python --version
pip install docling

安装前应确认 Python 为 3.10 或更高版本。README 声明该项目可在 macOS、Linux 和 Windows 的 x86_64、arm64 环境运行；具体平台上的模型依赖和可选格式依赖仍应按官方安装文档选择。

第二步：使用 CLI 转换

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

README 说明，该命令会在当前目录生成一个包含结构化文档内容的 .md 文件。示例使用公开论文 URL，不涉及账号、密钥或未授权目标；在生产环境处理远程地址时，仍应确认网络访问和内容使用权限。

第三步：使用 Python API 验证

from docling.document_converter import DocumentConverter

source = "https://arxiv.org/pdf/2408.09869"
converter = DocumentConverter()
result = converter.convert(source)
print(result.document.export_to_markdown())

验证点是程序能够完成转换，并调用 result.document.export_to_markdown() 输出 Markdown。README 给出的示例输出以“## Docling Technical Report”开头；完整输出内容会随输入文档而变化。

配置说明

资料中的可配置项主要集中在 Dockerfile 环境变量和 Python 包的可选依赖组。下表只列出资料明确出现的环境变量；“未提供”表示仓库片段没有声明默认值，不能据此推断运行时行为。

字段名	类型	默认值	作用
`GIT_SSH_COMMAND`	字符串	`ssh -o StrictHostKeyChecking=no`	Dockerfile 中设置的 Git SSH 命令环境变量。
`HF_HOME`	路径字符串	`/tmp/`	Dockerfile 中用于 Hugging Face 相关缓存位置的环境变量。
`TORCH_HOME`	路径字符串	`/tmp/`	Dockerfile 中用于 PyTorch 相关缓存位置的环境变量。
`OMP_NUM_THREADS`	整数形式字符串	`4`	Dockerfile 设置的线程预算，用于容器环境中的线程数量控制。
`DOCLING_ARTIFACTS_PATH`	路径字符串	未提供	Dockerfile 注释给出的模型权重目录用法；设置为 `/root/.cache/docling/models` 时使用容器镜像内包含的模型权重。
`requires-python`	版本约束字符串	`>=3.10,<4.0`	根据 `pyproject.toml` 声明 Python 运行时版本范围。

模型、OCR、格式和服务能力通过可选依赖组启用，而不是由资料中单独列出的配置文件控制。例如，standard 组合了 PDF、本地模型、RapidOCR、Office、Web、LaTeX、邮件、分块、服务客户端和 CLI 相关能力；完整组合列表在所给文件片段中未展示完毕，安装组合应以当前 pyproject.toml 为准。

进阶用法

进阶使用的关键是根据文档来源和部署边界选择处理管道，而不是所有文档都使用同一套模型。README 已明确展示 CLI 的 VLM 管道入口，Python API 则适合把转换结果嵌入应用代码。

使用视觉语言模型管道

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

该命令使用 vlm 管道和 granite_docling 模型标识处理 PDF。README 提到的模型为 GraniteDocling，资料没有说明该命令的完整参数表、显存要求、下载缓存策略或输出差异，因此这些内容不能从示例命令外推。

接入 RAG 文档分块

feat-chunking 可选依赖指向 docling-core[chunking]，用途是面向 RAG 应用进行文档分块。其输入应是已解析的统一文档对象或文档内容，输出形式、分块字段和边界规则需要依据官方分块文档确认；资料没有提供完整的 Python 调用签名。

使用 API 服务与 MCP

README 提供 docling-serve API 服务和 MCP 服务器入口，分别用于将 Docling 作为服务运行以及连接到支持 MCP 的代理。资料未提供 API 服务端口、认证机制、请求体格式、并发限制或部署拓扑，因此不能在此补充未经核实的端口和接口示例。

容器化与模型预下载

Dockerfile 基于 python:3.11-slim-bookworm，安装 libgl1、libglib2.0-0、curl、wget、git 和 procps，随后使用 CPU 版本 PyTorch 安装源安装 docling。镜像构建阶段执行 docling-tools models download，并复制 docs/examples/minimal.py 到 /root/minimal.py。

FROM python:3.11-slim-bookworm

ENV HF_HOME=/tmp/
ENV TORCH_HOME=/tmp/
ENV OMP_NUM_THREADS=4

COPY docs/examples/minimal.py /root/minimal.py

RUN docling-tools models download

Dockerfile 还说明，容器环境应设置线程预算，以避免线程拥塞；示例设置为 OMP_NUM_THREADS=4。资料未提供镜像标签、容器端口映射或生产编排文件，部署这些部分时应根据官方文档和实际环境补充。

可观测性与运维

资料能确认的运维控制点包括模型缓存路径、容器线程预算、模型预下载和 CLI 运行方式。它没有给出日志格式、指标名称、健康检查接口、追踪协议、重试策略或服务级别协议（Service Level Agreement，SLA），因此这些能力不能被视为项目已经承诺的标准特性。

模型缓存：Dockerfile 设置 HF_HOME 和 TORCH_HOME 为 /tmp/，并通过 docling-tools models download 预下载模型。
模型复用：Dockerfile 注释给出 DOCLING_ARTIFACTS_PATH=/root/.cache/docling/models 的运行方式，用于使用镜像中包含的模型权重。
线程控制：容器示例设置 OMP_NUM_THREADS=4，用于限制线程预算。
输出检查：CLI 生成 .md 文件，Python API 可以通过 Markdown 导出结果进行基础验证。
版本追踪：所给 pyproject.toml 的版本为 2.120.1，但文件注释说明该值会自动更新，不应手工编辑。

根据本文作者的经验判断，生产运维应额外建立输入文件样本、解析失败记录、输出结构校验和模型缓存校验，但这些属于部署方的工程措施，并非资料中已声明的 Docling 内置监控功能。

安全与合规边界

Docling 的安全相关价值主要体现在本地执行能力和对隔离网络环境的支持，而不是提供攻击、绕过或未授权访问能力。README 明确提到本地执行可用于敏感数据和 air-gapped environments，但本地运行不等于自动完成数据合规。

授权边界：只处理组织拥有、获得许可或明确授权的文档、URL 和媒体文件。
隐私边界：上传到远程模型、远程 API 或外部服务前，应完成数据分类和传输审批；敏感数据可以优先评估本地执行路径。
隔离边界：在隔离环境中运行时，需要预先准备 Python 依赖、模型权重和系统库；资料没有给出完整离线安装流程。
模型边界：代码使用 MIT 许可，但单独模型的使用应遵循原始模型包中的模型许可证。
输出边界：OCR、表格、图表、公式和转录结果应进行人工或程序校验，不能把解析结果直接当作事实依据。

项目资料没有声明特定安全认证、CVE 修复承诺、数据留存策略、远程服务 SLA 或隐私保证。涉及个人信息、医疗资料、财务报告、专利材料或内部机密时，应以组织的授权、最小权限、网络隔离、日志管理和数据保留制度为准。

许可证与商用条款

商用方面，MIT 许可证允许商业使用，但项目代码许可证与模型许可证是两个层面。README 特别要求针对单独模型使用查阅原始包中的模型许可证，因此引入 GraniteDocling、OCR 模型或其他模型时，不能只依据 Docling 的 MIT 声明完成合规判断。

局限性与已知限制

资料对功能覆盖描述较多，但没有提供统一的性能、准确率、资源消耗、并发能力和服务可用性数据。使用者应把文档类型、扫描质量、语言、表格复杂度、模型选择和部署架构纳入验收，而不能仅凭支持的扩展名判断结果质量。

解析结果并非天然无误：版面、阅读顺序、OCR、表格、公式、代码和图表都需要针对目标数据集验证。
功能依赖存在差异：许多格式、OCR 引擎和模型位于可选依赖组，基础安装不等于包含所有能力。
模型许可证独立存在：代码使用 MIT 不代表所有模型权重都使用 MIT。
资源需求未给出：官方资料未提供统一的 CPU、GPU、内存、磁盘和处理速度指标。
服务接口信息不完整：资料未提供 API 服务的端口、认证、请求格式、限流和高可用配置。
路线图仍有未完成项：README 的 Coming soon 部分列出标题、作者、引用和语言等元数据抽取，以及复杂化学结构理解。

如果目标是严格保真地复现原始排版、公式或视觉内容，应先定义可接受误差和人工复核流程。根据本文作者的经验判断，文档解析项目的“支持格式”更适合被理解为具备处理入口，而不是对所有文件都提供相同程度的结构还原。

适合谁

以下信号表明 Docling 与项目需求匹配度较高，尤其适用于需要把文档解析作为数据管道组成部分的团队。判断重点应放在输入异构程度、结构保留要求和部署边界上。

团队已有 Python 技术栈，需要通过 CLI 或 DocumentConverter 将文档转换后接入应用。
数据来源同时包含 PDF、Office、HTML、图片、邮件或 EPUB，单一格式解析器不足以覆盖输入集合。
下游需要标题、阅读顺序、表格、代码、公式、图像描述或统一 JSON，而不是只提取连续纯文本。
项目需要本地执行或隔离网络部署，以减少敏感文档离开内部环境的路径。
团队正在构建 RAG、代理式人工智能应用，或者已经使用 README 列出的 LangChain、LlamaIndex、Crew AI、Haystack、MCP 集成方向。

不适合谁

以下信号说明采用 Docling 前应谨慎评估，或需要先补充外围系统。它们并不表示项目不能使用，而是说明现有资料无法直接满足这些要求。

需求只包含单一、结构简单的文本格式，且不需要 PDF 版面、表格、OCR 或统一表示。
项目要求官方明确承诺固定吞吐量、SLA、端口、认证、审计或高可用方案，而当前资料没有这些声明。
团队无法为模型、OCR 引擎和格式支持安装对应可选依赖，或无法准备模型权重和缓存目录。
业务要求对所有扫描件、复杂表格、公式和图表达到未经验证的零错误结果。
合规要求禁止使用许可证未完成审查的模型或第三方依赖；此时应先完成代码、模型和依赖的逐项审核。

常见问题与排查（FAQ / Troubleshooting）

排查应先区分 Python 版本、可选依赖、模型缓存和输入格式四类问题。下面的判断均基于 README、pyproject.toml 和 Dockerfile 中明确出现的信息。

为什么安装环境不能使用 Python 3.9？

README 明确说明，docling 2.70.0 起移除了 Python 3.9 支持；所给 pyproject.toml 的运行时约束为 >=3.10,<4.0。应先执行 python --version，再按照官方安装文档准备 Python 3.10 或更高版本。

基础安装后为什么某种格式或 OCR 能力不可用？

pyproject.toml 将 PDF、Office、Web、音视频、OCR 和模型拆分为可选依赖组。应根据目标格式安装对应能力，并核对当前版本的依赖名称；资料未提供一条覆盖所有可选组的稳定安装命令，因此不应自行拼接未核实的组合。

CLI 命令是否会自动生成 Markdown？

README 的 CLI 示例使用 docling https://arxiv.org/pdf/2206.01062，并说明会在当前目录生成 .md 文件。若当前目录没有预期文件，应先检查命令是否成功结束、当前工作目录是否可写、输入 URL 是否能在授权网络环境中访问。

模型下载位置如何处理？

Dockerfile 设置 HF_HOME=/tmp/ 和 TORCH_HOME=/tmp/，构建阶段执行 docling-tools models download。Dockerfile 注释还给出了 DOCLING_ARTIFACTS_PATH=/root/.cache/docling/models 的容器运行方式；其他缓存策略和离线迁移步骤，官方仓库片段未提供该信息，建议以最新 README 为准。

转换结果与原文不一致怎么办？

应保存原始输入、Docling 输出、使用的管道、模型标识、OCR 引擎和运行环境信息，再针对标题、表格、阅读顺序、公式、图表和 OCR 文本逐项比对。仓库资料没有提供统一准确率或基准数据，无法用一个项目级数字替代针对业务文档的验证。

API 服务的端口和认证参数在哪里？

README 只给出 API server（docling-serve）和相关文档链接，没有在所给资料中列出端口、认证参数和请求接口。官方仓库未提供该信息，建议以最新 API 服务文档为准，不应把未核实的端口或认证方式直接写入生产配置。

项目维护与贡献

仓库 README 提供了贡献指南入口、讨论区入口、技术报告和官方文档。需要提交代码、报告问题或讨论使用方式时，应优先依据仓库当前的贡献规则和讨论分类进行处理。

项目 README 还列出其由 LF AI & Data Foundation 托管，并提供技术报告引用信息。若研究工作使用 Docling，README 建议引用《Docling Technical Report》；引用格式应以仓库当前 README 中的 BibTeX 为准。

项目地址与资源

以下链接均来自项目资料、README 或仓库元信息，适合用于代码获取、安装核对、API 使用和许可证审查。