Docling CLI 实战指南：把 PDF、Office 与多格式文档高效转换为 Gen AI 可用数据

Docling CLI（docling 命令）是把任意受支持文档转换为统一表示的最快途径：无需写任何 Python 代码，一条命令即可把 PDF、DOCX、PPTX、XLSX、HTML、Markdown、图片、音频等转换为 Markdown、JSON（DoclingDocument）、HTML 等多种下游可直接消费的形式。本文基于仓库内的 CLI 参考文档 cli.md 与 docling/cli/ 下的实际实现，完整覆盖基础命令、管道（Pipeline）选型、OCR 与表格控制、常见场景排障、远程 VLM 与离线模型下载等全部实操要点，并给出源码级的参数默认值与行为验证，读完即可独立完成从“单文件转换”到“批量目录处理 + 离线部署”的完整工作流。

一、CLI 概览：两个命令入口与“免子命令”设计

安装 docling 包（pip install docling）后，会得到两个可执行入口：

• docling：文档转换主命令，实现位于 main.py；
• docling-tools：辅助工具命令（主要是模型下载），实现位于 tools.py。

从源码结构看，docling 是基于 Typer 构建的应用（main.py 中 app = typer.Typer(...)），并通过一个自定义命令组 _DefaultCommandGroup（main.py#L304-L320）保留了历史上的单命令用法：当第一个参数不是已知子命令时，会被自动路由为 convert 命令的参数。因此 docling report.pdf 与 docling convert report.pdf 完全等价，--help 时则仍显示命令列表。

两个与自动化集成直接相关的细节：

• --quiet / -q：抑制默认档位下的逐文件进度日志，输出完全静默（仅保留警告与错误），源码注释明确说明这是为 AI Agent 或脚本调用场景设计的（main.py#L1019-L1028）；
• --version：打印 Docling、Docling Core、Docling Parse 及 Python 平台版本（main.py#L404-L418）。

完整的选项清单以 docling convert --help 为准；仓库内另有一份由 Typer 应用自动生成（不手工维护）的权威参考 docs/reference/cli.md，由 scripts/render_cli_reference.py 渲染产出。

二、基础用法：docling <source> [--to ...] [--output DIR]

核心语法：

docling <source> [--to md|json|html|text|doctags] [--output DIR]

关键规则（与源码一一对应）：

• <source> 支持本地路径或 http(s) URL，均可直接使用。源码中 _is_http_url 判断 URL（main.py#L182-L184），非本地文件会通过 resolve_source_to_path 下载到临时目录后转换（main.py#L1212-L1241）；
• 输出文件以输入文件命名：report.pdf → report.md。export_documents 使用 conv_res.input.file.stem 作为各格式输出的文件名（main.py#L502）；
• --output 默认当前目录，可传 --output /tmp/ 重定向，目录不存在时会自动创建（main.py#L1579）；
• --to 可重复使用，一次运行输出多种格式（main.py#L747-L749）；不指定时默认为 Markdown（main.py#L1270-L1271）。

常用示例：

docling report.pdf --to md --output /tmp/              # Markdown（可读）
docling report.pdf --to json --output /tmp/            # DoclingDocument JSON（无损）
docling https://arxiv.org/pdf/2408.09869 --to md       # 直接转换 URL
docling report.pdf --to md --to json --output /tmp/    # 一次输出两种格式

全部输出格式

--to 的完整取值（来自 docs/reference/cli.md 与 export_utils.py 中的 _export_flags_from_formats）：

格式	说明	产物
md	Markdown，默认	report.md
json	DoclingDocument JSON，无损结构化	report.json
yaml	DoclingDocument YAML	report.yaml
html / html_split_page	HTML（后者按页拆分视图，可配合 --show-layout 画检测框）	report.html
text	纯文本（严格文本，图片位置用占位符）	report.txt
doctags	DocTags 标记流	report.doctags
vtt	WebVTT（音/视频转写）	report.vtt
doclang / dclx	DocLang XML / DocLang 归档包	report.dclg.xml / report.dclx
chunks	切块输出（见下文）	report.chunks.jsonl

其中 chunks 值得单独说明：它会在转换后对 DoclingDocument 执行切块并输出 JSONL，--chunks-type 可选 hybrid（默认，基于 HuggingFace tokenizer，默认 sentence-transformers/all-MiniLM-L6-v2，可用 --chunks-max-tokens、--chunks-tokenizer 覆盖）或 hierarchical，每条记录包含切块文本、token 数、标题、页码等元数据（main.py#L474-L670），是“转换即切块”进入 RAG 管线的最短路径。

