企业官网建设流程全解析

Docling 怎么安装 Nemotron OCR 引擎（feat-ocr-nemotron 与 CUDA 13 配置）？

【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling

Docling 支持多个可插拔的 OCR 引擎，其中 NVIDIA Nemotron OCR 只走一条安装路径：feat-ocr-nemotronextra。它和普通的pip install docling不同，必须额外指定 CUDA 13 的 PyTorch wheel 索引，否则 pip 会解析到非 CUDA 的 torch 包，引擎无法运行。本文给出在满足条件的机器上安装 Nemotron OCR、验证运行时环境、并把它接入 PDF 转换的最小路径。

安装前提：先确认环境是否满足

安装文档 和引擎实现都明确限定了 Nemotron OCR 的适用范围，三项缺一不可：

• Linux x86_64；
• Python 3.12；
• CUDA 13.x（Docling 运行时强制要求 13.x，见 OCR 引擎说明：Nemotron works only on Linux and requires CUDA (Docling enforces 13.x)）。

这个限制同样写进了依赖声明里。pyproject.toml 中feat-ocr-nemotronextra 的实际依赖带有环境标记：

feat-ocr-nemotron = [ 'nemotron-ocr>=2.0.0 ; python_version == "3.12" and sys_platform == "linux" and platform_machine == "x86_64"', ]

也就是说在 macOS、ARM 架构或 Python 3.11/3.13 的机器上安装该 extra 时，nemotron-ocr包本身不会被装上，后续运行时校验会直接失败。如果环境不满足，应改用文档中列出的其他 OCR 引擎（EasyOCR、Tesseract、RapidOCR 等）。

安装命令：feat-ocr-nemotron 加 CUDA 13 索引

安装文档 给出的完整安装命令是：

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

三个部分各自的作用，文档均有说明：

• docling[feat-ocr-nemotron]：安装 NVIDIA Nemotron OCR 的可选依赖；
• --extra-index-url https://download.pytorch.org/whl/cu130：Nemotron OCR requires the CUDA 13 PyTorch wheels，即从 PyTorch 官方的 CUDA 13 wheel 索引拉取torch；
• --index-strategy unsafe-best-match：让pip在多个索引间按最佳匹配解析，正确选中 CUDA-enabled 的torch包。

命令中的cu130索引地址与unsafe-best-match参数必须原样保留，它们是安装文档中针对 CUDA 13 配置明确给出的内容，删掉任一参数都可能导致解析到 CPU 版 torch，使 CUDA 13.x 运行时校验不通过。

验证安装与运行时

Docling 对 Nemotron OCR 的运行时校验集中在NemotronOcrModel.validate_runtime（见 引擎实现）。它按顺序检查平台、架构、Python 版本、加速器与 CUDA 版本，任一不满足都会抛出带明确原因的RuntimeError。仓库的端到端测试 tests/test_e2e_nemotron_ocr_conversion.py 中复用了同一个校验入口，可以照抄这段代码做安装后的自检：

from docling.datamodel.accelerator_options import ( AcceleratorDevice, AcceleratorOptions, ) from docling.models.stages.ocr.nemotron_ocr_model import NemotronOcrModel # 1. 可选依赖是否装上 import nemotron_ocr.inference.pipeline_v2 # 未安装会抛 ImportError # 2. 运行时环境是否满足（Linux x86_64 / Python 3.12 / CUDA 13.x） NemotronOcrModel.validate_runtime( AcceleratorOptions(device=AcceleratorDevice.AUTO) )

validate_runtime的实际判断逻辑（与 引擎实现 一致）：

• sys.platform != "linux"→Nemotron OCR is only supported on Linux.
• platform.machine() != "x86_64"→Nemotron OCR is only supported on x86_64 machines.
• Python 不是 3.12 →Nemotron OCR requires Python 3.12.
• 加速器不是 CUDA →Nemotron OCR requires a CUDA accelerator. Set "pipeline_options.accelerator_options.device" to CUDA or AUTO on a CUDA-enabled machine.
• torch.cuda.is_available()为 false →Nemotron OCR requires CUDA at initialization time, but "torch.cuda.is_available()" is false.
• torch.version.cuda不是 13.x 开头 →Nemotron OCR requires CUDA 13.x, but the current PyTorch runtime reports CUDA ...

