Docling 快速上手：从安装到第一个文档转换，Python API 与 CLI 完整指南

本文基于 Docling 仓库 docs/getting_started/ 下的快速入门文档展开，覆盖安装配置（含 extras 与 OCR 引擎选型）、Python API 最小转换流程（DocumentConverter 的完整参数语义），以及 CLI 终端用法（含 VLM 管线与 GraniteDocling 预设）。读完后你可以直接在本地或服务器环境跑通 Docling 的文档转换，并知道如何深入定制管线。

一、安装与环境准备

Docling 是一个标准的 Python 包，通过包管理器安装即可。支持 macOS、Linux、Windows，覆盖 x86_64 与 arm64 两种架构。

# pip 安装
pip install docling

# 或使用 uv
uv add docling

Docling 的模型依赖 PyTorch。如果你的目标硬件/加速器与默认 wheel 不匹配（例如纯 CPU 服务器），需要指定对应的 torch 分发。

Linux 纯 CPU 环境的推荐安装方式（见 安装文档）：

# 安装 Linux cpu-only 版本的示例
pip install docling --extra-index-url https://download.pytorch.org/whl/cpu

若使用 uv，在 pyproject.toml 中添加 PyTorch CPU 索引并固定 torch 来源：

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[tool.uv.sources]
torch = [{ index = "pytorch-cpu" }]

然后执行 uv add docling。

macOS Intel（x86_64）注意：较新的 PyTorch（2.6.0+）不再提供 Intel Mac 的 wheel，需要固定兼容版本（PyTorch 2.2.2 要求 Python ≤ 3.12）：

# For uv users
uv add torch==2.2.2 torchvision==0.17.2 docling

# For pip users
pip install "docling[mac_intel]"

# For Poetry users
poetry add docling

可用的 extras

docling 主包自带默认选项所需的全部依赖；部分功能依赖额外的第三方库，需以 extras 形式显式安装（pip install "docling[NAME1,NAME2]"）：

Extra	说明
asr	安装 ASR（语音转写）管线依赖
vlm	安装 VLM（视觉语言模型）管线依赖
easyocr	安装 EasyOCR OCR 引擎
feat-ocr-nemotron	安装 NVIDIA Nemotron OCR，仅支持 Linux x86_64 + Python 3.12 + CUDA 13.x
tesserocr	安装 Tesseract 绑定，用于将 Tesseract 作为 OCR 引擎
ocrmac	安装 OcrMac OCR 引擎（macOS 系统 OCR）
htmlrender	安装 HTML 后端页面渲染依赖
rapidocr	安装 RapidOCR OCR 引擎（onnxruntime 后端）

开发环境

若要参与 Docling 开发（新功能、缺陷修复等），在本地克隆仓库的根目录执行：

uv sync --all-extras --no-extra feat-ocr-nemotron

feat-ocr-nemotron 被刻意排除在默认开发依赖之外，因为它仅能在 Linux x86_64 + Python 3.12 + CUDA 13.x 上使用。

二、Python 基本用法

在 Docling 中处理文档遵循两个步骤：

1. 将源文件转换为 Docling Document（统一的文档模型）；
2. 用该文档执行你的工作流（导出、切块、RAG、富化等）。

最小示例（与 docs/examples/minimal.py 一致）：

from docling.document_converter import DocumentConverter

source = "https://arxiv.org/pdf/2408.09869"  # 本地文件路径或 URL
converter = DocumentConverter()
doc = converter.convert(source).document

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

DocumentConverter 会自动探测受支持的输入格式（PDF、DOCX、HTML、PPTX、图片等），无需手工指定格式。完整的输入/输出格式清单见 支持格式文档：输入侧涵盖 PDF、Office 全家桶（含 97–2004 旧二进制格式）、ODF、EPUB、Pages、Markdown、AsciiDoc、LaTeX、HTML、CSV、常见图片格式、音频/视频（需 asr extra）、WebVTT、BoxNote、Email 以及 DocLang/USPTO/JATS/XBRL/EBCDIC 等 XML 专用格式；输出侧涵盖 Markdown、HTML、JSON、DocLang XML、纯文本、Doctags、WebVTT、Chunks (JSONL)、LaTeX 等。

convert() 方法参数详解

上面的最小示例只用了默认参数。从 DocumentConverter.convert 的源码定义 看，该方法完整签名为：

def convert(
    self,
    source: Union[Path, str, DocumentStream, HttpSource],
    headers: Optional[dict[str, str]] = None,
    raises_on_error: bool = True,
    max_num_pages: int = sys.maxsize,
    max_file_size: int = sys.maxsize,
    page_range: PageRange = DEFAULT_PAGE_RANGE,
) -> ConversionResult:

各参数含义（依据源码 docstring）：

• source：输入来源，可以是文件路径（Path 或字符串）、URL、内存流 DocumentStream，或自带请求头的 HttpSource。注意：若输入本身是字符串内容（Markdown/HTML 文本），应使用 convert_string 方法而非 convert；
• headers：URL 输入时的 HTTP 请求头字典；对 HttpSource 输入会被忽略（其自带头按 key 覆盖批量头）；
• raises_on_error：首个转换失败时是否抛异常。设为 False 时，错误会被记录到 ConversionResult 对象中，适合批量容错场景；
• max_num_pages / max_file_size：单文档页数与文件大小上限，超过则拒绝转换，默认不限制；
• page_range：仅转换指定页码范围，默认全页。

返回值为 ConversionResult，其中 document 属性即统一的 DoclingDocument 模型。除 export_to_markdown() 外，该模型还支持导出 JSON、HTML、DocLang 等格式，详见 Docling Document 概念文档 与 架构文档。

三、CLI 终端用法

