`docling` 和 `docling convert` 有什么区别？

在 Docling v1 中可以直接运行 `docling file.pdf`。在 v2 中，转换位于显式的 `docling convert` 子命令下。省略 `convert` 的旧教程是为 v1 编写的，在当前版本上无法运行——请使用 `docling convert file.pdf --to md`。

为什么我的扫描版 PDF 转换后输出为空？

扫描版 PDF 没有文本层，因此必须强制 OCR。运行 `docling convert scan.pdf --ocr-mode full_page`。如果页面是更大 PDF 中的图像，还要确保 OCR 已启用（默认已启用）并且已安装 OCR 引擎。

如何让转换更快？

对数字 PDF 添加 `--no-ocr`（通常快数倍），并跳过不需要的功能，例如 `--no-tables`。有 GPU 时使用 `--device cuda` 或 `--device mps`，并调整 `--num-threads` 和 `--page-batch-size`。用 `--profiling` 查看时间实际花在哪里。

我应该选择哪个 OCR 引擎？

先从 `auto` 开始。RapidOCR 是强大的跨平台默认选项，对 CPU 友好。多语言使用 `tesseract`/`tesserocr`，macOS 使用 `ocrmac`，仅在 CUDA 环境中使用 `nemotron-ocr`。在 OCR 指南中用自己的文档进行比较。

不需要。Docling 可在 CPU 上运行。GPU 主要加速大文档上的 OCR 和增强模型。在 Apple Silicon 上可使用 `--device mps`；在 NVIDIA 上使用 `--device cuda`。

转换后的文件写到哪里？

默认写入当前目录，即运行命令的位置旁边。使用 `--output ./some/folder` 选择目录。请注意 `--output` 是目录，而不是文件名。

如何转换多个文件或整个文件夹？

传入一个目录（`docling convert ./inbox --output ./out`）、一次传入多个路径，或使用 shell 循环获得完全控制。上面的基础命令和批处理配方涵盖了 bash、PowerShell 和并行运行。

如何为 RAG 系统获取分块？

使用 `docling convert report.pdf --to chunks --chunks-type hybrid`。分块会保留标题和表格结构。可以用 `--chunks-max-tokens` 限制大小，并用 `--chunks-tokenizer` 选择分词器。

可以完全离线运行 Docling 吗？

可以。先在联网机器上用 `docling-tools models download --all` 预下载模型，然后在隔离主机上设置 `DOCLING_ARTIFACTS_PATH`（以及 `HF_HUB_OFFLINE=1`），并用 `--artifacts-path` 指向复制的缓存。

什么时候应该使用 VLM 流水线而不是标准流水线？

对于传统版面分析难以处理的复杂、视觉丰富的页面，或希望使用单一端到端模型时，使用 `--pipeline vlm`。对于普通数字 PDF，标准流水线更快、更省，因此先从它开始。

Docling 会上传我的文档吗？

不会。Docling 默认在本地处理文档，不发送任何遥测数据。仅当您用 `--enable-remote-services` 显式启用或将流水线指向外部服务时，才会使用远程模型。

还支持 `--force-ocr` 吗？

已弃用。请使用 `--ocr-mode full_page`，这是对每一页执行 OCR 并替换任何现有文本的受支持方式。

参考

Docling 命令查找器

常见 Docling 任务及其准确命令。可搜索、按分类筛选并复制。命令使用当前的 docling convert 语法；请以官方文档为准。

将 PDF 转换为 Markdown

BasicStarter

将本地 PDF 转换为结构化 Markdown。

docling convert report.pdf --to md

标志、输出与提示

使用的标志

--to md 输出格式。重复该标志可一次导出多种格式。

预期输出

# Annual Report

## Revenue

| Year | Revenue |
|------|--------:|
| 2025 | $12M |
| 2026 | $15M |

变体

对数字 PDF 跳过 OCR（快得多）

docling convert report.pdf --to md --no-ocr

直接写入文件夹

docling convert report.pdf --to md --output ./out

常见错误： 在扫描版 PDF 上运行并得到空文本。如果 PDF 没有文本层，请添加 --ocr-mode full_page。

从 URL 转换文档

BasicStarter

直接通过 HTTP URL 下载并转换在线文档。

docling convert https://arxiv.org/pdf/2408.09869 --to md

标志、输出与提示

使用的标志

--to md 输出格式。重复该标志可一次导出多种格式。

预期输出

## Docling Technical Report

The conversion pipeline analyses layout, reading order and tables…

变体

发送请求头（auth / token）

docling convert https://example.com/report.pdf --headers '{"Authorization":"Bearer TOKEN"}' --to md

改为导出 JSON

docling convert https://arxiv.org/pdf/2408.09869 --to json

常见错误： 以为任何 URL 都可用。源必须是可通过 HTTP(S) 访问的受支持文档格式。

导出无损 JSON

BasicStarter

导出 DoclingDocument JSON 结构，包含边界框。

docling convert report.pdf --to json

标志、输出与提示

使用的标志

--to json 输出格式。重复该标志可一次导出多种格式。

预期输出

{
  "schema_name": "DoclingDocument",
  "texts": [ ... ],
  "tables": [ ... ],
  "pictures": [ ... ]
}

变体

为速度跳过 OCR

docling convert report.pdf --to json --no-ocr

将图像嵌入为 base64

docling convert report.pdf --to json --image-export-mode embedded

常见错误： 期望 CLI JSON 与 export_to_dict() 逐字节相同；它们是同一文档的等价视图。

检查已安装版本

BasicStarter

打印 Docling、docling-core 和 docling-ibm-models 的版本。

docling --version

标志、输出与提示

使用的标志

--version 显示已安装的 Docling 版本。

预期输出

