Docling docling-slim 打包与 Install Extras 深度指南：按需裁剪 PDF、OCR 与模型依赖

本文基于 Docling 仓库中的官方参考文档 slim-packaging.md，结合仓库根目录 pyproject.toml、packages/docling/pyproject.toml 与实际源码结构，系统讲解 docling-slim 的模块化打包机制：如何按使用场景（PDF 转换、OCR、本地模型、VLM、远程服务、RAG 分块）挑选 install extras、每个 extra 背后真实的第三方依赖构成、standard/all 两个便捷捆绑包的组合方式，以及如何用 service-client 实现零本地模型的轻量部署。读完后你可以为任何环境精确计算 Docling 的依赖体积，避免不必要的 torch 与 OCR 引擎。

两个包，同一份代码库

Docling 目前以两个 PyPI 包的形式发布，二者版本同步（当前仓库版本为 2.124.0）：

• pip install docling：batteries-included 的 meta 包，等价于 docling-slim[standard]；
• pip install docling-slim[...]：同一套代码，但默认不携带任何依赖，由你通过 install extras 精确选择需要的格式、OCR 引擎、模型与功能。

这一点可以直接在源码中验证。packages/docling/pyproject.toml 中 docling 包的依赖只有一行：docling-slim[standard]==2.124.0，且注释明确写道 "Meta-package: pulls in docling-slim with standard extras"。进一步地，该文件的构建配置使用 bypass-selection = true（packages/docling/pyproject.toml），意味着 docling wheel 是一个纯依赖 wheel，不打包任何 Python 模块——所有 docling/ 源码实际由 docling-slim wheel 提供。这样设计是为了避免两个 wheel 同时携带同名 docling/ 模块在安装时互相冲突。

docling-slim 的最小基础依赖只有 8 个包，约 50MB，见 pyproject.toml：pydantic、docling-core、pydantic-settings、filetype、requests、certifi、pluggy、tqdm。requires-python 为 >=3.10,<4.0，官方文档说明支持 macOS、Linux、Windows 以及 x86_64/arm64 架构（见 installation.md）。所有重型依赖——torch、OCR 引擎、VLM 技术栈——都被隔离在 extras 之后，不安装就完全不进环境。

CLI 入口点 docling 与 docling-tools 在 pyproject.toml 的 [project.scripts] 中声明，分别指向 docling/cli/main.py 与 docling/cli/tools.py，但文件上方注释特别说明：CLI 需要 cli extra 才能工作（standard 捆绑包已包含它）。

选择 extras：场景配方

以下是原参考文档给出的“目标 → 安装命令”配方表，覆盖了最常见的部署场景：

目标	安装命令
PDF → Markdown/JSON，不用 ML，带 CLI	docling-slim[format-pdf,cli]
只调用远程服务（不装本地模型）	docling-slim[service-client]
Office 文件（DOCX/PPTX/XLSX）	docling-slim[format-office]
Web（HTML + Markdown）	docling-slim[format-web]
扫描件 PDF + 轻量 OCR 引擎	docling-slim[format-pdf,feat-ocr-rapidocr]
本地 layout/table/OCR ML 模型	docling-slim[models-local]
本地 VLM 流水线	docling-slim[models-vlm-inline]
RAG 分块	docling-slim[feat-chunking]
与默认 docling 包完全等价	docling-slim[standard]
一切可选功能（kitchen sink）	docling-slim[all]

Extras 可以任意组合，用逗号拼接即可，例如：

pip install "docling-slim[format-pdf,models-local,feat-ocr-rapidocr,feat-chunking,cli]"

注意 extras 内部支持嵌套引用：例如 format-pdf 本身就是对 format-pdf-pypdfium2 和 format-pdf-docling 两个细粒度 extra 的组合，因此你可以只装其中一层（如仅渲染不需要结构化解析的场景只装 format-pdf-pypdfium2）。

Extras 完整目录（对照 pyproject.toml 逐项说明）

以下目录在继承原参考文档分组结构的基础上，逐一对照 pyproject.toml 中 [project.optional-dependencies] 的真实依赖声明进行扩充。

核心组件

• convert-core —— 基础转换依赖：numpy>=1.24,<3、pillow>=10,<13、rtree>=1.3,<2、scipy>=1.6,<2（pyproject.toml）。它是绝大多数格式 extra 的地基。
• extract-core —— 结构化信息抽取支持：在 convert-core 之上追加 polyfactory（pyproject.toml）。对应 Python SDK 中的 DocumentExtractor（结构化抽取，beta 阶段）。

格式支持（Formats）

