Docling 基础使用实战：DocumentConverter 与 CLI 文档转换全流程

本文基于 Docling 官方文档 Usage 入门指南 展开，完整覆盖其两条核心使用路径：通过 Python API DocumentConverter 将任意受支持格式的文件（或 URL、内存流）转换为统一的 Docling Document 并导出 Markdown/JSON 等格式，以及通过终端 CLI 一行命令完成本地转换与 VLM 流水线转换。读完后你将掌握 Docling 的格式-后端-流水线映射机制、转换控制参数（页数/大小/页范围/错误策略）以及 CLI 的关键选项，能够独立完成从“拿到一份 PDF”到“产出可入 RAG 语料的 Markdown/JSON/Chunks”的完整链路。

两条核心使用路径

Docling 官方文档将使用方式归纳为两步：

1. 把源文件转换（convert）为一个 Docling Document；
2. 用这个 Docling Document 驱动你的后续工作流（导出、分块、序列化等）。

对应地，Docling 提供两种等价入口：

• Python API：核心类是 DocumentConverter，通过 convert() 拿到 ConversionResult，其 .document 属性即统一的文档模型；
• CLI：docling 命令（Typer 应用定义于 docling/cli/main.py），适合脚本化、批处理和快速验证场景。

Python API：DocumentConverter 最小示例

官方入门片段（与 docs/examples/minimal.py 完全一致）：

from docling.document_converter import DocumentConverter

source = "report.pdf"  # 文件路径或 URL，官方示例使用 arXiv 论文 PDF
converter = DocumentConverter()
doc = converter.convert(source).document

print(doc.export_to_markdown())  # 输出: "### Docling Technical Report[...]"

要点：

• DocumentConverter() 默认接受全部受支持的输入格式，格式到后端/流水线的映射在内部自动完成；
• convert() 的 source 可以是本地路径、Path、URL，或 DocumentStream（内存字节流，适合 Web 应用场景）；
• 返回的 ConversionResult 除 document 外还携带 status（成功/部分成功/失败/跳过）与 errors 列表，便于做批量作业的失败分类。

格式 → 后端 → 流水线的默认映射

document_converter.py 中的 _get_default_option() 定义了每种 InputFormat 的默认 FormatOption，从源码结构看，映射遵循清晰的分层：

输入类型	默认流水线	默认后端	源码依据
PDF	StandardPdfPipeline（布局检测 + OCR + 表格结构）	ThreadedDoclingParseDocumentBackend	PdfFormatOption
图片（PNG/JPEG/TIFF 等）	StandardPdfPipeline	ImageDocumentBackend	ImageFormatOption
DOCX/XLSX/PPTX、MD、HTML、LaTeX、EPUB、CSV 等结构化格式	SimplePipeline（无页面布局分析，直接解析结构）	各格式专用 Backend	WordFormatOption 等
音频（WAV/MP3 等）	AsrPipeline	NoOpBackend	AudioFormatOption
视频（MP4/AVI/MOV）	VideoPipeline	NoOpBackend	VideoFormatOption
已序列化的 Docling JSON	SimplePipeline	DoclingJSONBackend	映射表

这套默认映射是可参数化的：构造 DocumentConverter 时可通过 allowed_formats 限定接受哪些格式、通过 format_options 覆盖某个格式的后端与流水线选项。例如 docs/usage/advanced_options.md 展示了离线模型部署的写法：

from docling.datamodel.base_models import InputFormat
from docling.datamodel.pipeline_options import PdfPipelineOptions
from docling.document_converter import DocumentConverter, PdfFormatOption

artifacts_path = "/local/path/to/models"
pipeline_options = PdfPipelineOptions(artifacts_path=artifacts_path)
converter = DocumentConverter(
    format_options={
        InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)
    }
)

此外，DocumentConverter 内部以 (流水线类, 选项哈希) 为键缓存已初始化的流水线实例（见 初始化缓存，哈希由 create_pipeline_options_hash 生成），因此批量转换同一格式文档时不会重复加载模型。

批量转换与转换控制参数

convert() 实际上是 convert_all() 的单体封装（convert 实现），两者共享同一组控制参数，均来自 docstring 声明：

参数	默认值	说明
source	必填	路径/URL/DocumentStream/HttpSource 的列表（convert_all）或单个（convert）
headers	None	URL 拉取时的 HTTP 请求头字典
raises_on_error	True	True 时首个失败直接抛 ConversionError；False 时错误捕获进 ConversionResult 供逐文档处理
max_num_pages	不限	单文档接受的最大页数，超限文档不转换
max_file_size	不限	单文件大小上限（字节）
page_range	全部页	只转换指定页范围（PDF 等页面型文档）

批量示例（对应 convert_all 的官方 docstring）：

