Docling 实战 FAQ：Python 版本兼容、依赖冲突、离线部署与推理加速完整指南

本文基于 Docling 官方 FAQ（docs/faq/index.md）整理，覆盖安装与运行环境中最常见的问题：Python 3.13/3.14 兼容性与 numpy 版本冲突、macOS x86_64 与无头环境的依赖陷阱、模型权重离线部署、OCR 语言配置、分块器告警判读以及 Flash Attention 2 加速。读完之后，你可以独立排查 Docling 在各类环境（Docker、远程 VM、Apple 芯片、NVIDIA GPU）下的安装失败与运行异常，并正确配置离线推理与性能选项。

Python 版本支持：3.13 与 3.14

FAQ 给出的官方结论是：

• Python 3.13 从 Docling 2.18.0 开始支持；
• Python 3.14 从 Docling 2.59.0 开始支持。

从当前仓库的 pyproject.toml 可以印证这一事实：requires-python = '>=3.10,<4.0'，且打包 classifiers 中明确列出了 Programming Language :: Python :: 3.13 与 3.14（pyproject.toml#L30-L34）。如果你使用的版本早于上述里程碑版本，请升级 Docling 而不是强行在新版 Python 上运行旧包。

安装冲突：numpy 与 Python 3.13 的三方依赖难题

这是 FAQ 中篇幅最长的问题。典型报错场景是通过 poetry 同时安装 docling 和 langchain：

...
Thus, docling (>=2.7.0,<3.0.0) requires numpy (>=1.26.4,<2.0.0).
So, because ... depends on both numpy (>=2.0.2,<3.0.0) and docling (^2.7.0), version solving failed.

冲突根源

numpy 直到部分 2.x.y 版本才加入 Python 3.13 支持。为了兼容 3.13，Docling 针对 3.13 依赖 numpy 2.x.y，否则依赖 1.x.y。当你的 pyproject.toml 允许 3.13 时，Poetry 会尝试调和 Docling 面向 3.13 的 numpy 2.x.y 与 LangChain 的 numpy 1.x.y，两者互斥，于是求解失败。

当前仓库的依赖声明为 numpy>=1.24.0,<3.0.0（pyproject.toml#L78-L83 的 convert-core 组件），FAQ 也说明 Docling 支持 >=1.24.4,<3.0.0 的 numpy，可以匹配绝大多数用法。

解决方式

1. 新版直接升级：使用 docling-ibm-models>=2.0.7 与 deepsearch-glm>=0.26.2 时，上述问题不再出现。
2. 旧版临时规避：检查 pyproject.toml 允许的 Python 版本中是否包含 3.13，若有则移除。例如把 python = "^3.10" 改为 python = ">=3.10,<3.13"。
3. 需要保留 3.9–3.13 全兼容时，用版本选择器分别约束 numpy：

numpy = [
    { version = "^2.1.0", markers = 'python_version >= "3.13"' },
    { version = "^1.24.4", markers = 'python_version < "3.13"' },
]

运行环境问题：macOS x86_64 与 libGL 缺失

macOS x86_64：必须锁定 numpy 1.x

Docling（目前）仍支持在 macOS x86_64 上运行标准流水线。但新装环境容易落入依赖组合陷阱：Docling 依赖 PyTorch，而 PyTorch 在 2.2.2 之后放弃了对 macOS x86_64 的支持；这个旧版 PyTorch 又只兼容 NumPy 1.x。因此必须确保 numpy 版本正确：

pip install docling "numpy<2.0.0"

ImportError: libGL.so.1 缺失（OpenCV 发行版冲突）

ImportError: libGL.so.1: cannot open shared object file: No such file or directory

该错误源于某些第三方依赖中 OpenCV 发行版冲突：opencv-python 与 opencv-python-headless 都定义了同一个 Python 包 cv2，同时安装时常产生冲突。而且 opencv-python 依赖 OpenGL UI 框架，在 Docker 容器、远程 VM 等无头环境中通常不存在。

方案 1（推荐）：强制使用无头 OpenCV

pip uninstall -y opencv-python opencv-python-headless
pip install --no-cache-dir opencv-python-headless

方案 2：安装 libGL 系统依赖

Debian 系：

apt-get install libgl1

RHEL / Fedora：

dnf install mesa-libGL

文本样式（加粗、下划线等）支持情况