Docling version: 2.129.0
Docling Core version: 2.x.x
Docling IBM Models version: 3.x.x
Python: cpython-312 …

变体

升级到最新版本

pip install -U docling docling-core docling-ibm-models

常见错误： 报告缺陷时不附带版本输出——务必包含它，因为不同版本之间标志会变化。

阅读内置帮助

BasicStarter

直接从 CLI 列出已安装 Docling 版本支持的所有标志。

docling convert --help

标志、输出与提示

预期输出

Usage: docling convert [OPTIONS] SOURCE

  --from TEXT        Input formats to accept…
  --to TEXT          Output formats…
  --ocr-engine TEXT  The OCR engine to use…

变体

列出顶层命令

docling --help

检查远程转换器

docling convert-remote --help

常见错误： 相信旧的博客文章。务必用 --help 确认你所安装版本的标志。

将结果保存到文件夹

BasicStarter

将转换后的文件写入指定的输出目录，而不是当前目录。

docling convert report.pdf --to md --output ./out

标志、输出与提示

使用的标志

--output 保存结果的目录（不是文件名）。

预期输出

./out/report.md

变体

一次导出多种格式

docling convert report.pdf --to md --to json --to html --output ./out

常见错误： 忘记 --output 接受的是目录而非文件名。与 --to 组合以选择扩展名。

一次导出多种格式

OutputIntermediate

--to 标志可重复：一次运行即可生成 Markdown、JSON 和 HTML。

docling convert report.pdf --to md --to json --to html

标志、输出与提示

使用的标志

--to 输出格式。重复该标志可一次导出多种格式。

预期输出

report.md  report.json  report.html

变体

全部放入一个文件夹

docling convert report.pdf --to md --to json --output ./out

常见错误： 传入逗号分隔的列表（--to md,json）。应改为重复该标志。

转换整个文件夹

BasicIntermediate

将 Docling 指向一个目录，它会遍历其中每个受支持的文档。

docling convert ./inbox --output ./out

标志、输出与提示

使用的标志

--output 保存结果的目录（不是文件名）。
--abort-on-error 第一个文件失败时停止整个运行。

预期输出

Converting ./inbox/a.pdf … done
Converting ./inbox/b.docx … done

变体

即使某个文件失败也继续

docling convert ./inbox --output ./out --no-abort-on-error

筛选为单一格式

docling convert ./inbox --from pdf --output ./out

常见错误： 以为递归进入子文件夹总是需要的——在大批量运行前检查打印出的文件列表。

转换多个指定文件

BasicIntermediate

在一条命令中传入多个路径；每个都独立转换。

docling convert a.pdf b.docx c.pptx --output ./out

标志、输出与提示

使用的标志

source Accepts one or more local paths, directories or URLs.

预期输出

a.md  b.md  c.md  written to ./out

变体

包含 URL 的混合来源

docling convert a.pdf https://example.com/b.pdf --output ./out

常见错误： 给通配符加引号（“*.pdf”）并期望 shell 展开它——让 shell 展开，或直接传入目录。

预下载所有模型

OfflineIntermediate

在离线使用前将版面和表格模型缓存到本地。

docling-tools models download --all

标志、输出与提示

使用的标志

--all Download every available model (large).

预期输出

Downloading layout model…
Downloading tableformer model…
Models cached in $HOME/.cache/docling/models

变体

只下载你需要的

docling-tools models download layout tableformer rapidocr

下载 HuggingFace 仓库

docling-tools models download-hf-repo docling-project/docling-models

常见错误： 在计费连接上下载 --all——请挑选你实际使用的特定模型。

将 DOCX 转换为 Markdown

ConversionStarter

将 Microsoft Word 文档解析为 Markdown。

docling convert contract.docx --to md

标志、输出与提示

使用的标志

--to md 输出格式。重复该标志可一次导出多种格式。

预期输出

# Service Agreement

1. Scope
2. Payment terms…

变体

旧版 .doc 文件

docling convert contract.doc --to md

常见错误： 以为 OCR 选项会起作用——Office 格式是原生解析的，因此 --ocr-engine 无效。

将 PPTX 转换为 Markdown

ConversionStarter

解析 PowerPoint 幻灯片、文本框和演讲者备注。

docling convert slides.pptx --to md

标志、输出与提示

使用的标志

--page-range 仅转换指定页码范围。PDF、XLSX 和 PPTX 支持。

预期输出

## Slide 1 — Overview

Bullet one
Bullet two

变体

仅前 10 张幻灯片

docling convert slides.pptx --page-range 1-10 --to md

常见错误： 以为幻灯片内的图像会被描述——为此需添加 --enrich-picture-description。

将 XLSX 转换为 Markdown

ConversionStarter

将 Excel 工作簿解析为按工作表的结构化表格。

docling convert workbook.xlsx --to md

标志、输出与提示

使用的标志

--page-range 仅转换指定页码范围。PDF、XLSX 和 PPTX 支持。

预期输出

## Sheet 1

| Region | Q1 | Q2 |
|--------|----|----|
| EMEA   | 12 | 15 |

变体

无损结构

docling convert workbook.xlsx --to json

常见错误： 把 XLSX 当作 PDF 并启用 OCR——电子表格默认没有位图页面。

将 HTML 转换为 Markdown

ConversionStarter

将本地 HTML 页面解析为 Markdown。

docling convert page.html --to md

标志、输出与提示

使用的标志

--html-image-fetch 获取 HTML 和 EPUB 输入所引用的图像。

预期输出

# Page title

Body text converted from HTML…

变体

同时下载远程图像

docling convert page.html --html-image-fetch remote --to md

常见错误： 忘记图像获取默认关闭；如果需要图片请传入 --html-image-fetch。