from pathlib import Path

converter = DocumentConverter()
paths = list(Path("docs/").glob("*.pdf"))
for result in converter.convert_all(paths, max_file_size=20 * 1024 * 1024):
    print(result.status, result.document.export_to_markdown()[:100])

当批量大小与并发度配置大于 1 时（settings.perf.doc_batch_size / doc_batch_concurrency），转换会走线程池并行处理（_convert 实现）。

convert_string：直接转换字符串内容

对于已有 Markdown/HTML/DocLang 字符串的场景，convert_string 支持 InputFormat.MD、InputFormat.HTML、InputFormat.XML_DOCLANG 三种格式，内部自动包装成 DocumentStream 并补齐扩展名：

from docling.datamodel.base_models import InputFormat

result = converter.convert_string(
    "<h1>Title</h1><p>Some text.</p>",
    format=InputFormat.HTML,
    name="my_page",
)
print(result.document.export_to_markdown())

CLI 使用

终端直接转换

安装后最简用法（与 docs/examples/minimal.py 的 CLI 等价物）：

docling report.pdf

这里有个值得注意的实现细节：docling 命令组通过 _DefaultCommandGroup 重写了参数解析——当第一个 token 不是已知子命令（convert、convert-remote）时，会自动在其前补上 convert，因此 docling report.pdf 等价于 docling convert report.pdf。source 参数支持本地文件、目录或 URL，多个源可重复传入。

完整选项可通过 docling --help 查看；仓库内 docs/reference/cli.md 是由 scripts/render_cli_reference.py 从活的 Typer 应用自动生成的 CLI 参考（文档明确注明“勿手改”），可作为选项的权威出处。

关键选项速查

以下选项摘自 convert 命令定义 与 CLI 参考，默认值均来自源码：

选项	取值/默认值	说明
--from	可重复，默认全部格式	限定接受的输入格式；odf 一次展开为 odt/ods/odp
--to	可重复，默认 md	输出格式：md、json、yaml、html、html_split_page、text、doctags、vtt、doclang、dclx、chunks
--pipeline	legacy / standard / vlm / asr，默认 standard	处理 PDF 或图片的流水线
--vlm-model	默认 granite_docling	VLM 预设（见下文列表）
--asr-model	默认 whisper_tiny	音频/视频的 Whisper 系列预设（含 MLX、native、S2T 变体）
--ocr / --no-ocr	默认开启	是否对位图内容跑 OCR
--ocr-mode	default / full_page / layout_regions / pdf_aware_layout_regions	送进 OCR 引擎的文档区域
--ocr-engine / --layout-engine / --table-structure-engine	默认 auto / layout_object_detection / docling_tableformer	三个阶段的模型引擎；启用 --allow-external-plugins 后可用第三方插件，--show-external-plugins 可列出
--pdf-backend	threaded_docling_parse（另有 pypdfium2、docling_parse 等）	PDF 解析后端
--pdf-password	无默认	受保护 PDF 的密码
--page-range	无默认	只转换页范围，如 1-4（PDF、XLSX、PPTX 后端支持）
--tables / --no-tables	默认开启	是否启用表格结构模型
--table-mode	accurate / fast	表格结构模型模式
--image-export-mode	placeholder / embedded / referenced，默认 embedded	图片在 JSON/YAML/HTML/Markdown 输出中的呈现方式（base64 内嵌 vs PNG 引用 vs 占位）
--html-image-fetch	none / local / remote / all，默认 none	HTML/EPUB 输入中图片资源的抓取策略
--output	.	结果输出目录
--artifacts-path	无默认	模型工件本地路径（离线部署）
--enable-remote-services	默认关闭	使用连接远程服务的模型前必须显式开启
--enrich-code / --enrich-formula / --enrich-picture-classes / --enrich-picture-description / --enrich-chart-extraction	默认全关	各增强模型开关
--device	auto	加速设备选择
--num-threads	4	线程数
--verbose / --quiet	-v/-vv / -q	日志级别；-q 适合被 AI Agent 或脚本调用时静默输出
--profiling / --save-profiling	默认关	阶段级耗时统计（表格打印/落 JSON）
--abort-on-error	默认关	首个错误即中止整批处理

用 VLM 流水线转换

官方入门文档给出的第二条命令演示了视觉语言模型路径：

docling --pipeline vlm --vlm-model granite_docling report.pdf

从 convert 命令定义 可见 --pipeline 与 --vlm-model 的作用域限定为“PDF 或图片文件”，默认 VLM 预设即 granite_docling（源码注释指出它支持含 MLX 在内的加速路径）。--vlm-model 的 help 文本会在运行时列出当前安装可用的全部预设，CLI 参考 中记录的预设列表为：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。