安装后 docling 命令可直接在终端转换文档，支持本地路径、目录和 URL：

docling https://arxiv.org/pdf/2206.01062

默认输出格式为 Markdown（CLI 源码中 --to 选项的帮助文本说明“Defaults to Markdown”）。

使用 VLM 管线与 GraniteDocling

CLI 提供 --pipeline 选项选择 PDF/图片的处理管线。配合视觉语言模型（VLM）预设（如 GraniteDocling，支持 MLX 加速）可以做更精细的文档理解：

docling --pipeline vlm --vlm-model granite_docling https://arxiv.org/pdf/2206.01062

从 CLI 入口实现 可以确认以下行为事实：

• --pipeline 的可选值来自 ProcessingPipeline 枚举（STANDARD、VLM、ASR、LEGACY），默认 STANDARD；
• --vlm-model 默认值即 granite_docling，帮助文本会动态列出当前全部可用预设；
• --vlm-max-new-tokens 可覆盖 VLM 生成的最大 token 数。

常用 CLI 选项速查

以下选项均来自 docling/cli/main.py 中 convert 命令的实际定义：

选项	默认值	说明
source（位置参数）	—	待转换的本地文件/目录路径或 URL，可传多个
--from	全部支持格式	限定接受的输入格式（odf 覆盖 odt/ods/odp）
--to	Markdown	输出格式，可组合（如 Markdown、JSON、HTML、chunks 等）
--pipeline	standard	PDF/图片处理管线（standard / vlm / asr 等）
--vlm-model	granite_docling	VLM 预设，配合 --pipeline vlm 使用
--ocr	True	是否对位图内容启用 OCR
--ocr-mode	default	哪些文档区域送 OCR 引擎（--force-ocr 已废弃，改用 --ocr-mode full_page）
--show-layout	False	在页面图片上绘制检测到的元素边界框，便于调试
--headers	无	URL 输入的 HTTP 请求头（JSON 字符串）
--image-export-mode	embedded	图片导出模式：placeholder / embedded（base64 内嵌）/ referenced（独立 PNG 引用）
--chunks-type / --chunks-max-tokens / --chunks-tokenizer	hybrid / tokenizer 上限 / all-MiniLM-L6-v2	配合 --to chunks 输出 RAG 切块（JSONL）
--asr-model	whisper_tiny	音频/视频转写使用的 ASR 模型

完整选项请运行 docling --help 或查阅 CLI 参考文档。

一个实现细节值得注意：CLI 依赖 typer 和 rich，若你安装的是精简包而缺少这两个依赖，程序会直接给出三种补救方案（安装完整 docling、docling-slim[cli]，或单独 pip install typer rich），见 CLI 入口的依赖检查逻辑。

四、按需选择 OCR 引擎

Docling 支持多种 OCR 引擎处理扫描件，可通过 DocumentConverter 的 ocr_options 设置切换（见 安装文档）：

引擎	安装方式	用法（options 类）
EasyOCR	easyocr extra 或 pip install easyocr	EasyOcrOptions
Nemotron OCR	feat-ocr-nemotron extra（仅 Linux x86_64 + Python 3.12 + CUDA 13.x）	NemotronOcrOptions
Tesseract	系统依赖（见下文安装说明）	TesseractOcrOptions
Tesseract CLI	系统依赖	TesseractCliOcrOptions
OcrMac	系统依赖	OcrMacOptions
RapidOCR	rapidocr extra 或 pip install rapidocr onnxruntime	RapidOcrOptions
OnnxTR	插件系统：pip install "docling-ocr-onnxtr[cpu]"	OnnxtrOcrOptions

切换引擎的典型写法：

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

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = TesseractOcrOptions()  # 使用 Tesseract

doc_converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)

Tesseract 的系统安装

Tesseract 需要通过系统包管理器安装，并要求用 TESSDATA_PREFIX 环境变量指定语言数据目录（必须以斜杠 / 结尾）：

# macOS (Homebrew)
brew install tesseract leptonica pkg-config
export TESSDATA_PREFIX=/opt/homebrew/share/tessdata/

# Debian 系
apt-get install tesseract-ocr tesseract-ocr-eng libtesseract-dev libleptonica-dev pkg-config
export TESSDATA_PREFIX=$(dpkg -L tesseract-ocr-eng | grep tessdata$)

# RHEL
dnf install tesseract tesseract-devel tesseract-langpack-eng tesseract-osd leptonica-devel
export TESSDATA_PREFIX=/usr/share/tesseract/tessdata/

Docling 通过 Tesserocr 包以链接方式调用 Tesseract（效率最高）。若 Tesserocr 安装失败，建议先卸载再以纯源码方式重装：

pip uninstall tesserocr
pip install --no-binary :all: tesserocr

Nemotron OCR 的安装前提

Nemotron OCR 需要 CUDA 13 的 PyTorch wheel，需搭配 unsafe-best-match 索引策略让 pip 正确解析 CUDA 版 torch：

pip install "docling[feat-ocr-nemotron]" \
  --extra-index-url https://download.pytorch.org/whl/cu130 \
  --index-strategy unsafe-best-match

当前仅支持 Linux x86_64 + Python 3.12 + CUDA 13.x。

五、下一步

快速入门跑通后，建议按以下路径继续深入（均位于当前仓库内）：

• 使用文档目录：转换定制、置信度、GPU 加速、富化（enrichments）等进阶主题；
• 特色示例目录：包括 批量转换示例、自定义转换、RAG 集成（LangChain / LlamaIndex / Haystack 等）、chunking 与序列化、图片描述、PII 脱敏等完整工作流；
• 架构文档 与 Docling Document 概念：理解统一文档模型与后端/管线的设计。