精选的常见 Docling 问题，包含快速修复、推荐修复和官方来源。仅收录可复现的问题。
error: Microsoft Visual C++ 14.0 or greater is required / Failed building wheel for docling-parse
原因： 部分可选依赖会编译原生 C++ 或 Rust 扩展，需要默认未安装的编译器。
快速修复： 改用 Astral uv 而不是 pip 以使用预编译 wheel：uv add docling。
推荐修复： 如果必须使用 pip，请安装 Microsoft Visual C++ Build Tools (14.0+) 和 64 位 Python 后重试。在不支持的系统或 Python 上，请使用受支持的组合（Python 3.10-3.12）或容器。
uv add docling不适用的情况： 如果您的系统和 Python 没有对应 wheel，仍可能需要编译器。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Microsoft Visual C++ 14.0 is required. Get it with Microsoft C++ Build Tools
原因： pip 正在从源码构建原生扩展，但找不到 MSVC 工具链。
快速修复： 优先使用 uv，它会解析预编译 wheel，完全避免编译器。
推荐修复： 否则请安装 Build Tools 并勾选“使用 C++ 的桌面开发”工作负载：winget install Microsoft.VisualStudio.2022.BuildTools。
winget install Microsoft.VisualStudio.2022.BuildTools不适用的情况： 主要影响 tesserocr 或 fasttext 等可选扩展；核心包通常提供 wheel。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
No matching distribution found for docling / Requires-Python >=3.10
原因： Docling 需要 Python 3.10 或更高版本；Python 3.9 及更早版本不受支持。
快速修复： 创建 Python 3.10+ 环境并重新安装。
推荐修复： 使用虚拟环境或 uv：uv venv --python 3.12 然后 uv add docling。
uv venv --python 3.12不适用的情况： 非常新的 Python 版本可能延迟获得 wheel；请查看官方支持矩阵。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Failed building wheel for docling-parse / ERROR: Failed to build installable wheels for some pyproject.toml based projects
原因： 您的平台或 Python 没有预编译 wheel（例如低于 13 的 macOS、Alpine/Termux、特殊架构或非常新的 Python），因此 pip 尝试从源码编译。
快速修复： 使用受支持的平台和 Python 3.10-3.12，并用 uv 安装以获取 wheel。
推荐修复： 在 macOS 上使用 macOS 13+（Apple Silicon）；在 Linux 上优先使用主流 x86_64/arm64 发行版或官方容器。固定一个 wheel 匹配的 docling 版本，或用完整的 C++ 工具链构建。
uv venv --python 3.12 && uv add docling不适用的情况： 32 位、缺少构建依赖的 musl/Alpine 以及部分 ARM 系统不受官方支持。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
ImportError: libGL.so.1: cannot open shared object file: No such file or directory / ModuleNotFoundError: No module named 'cv2'
原因： 带有 OpenGL 界面的 opencv-python 被安装在 Docker 或远程 VM 等无头环境中，或全新环境完全缺少 OpenCV。
快速修复： 强制使用无头版 OpenCV。
推荐修复： pip uninstall -y opencv-python opencv-python-headless && pip install --no-cache-dir opencv-python-headless。或安装系统库：apt-get install libgl1（Debian）或 dnf install mesa-libGL（RHEL）。
pip uninstall -y opencv-python opencv-python-headless && pip install --no-cache-dir opencv-python-headless不适用的情况： 如果确实需要 OpenCV 图形窗口，请安装系统 libGL，而不是改用无头版。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
version solving failed ... depends on numpy (>=2.0.2,<3.0.0) and docling requires numpy (>=1.26.4,<2.0.0)
原因： 在 Python 3.13 上 Docling 需要 numpy 2.x，但较旧的 LangChain 等固定项强制 numpy 1.x，解析器无法同时满足。
快速修复： 从项目的 Python 范围中排除 3.13。
推荐修复： 在 pyproject.toml 中设置 python = ">=3.10,<3.13"，或升级 docling-ibm-models>=2.0.7 和 deepsearch-glm>=0.26.2。混合需求时按 Python 版本使用 numpy 标记。
python = ">=3.10,<3.13"不适用的情况： 部分第三方包尚无 Python 3.13 的 wheel。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Could not find a version that satisfies the requirement torch / no matching distribution found for torch
原因： PyTorch 在 2.2.2 之后停止提供 macOS x86_64（Intel）wheel，而 2.2.2 需要 numpy 1.x 和 Python 3.12 或更低版本。
快速修复： 安装 mac_intel 扩展，它会固定兼容版本。
推荐修复： pip install "docling[mac_intel]"（或 uv add torch==2.2.2 torchvision==0.17.2 docling）。保持 numpy<2 和 Python 3.12 或更低。
pip install "docling[mac_intel]"不适用的情况： Apple Silicon 是受支持的默认平台；Intel Mac 需要这套固定组合。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
URLError: <urlopen error [SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate>
原因： 从 Hugging Face 获取模型权重时，Python 环境的受信任证书列表已过期。
快速修复： 更新 certifi。
推荐修复： pip install --upgrade certifi。若仍失败，将 SSL_CERT_FILE 和 REQUESTS_CA_BUNDLE 指向 `python -m certifi`，或安装 pip-system-certs。
pip install --upgrade certifi不适用的情况： 在企业代理后，还需配置 HTTPS_PROXY 和内部根 CA。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
docling: command not found / Docling version: unknown
原因： 升级旧安装可能导致 docling 控制台脚本未注册，因为项目已拆分为 docling 和 docling-slim。
快速修复： 重新安装提供该命令的包。
推荐修复： pip install --force-reinstall docling（或 pip install -U docling docling-slim），然后运行 docling --version。在虚拟环境中确保 bin/Scripts 在 PATH 中。
pip install --force-reinstall docling不适用的情况： uv tool install docling 也可能因同样原因失败；请改用 docling-slim[standard]。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
'pip' is not recognized as an internal or external command
原因： 嵌入式 Python 或默认 Windows 安装不会把 Python 和 Scripts 加入 PATH。
快速修复： 使用常规 Python 安装和虚拟环境，而不是嵌入式 Python。
推荐修复： 从 python.org 安装 Python 3.12 并勾选“Add python.exe to PATH”，创建 venv（py -m venv .venv），激活后 pip install docling。若缺少 pip：py -m ensurepip --upgrade。
py -m venv .venv && .venv\Scripts\activate不适用的情况： 嵌入式 Python 并非为已安装的控制台脚本设计，不推荐用于 Docling。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
OSError / ConnectionError while downloading ds4sd/docling-models / a partial cache blocks later runs
原因： 首次处理 PDF 会下载版式、表格和 OCR 模型；下载失败或中断会留下损坏的缓存。
快速修复： 在网络正常时重试一次，或提前下载模型。
推荐修复： 使用 docling-tools models download --all 提前下载全部模型，并将 DOCLING_CACHE_DIR 指向可写位置。
docling-tools models download --all不适用的情况： 隔离网络机器需要先从联网主机复制缓存。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Still tries to reach huggingface.co / FileNotFoundError: Missing .../model.safetensors
原因： artifacts_path 指向了错误的目录，或文件夹结构与 Docling 的预期不符。
快速修复： 将 Docling 指向包含模型子文件夹的父目录。
推荐修复： 运行 docling-tools models download -o ./models，然后设置 artifacts_path="./models"（容器中用绝对路径）。该目录必须包含 ds4sd--docling-models 等子文件夹，且其中直接包含 model.safetensors、config.json 和 preprocessor_config.json。
docling-tools models download -o ./models不适用的情况： Python API 仅靠环境变量不够，需显式传入 artifacts_path。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Models appear in both ./models and ~/.cache/huggingface
原因： Hugging Face 库会在您传入的目录之外维护自己的全局缓存。
快速修复： 设置 HF_HOME 使下载集中到一处。
推荐修复： 运行前 export HF_HOME=/your/cache（或 HF_HUB_CACHE），并把同一文件夹作为 artifacts_path 传入。
export HF_HOME=./models-cache不适用的情况： Docling 会遵循您的路径，但 Hugging Face 库仍会创建自己的缓存。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
403 Client Error / rate limit exceeded / HTTPError while downloading model weights
原因： 受限仓库、限流或企业代理阻止了匿名 Hugging Face 下载。
快速修复： 使用 Hugging Face token 进行认证。
推荐修复： export HF_TOKEN=your_token（或 huggingface-cli login），并用 HF_HUB_ETAG_TIMEOUT 和 HF_HUB_DOWNLOAD_TIMEOUT 提高超时。代理环境请设置 HTTPS_PROXY。
export HF_TOKEN=your_token不适用的情况： 部分模型需先在 Hugging Face 接受许可。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
OSError: [Errno 30] Read-only file system: '/models/models--ds4sd--docling-models/snapshots/...'
原因： 加载本地模型时 Hugging Face 试图在只读挂载中创建缓存或符号链接。
快速修复： 将缓存指向可写路径。
推荐修复： 将 HF_HOME 和 HF_HUB_CACHE 设为可写目录，并在所有模型就位后设置 HF_HUB_OFFLINE=1；把模型目录作为数据挂载，而不是 HF 缓存。
export HF_HUB_CACHE=/tmp/hf-cache不适用的情况： HF_HUB_OFFLINE=1 会完全禁用网络访问，请先确保所有模型都已存在。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
ModuleNotFoundError: No module named 'tesserocr' / OCR engine import fails
原因： 部分 OCR 引擎需要 pip 无法安装的系统二进制文件（例如 Tesseract）。
快速修复： 使用纯 Python、安装更简单的 RapidOCR 或 EasyOCR。
推荐修复： pip install "docling[rapidocr]" 或 "docling[easyocr]"。使用 Tesseract 时先安装系统二进制（brew/apt/dnf），再安装扩展。
pip install "docling[rapidocr]"不适用的情况： Tesseract 还需要语言数据；缺少语言时请设置 TESSDATA_PREFIX。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
RapidOCR is not installed. Please install it via 'pip install rapidocr_onnxruntime' to use this OCR engine
原因： RapidOCR 是可选引擎，不属于基础安装。
快速修复： 安装 rapidocr 扩展。
推荐修复： pip install "docling[rapidocr]"（或 pip install rapidocr onnxruntime）。
pip install "docling[rapidocr]"不适用的情况： RapidOCR 的 GPU 加速有限，默认在 CPU 上运行。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Error: Failed loading language 'deu' / TESSDATA_PREFIX is not set
原因： Tesseract 需要 .traineddata 文件以及指向 tessdata 文件夹的正确 TESSDATA_PREFIX。
快速修复： 安装语言包并设置 TESSDATA_PREFIX（必须以斜杠结尾）。
推荐修复： apt-get install tesseract-ocr-eng tesseract-ocr-deu（Debian），然后 export TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata/。将 ocr_options.lang 设为已安装的语言。
export TESSDATA_PREFIX=/usr/share/tesseract-ocr/5/tessdata/不适用的情况： 容器通常只包含英语；如需更多语言请构建自定义镜像。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Invalid resolution 0 dpi. Using 70 instead. / tesseract OCR failed
原因： 未带 DPI 元数据渲染的页面图像会让 Tesseract 出错，在容器中尤其常见。
快速修复： 尝试其他 OCR 引擎，或以明确的 DPI 将页面渲染为图像后再处理。
推荐修复： 切换到 RapidOCR 或 EasyOCR，或用固定密度预渲染（ImageMagick：convert -density 216 input.pdf page.png）后对图像做 OCR。
convert -density 216 input.pdf page.png不适用的情况： 这是 Tesseract 特有的问题，其他引擎不受影响。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Non-English text comes out garbled or empty / wrong characters
原因： OCR 引擎默认只使用有限的语言集合。
快速修复： 在流水线选项中设置 OCR 语言。
推荐修复： pipeline_options.ocr_options.lang = ["fr", "de", "en"] —— 所选引擎必须支持这些语言，使用 Tesseract 时还需安装语言数据。
pipeline_options.ocr_options.lang = ["fr", "de", "en"]不适用的情况： 各引擎支持的语言集合不同。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
torch.cuda.is_available() is False / processing stays on the CPU
原因： PyTorch 安装时未包含 CUDA 支持，或没有兼容的 GPU 与驱动。
快速修复： 确认 torch.cuda.is_available() 返回 True。
推荐修复： 卸载 CPU wheel，安装与 CUDA 版本匹配的 CUDA 版 PyTorch，然后用 --device cuda 选择设备。用 nvidia-smi 验证。
pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128不适用的情况： Apple Silicon 使用 MPS（--device mps），不是 CUDA。部分 OCR 引擎仅支持 CPU。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate ...
原因： 批大小超过可用 VRAM，或另一个进程占用了 GPU 显存。
快速修复： 减小批大小并清空缓存。
推荐修复： 降低 layout_batch_size、ocr_batch_size 和 table_batch_size，设置 queue_max_size，在文档之间调用 torch.cuda.empty_cache()，并减少并行文件数。
import torch
torch.cuda.empty_cache()pipeline_options.ocr_batch_size = 2不适用的情况： 超大页面仍可能超出 VRAM；这些文件可回退到 CPU。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
CUDA error: no kernel image is available for execution on the device
原因： PyTorch 的 CUDA 构建不包含您 GPU 计算能力的 kernel，在很新的 GPU 或旧驱动上常见。
快速修复： 使用与 GPU 和驱动匹配的 PyTorch 或容器构建。
推荐修复： 检查驱动/CUDA 兼容性，升级 NVIDIA 驱动，并使用匹配的 CUDA wheel（cu128/cu130）或对应的 docling-serve CUDA 镜像。在 Docker 中用 NVIDIA Container Toolkit 暴露 GPU。
nvidia-smi不适用的情况： 很新的 GPU 可能需要比当前镜像更新的 CUDA 构建。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
flash-attn fails to build / ImportError: cannot import name 'flash_attn'
原因： Flash Attention 2 需要 Ampere 或更新的 GPU、CUDA 11.8+ 和 PyTorch 2.0+，且从源码构建困难。
快速修复： 如不需要请禁用它。
推荐修复： 设置 accelerator_options = AcceleratorOptions(cuda_use_flash_attention2=False)，或用 FLASH_ATTENTION_SKIP_CUDA_BUILD=TRUE pip install flash-attn 安装。
FLASH_ATTENTION_SKIP_CUDA_BUILD=TRUE pip install flash-attn不适用的情况： 不支持 Ampere 之前的 GPU 或 Apple Silicon。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
torch.backends.mps.is_available() is False / inference falls back to CPU
原因： MPS 需要 M 系列芯片上的 macOS 12.3+ 以及支持 MPS 的 PyTorch 构建；部分算子仍会回退到 CPU。
快速修复： 使用 device auto 让 Docling 选择最佳可用设备。
推荐修复： 在 Apple Silicon 上以 --device mps 运行并升级 macOS 与 PyTorch；使用 auto 以自动回退。
docling convert report.pdf --device mps不适用的情况： 部分模型仍会在 CPU 上执行流水线的部分环节。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
A single document takes minutes / high CPU usage
原因： OCR 和增强模型开销大，在 CPU 上尤其明显。
快速修复： 对数字版 PDF 关闭 OCR，并关闭不需要的增强。
推荐修复： 文本 PDF 用 --no-ocr，精度允许时用 --table-mode fast，设置 generate_page_images=False，并尽量使用 GPU。按 CPU 核心数调整 --num-threads。
docling convert report.pdf --no-ocr --to md不适用的情况： 扫描文档确实需要 OCR，无法跳过。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Killed / std::bad_alloc / the process is OOM-killed
原因： 图像或公式密集的大型 PDF 可能耗尽内存，docling-parse 后端还可能在页面间累积内存。
快速修复： 按页码范围处理或拆分为更小的文件。
推荐修复： converter.convert("large.pdf", page_range=[1, 100])；超大文件切换到 PyPdfium 后端；关闭增强；保持 generate_parsed_pages=False；在子进程中处理并在文件间重启。
docling convert large.pdf --page-range 1-100不适用的情况： 拆分可能破坏跨边界的标题和多页表格。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
RAM rises steadily when processing a batch / DoclingLoader leaks memory
原因： PDF 后端在每次转换后保留缓存和文档引用。
快速修复： 在每个文件后显式释放后端。
推荐修复： 转换后调用 result.input._backend.unload()，每隔几个文件重建 DocumentConverter，或每个文件使用子进程。保持 docling、docling-core 和 docling-parse 为最新。
result.input._backend.unload()不适用的情况： 公式增强有其已知泄漏；请将其隔离到单独进程。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
ConversionError: Input document file.pdf is not valid / status FAILURE
原因： 文件可能已加密、损坏、受密码保护或属于不支持的变体。
快速修复： 换一个示例文件，判断问题出在文档还是环境。
推荐修复： 移除密码保护或传入 --pdf-password；修复或重新导出文件；查看支持的格式列表并附带样例提交 issue。
docling convert report.pdf --to md不适用的情况： 加密 PDF 不会被静默解密；请提供无保护副本或密码。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
PdfiumError: Failed to load document (PDFium: Incorrect password error) / ConversionError with cause PdfiumError
原因： PDF 已加密且未提供密码。
快速修复： 提供文档密码。
推荐修复： CLI：docling convert secret.pdf --pdf-password 'secret'。Python：通过 PdfFormatOption(backend_options=...) 传入 PdfBackendOptions(password=SecretStr('secret'))。
docling convert secret.pdf --pdf-password 'secret'不适用的情况： 密码支持需要 docling-parse v4 或 PyPdfium2 后端。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
GLYPH<38> GLYPH<39> ... / /gid00020 / unreadable characters
原因： 缺少 ToUnicode 映射的自定义嵌入字体的 PDF 无法映射为真实字符。
快速修复： 强制全页 OCR。
推荐修复： 设置 pipeline_options.ocr_options.force_full_page_ocr = True（或 --ocr-mode full_page）。或切换到有时能更好解码这类字体的 PyPdfium2 后端。
docling convert broken.pdf --ocr-mode full_page不适用的情况： 部分版本的 OCR 仍会在表格中留下 GLYPH；请升级 Docling。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
"fi" / "fl" / "ffi" appear with spaces, e.g. "e ffi cient"
原因： 部分 PDF 字体把连字字形映射为带多余空格的独立字符。
快速修复： 升级 Docling，它会规范化常见连字。
推荐修复： 新版 Docling 会在页面组装阶段清理连字。若仍出问题，请使用 OCR 或预处理字体。
pip install -U docling不适用的情况： 如果后端无法解码，基于字形名称的连字仍可能残留。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Images are missing from DOCX or PPTX output on macOS or Linux
原因： WMF/EMF 图片的处理仅在 Windows 上使用默认图像库时有效。
快速修复： 转换这些图片，或在 Windows 上执行转换。
推荐修复： 在转换前把 WMF/EMF 资源转为 PNG/SVG（例如用 LibreOffice headless），或在 Windows 上执行该步骤。
libreoffice --headless --convert-to png document.docx不适用的情况： 仅影响 WMF/EMF 图片；其他图片格式正常转换。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
HTTPError 403/404 or a timeout when converting an URL
原因： 服务器阻止匿名请求，URL 是落地页，或连接超时。
快速修复： 先下载文件，再传入本地路径。
推荐修复： 在 Python 中传入自定义请求头：converter.convert(url, headers={"User-Agent": "..."})。确认 URL 指向 PDF/DOCX 而非 HTML 页面。
docling convert ./downloaded.pdf --to md不适用的情况： 部分网站需要 Cookie 或认证，Docling 无法处理。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
IndexError: list index out of range in md_backend.py
原因： Markdown 中的空列表项（仅有“-”的行）会让旧版后端出错；已在 v2.18 修复。
快速修复： 升级 Docling。
推荐修复： pip install -U docling。作为备选，移除 Markdown 中的空列表标记。
pip install -U docling不适用的情况： 仅影响旧版本的 Markdown 后端。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
convert_all raises at the first invalid document
原因： 默认 raises_on_error=True 会在首次失败时中止整批。
快速修复： 设置 raises_on_error=False 并逐个检查结果。
推荐修复： for res in converter.convert_all(files, raises_on_error=False)：检查 res.status 和 res.errors 并按文件处理。
converter.convert_all(files, raises_on_error=False)不适用的情况： 你需要自行处理 PARTIAL_SUCCESS 和 FAILURE 结果。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Wrong table structure / cells merged or columns shifted
原因： 复杂的合并单元格和无边框表格较难，fast 模式以精度换速度。
快速修复： 使用精确表格模式。
推荐修复： 以 --table-mode accurate 运行。遇到 TableFormer V2 的合并单元格问题，可尝试 do_cell_matching=False 或回退到 V1，并保持 Docling 更新。
docling convert report.pdf --table-mode accurate不适用的情况： 没有解析器能对所有表格都完美；可能需要人工复核。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Table structure is detected but all cell text values are empty
原因： 2.78.0 中 TableFormer V2 的回归导致单元格为空。
快速修复： 升级 Docling。
推荐修复： pip install -U docling —— 空单元格回归已在 2.78.0 之后的版本修复。
pip install -U docling不适用的情况： 仅影响受影响版本的 TableFormer V2。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
A whitespace-aligned table is extracted as prose / the table is missed
原因： 版式模型可能漏掉没有可见边框的表格，把对齐的列当作普通文本。
快速修复： 尝试强制 OCR 或更换后端。
推荐修复： 强制 OCR 可能揭示网格；切换到 PyPdfium2 后端或提高 images_scale。关键文档请人工复核。
docling convert report.pdf --ocr-mode full_page不适用的情况： 如果版式模型从未标记该区域，下游代码无法恢复。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Full-page or edge-to-edge tables are not detected
原因： 版式模型需要表格与页面边界之间有边距才能区分。
快速修复： 转换前在页面周围添加少量白边。
推荐修复： 转换前给 PDF 增加约 40pt 的左右内边距（例如用 pypdf）；上游正在讨论原生 page_padding 选项。
python add_padding.py input.pdf不适用的情况： 外部内边距可能改变部分文档的版式。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
docling-serve does not start / connection refused on port 5001
原因： 端口冲突、缺少 UI 扩展，或容器需要不同的入口点。
快速修复： 带 UI 扩展运行服务器，并确认端口空闲。
推荐修复： pip install "docling-serve[ui]" && docling-serve run --enable-ui，或使用官方容器镜像。用 UVICORN_HOST/UVICORN_PORT 修改绑定地址或端口。
docling-serve run --enable-ui不适用的情况： 高级部署（扩缩容、认证）超出范围；请参阅官方文档。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
GET /ready returns 503 / requests time out while models load
原因： 在模型加载完成前 /ready 一直返回 503；使用 RQ 引擎时还需 Redis 可达。
快速修复： 在发送流量前等待就绪。
推荐修复： 将 startupProbe 和 readinessProbe 配置到 /ready，livenessProbe 配置到 /health，并用 DOCLING_SERVE_ARTIFACTS_PATH 预加载模型以缩短启动时间。
curl -i http://localhost:5001/ready不适用的情况： 使用 RQ 引擎时，/ready 还需要 Redis 连接。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
CUDA error: no kernel image is available / the container runs on CPU despite --gpus
原因： 容器没有 GPU 访问权限，或 CUDA 镜像标签与主机驱动不匹配。
快速修复： 用 NVIDIA Container Toolkit 暴露 GPU。
推荐修复： 安装并更新 nvidia-container-toolkit，配置 nvidia 运行时，并请求 GPU（docker run --gpus all，或在 Compose 中设置 devices count: all）。使用与驱动匹配的 CUDA 镜像标签。
docker run --gpus all -p 5001:5001 quay.io/docling-project/docling-serve-cu128不适用的情况： 很新的 GPU 可能需要比已发布镜像更新的 CUDA 镜像。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
The MCP server is not listed in the client / no tools appear / the server exits immediately
原因： 客户端配置指向了错误的命令、包不可用，或传输方式不正确。
快速修复： 先手动启动一次服务器以确认可用。
推荐修复： 运行 uvx --from=docling-mcp docling-mcp-server，并把对应 JSON 添加到 claude_desktop_config.json（或 mcp.json）。重启客户端，必要时加上 --transport stdio。
uvx --from=docling-mcp docling-mcp-server不适用的情况： 各客户端的配置文件位置不同；请查阅其文档。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
[Errno 2] No such file or directory / the MCP client times out on a cold start
原因： MCP 服务器看不到客户端的文件系统，或首次转换在加载模型时较慢。
快速修复： 使用共享目录，或通过 docling-serve 切换到远程模式。
推荐修复： 设置 DOCLING_MCP_CONVERSION_MODE=remote 和 DOCLING_MCP_SERVICE_URL，或挂载两个进程都能读取的共享文件夹。预热模型缓存以避免冷启动超时。
export DOCLING_MCP_CONVERSION_MODE=remote不适用的情况： Web 客户端与本地 MCP 服务器不共享文件系统。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Token indices sequence length is longer than the specified maximum sequence length for this model (531 > 512)
原因： Transformers 在 chunker 统计过长序列的 token 数时发出警告，随后会进行拆分，属于误报。
快速修复： 忽略该警告。
推荐修复： 通过序列化每个 chunk 并用同一 tokenizer 统计 token 数，确认实际大小在限制内。
for c in chunker.chunk(doc):
print(len(tokenizer.tokenize(chunker.serialize(chunk=c))))pip install -U docling-core不适用的情况： 如果真实 chunk 超过模型上限，请让 chunker 的 tokenizer 与嵌入模型对齐。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
ImportError: semchunk ... / the chunking extra is required
原因： 支持 token 的分块依赖是 docling-core 的可选扩展。
快速修复： 安装 chunking 扩展。
推荐修复： Hugging Face tokenizer 用 pip install 'docling-core[chunking]'，tiktoken 用 'docling-core[chunking-openai]'。
pip install 'docling-core[chunking]'不适用的情况： 选择与嵌入模型 tokenizer 匹配的扩展。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
Audio or video conversion fails / the ASR pipeline is not available
原因： ASR 是可选扩展，不包含在基础安装中。
快速修复： 安装 asr 扩展。
推荐修复： pip install "docling[asr]"（或 uv add "docling[asr]"）。
pip install "docling[asr]"不适用的情况： ASR 流水线只转录音频；视频还需要视频流水线。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
[WinError 2] The system cannot find the file specified / FileNotFoundError: ffmpeg
原因： Whisper 通过调用 ffmpeg 二进制来解码音频，因此必须安装并位于 PATH 中。
快速修复： 安装 ffmpeg 并确保其在 PATH 中。
推荐修复： brew install ffmpeg（macOS）、apt-get install ffmpeg（Debian）或 winget install ffmpeg（Windows）。用 ffmpeg -version 验证。
ffmpeg -version不适用的情况： 所有音频格式和所有视频输入都需要 ffmpeg。
已验证： Docling v2.129.0 · 最后核对 2026-09-22
没有匹配的问题。
Docling 的大多数问题源于版本过旧、缺少可选扩展或某个难处理的文档。请先按以下步骤排查。
pip install -U docling docling-core docling-parse。--pdf-backend pypdfium2、--ocr-mode full_page 或 --table-mode fast。--page-range，关闭增强，只转换一个文件。复制这些命令，出错时就能随时提供版本号和设备信息。
-vv 以获取详细输出。docling --version
python -c "import torch; print(torch.__version__, torch.cuda.is_available())"
python -c "import docling, docling_core; print(docling.__version__, docling_core.__version__)"PDF 转换需要模型权重；下载损坏或被阻挡是很常见的故障。
docling-tools models download --all 预先获取全部模型。artifacts_path 指向包含模型子文件夹的父目录。HF_HOME 统一缓存位置，代理或受限仓库用 HF_TOKEN。OCR 问题通常是缺少引擎、缺少语言数据或模式不正确。
pip install "docling[rapidocr]" 或 [easyocr]。TESSDATA_PREFIX。--ocr-mode full_page 强制 OCR。转换缓慢或被杀通常是内存压力或纯 CPU 执行。
torch.cuda.empty_cache()。--page-range 处理或切换到 PyPdfium 后端。result.input._backend.unload() 释放内存。--num-threads。输出问题通常源于源文档、后端或表格模式。
--pdf-password。--table-mode accurate；V2 合并单元格可试 do_cell_matching=False 或 V1。raises_on_error=False 并逐个检查结果。服务和智能体集成失败通常有三个原因：端口、就绪状态或 GPU 访问。
docling-serve run --enable-ui（或容器镜像）启动 API。/ready 一直返回 503；用它做 startup/readiness 探针。--gpus all）并安装 NVIDIA Container Toolkit。uvx --from=docling-mcp docling-mcp-server；Web 客户端使用远程模式。分块警告通常无害；音频和视频需要额外依赖。
HybridChunker 的 token 长度警告是误报；请核实实际大小。docling-core[chunking]。pip install "docling[asr]" 以及 PATH 中的 ffmpeg。好的报告能带来快速修复。请包含复现所需的一切信息。
pip install docling==<version> 固定到之前版本以解困，然后附带样例报告该回归。--page-range，再考虑拆分，并预期跨页结构会有一定损失。do_cell_matching=False 或 TableFormer V1，并复核关键表格。PdfFormatOption 传入选项，确保它们真正到达流水线。