Docling 中的 OCR——选对引擎、选对语言，或者干脆不用

你真的需要 OCR 吗？#

打开 PDF，试着选中一句话。如果能选中，说明 PDF 有文本层，Docling 会直接读取——字符精确，不需要 OCR。此时 OCR 只会额外识别图片里的文字，而且代价很高：

多出的约 5,000 个字符来自论文插图中的截图。如果这些文字重要就保留 OCR，否则就关掉。

选择引擎#

各个引擎#

引擎列表和默认语言读取自 2.148.0 中 docling options ocr <engine> 的输出。引擎软件包的许可证：RapidOCR、EasyOCR 和 Nemotron OCR 为 Apache-2.0；tesserocr 和 ocrmac 为 MIT；Tesseract 本身为 Apache-2.0。

auto 如何选择

1. macOS：如已安装，使用 ocrmac。
2. 带 CUDA 的 Linux：如已安装，使用 Nemotron OCR。
3. onnxruntime 后端的 RapidOCR，如已安装 onnxruntime。
4. EasyOCR，如已安装。
5. PyTorch 后端的 RapidOCR——普通 pip install docling 最终使用的就是它。

无法支持所请求语言的引擎会被跳过。Tesseract 永远不会被自动选中——请用 --ocr-engine tesseract 指定。顺序读取自 2.148.0 的 auto_ocr_model.py；我们在 Linux 上的测试运行确认了最后一步。

语言#

--ocr-lang 接受引擎自己的代码，或带 iso: 前缀的 BCP-47 标签（Docling 会为所选引擎自动转换）。传空值（--ocr-lang ''）则由引擎自行决定。

• RapidOCR 每次只用一种语言，多余的语言会被忽略并给出警告。其 PyTorch 后端对很多语言只有按文字体系划分的模型——在默认安装下，我们用 iso:ru 时遇到 OcrLanguageNotSupportedError，改用 cyrillic 才行。 * eslav 同样被拒绝；en、latin、ch、chinese_cht、japan 和 cyrillic 在我们的测试中都能在 PyTorch 后端上运行。
• Tesseract 可以组合多种语言（按给出的顺序，如 chi_sim,eng），并需要安装对应的 traineddata；缺少时会在引擎启动时报错。
• EasyOCR 在语言属于同一文字体系时可以同时识别多种语言。

OCR 模式#

定义取自 2.148.0 中的 OcrMode 枚举。

替换损坏的文本层（2.144.0 新增）#

有些 PDF 在屏幕上看起来完全正常，但复制出来的文字毫无意义——8VceZWZTReV 而不是 Certificate——因为字体把字形映射到了错误的字符。OCR 模式对此帮不上忙：默认模式信任 PDF 文本，而 full_page 会丢弃每一页的文本层。--replace-broken-text-layer 介于两者之间：Docling 逐页检查文本层，只对损坏的页面做整页 OCR。

docling convert contract.pdf --replace-broken-text-layer
docling convert contract.pdf --replace-broken-text-layer --ocr-engine rapidocr --ocr-option backend=torch --ocr-lang ch

• 默认关闭，适用于所有引擎。在 Python 中是任意 OCR 选项类上的 replace_broken_text_layer=True，例如 RapidOcrOptions(replace_broken_text_layer=True)；命令行也可以写成 --ocr-option replace_broken_text_layer=true。
• 怎样算损坏：页面上或多行中出现控制字符、� 或私用区字符（适用于所有文字）；对拉丁字母文本，还会识别代替其他文字的带重音字母（俄文显示成 Îò÷¸ò）以及元音过少的单词。一页中只有一个坏单元格不会触发替换。
• 检测不到的情况：字母表正确但字母错误或顺序错乱（Cartifecita）。这类文件请用 --ocr-mode full_page。
• 被替换的页面在置信度报告中保留较低的 parse_score，因为该分数描述的是 PDF 文本层。请选择能识别文档语言的引擎和 --ocr-lang。

值得了解的引擎设置#

用 docling options ocr ENGINE 列出某个引擎的所有键，再用 --ocr-option KEY=VALUE（可重复）传入。

docling convert scan.pdf --ocr-engine rapidocr --ocr-option backend=torch --ocr-lang ch --ocr-option scale=2
docling convert scan.pdf --ocr-engine tesseract --ocr-lang chi_sim,eng --ocr-option psm=6
docling convert scan.pdf --ocr-engine easyocr --ocr-lang iso:zh-Hans --ocr-option confidence_threshold=0.3
docling convert sideways.pdf --ocr-engine rapidocr --ocr-option backend=torch --ocr-option detect_orientation=true

Python#

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

opts = PdfPipelineOptions()
opts.do_ocr = True
opts.ocr_options = RapidOcrOptions(lang=["ch"], backend="torch", mode=OcrMode.FULL_PAGE)

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

选项类：OcrAutoOptions、RapidOcrOptions、EasyOcrOptions、TesseractCliOcrOptions（引擎 tesseract）、TesseractOcrOptions（tesserocr）、OcrMacOptions、NemotronOcrOptions、KserveV2OcrOptions。

扫描件上的引擎对比#

同一份扫描文档（Docling 论文前四页，以 150 DPI 栅格化并加入轻微模糊和倾斜），同一条标准流水线，只更换 OCR 引擎。每个引擎在无 GPU 的 4 vCPU 机器上预热一次、计时三次，使用 Docling 2.148.0，测于 2026 年 11 月 6 日。

• 在这里 Tesseract 既最快又最准（每页 5.5 秒，还原 96.1% 的词语）——对清晰的英文排版页面很难被超越。它需要系统程序和语言包。
• onnxruntime 后端的 RapidOCR 比默认的 PyTorch 后端快约一倍（每页 7.0 秒对 15.4 秒），输出完全相同。安装 docling[rapidocr] 是纯 Python 环境下最省事的提速方式——装好 onnxruntime 后 auto 会自动选用它。
• EasyOCR 在 CPU 上最慢（每页 29 秒）。在 Docling 默认置信度阈值（0.5）下保留了 85.1% 的词语；降到 0.1（--ocr-option confidence_threshold=0.1）后提高到 94.4%。它的结果也很依赖图像：在 10 月 27 日那次测试所用的扫描件上，同样的默认阈值只保留了 12.3%。

常见问题

资料来源

• Docling 源码：OCR 引擎（docling/models/stages/ocr）
• 取自 Docling 2.148.0：docling options ocr <engine> 的输出
• PyPI 上的 RapidOCR
• PyPI 上的 EasyOCR
• Tesseract OCR