Extra	底层依赖	说明
format-pdf-pypdfium2	pypdfium2>=4.30,<6（排除 4.30.1）	仅 PDF 渲染，最轻量的 PDF 支持
format-pdf-docling	docling-parse>=7.16,<8 + pypdfium2	基于 docling-parse 的深度 PDF 解析（布局、表格结构等）
format-pdf	上面两者的组合	完整 PDF 转换能力
format-office	format-docx（python-docx）+ format-pptx（python-pptx）+ format-xlsx（openpyxl）	Office 三件套，可单独安装
format-web	format-html（beautifulsoup4）+ format-markdown（marko）	HTML 与 Markdown
format-opendocument	odfdo>=3.22,<4	ODT/ODS/ODP
format-latex	pylatexenc>=2.10,<3	LaTeX 文档
format-email	format-html + mail-parser + python-oxmsg	EML/MSG 邮件
format-xml-jats	format-html + lxml	JATS XML
format-xml-uspto	format-html + defusedxml	USPTO 专利 XML
format-xml-xbrl	arelle-release>=2.38.17,<3	XBRL 财务报告
format-html-render	playwright>=1.58	渲染 JS 动态生成的 HTML
format-audio	openai-whisper、numba；macOS arm64 用 mlx-whisper，其他平台用 whisper-s2t-reborn	ASR 语音转写
format-video	format-audio + resemblyzer、soundfile、scikit-learn、librosa	ASR + 说话人分离（diarization）

一个值得注意的源码细节：pyproject.toml 中还有 format-iwork（Apple .pages）extra，其注释说明 Pages 5+ 将内容存为 Snappy-framed protobuf，而 Snappy 解压器是纯 Python 实现，因此无需任何编译依赖。

OCR 引擎（feat-ocr-*）

原则是“只装你要用的那一个”。从 pyproject.toml 可以看到各引擎的精确约束：

• feat-ocr-rapidocr —— rapidocr>=3.9.1,<4，轻量级引擎，无重型运行时；
• feat-ocr-rapidocr-onnx —— 在 rapidocr 之上追加 onnxruntime，且按 Python 版本分档 pin（Python <3.11 用 <1.24，3.11–3.13 用 <2.0.0，≥3.14 用 >=1.24.1,<2）；
• feat-ocr-easyocr —— easyocr>=1.7,<2 + scikit-image>=0.19。源码注释解释了后者为何要显式加下限：easyocr 声明 scikit-image 时未设下限，Python 3.10 下的依赖解析器会回溯到 2019 年的 0.16.2，该版本没有 Py3.10 wheel 只能从源码构建而失败；
• feat-ocr-tesserocr —— tesserocr + pandas，需要系统级安装 Tesseract；
• feat-ocr-mac —— ocrmac，带环境标记 sys_platform == "darwin"，仅 macOS 生效；
• feat-ocr-nemotron —— nemotron-ocr>=2.0.0，环境标记限定为 python_version == "3.12" and sys_platform == "linux" and platform_machine == "x86_64"，即仅 Linux x86_64 + Python 3.12 可用。

这些环境标记（environment markers）是 extras 机制的精髓：同一个 extra 在不匹配平台上会自动解析为空依赖，不会导致安装失败。

模型（Models）

• models-local —— 本地 layout/table/OCR 模型，是最“重”的 extra：torch>=2.2.2,<3、torchvision、docling-ibm-models>=3.13,<5、accelerate、huggingface_hub、defusedxml（pyproject.toml）。只要你不跑本地 ML 模型，就不应安装它；
• models-vlm-inline —— 内联 VLM 流水线：transformers>=4.42（darwin 与其他平台的版本上限不同）、accelerate、qwen-vl-utils、peft，macOS arm64 上追加 mlx-vlm（pyproject.toml）；
• models-remote —— 远程模型服务客户端：tritonclient[grpc]>=2.65,<3；
• models-onnxruntime —— ONNX 运行时后端：macOS 上安装 onnxruntime，Linux/Windows 上安装 onnxruntime-gpu，且均按 Python 版本分档 pin（pyproject.toml）。

功能与工具（Features & tooling）

• feat-chunking —— docling-core[chunking]>=2.73,<3，即 HybridChunker / RAG 分块能力；
• service-client —— 远程 docling-serve 客户端与 docling convert-remote 命令：httpx、websockets、typer、rich、python-dotenv（后者的注释说明它只是 best-effort 的 .env 加载，缺失时 flags + 环境变量仍然可用）；
• cli —— docling / docling-tools 命令入口所需的 typer、rich、python-dotenv。

捆绑包（Bundles）

• standard —— 默认 docling 包的能力集。以 pyproject.toml 为准，其完整成员为：format-pdf、models-local、feat-ocr-rapidocr、format-office、format-web、format-latex、format-email、format-iwork、feat-chunking、extract-core、service-client、cli。注意：参考文档中的摘要列表未列出 format-iwork，权威清单以 pyproject.toml 为准——这也正是原文档给出的建议：“如果某个 extra 名称解析不到，去 [project.optional-dependencies] 查当前拼写”。
• all —— standard 再加 models-vlm-inline、format-audio、format-html-render、三个 XML extra、models-remote、models-onnxruntime 以及 EasyOCR/TesserOCR/OcrMac 三个额外 OCR 引擎。刻意排除 format-video：pyproject.toml 的注释说明 format-video 会引入 resemblyzer，其依赖 webrtcvad 没有 wheel，需要从源码编译并安装 Python 开发头文件（Python.h）和 C 编译器；all 必须保证在无编译器环境下也能干净安装，因此说话人分离保持为显式 opt-in（docling-slim[format-video]）。

