粘贴你的报错#
粘贴报错信息或 traceback 的最后几行。匹配在你的浏览器中完成，不会发送到任何地方。也可以按类别浏览所有条目。报错原文保持英文，与终端输出一致。
四步排查任何 Docling 故障#
- 确认版本和 Python
docling --version python --version大多数“未知选项”和“缺少功能”的问题都是 Docling 版本过旧，常常由 Python 3.9 导致。
- 拿到真正的报错
docling convert problem.pdf -vv 2>&1 | tail -40 - 定位出问题的阶段
依次加
--no-ocr、--no-tables重跑。如果报错消失，问题就在该阶段（通常是 OCR 引擎或其语言）。 - 看看 Docling 看到了什么
docling convert problem.pdf --to html_split_page --show-layout每页原图与提取内容并排显示，并画出版面框——这是诊断表格错误、文字缺失或阅读顺序错误最快的方法。
没有报错，但输出不对#
| 现象 | 可能原因 | 尝试 |
|---|---|---|
| 扫描 PDF 输出为空或乱码 | PDF 带有错误的文本层，因此跳过了 OCR | --ocr-mode full_page |
| 查看器里文字正常，提取出来却是乱码（“8VceZWZTReV”） | 字体把字形映射到了错误的字符 | --replace-broken-text-layer（2.144.0+）只对受影响的页面做 OCR——见 OCR 指南 |
所有标题都输出为 ## | 版面模型只标注章节标题，不标注层级 | --heading-hierarchy（2.144.0+） |
| 横放的扫描页用 RapidOCR 识别成乱码 | RapidOCR 的方向分类器只会把文字翻转 180° | --ocr-option detect_orientation=true（2.145.0+） |
| 中文扫描件识别出错字 | OCR 模型的默认语言不对 | 用 --ocr-lang 指定引擎代码或 iso: 标签——见 OCR 指南 |
| 表格两行合并到一个单元格 | 表格没有横线（我们在 Docling 报告自己的表 1 上复现了这一点） | 用 --show-layout 检查；对该页试用 VLM 流水线 |
| 单词粘连（“MaksymLysak”） | PDF 文本层的字间距过紧 | 对比 --pdf-backend pypdfium2；或 --ocr-mode full_page |
| Markdown 文件巨大 | 嵌入了 base64 图片（CLI 默认 embedded） | --image-export-mode placeholder 或 referenced |
| 正文中出现页眉页脚 | 读取了包括页面装饰在内的完整文档 | 只导出正文（默认的 Markdown 导出会跳过页眉页脚） |
| 分块切断表格，或对嵌入模型来说太长 | 使用了 HierarchicalChunker 或不匹配的分词器 | 使用 HybridChunker 并传入嵌入模型的分词器——见 RAG 与分块 |
仍然没解决？#
用完整的报错文本搜索官方 issue 列表；如需新建 issue，请附上 docling --version 的输出、操作系统和一个最小复现文件。如果本页某条内容有误或解决方法失效，请发邮件至 hello@docling.org。
常见问题
为什么 Docling 提示 onnxruntime 未安装？
因为 --ocr-engine rapidocr 使用 RapidOCR 的 onnxruntime 后端，而默认的 pip install docling 不包含它。安装 docling[rapidocr]，或加上 --ocr-option backend=torch 使用已安装的 PyTorch 后端。
为什么安装后找不到 Docling 的新选项？
检查 docling --version。在 Python 3.9 上，pip 会不报错地安装 Docling 2.69.1——支持 3.9 的最后一个版本。请使用 Python 3.10–3.14 以获得最新版本。
如何查看 Docling 文档转换失败的原因？
对同一文件加 -vv 运行以获得调试日志。命令行中的 “Document … failed to convert” 只是摘要，真正的异常记录在它上方。
为什么 Docling 处理 .doc、.ppt 或 .xls 文件会失败？
这些旧格式（以及 .rtf）会先用 LibreOffice 转为 .docx、.pptx 或 .xlsx。请安装 LibreOffice 并确保 soffice 在 PATH 中，或设置 DOCLING_LIBREOFFICE_CMD。