图片导出不受 --to 直接控制，而由 --image-export-mode 决定：placeholder（仅标记位置）、embedded（base64 内嵌，默认）、referenced（导出 PNG 并被引用）；text、doctags、vtt 等纯文本格式不支持图片导出（main.py#L782-L788 及 export_utils.py#L25-L32）。

三、输入格式与 --from：批量目录转换

source 可以是多个本地文件、本地目录或 URL 的混合：

• 目录会被递归遍历（rglob），按 --from 允许的后缀集合过滤，并自动忽略 ~$ 开头的 Word 临时文件（main.py#L209-L223）；
• --from 可重复，用于限定/强制格式检测，例如 --from pdf --from docx ./inbox 批量转换一个目录（main.py#L742-L746）。

支持的输入格式包括：pdf、docx/doc、pptx/ppt、xlsx/xls、html、md、asciidoc、csv、odt/ods/odp、图片、音频、视频及多种 XML 风味（xml_uspto、xml_jats、xml_xbrl、xml_doclang、json_docling、mets_gbs、dclx、epub、latex、email、vtt 等，完整枚举见 docs/reference/cli.md 中 convert-remote 的 --from 选项）。

从源码结构看，--from 的解析在 _expand_from_formats（main.py#L226-L244）中完成：传 odf 会展开为 ODT + ODS + ODP 三种格式，非法格式名会直接报 BadParameter 并列出全部合法取值。每个输入格式在 convert 命令内被映射到对应的 FormatOption（PDF/图片走 PdfFormatOption，Word/Excel/PPT/HTML/MD/LaTeX 等走各自的 FormatOption，音频走 AsrPipeline，视频按需惰性加载 VideoPipeline），见 main.py#L1405-L1557。

四、管道选型：--pipeline standard 还是 --pipeline vlm

Docling 为 PDF 和图片提供两族处理管道，用 --pipeline 选择（main.py#L797-L800，默认 standard）：

管道	Flag	适用场景	代价
Standard（默认）	--pipeline standard	数字原生 PDF、追求速度	CPU 即可运行；OCR 处理扫描页
VLM	--pipeline vlm	复杂版式、手写、公式、含文字图片	需要 GPU（或 Apple MPS），更慢

docling report.pdf --pipeline vlm --output /tmp/
docling report.pdf --pipeline vlm --vlm-model granite_docling --output /tmp/
docling report.pdf --pipeline vlm --vlm-model smoldocling --output /tmp/

选型决策指南：

文档特征	建议
数字原生 PDF（文字可选中）	Standard（快、无需 GPU）
扫描版 / 纯图片 PDF	Standard + OCR，或用 --pipeline vlm 追求最高质量
复杂/多栏版式、密集表格	--pipeline vlm
手写或公式	--pipeline vlm（Standard 的 OCR 无法处理）
离线（air-gapped）/ 无 GPU	Standard
速度优先、精度次之	Standard + --no-ocr 和/或 --no-tables

VLM 模型通过 --vlm-model 指定预设（preset），默认 granite_docling。源码中预设 ID 动态取自 VlmConvertOptions.list_preset_ids()（main.py#L263-L264），当前注册表包含：smoldocling、granite_docling、deepseek_ocr、granite_vision、pixtral、got_ocr、phi4、qwen、nanonets_ocr2、gemma_12b、gemma_27b、dolphin、glm_ocr、lightonocr、falcon_ocr、chandra_ocr2、unlimited_ocr、dots_ocr、dots_mocr（见 docs/reference/cli.md）。若预设名写错，CLI 会打印可用列表并终止（main.py#L1461-L1476）。

硬件选择用 --device：auto（默认）/ cpu / cuda / mps / xpu，另有 --num-threads（默认 4）、--page-batch-size（默认 4）等吞吐参数（main.py#L1063-L1089）。

五、OCR 控制：扫描版 PDF 与图片

Standard 管道中 OCR 默认开启（--ocr 默认 true），相关开关（main.py#L847-L923）：

docling scan.pdf --ocr-engine easyocr --output /tmp/     # 默认引擎
docling scan.pdf --ocr-engine rapidocr --output /tmp/    # 轻量引擎
docling scan.pdf --ocr-engine tesserocr --output /tmp/   # 需要系统安装 Tesseract
docling scan.pdf --ocr-engine ocrmac --output /tmp/      # macOS Vision（仅 Mac）
docling scan.pdf --ocr-mode full_page --output /tmp/      # 对可提取文本也强制重 OCR
docling report.pdf --no-ocr --output /tmp/               # 跳过 OCR（更快）
docling scan.pdf --ocr-lang en,de --output /tmp/         # 限制识别语言

