Docling OCR 引擎

数字（文本）PDF 常无需 OCR——先试 --no-ocr 求最快，仅扫描页再加引擎。

OCR 默认开启（--ocr）。三个参数决定作用范围与执行引擎。Python 等价：PdfPipelineOptions().do_ocr = True 加 RapidOcrOptions / EasyOcrOptions / TesseractOcrOptions / TesseractCliOcrOptions / OcrMacOptions / NemotronOcrOptions 之一，整页行为配 mode=OcrMode.FULL_PAGE。以 --debug-visualize-ocr 查看 OCR 视野。

Tesseract 可执行文件分系统。分系统完整步骤见安装总览与系统指南。离线或 CI 机器预下载 OCR 模型：docling-tools models download --all，或定向 --easyocr-lang de / --rapidocr-backend-lang onnxruntime:el。见CLI 说明。

Windows：安装 UB Mannheim 构建并加入 PATH，将 TESSDATA_PREFIX 指向其 tessdata\ 目录。tesserocr 构建失败：pip uninstall tesserocr 后 pip install --no-binary :all: tesserocr。

RapidOCR 封装 PP-OCR 模型。后端（运行时）与 PP-OCR 版本（模型代际）各自独立变化。

语言词符（原生代码）：v4：arabic, ch, chinese_cht, cyrillic, devanagari, en, japan, ka, korean, latin, ta, te。v5：arabic, ch, cyrillic, devanagari, el, en, eslav, korean, latin, ta, te, th。v6：ch, chinese_cht, en, japan + 约 45 个欧洲代码（de, fr, es, it, pt, nl, pl …），别名 zh→ch, zh_cn→ch, zh_tw→chinese_cht, ja/jp→japan, ko→korean（注意：v6 韩语仅别名）。de/german 与 fr/french 各有两种写法。

文字语系（一符多语）：cyrillic（34 种：俄、乌、哈萨克…+英语）、devanagari（14 种：印地、马拉地、梵…+英语）、arabic（9 种：阿、波斯、乌尔都…+英语）、eslav（东斯拉夫：俄、白俄、乌 + 英语）。

每次运行一种语言：RapidOCR 取 lang 首项，其余警告。Python：RapidOcrOptions(lang=["eslav"], backend="onnxruntime")；支持自备 checkpoint（见自备模型示例）。

EasyOCR（Gen2 checkpoint、craft_mlt_25k.pth 检测器）可一次多种语言，但解析只选覆盖全部所请语言的单一 checkpoint。多余语言会悄悄降级：["en"] 选中精准的 english_g2.pth，而 ["en","de"] 回落到宽泛的 latin_g2.pth。

• 两味一引擎：tesseract 调系统 CLI（无需 pip extra）；tesserocr 进程内绑定（更快，需编译好的绑定）。精度相同，traineddata 相同。
• 语言即 traineddata 词干：deu, chi_sim, chi_tra, srp_latn, aze_cyrl, deu_latf, frk, jpn_vert, script/Latin, script/Cyrillic，另可加自训练文件。已安装的 .traineddata 即用。
• 构造时校验：缺文件立即失败，并在报错中列出已安装集合，而非转到一半才崩。
• 空 lang 即文字检测：--ocr-lang "" 触发按页方向/文字检测，需 osd traineddata。
• 自动语言检测见官方示例。

OcrMac 是 Apple Vision 的薄封装：无可执行文件、无可下载模型，识别器随系统自带，故语言覆盖是自身 macOS 版本的属性，而非 ocrmac 发版的属性。

• 安装：pip install "docling[ocrmac]"；Python：OcrMacOptions。
• 按带区域的 BCP-47 匹配：iso:de 命中 de-DE，iso:pt 命中 pt-BR，iso:zh-CN 命中 zh-Hans。
• 古怪区域码如 vi-VT 须裸传（原生）。空 lang 由 Vision 自动。

要求 Linux x86_64 + CUDA 13.x 及 cu130 版 torch 索引（安装行见第 4 节）。每次运行一种语言（首项胜出）。Python：NemotronOcrOptions。

• KServe v2：OCR 跑在远端微服务时使用。lang 不校验不映射，首项逐字发出、其余警告丢弃。请用自有部署的代码；iso: 仅对方支持时有效（皆不支持）。
• OnnxTR 插件：pip install "docling-ocr-onnxtr[cpu]" 并启用 --allow-external-plugins，以插件引擎名选用。见 docling-OCR-OnnxTR 仓库。
• 自备模型的 SuryaOCR见官方示例；第三方选项以 --show-external-plugins 列出。