将 CSV 转换为 Markdown

ConversionStarter

将逗号分隔的数据转换为 Markdown 表格。

docling convert data.csv --to md

标志、输出与提示

使用的标志

--to md 输出格式。重复该标志可一次导出多种格式。

预期输出

| name | score |
|------|------:|
| Ada  | 98    |

变体

保留为结构化 JSON

docling convert data.csv --to json

常见错误： 使用逗号/标准 CSV 方言以外的分隔符——请先规范化。

将 EPUB 转换为 Markdown

ConversionIntermediate

在保留章节结构的同时转换电子书和长篇 EPUB 内容。

docling convert book.epub --to md

标志、输出与提示

使用的标志

--html-image-fetch 获取 HTML 和 EPUB 输入所引用的图像。

预期输出

# Chapter 1

Long-form text…

变体

包含插图

docling convert book.epub --html-image-fetch all --to md

常见错误： 不获取图像，然后疑惑为什么图缺失。

将 Markdown 转换为 HTML

ConversionIntermediate

重新处理 Markdown 文件并导出干净的 HTML（保留表格和代码）。

docling convert notes.md --to html

标志、输出与提示

使用的标志

--to html 输出格式。重复该标志可一次导出多种格式。

预期输出

<h1>Notes</h1>
<p>…</p>

变体

拆分长页面

docling convert notes.md --to html_split_page

常见错误： 期望生成图像文件——HTML 导出只引用框，不会渲染新图像。

将 LaTeX 转换为 Markdown

ConversionAdvanced

解析 LaTeX 源，并可选择渲染 TikZ 图。

docling convert paper.tex --to md

标志、输出与提示

使用的标志

--tikz-engine Set to 'tectonic' to rasterize tikzpicture diagrams.

预期输出

# Introduction

The math is preserved as LaTeX where possible…

变体

将 TikZ 图渲染为图像

docling convert paper.tex --tikz-engine tectonic --to md

常见错误： 当缺少 Tectonic 或渲染失败时，TikZ 渲染会静默回退为保留源代码。

对单张图像做 OCR

OCRIntermediate

使用 OCR 将包含文本的 PNG/JPEG/TIFF 图像转换为 Markdown。

docling convert scan.png --to md --ocr-mode full_page

标志、输出与提示

使用的标志

--ocr-mode full_page 哪些文档区域会送入 OCR 引擎。
--ocr-engine OCR 引擎提供方。

预期输出

Text recognised from the image…

变体

使用 RapidOCR

docling convert scan.png --ocr-engine rapidocr --to md

常见错误： 在低 DPI 照片上使用默认 OCR 模式：提高分辨率以获得更好的精度。

对扫描 PDF 进行 OCR

OCRStarter

对纯图像页面强制整页 OCR。

docling convert scan.pdf --ocr-mode full_page --to md

标志、输出与提示

使用的标志

--ocr-mode full_page 哪些文档区域会送入 OCR 引擎。

预期输出

Text reconstructed from the scanned page images…

变体

同时选择引擎

docling convert scan.pdf --ocr-mode full_page --ocr-engine rapidocr --to md

常见错误： 对数字 PDF 保持 OCR 开启会浪费时间。仅当文本层缺失或错误时才强制启用。

选择 OCR 引擎

OCRIntermediate

使用指定引擎运行 OCR（例如 RapidOCR）。

docling convert scan.pdf --ocr-engine rapidocr --to md

标志、输出与提示

使用的标志

--ocr-engine OCR 引擎提供方。

预期输出

Using OCR engine: rapidocr

变体

带语言的 Tesseract

docling convert scan.pdf --ocr-engine tesseract --ocr-lang eng --to md

macOS 上的 Apple Vision

docling convert scan.pdf --ocr-engine ocrmac --to md

常见错误： 选择未安装的引擎。RapidOCR 是最安全的跨平台默认选项。

以指定语言进行 OCR

OCRIntermediate

告诉 OCR 引擎预期使用哪些语言，以获得更好的精度。

docling convert scan.pdf --ocr-engine tesseract --ocr-lang deu,fra --to md

标志、输出与提示

使用的标志

--ocr-lang OCR 语言；使用引擎原生代码或带 iso: 前缀的 BCP-47 标签。

预期输出

Using OCR languages: deu, fra

变体

通过 BCP-47 指定简体中文

docling convert scan.pdf --ocr-engine rapidocr --ocr-lang iso:zh-Hans --to md

让引擎自动检测

docling convert scan.pdf --ocr-lang '' --to md

常见错误： 混用引擎约定。每个引擎都有自己的代码——给规范的 BCP-47 标签加上 iso: 前缀。

禁用 OCR（数字 PDF）

OCRStarter

对已有文本层的 PDF 跳过 OCR。

docling convert report.pdf --no-ocr --to md

标志、输出与提示

使用的标志

--no-ocr Turn OCR off; the embedded text layer is used as-is.

预期输出

Skipping OCR (digital text layer detected)…

变体

同时跳过不需要的表格

docling convert report.pdf --no-ocr --no-tables --to md

常见错误： 在扫描件上使用 --no-ocr：你将得到空或近乎空的输出。

仅对版面区域做 OCR

OCRAdvanced

仅对检测到的版面区域执行 OCR，而不是整页。

docling convert report.pdf --ocr-mode layout_regions --to md

标志、输出与提示

使用的标志

--ocr-mode layout_regions 哪些文档区域会送入 OCR 引擎。

预期输出

OCR applied to detected layout regions…

变体

PDF 感知的区域选择

docling convert report.pdf --ocr-mode pdf_aware_layout_regions --to md

常见错误： 整页是一张照片时却使用区域模式——此时应使用 full_page。

设置 Tesseract 页面分割模式