DoclingDocument 格式本身支持文本样式，但目前只有声明式后端（declarative backends，即 docx、pptx、markdown、html 等格式）能正确设置文本样式；PDF 暂不支持。如果你的流程从 PDF 提取文本并期望保留粗体/下划线信息，当前版本做不到，应改从 docx/html 等源格式转换。

完全离线运行（air-gapped 环境）

Docling 不使用任何远程服务，可以在完全隔离的内网环境运行。唯一要求是把运行时指向已存放模型工件（artifacts）的本地位置：

pipeline_options = PdfPipelineOptions(artifacts_path="your location")
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    }
)

artifacts_path 的定义见 docling/datamodel/pipeline_options.py#L1287-L1297：它是指向“预下载模型工件（权重、配置）”的本地目录；为 None 时模型会在首次使用时从远端获取。其字段描述同时提示可用 docling-tools models download 预取工件。

从源码结构看，该路径的解析逻辑被统一在 resolve_model_artifacts_path（docling/models/inference_engines/vlm/_utils.py）：

• artifacts_path 为 None → 触发下载；
• 目录存在 {artifacts_path}/{repo_id 中 / 替换为 --} 子目录 → 直接使用该本地目录；
• 否则抛出 FileNotFoundError，并在错误信息中列出该目录下实际可用的模型以及三条修复建议（下载模型、移除 artifacts 路径恢复自动下载、或换用已存在的模型）。

也就是说，离线部署时务必保证目录名与 Hugging Face 仓库 ID 的 -- 映射一致，否则会得到一份列出“可用模型”的明确报错，便于排错。

需要哪些模型权重

• PDF 流水线：AI 模型（布局、表格结构等）需要权重，来源为 Hugging Face 上的 ds4sd/docling-models 仓库。
• docx、pptx 等其他文档类型：没有此类权重要求，声明式后端纯解析即可完成转换。
• 启用 OCR 时：部分引擎还需要各自的模型工件。例如 EasyOCR，Docling 通过专门的 pipeline options 控制其运行时行为（见下文 OCR 语言配置一节）。

SSL 证书错误：下载模型权重失败

典型报错：

URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)>

当从 Hugging Face 拉取模型权重时，如果 Python 环境的受信任证书列表过期，就会出现该错误。FAQ 给出的三种可行方案：

1. 升级证书包 certifi：pip install --upgrade certifi；
2. 使用 pip-system-certs 改用系统最新的受信任证书；
3. 将环境变量 SSL_CERT_FILE 与 REQUESTS_CA_BUNDLE 指向 certifi 的证书路径：

CERT_PATH=$(python -m certifi)
export SSL_CERT_FILE=${CERT_PATH}
export REQUESTS_CA_BUNDLE=${CERT_PATH}

这一思路与仓库基线依赖一致：pyproject.toml 的基础依赖中已包含 certifi>=2024.7.4，因此升级/更新证书包是首选方案。

OCR 支持哪些语言、如何配置

Docling 支持多个 OCR 引擎（EasyOCR、Tesseract、RapidOCR、Mac OCR 等），每个引擎各自维护支持语言列表，完整清单请查阅对应引擎的官方文档（EasyOCR、Tesseract、RapidOCR、ocrmac）。

在 Docling 中通过 OCR pipeline options 设置语言：

from docling.datamodel.pipeline_options import PdfPipelineOptions

pipeline_options = PdfPipelineOptions()
pipeline_options.ocr_options.lang = ["fr", "de", "es", "en"]  # example of languages for EasyOCR

从源码看，EasyOcrOptions（docling/datamodel/pipeline_options.py#L449-L498）还暴露了若干与部署强相关的字段，可按需配置：

字段	默认值	说明
lang	["fr", "de", "es", "en"]	ISO 639-1 语言码列表，支持多语言文档
use_gpu	None	None 表示自动检测并使用 GPU；设为 False 强制 CPU
confidence_threshold	0.5	置信度下限，低于该值的文本被过滤，范围 0.0–1.0
model_storage_directory	None	下载模型的存储目录，离线/自定义模型管理时很有用
recog_network	"standard"	识别网络架构，可选 standard（均衡）或 craft（更高精度）

对离线环境，model_storage_directory 与前述 artifacts_path 配合使用，可把 EasyOCR 的模型文件完全落在本地。

常见问题：Word/PowerPoint 图片缺失与 HybridChunker 告警

MS Word / PowerPoint 中部分图片丢失

Docling 使用的图像处理库仅在 Windows 平台能处理嵌入的 WMF 图片。其他操作系统上这些图片会被忽略——如果你在 Linux/macOS 上发现某些 Office 文档图片缺失，先确认原文件是否包含 WMF 格式图形。

HybridChunker 的 “Token indices sequence length ...” 告警

使用 HybridChunker 时经常触发 transformers 的告警：

Token indices sequence length is longer than the specified maximum sequence length for this model (531 > 512). Running this sequence through the model will result in indexing errors

TLDR：在 HybridChunker 场景下这是已知的“虚惊一场”（false alarm）。

原理是：transformers 的该告警只表示“把这段序列真正送入模型会产生索引错误”。而 HybridChunker 的调用链是——分块器先用 tokenizer 统计一个可能很长的序列（如 530 token）的 token 数以判断是否过长，统计这一步就会触发告警；随后若序列确实超限，分块器继续执行切分。真正重要的是最终产出 chunk 的 token 长度，它并不会超过限制。

如需验证，可用下面片段统计实际最大 chunk 长度：

chunk_max_len = 0
for i, chunk in enumerate(chunks):
    ser_txt = chunker.serialize(chunk=chunk)
    ser_tokens = len(tokenizer.tokenize(ser_txt))
    if ser_tokens > chunk_max_len:
        chunk_max_len = ser_tokens
    print(f"{i}\t{ser_tokens}\t{repr(ser_txt[:100])}...")
print(f"Longest chunk yielded: {chunk_max_len} tokens")
print(f"Model max length: {tokenizer.model_max_length}")

只要输出的 Longest chunk yielded 不超过 Model max length，该告警可以安全忽略。

在 CUDA 上启用 Flash Attention 2

在 CUDA 设备上运行模型时，可启用 Flash Attention 2 库以获得 Transformer 模型加速与显存下降（适用于 Ampere 及更新的 NVIDIA GPU）。

方式一：环境变量

DOCLING_CUDA_USE_FLASH_ATTENTION2=1

方式二：代码

from docling.datamodel.accelerator_options import (
    AcceleratorOptions,
)

pipeline_options = VlmPipelineOptions(
    accelerator_options=AcceleratorOptions(cuda_use_flash_attention2=True)
)

对应实现见 AcceleratorOptions（docling/datamodel/accelerator_options.py）：该字段基于 pydantic-settings 声明，默认 False，通过 DOCLING_ 前缀环境变量配置，因此设置 DOCLING_CUDA_USE_FLASH_ATTENTION2=1 即可全局生效，无需逐处改代码。从源码结构看，该开关在多个推理点被消费（如 transformers_engine.py#L250、hf_transformers_model.py#L168 等），统一控制 VLM、抽取、图表/表格等模型是否走 Flash Attention 2 路径。

前提是需要安装 flash-attn 包，两种安装方式：

# Building from sources (required the CUDA dev environment)
pip install flash-attn

# Using pre-built wheels (not available in all possible setups)
FLASH_ATTENTION_SKIP_CUDA_BUILD=TRUE pip install flash-attn

预编译 wheel 并非在所有组合下都有可用版本，源码构建则需要完整的 CUDA 开发环境。

小结

FAQ 覆盖的问题可以归纳为四类排查路径：

1. 版本与依赖：先确认 Python 版本（3.13 需 ≥2.18.0，3.14 需 ≥2.59.0）与 numpy 约束（>=1.24.0,<3.0.0），Poetry 冲突优先用版本选择器解决；
2. 平台环境：macOS x86_64 锁 numpy<2.0.0，无头环境统一换 opencv-python-headless；
3. 离线与下载：用 artifacts_path + docling-tools models download 完成内网部署，证书问题用 certifi 系列方案修复；
4. 运行期行为：OCR 语言按引擎配置 ocr_options.lang，HybridChunker 告警为预期内的虚警，CUDA 加速用 DOCLING_CUDA_USE_FLASH_ATTENTION2=1 一键开启。

以上所有结论均可在当前仓库中复核：依赖声明见 pyproject.toml，参数定义见 docling/datamodel/pipeline_options.py 与 docling/datamodel/accelerator_options.py，工件解析逻辑见 docling/models/inference_engines/vlm/_utils.py，分块概念可继续延伸阅读 docs/concepts/chunking.md。