注意 CLI 的依赖前提：docling/cli/main.py 顶部对 typer/rich 做了导入保护，缺少时会提示 pip install docling（完整包，推荐）、pip install docling-slim[cli] 或 pip install typer rich 三种安装路径（依赖检查）。

导出与 RAG 分块

--to 各格式的落盘逻辑集中在 export_documents：

• json/yaml/html/md/text 分别调用 save_as_json、save_as_yaml、save_as_html、save_as_markdown 等方法；
• doctags 走 save_as_doctags，vtt 走 save_as_vtt，doclang 调 export_to_doclang()，dclx 调 save_as_doclang_archive，latex 使用 docling-core 的 LaTeXDocSerializer；
• --to chunks 时初始化分块器：--chunks-type hierarchical 用 HierarchicalChunker，默认 hybrid 则基于 HuggingFace tokenizer 构建 HybridChunker（--chunks-tokenizer 默认 sentence-transformers/all-MiniLM-L6-v2，--chunks-max-tokens 控制单块 token 上限），输出逐行 JSONL，每行携带 chunk_index、text、headings、page_numbers 等 RAG 元数据。

一个典型的“转 RAG 语料”命令：

docling report.pdf \
  --to md --to json \
  --to chunks --chunks-type hybrid --chunks-max-tokens 512 \
  --output ./out

Markdown 导出若产生空文件，CLI 会把该文档标记为失败并记录 ErrorItem（空输出检查），这是排查“转换成功但内容为空”类问题时的关键日志点。

支持的输入/输出格式速览

格式清单以 docs/usage/supported_formats.md 为准。输入格式覆盖：

• 办公与文档：PDF；DOCX/XLSX/PPTX；旧版 DOC/XLS/PPT（依赖 LibreOffice）；ODT/ODS/ODP；EPUB；Apple Pages（需 format-iwork 依赖）；
• 文本标记：Markdown、AsciiDoc、LaTeX、HTML/XHTML、CSV、WebVTT、BoxNote；
• 图像与媒体：PNG/JPEG/TIFF/BMP/WEBP；音频（WAV/MP3/M4A/AAC/OGG/FLAC，需 asr 扩展）；视频（MP4/AVI/MOV，音频轨将被提取转写，需 asr 扩展与 ffmpeg）；邮件（.eml/.msg）；
• Schema 专用：DocLang XML（.dclg/.dclg.xml）、DocLang 归档（.dclx）、USPTO XML、JATS XML、XBRL XML、EBCDIC（需通过 EbcdicBackendOptions 传入 COBOL 记录布局）、Docling JSON。

输出格式包括：HTML（支持图片内嵌与引用两种模式）、Markdown、JSON（Docling Document 无损序列化）、DocLang XML、纯文本、Doctags、WebVTT、DocLang 归档（.dclx）、Chunks（JSONL，RAG 分块）、LaTeX（.tex 独立文档，图片输出为占位符）。

从入门到进阶：下一步

官方文档的 “What's next” 指向 Usage 子页面与示例目录，结合仓库结构，建议的深入路径为：

• 转换定制与流水线功能开关：docs/usage/advanced_options.md（模型预取与离线使用、远程服务开关 enable_remote_services、图像分辨率/缩放、表格抽取控制），完整示例见 docs/examples/custom_convert.py；
• 格式能力边界：docs/usage/supported_formats.md；
• 增强功能（图片描述、代码/公式识别、图表数据提取）：docs/usage/enrichments.md 及 docs/examples/enrich_doclingdocument.py；
• RAG 集成与分块序列化：docs/examples/ 中的 hybrid_chunking.ipynb、rag_langchain.ipynb、rag_llamaindex.ipynb 等系列笔记本；
• 架构原理：docs/concepts/architecture.md 解释了“转换器 → 后端 → 流水线 → 选项”的组件关系，其中虚线框组件为可子类化的基类，是理解本文 FormatOption 机制的底图；
• GPU/RTX 加速：docs/usage/gpu.md 与 docs/usage/vision_models.md。

关键源码与验证路径

• docling/document_converter.py：DocumentConverter、各 *FormatOption 默认映射、convert/convert_all/convert_string 全量实现；
• docling/cli/main.py：Typer 应用、convert 命令全部选项、导出与分块落盘逻辑；
• docling/datamodel/pipeline_options.py：PdfPipelineOptions、VlmPipelineOptions、OCR/布局/表格各选项模型；
• 测试用例：tests/test_e2e_conversion.py、tests/test_cli.py、tests/test_backend_docling_parse.py 覆盖了端到端转换、CLI 行为与 PDF 解析后端的回归验证；
• 最小可运行示例：docs/examples/minimal.py、docs/examples/batch_convert.py。