关键参数说明：

• --ocr-engine：取值 auto（默认）、easyocr、rapidocr、tesserocr、tesseract、ocrmac、kserve_v2_ocr、nemotron-ocr（内置取值清单见 docs/reference/cli.md；启用 --allow-external-plugins 后可见第三方插件引擎）；
• --ocr-mode：决定哪些区域送入 OCR，取值 default（默认）、layout_regions、pdf_aware_layout_regions、full_page。注意 --force-ocr 已弃用，等价于 --ocr-mode full_page，使用时会触发 DeprecationWarning（main.py#L853-L862 与 main.py#L1276-L1286）；
• --ocr-lang：源码注释写明是“逗号分隔的语言列表”，_split_list 同时接受 , 和 ; 分隔（export_utils.py#L87-L90），不同引擎的语言代码写法各不相同；
• --psm：Page Segmentation Mode（0-13），仅对 Tesseract 系选项生效（main.py#L917-L923）。

注意：各 OCR 引擎均为可选依赖（extra），按需安装对应 feat-ocr-* 扩展包，详见仓库内的 slim-packaging.md。

六、表格、增强（enrichment）与其他内容模型

docling report.pdf --no-tables --output /tmp/                                    # 跳过表格结构识别（更快）
docling report.pdf --table-mode accurate --output /tmp/                           # fast vs accurate
docling report.pdf --layout-engine docling_layout_default --output /tmp/          # 切换版面引擎
docling report.pdf --table-structure-engine docling_tableformer_v2 --output /tmp/ # 切换表格引擎
docling report.pdf --enrich-code --output /tmp/                                   # 代码理解
docling report.pdf --enrich-formula --output /tmp/                                # 公式理解
docling report.pdf --enrich-picture-classes --output /tmp/                        # 图片分类
docling report.pdf --enrich-picture-description --output /tmp/                    # 图片描述

• 表格：--tables 默认 true；--table-mode 取值 fast / accurate，默认 accurate（main.py#L870-L876、main.py#L938-L941）；--table-structure-engine 内置取值 docling_tableformer（默认）、docling_tableformer_v2、granite_vision_table；--layout-engine 内置取值 layout_object_detection（默认）、docling_layout_default、docling_experimental_table_crops_layout；
• 增强模型：上述四个 --enrich-* 开关（外加 --enrich-chart-extraction，从柱状/饼/折线图抽取数据）默认全部 false，在 Standard 管道中映射到 PdfPipelineOptions 的对应 do_* 字段（main.py#L1324-L1339）。

七、常见场景速查表

场景	处理方式
扫描版 / 纯图片 PDF	Standard + OCR，或 --pipeline vlm
密码保护 PDF	--pdf-password PASSWORD（密码错误抛 ConversionError）
超大文档（500+ 页）	Standard + --no-tables 提速；配合 --device / --num-threads
只需要文档的一部分	--page-range 1-4（或单页 --page-range 4）；页码从 1 开始，PDF、XLSX、PPTX 后端支持
复杂 / 多栏版式	--pipeline vlm（Standard 可能读错顺序）
手写或公式	仅 --pipeline vlm
输出几乎为空	开启 OCR，或改用 --pipeline vlm
出现 U+FFFD 替换字符	换 --ocr-engine，或改用 --pipeline vlm
同一行重复出现多次	--pipeline vlm（混合策略 force_backend_text 仅 Python SDK 可用）
显式指定 GPU/CPU	--device cuda / --device cpu / --device mps

其中 --page-range 的解析实现于 _parse_page_range（export_utils.py#L59-L84）：接受 START-END 或单页号，页码从 1 开始，非法值会报出明确的 BadParameter 信息。

八、远程 VLM 服务与 convert-remote

CLI 可以把页面路由到远程 VLM 服务：--pipeline vlm --enable-remote-services。但端点 URL、模型名与 API key 必须通过 Python SDK（ApiVlmOptions）配置，参见仓库内的 python-sdk.md。Docling 在默认状态下阻止出站 HTTP，只有设置 --enable-remote-services 才放行（main.py#L978-L983）。