源码级的设计要点

以下几点从仓库源码可以确认，有助于理解这套打包设计为什么能保持环境精简：

1. 重型依赖被完全后置。docling-slim 的 dependencies 列表不含任何 ML/OCR/格式解析库，只有 pydantic 数据模型栈与基础工具（pyproject.toml）。因此 docling-slim[format-office] 这类安装不会触碰 torch。
2. 条件依赖用 PEP 508 环境标记而非安装时判断。例如 feat-ocr-mac 与 feat-ocr-nemotron 都带 sys_platform/platform_machine/python_version 标记，在非目标平台上该 extra 解析后不引入任何包，安装不会报错。
3. docling meta 包保留了向后兼容的 extras 别名。packages/docling/pyproject.toml 将旧式 extras 名一一映射到 slim 的新命名，例如 easyocr → docling-slim[feat-ocr-easyocr]、vlm → docling-slim[models-vlm-inline]、rapidocr → docling-slim[feat-ocr-rapidocr-onnx]、asr → docling-slim[format-audio] 等，老项目的 pip install "docling[easyocr]" 写法不受破坏。
4. CLI 入口点随 meta 包重新声明。packages/docling/pyproject.toml 的注释解释了原因：uv tool install docling 只会把“命名包自身”的 scripts 链接到 ~/.local/bin，从不链接依赖包的，因此 docling 包必须重新声明这两个入口点（运行时模块仍由 docling-slim 提供）。
5. 插件默认值通过 entry point 注册。pyproject.toml 声明了 [project.entry-points.docling] 的 docling_defaults = "docling.models.plugins.defaults"，指向 docling/models/plugins/defaults.py，模型/OCR 默认值的发现机制与 extras 解耦。
6. 仓库 tests 目录中还有 tests/test_backend_optional_dependencies.py，从命名与仓库测试组织方式看，它是用于验证缺少某个可选依赖时各后端行为的用例，可作为你排查“装了 extra 却仍报 ModuleNotFound”时阅读的材料。

另外两个与 extras 配合安装的注意事项，见官方 installation.md：

• 需要本地模型时 torch 是关键体积来源，Linux CPU-only 场景可通过 --extra-index-url https://download.pytorch.org/whl/cpu 安装 CPU 版 torch；
• feat-ocr-nemotron 需要 CUDA 13 的 PyTorch wheels，且仅在 Linux x86_64 + Python 3.12 下可用。

零本地模型部署：service-client 组合

如果目标机器只需要“调用转换能力”而不需要跑任何模型，参考文档给出的最小组装是：

pip install "docling-slim[service-client]"

该 extra 只引入 httpx、websockets、typer、rich、python-dotenv（pyproject.toml），环境里完全没有 torch 与 OCR 引擎。转换请求被转发到一个已在运行的 docling-serve 端点，客户端代码形态与本地 DocumentConverter 一致（client.convert(...) 返回的 result.document 可直接 export_to_markdown()），批量场景可用 convert_all 并发提交，RAG 场景可直接 client.chunk(source=..., chunker=ChunkerKind.HYBRID)。服务地址与密钥通过 DOCLING_SERVICE_URL / DOCLING_SERVICE_API_KEY 环境变量（或工作目录 .env）配置，无代码的一次性远程转换可用 docling convert-remote report.pdf --service-url ... --to md 完成。完整的客户端 API、异步接口（AsyncDoclingServiceClient）、作业生命周期与异常类型（ConversionError、TaskTimeoutError 等）说明见 service-client.md，底层实现位于 docling/service_client/client.py。

如何自行验证与延伸阅读

• 权威清单：extras 的最终事实来源是 pyproject.toml 的 [project.optional-dependencies] 与 [project.scripts] 段，本文所有依赖版本区间均逐行取自该文件；若发现文档与包管理器解析结果不一致，以该文件为准。
• 包级文档：packages/docling-slim/README.md 给出了“何时用 docling、何时用 docling-slim”的官方建议——大多数用户直接 pip install docling，需要细粒度依赖控制或最小安装体积时才用 docling-slim。
• 安装细节：docs/getting_started/installation.md 覆盖 uv 安装、torch 分布选择与 OCR 引擎系统依赖（Tesseract 的 TESSDATA_PREFIX 等）。
• 使用决策表：SKILL.md 将 CLI、Python SDK、结构化抽取、RAG 分块、Service Client 与 docling-slim extras 按“你需要做什么”做了横向对比，可与本文配合使用。

小结：docling-slim 的价值不在功能差异——它与 docling 是同一代码库——而在依赖足迹的可控性：从 8 个基础包起步，按 format-* / feat-ocr-* / models-* / feat-chunking / service-client / cli 六个维度自由组合，standard 与 all 两个捆绑包覆盖“与默认包等价”和“全量（除需编译的 video）”两个极端。理解了 extras 背后的真实依赖与环境标记，你就可以为生产容器、边缘设备或纯远程调用服务精确裁剪 Docling 的安装体积。