OCRAdvanced

使用页面分割模式（0-13）微调 Tesseract 版面分析。

docling convert scan.pdf --ocr-engine tesseract --psm 6 --to md

标志、输出与提示

使用的标志

--psm Tesseract 引擎的页面分割模式（Page Segmentation Mode）。

预期输出

Tesseract PSM 6 — assume a single uniform block of text.

变体

单行文本

docling convert scan.pdf --ocr-engine tesseract --psm 7 --to md

常见错误： 对会被忽略的非 Tesseract 引擎设置 PSM。

更快的表格提取

TablesIntermediate

使用快速表格模式而非精确模型。

docling convert report.pdf --table-mode fast --to md

标志、输出与提示

使用的标志

--table-mode 表格结构模型在精度与速度之间的取舍。

预期输出

Rough table grid, produced faster…

变体

完全跳过表格

docling convert report.pdf --no-tables --to md

常见错误： 在含合并单元格的财务表上使用 fast——精度会明显下降。

禁用表格提取

TablesIntermediate

当只需要正文文本时，跳过表格结构模型。

docling convert report.pdf --no-tables --to md

标志、输出与提示

使用的标志

--no-tables Do not run the table structure model.

预期输出

Tables rendered as plain text flow…

变体

最快的数字文本路径

docling convert report.pdf --no-ocr --no-tables --to md

常见错误： 在表格很重要时启用它——表格内容会塌缩成段落。

使用 TableFormer v2 引擎

TablesAdvanced

选择特定的表格结构引擎，包括较新的 TableFormer v2。

docling convert report.pdf --table-structure-engine docling_tableformer_v2 --to md

标志、输出与提示

使用的标志

--table-structure-engine 选择表格结构引擎。

预期输出

Using table structure engine: docling_tableformer_v2

变体

Granite vision 表格引擎

docling convert report.pdf --table-structure-engine granite_vision_table --to md

常见错误： 以为每个引擎都已捆绑——有些需要额外的模型下载或插件。

启用代码与公式增强

EnrichmentIntermediate

使用增强模型提取 LaTeX 公式和代码块。

docling convert paper.pdf --enrich-code --enrich-formula --to md

标志、输出与提示

使用的标志

--enrich-code 检测并标注代码块。
--enrich-formula 将公式提取为 LaTeX。

预期输出

```python
def hello(): …
```

$$ E = mc^2 $$

变体

仅公式

docling convert paper.pdf --enrich-formula --to md

仅代码

docling convert repo.pdf --enrich-code --to md

常见错误： 在没有代码或数学的文档上同时启用两者——每个都会增加一次神经处理并拖慢转换。

用 VLM 描述图片

EnrichmentAdvanced

为图和图像生成自然语言描述。

docling convert report.pdf --enrich-picture-description --to md

标志、输出与提示

使用的标志

--enrich-picture-description 使用视觉模型为图像生成描述。

预期输出

<!-- picture: a bar chart showing revenue growth from 2020 to 2026 -->

变体

限制生成的 token 数

docling convert report.pdf --enrich-picture-description --picture-description-max-new-tokens 256 --to md

常见错误： 在 RAM/VRAM 不足的图片密集文档上运行它——它会加载视觉模型。

对图片分类

EnrichmentAdvanced

用分类模型按类别（图表、示意图、截图、照片等）标注图片。

docling convert report.pdf --enrich-picture-classes --to md

标志、输出与提示

使用的标志

--enrich-picture-classes 对图像进行分类（图表、示意图、截图等）。

预期输出

<!-- picture class: chart -->

变体

分类并描述

docling convert report.pdf --enrich-picture-classes --enrich-picture-description --to md

常见错误： 期望像素级精确的标签——它是轻量级分类器，不是完整的视觉模型。

将图表数据提取为表格

EnrichmentAdvanced

使用图表提取模型将柱状图、饼图和折线图转换为表格数据。

docling convert report.pdf --enrich-chart-extraction --to md

标志、输出与提示

使用的标志

--enrich-chart-extraction 从柱状图、饼图和折线图中提取数据。

预期输出

<!-- chart: category | value -->
<!-- 2025 | 12 -->

变体

与表格输出结合

docling convert report.pdf --enrich-chart-extraction --to json

常见错误： 期望提取复杂 3D 图表的扫描件——柱状/饼/折线以外的图表不在范围内。

导出 RAG 分块

RAGIntermediate

生成保留结构的 HybridChunker 分块。

docling convert report.pdf --to chunks --chunks-type hybrid

标志、输出与提示

使用的标志

--to chunks 输出格式。重复该标志可一次导出多种格式。
--chunks-type 与 --to chunks 搭配使用的分块器类型。

预期输出

{ "text": "…", "meta": { "headings": ["Revenue"] } }

变体

限制分块大小

docling convert report.pdf --to chunks --chunks-max-tokens 512

层级分块

docling convert report.pdf --to chunks --chunks-type hierarchical

常见错误： 用朴素分割器分割 Markdown 导出，而不是使用 Docling 的结构感知分块器。

设置分块大小

RAGAdvanced

控制每个分块的最大 token 数以及用于混合分块的分词器。

docling convert report.pdf --to chunks --chunks-max-tokens 512

标志、输出与提示

使用的标志

--chunks-max-tokens 每个分块的最大 token 数。
--chunks-tokenizer 混合分块所使用的分词器。

预期输出

Chunks sized to the embedding model's token limit…

变体

匹配另一个嵌入模型

docling convert report.pdf --to chunks --chunks-tokenizer BAAI/bge-small-en-v1.5

常见错误： 设置的分块大小超过嵌入模型支持的上限——它会被截断。

使用 VLM 流水线转换

VLMAdvanced