注意区分：把整个转换任务卸载到 docling-serve 端点是另一条路 —— docling convert-remote（Service Client），见 service-client.md。

convert-remote 子命令仅在安装了 service-client extra 时注册（main.py#L1598-L1609），通过 --service-url / --api-key 或环境变量 DOCLING_SERVICE_URL / DOCLING_SERVICE_API_KEY 认证；结果格式与本地 convert 完全一致，但本地执行类参数（device、threads、pdf-backend 等）被有意省略。其特有参数包括 --max-concurrency（默认 8）、--timeout（默认 300 秒）、--watcher（websocket 默认 / polling），完整清单见 docs/reference/cli.md 中 convert-remote 一节。

九、离线模型：预下载 + --artifacts-path

面向 air-gapped 部署，先用 docling-tools models download 预取模型工件，再用 --artifacts-path 指向本地目录：

docling-tools models download --output-dir /models   # 获取模型工件
docling report.pdf --artifacts-path /models --output /tmp/

docling-tools models 的实现位于 models.py：

• 不指定模型名时下载默认集合：layout、tableformer、code_formula、picture_classifier、rapidocr（models.py#L73-L79）；
• 可按名下载单个模型（tableformerv2、smolvlm、granitedocling(_mlx)、smoldocling(_mlx)、granite_vision、granite_chart_extraction(_v4)、rapidocr、easyocr、nemotron_ocr_v2 等），或用 --all 全量下载（与具名参数互斥）；
• OCR 语言包可预取：--easyocr-lang（需配合 easyocr 模型）与 --rapidocr-backend-lang（形如 onnxruntime:el，需配合 rapidocr 模型，会替换默认检查点集）；
• -o/--output-dir 默认为缓存目录下的 models 子目录，-q/--quiet 只输出目录路径，便于脚本串联；
• 另有 docling-tools models download-hf-repo，按 HuggingFace repo id 下载任意仓库到本地（models.py#L216-L269）。

--artifacts-path 会覆盖默认的 Hugging Face 缓存位置，同时作用于转换管道与 ASR 选项（main.py#L1559-L1562）；也可以设置 HF_HOME 环境变量来迁移默认缓存。

十、源码级验证：CLI 行为如何被实现与测试

• 默认 Markdown 输出与空输出判定：to_formats 为 None 时回填 [OutputFormat.MARKDOWN]（main.py#L1270-L1271）；Markdown 导出若产生空文件，会被记录为 ErrorItem 并把结果标记为 FAILURE（main.py#L573-L587）——这就是“输出近乎为空时应开启 OCR 或换 VLM”这一排障建议的代码依据；
• 引擎工厂与插件：--ocr-engine / --layout-engine / --table-structure-engine 的取值通过 get_ocr_factory、get_layout_factory、get_table_structure_factory 动态生成枚举（main.py#L247-L261），--allow-external-plugins 打开第三方插件加载，--show-external-plugins 列出可用插件（main.py#L421-L445）；
• PDF 后端：--pdf-backend 默认 threaded_docling_parse，映射到 ThreadedDoclingParseDocumentBackend，其中 num_threads 会传入 parser_threads、--release-native-memory-every-n-pages（默认 128）控制原生内存释放节奏（main.py#L1138-L1156），这是处理超大 PDF 时的关键内存旋钮；
• 测试佐证：tests/test_cli.py 用 CliRunner 直接驱动 Typer 应用，例如 test_cli_convert 将 tests/data/pdf/sources/2305.03393v1-pg9.pdf 转换为 .md 并断言产物存在（tests/test_cli.py#L95-L103），test_cli_help 断言顶层帮助中可见 convert-remote 与 DOCLING_SERVICE_URL 提示（tests/test_cli.py#L71-L77），_parse_page_range、_should_generate_export_images 等工具函数亦有单测覆盖。

十一、转换后的快速核验清单

对保真度敏感的转换完成后，建议按以下清单自检输出：

• 页数与源文档大致一致（不一致时重跑 --pipeline vlm）；
• Markdown 不是近乎空的（是则开启 OCR 或改用 VLM）；
• 预期表格存在（去掉 --no-tables，或尝试 --pipeline vlm）；
• 没有成块的 U+FFFD 替换字符或无限重复的行（换 OCR 引擎或换管道）。

配合 --profiling / --save-profiling（输出/保存各阶段耗时统计，main.py#L1090-L1103），可以在定位“慢在哪一步”时获得阶段级数据，从而决定是否值得为个别文档付出 VLM 的额外成本。