如果第 1 步导入时报ImportError，引擎初始化时也会给出同一条安装提示：Install the optional dependency via 'pip install "docling[feat-ocr-nemotron]"' on Linux x86_64 with Python 3.12 and CUDA 13.x.按上面「安装命令」一节重新执行即可。

两段检查都通过（无异常抛出）即说明环境符合 Nemotron OCR 的运行条件。

首次使用：把 Nemotron OCR 接入 PDF 转换

安装完成后，通过ocr_options选择引擎。示例脚本 中展示了各引擎的切换方式，Nemotron 对应：

from docling.datamodel.base_models import InputFormat from docling.datamodel.pipeline_options import ( NemotronOcrOptions, OcrMode, PdfPipelineOptions, ) from docling.document_converter import DocumentConverter, PdfFormatOption pipeline_options = PdfPipelineOptions() pipeline_options.do_ocr = True pipeline_options.ocr_options = NemotronOcrOptions(mode=OcrMode.FULL_PAGE) doc_converter = DocumentConverter( format_options={InputFormat.PDF: PdfFormatOption(pipeline_options=pipeline_options)} )

Nemotron OCR 必须有 CUDA 加速器，端到端测试 中额外显式设置了设备，可以一并加上：

from docling.datamodel.accelerator_options import AcceleratorDevice pipeline_options.accelerator_options.device = AcceleratorDevice.CUDA

然后对任意 PDF 执行doc_converter.convert(<你的 PDF 路径>)得到ConversionResult。NemotronOcrOptions还支持batch_size参数（测试中使用了NemotronOcrOptions(batch_size=3)），用于控制一次送入 OCR 的页面/区域批量。

不走 Python API 的话，CLI 也支持该引擎：CLI 参考 中--ocr-engine的可选值包含nemotron-ocr，语言仍通过--ocr-lang传入。

模型文件：可预先下载

Nemotron OCR 的模型（nvidia/nemotron-ocr-v2）不需要手动放置权重。如需提前下载，CLI 提供了对应条目，docling-tools models download的模型列表中包括nemotron_ocr_v2（见 CLI 参考）：

docling-tools models download nemotron_ocr_v2

默认下载到$HOME/.cache/docling/models，可用-o/--output-dir改目录。此外NemotronOcrOptions的说明中提到，可以通过 pipeline 级artifacts_path指向预先下载好的 checkpoint。

语言支持与限制

OCR 语言文档 和 Nemotron 专节 给出的语言规则：

• 引擎原生代码只有两个：english（别名en）和multilingual（别名multi）；lang留空时默认走英语模型；
• multilingual覆盖英语、简体中文、繁体中文、日语、韩语、俄语；iso:zh、iso:zh-Hant、iso:ja、iso:ko、iso:ru都会映射到多语言模型；
• 一次转换只运行一个语言：lang中有多个条目时取第一个并警告其余条目；
• 无法覆盖的语言直接抛OcrLanguageNotSupportedError，不会静默回退到其他模型。

其他值得留意的边界：

• 开发环境默认排除该 extra：安装文档 的 development setup 使用uv sync --all-extras --no-extra feat-ocr-nemotron，原因是该 extra 只在 Linux x86_64 + Python 3.12 + CUDA 13.x 下可用，避免在无 CUDA 的开发机上引入装不上的依赖；
• 语言映射的完整行为可参考 测试文件 中的test_nemotron_language_mapping：en/eng/EN/en-US等均归一到english，zh-CN/zh-Hant/ja/ko/ru归一到multilingual。

环境满足且校验通过后，安装即完成：后续所有 PDF 转换只要把ocr_options设为NemotronOcrOptions（或 CLI 传--ocr-engine nemotron-ocr），OCR 阶段就会走 Nemotron 引擎，无需再额外配置。

【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling