工作流
Docling
把复杂文档整理成生成式 AI 更容易用的结构,MIT 许可。
docling-project/docling 用 MIT 许可发布,目标是把 PDF 一类复杂文档处理成生成式模型更好用的结构。它不是聊天产品,而是文档预处理这一步。
适合要让代理引用长文档、又希望保留标题和表格结构的人。先用一份你有权处理的样本看输出,再批量跑。处理后的文本同样不能当成你可以自由发表的原文。
推荐来源:
- @0x_rody 在 2026 年 11 月 14 日 的帖子里提到了这个项目(数字采集于 2026 年 11 月 15 日:26 次喜欢,0 次转发)。
本页是导读,不是原文。
解决什么问题
docling-project/docling 用 MIT 许可发布,目标是把 PDF、Office 文档、HTML、电子邮件等复杂文件解析成生成式模型更好用的结构。它提供统一的 DoclingDocument,可以再导出为 Markdown、HTML、JSON 等格式,并尽量保留标题、阅读顺序和表格。它不是聊天产品,而是文档进入模型之前的预处理一步。
项目由 IBM Research Zurich 的团队起步,现在托管在 LF AI & Data Foundation 下。技术细节见 Docling Technical Report。代码库是 MIT,但个别模型有自己的许可证,官方要求查看原模型包里的说明。
适合谁
适合要让代理引用长文档、又希望标题和表格结构还在的人。你可以在本机用 CLI 或 Python 库转换,也可以按文档把 Docling 接到 MCP、API 服务(docling-serve)以及 LangChain、LlamaIndex 等框架。敏感文件可以走本地路径,不必先上传到第三方聊天产品。
请先用一份你有权处理的样本看输出,再批量跑。转换后的文本同样是原作品,不能当成你可以自由发表的原文。第一次运行往往会下载模型,需要磁盘和内存,不适合在毫无准备的共享机器上直接开跑。
怎么装
核验日期为 2026-11-16(Asia/Shanghai)。安装命令以仓库 README 和官方 Installation 为准。当天 PyPI 上的 docling 为 2.150.1,要求 Python 3.10 或更新(<4.0,>=3.10)。README 写明:从 2.70.0 起已不再支持 Python 3.9。仓库当天最近一次推送是 2026-11-15 14:11(Asia/Shanghai),并未归档。
默认安装:
pip install docling若使用 uv,官方写法是 uv add docling。只使用 CPU 的 Linux 环境,文档建议加上 PyTorch 的 CPU 索引,例如:
pip install docling --extra-index-url https://download.pytorch.org/whl/cpuIntel 芯片的 macOS 可能遇到较新 PyTorch 不再提供 x86_64 轮子的问题。官方为 pip 用户提供了 pip install "docling[mac_intel]",并提醒 PyTorch 2.2.2 需要 Python 3.12 或更低。细节以安装页为准,不要在不核对的情况下混装多个 torch 版本。
扫描件、音频、视频或视觉语言模型不是默认包的全部能力。官方用 extras 按需安装,例如 pip install "docling[easyocr]"、docling[vlm]、docling[asr]。OCR 引擎、Tesseract 的系统依赖和 TESSDATA_PREFIX 的设置,见同一篇 Installation 页。本文不把这些 extras 写成人人必装。
命令行
官方快速示例会把一份公开论文转成当前目录下的 Markdown:
docling https://arxiv.org/pdf/2408.09869Python 库
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())MCP(可选)
若要把转换能力交给 MCP 客户端,官方文档给出的配置是通过 docling-mcp 启动服务器:
{
"mcpServers": {
"docling": {
"command": "uvx",
"args": ["--from=docling-mcp", "docling-mcp-server"]
}
}
}默认在本地转换。若改走已经部署的 docling-serve,需要按 MCP 说明 设置 DOCLING_SERVICE_URL 等环境变量。本文没有实跑这条 MCP 路径。
一个实际例子
下面用官方技术报告 PDF 做一次结构检查。该 URL 来自官方 README,请确认你所在网络可以访问 arXiv,并且只把输出当作阅读资料。本次没有实跑,因此不编造转换结果。
- 在 Python 3.10 或更新的环境中执行
pip install docling。 - 保存如下脚本,例如
try_docling.py:
from docling.document_converter import DocumentConverter
source = "https://arxiv.org/pdf/2408.09869"
converter = DocumentConverter()
result = converter.convert(source)
text = result.document.export_to_markdown()
print(len(text))
print(text.splitlines()[0] if text else "empty")- 运行
python try_docling.py。预期效果:首次运行可能下载模型并花费较长时间,成功后打印非零字数和第一行标题。请打开原 PDF,自己核对标题、章节和小表是否还在,而不是把导出文本再发布出去。 - 若你改用本地文件,把
source换成你有权处理的路径即可。扫描件如果版面识别很差,再按官方文档启用 OCR extras,不要假设默认安装已经包含你选定的引擎。
常见坑
- 在 Python 3.9 上安装当前稳定版。官方已写明 2.70.0 起不再支持 3.9,应使用 3.10 或更高。
- 把代码库的 MIT 许可直接套到模型权重上。README 的 License 一节要求查看各模型原包的许可。
- 第一次转换就在无磁盘空间或无网络的环境进行。模型需要下载,失败时不要误以为是文档格式不受支持。
- 扫描 PDF 不安装、也不配置 OCR,却期望表格和文字都完整。默认自动选择不会挑到 Tesseract;若你只用 Tesseract CLI,需要按文档显式指定引擎。
- 在 Intel Mac 上使用过新的 PyTorch,或同时安装
opencv-python与opencv-python-headless。安装页把这些写成了已知问题。 - 把转换结果当作你可以发表的新作品。输出仍是原文档的内容。
FAQ
Docling 能处理哪些格式?
README 在核验当天列出的输入包括 PDF、DOCX、PPTX、XLSX、HTML、EPUB、Apple Pages / Numbers / Keynote、多种图片、LaTeX、电子邮件、日历、音频,以及部分视频容器。导出包括 Markdown、HTML、JSON 等。完整清单以 supported formats 为准,会随版本增加。
必须安装 OCR extras 吗?
不是。数字版 PDF 往往用默认管道即可。扫描件或图片才需要 OCR。引擎和系统依赖以安装页为准,按需选择,不要一次装上全部 extras。
可以用 MCP 调用它吗?
可以。官方文档给出了 uvx --from=docling-mcp docling-mcp-server 的配置,默认本地转换,也可以改指向远程的 docling-serve。细节见 MCP 页。
许可证是 MIT,就可以任意再分发模型吗?
不可以直接这样推断。代码库是 MIT;官方明确写了个别模型要看原包许可。商用或再分发前请自己阅读那些说明。
它和 MarkItDown 有什么不同?
两者都可以把文件变成 Markdown,但定位不同。Docling 强调版面、阅读顺序和表格结构,并带有本地模型管道;本站另有 MarkItDown 条目。选择哪一个,取决于你要的是轻量转换,还是更完整的文档结构。本文没有做对比评测。
来源与许可
仓库 docling-project/docling 的代码库使用 MIT 许可,模型许可需另行核对。本文依据 2026-11-16 查阅的 README、安装文档、MCP 说明 和 PyPI 页面,用自己的话写成,供 CQBase 上下文库使用。若安装 extras、Python 版本或支持格式有变,以官方文档为准。