使用 Granite Docling 模型运行 VLM 流水线。

docling convert report.pdf --pipeline vlm --vlm-model granite_docling --to md

标志、输出与提示

使用的标志

--pipeline vlm PDF 和图像文件的处理流水线。
--vlm-model 与 --pipeline vlm 搭配使用的 VLM 预设。

预期输出

Markdown generated page-by-page by the vision model…

变体

更小的 SmolDocling 预设

docling convert report.pdf --pipeline vlm --vlm-model smoldocling --to md

保留原始模型输出

docling convert report.pdf --pipeline vlm --vlm-write-native-output

常见错误： 以为 VLM 总是更好——对于普通数字 PDF，标准流水线更快更省。

限制 VLM 生成长度

VLMAdvanced

覆盖 VLM 每页可生成的最大 token 数。

docling convert report.pdf --pipeline vlm --vlm-max-new-tokens 8192 --to md

标志、输出与提示

使用的标志

--vlm-max-new-tokens 覆盖 VLM 生成的 max_new_tokens。

预期输出

Long, dense pages no longer get cut off…

变体

保留原始输出以便调试

docling convert report.pdf --pipeline vlm --vlm-write-native-output

常见错误： 在非常密集的页面上保留默认值可能会截断页面输出。

转写音频或视频（ASR）

AudioIntermediate

使用 ASR 流水线转写 WAV/MP3（以及视频）。

docling convert lecture.mp3 --pipeline asr --to md

标志、输出与提示

使用的标志

--pipeline asr PDF 和图像文件的处理流水线。
--asr-model 用于音频和视频文件的 ASR 模型。

预期输出

00:00:00 — Welcome to the show…

变体

更高精度

docling convert lecture.mp3 --pipeline asr --asr-model whisper_medium --to md

字幕输出

docling convert lecture.mp3 --pipeline asr --to vtt

常见错误： 对重要转录使用默认的 whisper_tiny；为精度选择 medium/large。

将视频转写为字幕

AudioIntermediate

转写视频音频并导出带时间戳的 WebVTT 字幕。

docling convert talk.mp4 --pipeline asr --to vtt

标志、输出与提示

使用的标志

--to vtt 输出格式。重复该标志可一次导出多种格式。

预期输出

WEBVTT

00:00:00.000 --> 00:00:04.000
Hello and welcome…

变体

不同的 ASR 模型

docling convert talk.mp4 --pipeline asr --asr-model whisper_small --to vtt

常见错误： 期望 OCR/表格标志适用——视频仅使用 ASR 流水线。

按场景变化采样视频

AudioAdvanced

选择视频帧的采样方式：固定间隔或场景变化。

docling convert talk.mp4 --pipeline asr --video-sampling-mode scene

标志、输出与提示

使用的标志

--video-sampling-mode 视频帧的采样方式。
--video-frame-interval 固定间隔模式下帧之间的秒数。

预期输出

Frames sampled at scene changes…

变体

更密集的固定采样

docling convert talk.mp4 --pipeline asr --video-frame-interval 5

常见错误： 在单个固定摄像头上使用场景模式——固定间隔在那里更可预测。

说话人分离（谁说了什么）

AudioAdvanced

在音频/视频转录中标注说话人（需要 resemblyzer 组件）。

docling convert interview.mp4 --pipeline asr --video-diarization

标志、输出与提示

使用的标志

--video-diarization 启用说话人分离（需要 resemblyzer）。

预期输出

[SPEAKER_00] …
[SPEAKER_01] …

变体

显式禁用说话人分离

docling convert interview.mp4 --pipeline asr --no-video-diarization

常见错误： 忘记说话人分离需要安装 resemblyzer 依赖。

将图像导出为 PNG 文件

OutputIntermediate

将图写为单独的 PNG 文件，并从输出文档中引用它们。

docling convert report.pdf --to md --image-export-mode referenced --output ./out

标志、输出与提示

使用的标志

--image-export-mode JSON、YAML、HTML 和 Markdown 输出中图像的导出方式。

预期输出