各引擎经统一字段 OcrOptions.lang 接收语言。每项恰有两种写法：

原生代码（无前缀）——引擎自有拼写，逐字透传：ch（PP-OCR 中文）、deu（Tesseract 德语）、ch_sim（EasyOCR）、en-US（Vision）。

可移植标签——iso: 后的 BCP-47，映射到引擎：iso:de、iso:en-US、iso:zh-Hant。非默认文字务必写明：塞尔维亚拉丁文必须是 iso:sr-Latn（默认塞尔维亚文为西里尔）。

各引擎自报能力：supported_ocr_languages() 返回原生 + BCP-47 代码，拼写可直接贴回 lang。Docling 从不悄悄替换，不可服务的语言会抛错并列出该引擎可服务的写法。RapidOCR 与 Nemotron 一次一种语言（首标签胜出，其余警告）。

from docling.datamodel.pipeline_options import TesseractCliOcrOptions
TesseractCliOcrOptions(lang=["deu", "eng"])       # 原生：tesseract -l deu+eng
TesseractCliOcrOptions(lang=["iso:de", "iso:en"]) # 可移植：同义

空语言列表在各引擎的含义，以及遮蔽某标签的代码（裸写 = 模型，iso: = 语言）：

• CUDA 上的 RapidOCR：安装 GPU 版 ONNX Runtime（pip install "docling[onnxruntime]"），确认 CUDAExecutionProvider 在 ort.get_available_providers() 中，再以 onnxruntime 后端 + CUDA 设备运行。torch 后端为备选（注意：PP-OCRv5 + torch 仅中文）。
• Nemotron 按设计仅 GPU（CUDA 13.x、Linux x86_64）。
• EasyOCR / Tesseract / OcrMac 实际跑 CPU——配快 CPU，把 GPU 预算留给版式/表格阶段。精调（批量、VLM 服务）见官方 GPU 指南。

import onnxruntime as ort
assert "CUDAExecutionProvider" in ort.get_available_providers()

from docling.datamodel.accelerator_options import AcceleratorDevice, AcceleratorOptions
from docling.datamodel.pipeline_options import PdfPipelineOptions, RapidOcrOptions
pipeline_options = PdfPipelineOptions(
    accelerator_options=AcceleratorOptions(device=AcceleratorDevice.CUDA),
    ocr_options=RapidOcrOptions(backend="onnxruntime", lang=["eslav"]),
)

扫描 PDF 整页 OCR。显式选引擎。数字 PDF 跳过 OCR（最快）。德英可移植标签：

更多完整示例：强制整页 OCR、Tesseract 语言检测、RapidOCR 自备模型、本地示例库与配置生成器。

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

pipeline_options = PdfPipelineOptions()
pipeline_options.do_ocr = True
pipeline_options.ocr_options = RapidOcrOptions(mode=OcrMode.FULL_PAGE)
# 按需换 EasyOcrOptions / TesseractOcrOptions / TesseractCliOcrOptions
# / OcrMacOptions（macOS）/ NemotronOcrOptions（Linux CUDA）。

converter = DocumentConverter(
    format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)}
)
doc = converter.convert("scan.pdf").document
print(doc.export_to_markdown())

• 扫描文本未识别——OCR 关闭或默认模式漏掉缺失文本层：强制 --ocr-mode full_page，换引擎一试。见扫描版 PDF 文本未识别。
• OCR extra 装不上——RapidOCR/EasyOCR 纯 pip；Tesseract 须先备系统可执行文件 + TESSDATA_PREFIX。见OCR 包安装报错。
• 转换慢——OCR 与富化模型是最贵的 CPU 阶段：数字 PDF 用 --no-ocr，--table-mode fast 或上 GPU。见转换慢。
• GPU 被忽略——确认 torch.cuda.is_available() / CUDAExecutionProvider，用 --device cuda（Apple Silicon 用 mps）。见GPU 未使用。
• 输出语言错误——查影子（ka 与 iso:ka-Geor），EasyOCR 列表从简，以 supported_ocr_languages() 验证。

已按 Docling v2.129.0 验证 · 最近检查 2026-09-22 · 官方来源