./out/report.md + ./out/report_artifacts/*.png

变体

仅标记图像位置

docling convert report.pdf --to md --image-export-mode placeholder

嵌入为 base64

docling convert report.pdf --to json --image-export-mode embedded

常见错误： 使用 referenced 搭配 --to json 并期望 PNG 就在旁边——请检查产物文件夹。

导出 DocTags

OutputAdvanced

生成用作模型输入的紧凑 token 风格 DocTags 标记。

docling convert report.pdf --to doctags

标志、输出与提示

使用的标志

--to doctags 输出格式。重复该标志可一次导出多种格式。

预期输出

<doctag><page_1><section_header_level_1>Annual Report</section_header_level_1>…

变体

带 VLM 原生输出

docling convert report.pdf --pipeline vlm --to doctags

常见错误： 把 DocTags 当作 Markdown——它是供模型使用的紧凑内部表示。

导出分页 HTML

OutputAdvanced

生成按页拆分的 HTML——便于查看器和并排审阅。

docling convert report.pdf --to html_split_page --output ./out

标志、输出与提示

使用的标志

--to html_split_page 输出格式。重复该标志可一次导出多种格式。

预期输出

./out/report_1.html  report_2.html …

变体

单文件 HTML

docling convert report.pdf --to html

常见错误： 在拆分输出每页写一个文件时却寻找单个 HTML 文件。

可视化检测到的版面

OutputAdvanced

在输出中的页面图像上叠加检测到的元素边界框。

docling convert report.pdf --show-layout --to md --output ./out

标志、输出与提示

使用的标志

--show-layout 在导出的页面图像上叠加元素边界框。

预期输出

Page images with coloured layout boxes…

变体

可视化表格单元格

docling convert report.pdf --debug-visualize-tables

常见错误： 期望框画在 Markdown 本身之上——它们画在导出的页面图像上。

在 NVIDIA GPU（CUDA）上运行

PerformanceIntermediate

使用 CUDA 加速推理并调整线程/批处理设置。

docling convert report.pdf --device cuda --num-threads 8 --to md

标志、输出与提示

使用的标志

--device cuda 模型推理的硬件加速器。
--num-threads 模型推理使用的线程数。

预期输出

Using accelerator device: cuda

变体

更大的页面批次

docling convert big.pdf --device cuda --page-batch-size 16

常见错误： 在没有 CUDA 运行时的机器上传入 --device cuda；请改用 auto 或 cpu。

在 Apple Silicon（MPS）上运行

PerformanceIntermediate

在 M 系列 Mac 上使用 Metal 后端加速推理。

docling convert report.pdf --device mps --to md

标志、输出与提示

使用的标志

--device mps 模型推理的硬件加速器。

预期输出

Using accelerator device: mps

变体

让 Docling 选择

docling convert report.pdf --device auto --to md

常见错误： 期望 MPS 媲美独立 GPU——它是可靠的加速，不是数据中心级显卡。

增大页面批处理大小

PerformanceAdvanced

每批处理更多页面，以提升大文档上的 GPU/CPU 吞吐量。

docling convert big.pdf --page-batch-size 16 --to md

标志、输出与提示

使用的标志

--page-batch-size 一个批次处理的页数。

预期输出

Processing 16 pages per batch…

变体

内存不足时回退

docling convert big.pdf --page-batch-size 2

常见错误： 一直提高直到出现内存不足错误——如果转换崩溃就降低它。

设置每个文档的超时

PerformanceAdvanced

通过限制处理时间来保护批次免受单个异常文件的影响。

docling convert ./inbox --document-timeout 120 --output ./out

标志、输出与提示

使用的标志

--document-timeout 处理每个文档的超时时间。

预期输出

Timed out after 120s — moving to the next file…

变体

失败时中止整个批次

docling convert ./inbox --abort-on-error --output ./out

常见错误： 对巨大文档设置非常短的超时并得到误报失败。

对转换流水线进行性能分析

PerformanceAdvanced

汇总转换各阶段的时间去向，以找出瓶颈。

docling convert report.pdf --profiling --to md

标志、输出与提示

使用的标志

--profiling 汇总每个转换阶段所耗费的时间。
--save-profiling Save profiling summaries to JSON.

预期输出

layout: 3.2s  ocr: 1.1s  tableformer: 0.9s  total: 5.4s

变体

将数据保存为 JSON

docling convert report.pdf --profiling --save-profiling

常见错误： 在 -v 保持开启的情况下做性能分析，把日志时间误认为模型时间。

仅转换页码范围

ConversionIntermediate

只解析部分页面，而不是整个文档。

docling convert report.pdf --page-range 1-4 --to md

标志、输出与提示

使用的标志

--page-range 仅转换指定页码范围。PDF、XLSX 和 PPTX 支持。

预期输出

Converting pages 1-4 only…

变体

单页

docling convert report.pdf --page-range 3 --to md

常见错误： 期望所有后端都遵守范围——主要是 PDF、XLSX 和 PPTX。

打开受密码保护的 PDF

ConversionAdvanced

提供密码，以便转换加密的 PDF。

docling convert locked.pdf --pdf-password 'secret' --to md

标志、输出与提示

使用的标志

--pdf-password 受保护 PDF 文档的密码。

预期输出

Decrypting and converting locked.pdf…

变体

从环境变量读取密码

docling convert locked.pdf --pdf-password "$PDF_PW" --to md

常见错误： 把真实密码放进 shell 历史；优先使用环境变量。

切换 PDF 后端

ConversionAdvanced

对于有问题的 PDF，可在默认的 docling-parse 后端和 pypdfium2 之间选择。

docling convert report.pdf --pdf-backend pypdfium2 --to md

标志、输出与提示

使用的标志

--pdf-backend docling_parse (default) or pypdfium2.

预期输出

Using PDF backend: pypdfium2

变体

默认解析器

docling convert report.pdf --pdf-backend docling_parse --to md

常见错误： 在字体编码损坏的 PDF 上坚持默认——试试 pypdfium2。

使用自定义模型路径

OfflineAdvanced

将 Docling 指向预填充的模型目录，而不是默认缓存。

docling convert report.pdf --artifacts-path /opt/docling/models --to md

标志、输出与提示

使用的标志

--artifacts-path 预下载模型产物的位置。

预期输出

Loading models from /opt/docling/models…

变体

改用环境变量

DOCLING_ARTIFACTS_PATH=/opt/docling/models docling convert report.pdf --to md

常见错误： 指向空目录：Docling 随后会尝试下载，离线时可能失败。

完全离线（气隙）运行

OfflineAdvanced

在联网主机上预取模型，然后在无网络访问的情况下转换。

export HF_HUB_OFFLINE=1; export DOCLING_ARTIFACTS_PATH=/opt/docling/models; docling convert report.pdf --to md

标志、输出与提示

使用的标志

DOCLING_ARTIFACTS_PATH Directory holding the pre-downloaded models.
HF_HUB_OFFLINE Stop HuggingFace downloads and use the local cache only.

预期输出

Conversion completes with no outbound requests…

变体

选择 HF 缓存目录

export HF_HOME=/opt/docling/hf; docling convert report.pdf --to md

常见错误： 忘记 HF_HUB_OFFLINE=1，这会使 Docling 尝试网络获取并停滞或失败。

运行 Docling Serve API

ServerIntermediate

在 5001 端口启动 docling-serve HTTP API 和 UI。

docling-serve run --enable-ui

标志、输出与提示

使用的标志

--enable-ui Serve the built-in web UI alongside the API.

预期输出

Uvicorn running on http://0.0.0.0:5001  (docs at /docs)

变体

在 Docker 中运行

docker run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 quay.io/docling-project/docling-serve

常见错误： 在没有身份验证的情况下公开服务——请在前面加上代理和认证。

通过远程服务转换

ServerAdvanced

将转换卸载到正在运行的 docling-serve 实例（本地文件、文件夹或 URL）。

docling convert-remote report.pdf --service-url http://localhost:5001 --to md

标志、输出与提示

使用的标志

--service-url Base URL of docling-serve (or DOCLING_SERVICE_URL).
--api-key Optional API key (or DOCLING_SERVICE_API_KEY).

预期输出

submitting job… polling… report.md written

变体

经过身份验证的服务

docling convert-remote report.pdf --service-url https://docling.internal --api-key "$DOCLING_KEY" --to md

使用轮询代替 websocket

docling convert-remote report.pdf --service-url http://localhost:5001 --watcher polling --to md

常见错误： 把 --device 等仅本地标志传给 convert-remote；它们被有意省略。

运行 MCP 服务端

MCPIntermediate

为 AI 桌面客户端启动 Model Context Protocol 服务端。

uvx --from=docling-mcp docling-mcp-server

标志、输出与提示

使用的标志

--from=docling-mcp 限制接受的输入格式。对 odt、ods 和 odp 使用 'odf'。

预期输出

docling-mcp server ready (stdio)

变体

面向 AI 客户端的 JSON 配置

{"mcpServers": {"docling": {"command": "uvx", "args": ["--from=docling-mcp", "docling-mcp-server"]}}}

常见错误： 把命令而不是 JSON 块粘贴到客户端的 MCP 配置中。

提高日志详细程度

DebugIntermediate

打印进度（-v）或完整调试日志（-vv）以诊断转换。

docling convert report.pdf -vv --to md

标志、输出与提示

使用的标志

-v / --verbose Repeat for more detail: -v info, -vv debug.
-q / --quiet Silence per-file progress (warnings and errors remain).

预期输出

DEBUG docling.pipeline… loading layout model

变体

用于脚本的静默批处理

docling convert ./inbox --quiet --output ./out

常见错误： 在生产环境保持 -vv 开启——调试日志缓慢且非常嘈杂。

可视化单元格、OCR 和表格

DebugAdvanced

调试可视化器渲染每个阶段检测到的内容，用于调优和故障排除。

docling convert report.pdf --debug-visualize-tables

标志、输出与提示

使用的标志

--debug-visualize-layout 可视化版面聚类。
--debug-visualize-tables 可视化表格单元格。
--debug-visualize-ocr 可视化 OCR 单元格。
--debug-visualize-cells Visualise PDF cells.

预期输出

Annotated page images written next to the output…

变体

检查 OCR 检测

docling convert scan.pdf --debug-visualize-ocr

检查版面聚类

docling convert report.pdf --debug-visualize-layout

常见错误： 同时使用多个可视化器并得到数量惊人的图像。

流水线	适用场景	取舍
`standard`	PDF 和图像的默认值——版面、OCR、表格。	均衡且经过充分验证。
`native`	想对大型 PDF 使用线程化的原生解析器。	解析快；用 `--parser-threads` 调整。
`vlm`	单一模型更擅长的复杂、视觉丰富的版面。	加载视觉模型；更慢更重。
`asr`	音频和视频文件（Whisper 系列）。	仅语音；OCR/表格标志不适用。
`legacy`	复现旧版行为。	不推荐用于新工作。

格式	您将获得	最适合
`md`	含表格的可读 Markdown	笔记、文档、RAG 文本（默认）
`json`	带边界框的无损 DoclingDocument	自定义流水线和结构
`chunks`	结构感知的分块	嵌入和向量存储
`html`	单个 HTML 文件	网页预览和邮件
`html_split_page`	每页一个 HTML 文件	逐页查看器
`doctags`	紧凑的 token 风格标记	模型输入和 token 工作流
`yaml`、`text`、`vtt`、`doclang`、`dclx`、`latex`	序列化、字幕、归档和源格式	特定的下游工具

手段	效果
`--no-ocr`	数字 PDF 上收益最大。
`--no-tables`、跳过增强	避免不需要的神经处理。
`--device cuda\|mps\|xpu`	将推理移到 GPU（CUDA、Apple Silicon、Intel）。
`--num-threads`	模型推理的 CPU 并行度（默认 4）。
`--page-batch-size`	每批更多页面——提高到内存紧张为止。
`--profiling`	显示各阶段耗时，让您优化真正的瓶颈。

旧语法	当前语法	原因
`docling report.pdf`	`docling convert report.pdf --to md`	v1 直接转换；v2 将转换移到了 convert 子命令下。
`docling report.pdf --format json`	`docling convert report.pdf --to json`	--format 变为 --to。
`docling report.pdf -o out.md`	`docling convert report.pdf --to md --output ./out`	-o/--output 现在是目录，而不是目标文件。
`--force-ocr`	`--ocr-mode full_page`	--force-ocr 已弃用；请使用显式的 OCR 模式。
`--ocr-engine tesseract_cli`	`--ocr-engine tesseract`	引擎值已重命名；tesserocr 对 C 绑定引擎仍然有效。
`--table-mode fast (no engine choice)`	`--table-mode fast --table-structure-engine docling_tableformer_v2`	现在可以分别选择速度/精度模式和底层表格引擎。
`docling --pipeline vlm doc.pdf`	`docling convert doc.pdf --pipeline vlm --vlm-model granite_docling`	流水线和模型选择已移到 convert 下。
`docling-tools models download`	`docling-tools models download --all`	仍然可用；--all 预取所有模型，而仅写名称则获取特定集合。

症状	最可能的原因与修复
扫描件得到的 Markdown 为空或几乎为空	没有文本层——添加 `--ocr-mode full_page`。
转换非常慢	对数字 PDF 做了 OCR——添加 `--no-ocr`；否则使用 GPU（`--device`）。
乱码 / GLYPH 占位符	字体编码损坏——尝试 `--pdf-backend pypdfium2`。
OCR 语言错误	使用引擎的代码设置 `--ocr-lang`。
未使用 GPU	安装 PyTorch 的 CUDA/MPS 构建并传入 `--device cuda\|mps`。
MCP 客户端无法连接	使用确切的 JSON 块，而不是原始命令。

标志	接受的值	默认	作用
`--from`	repeatable text	all supported	限制接受的输入格式。对 odt、ods 和 odp 使用 'odf'。
`--to`	md, json, yaml, html, html_split_page, text, doctags, vtt, doclang, dclx, chunks, latex	md	输出格式。重复该标志可一次导出多种格式。
`--output`	path	.	保存结果的目录（不是文件名）。
`--image-export-mode`	placeholder, embedded, referenced	embedded	JSON、YAML、HTML 和 Markdown 输出中图像的导出方式。
`--html-image-fetch`	none, local, remote, all	none	获取 HTML 和 EPUB 输入所引用的图像。
`--page-range`	text (e.g. 1-4)	all pages	仅转换指定页码范围。PDF、XLSX 和 PPTX 支持。
`--pdf-password`	text	-	受保护 PDF 文档的密码。
`--pipeline`	legacy, standard, native, vlm, asr	standard	PDF 和图像文件的处理流水线。
`--vlm-model`	granite_docling, smoldocling, deepseek_ocr, granite_vision, pixtral, …	granite_docling	与 --pipeline vlm 搭配使用的 VLM 预设。
`--vlm-max-new-tokens`	integer	model default	覆盖 VLM 生成的 max_new_tokens。
`--vlm-write-native-output`	flag	false	将每页未解析的 VLM 响应写入 <output>/<doc>.vlm-native/。
`--asr-model`	whisper_tiny … whisper_large, plus _mlx and _native variants	whisper_tiny	用于音频和视频文件的 ASR 模型。
`--video-sampling-mode`	fixed, scene	fixed	视频帧的采样方式。
`--video-frame-interval`	float (seconds)	10.0	固定间隔模式下帧之间的秒数。
`--video-diarization`	flag	false	启用说话人分离（需要 resemblyzer）。
`--ocr / --no-ocr`	flag	true	启用或禁用位图内容的 OCR。
`--ocr-mode`	full_page, layout_regions, pdf_aware_layout_regions, default	default	哪些文档区域会送入 OCR 引擎。
`--ocr-engine`	auto, easyocr, rapidocr, tesserocr, tesseract, ocrmac, nemotron-ocr, kserve_v2_ocr	auto	OCR 引擎提供方。
`--ocr-lang`	comma-separated codes	engine default	OCR 语言；使用引擎原生代码或带 iso: 前缀的 BCP-47 标签。
`--psm`	integer 0-13	engine default	Tesseract 引擎的页面分割模式（Page Segmentation Mode）。
`--tables / --no-tables`	flag	true	启用或禁用表格结构模型。
`--table-mode`	accurate, fast	accurate	表格结构模型在精度与速度之间的取舍。
`--table-structure-engine`	docling_tableformer, docling_tableformer_v2, granite_vision_table	docling_tableformer	选择表格结构引擎。
`--layout-engine`	layout_object_detection, docling_layout_default, …	layout_object_detection	选择版面检测引擎。
`--enrich-code`	flag	false	检测并标注代码块。
`--enrich-formula`	flag	false	将公式提取为 LaTeX。
`--enrich-picture-classes`	flag	false	对图像进行分类（图表、示意图、截图等）。
`--enrich-picture-description`	flag	false	使用视觉模型为图像生成描述。
`--enrich-chart-extraction`	flag	false	从柱状图、饼图和折线图中提取数据。
`--chunks-type`	hybrid, hierarchical	hybrid	与 --to chunks 搭配使用的分块器类型。
`--chunks-max-tokens`	integer	tokenizer limit	每个分块的最大 token 数。
`--chunks-tokenizer`	HuggingFace model id	sentence-transformers/all-MiniLM-L6-v2	混合分块所使用的分词器。
`--device`	auto, cpu, cuda, mps, xpu	auto	模型推理的硬件加速器。
`--num-threads`	integer	4	模型推理使用的线程数。
`--page-batch-size`	integer	4	一个批次处理的页数。
`--document-timeout`	float (seconds)	none	处理每个文档的超时时间。
`--abort-on-error`	flag	false	第一个文件失败时停止整个运行。
`--profiling`	flag	false	汇总每个转换阶段所耗费的时间。
`--artifacts-path`	path	HF cache	预下载模型产物的位置。
`--enable-remote-services`	flag	false	当模型连接远程服务时需要此项。
`--allow-external-plugins`	flag	false	启用加载第三方插件引擎。
`-v / --verbose`	repeatable	0	-v 为信息日志，-vv 为调试日志。
`-q / --quiet`	flag	false	抑制逐文件的进度日志。
`--show-layout`	flag	false	在导出的页面图像上叠加元素边界框。
`--debug-visualize-layout`	flag	false	可视化版面聚类。
`--debug-visualize-tables`	flag	false	可视化表格单元格。
`--debug-visualize-ocr`	flag	false	可视化 OCR 单元格。
`--version`	flag	-	显示已安装的 Docling 版本。