NVIDIA Model Optimizer Linux 安装指南：系统要求、环境搭建与依赖配置全解析

本篇指南完整讲解 NVIDIA Model Optimizer（nvidia-modelopt）在 Linux 系统上的安装流程，覆盖系统要求、Docker 与本地（PIP/Conda）两种环境搭建路径、可选依赖模块的正确选取，以及安装后的核验方法。读者将能根据自身部署目标（TensorRT-LLM / ONNX / Hugging Face）准确选择安装方式与 optional dependencies，并完成首次 CUDA 扩展编译与预编译验证。

一、系统要求：先确认硬件与软件基线

根据官方安装文档，最新版nvidia-modelopt在 Linux 上的系统要求如下：

几点说明：

• Python 版本约束与项目元数据一致：pyproject.toml中声明requires-python = ">=3.10,<3.15"，与上表完全对应；这意味着 Python 3.10～3.14 均可用，3.15 及以上暂不支持。
• PyTorch 是硬性依赖：核心依赖列表固定了torch>=2.8，安装时会随主包一并解析。
• 可选项以部署目标为导向：TensorRT-LLM、ONNX Runtime、TensorRT 均标注为可选，说明仅当你要将量化产物导出到对应推理框架时才需要安装，这直接影响下文"可选依赖"的选择策略。

二、环境搭建：Docker 与本地环境的双路径选择

官方文档提供了两条并行的环境搭建路径，可根据使用场景二选一。

2.1 Docker 镜像（推荐，含完整部署依赖）

如果要在完整依赖（例如 TensorRT / TensorRT-LLM 部署）下使用 Model Optimizer，推荐直接使用预装了 Model Optimizer 的 TensorRT-LLM Docker 镜像：

nvcr.io/nvidia/tensorrt-llm/release:<version>

使用 Docker 路径时的三个要点：

1. 镜像内已预装 Model Optimizer，但建议用 pip 按下一节说明升级到最新版本，避免使用镜像内置的旧版本。

2. 按需设置 TensorRT 相关环境变量，官方给出的示例为：

   export PIP_CONSTRAINT="" export LD_LIBRARY_PATH="${LD_LIBRARY_PATH}:/usr/include:/usr/lib/x86_64-linux-gnu"

3. 补充示例依赖：具体示例（如 examples/hf_ptq）可能还需要安装各自requirements.txt中的额外依赖。

其他可选的 NVIDIA 官方镜像：

• PyTorch 场景：使用 NGC PyTorch 容器（nvcr.io/nvidia/pytorch:<version>-py3），Model Optimizer 已预装，适合以 PyTorch 为主的量化工作流。
• Megatron-Bridge / Megatron-LM 框架：使用 NeMo 容器（nvcr.io/nvidia/nemo:<version>），Model Optimizer 已预装，适合剪枝、蒸馏等训练型优化技术。
• ONNX / TensorRT 场景：使用 TensorRT 容器（nvcr.io/nvidia/tensorrt:<version>-py3），官方明确说明其性能优于 PyTorch 容器，适合 examples/onnx_ptq 这类工作流。

注意：拉取和使用容器镜像前，请先阅读并遵守各镜像自身的许可条款。

2.2 本地环境（PIP / Conda）

不使用 Docker 时，推荐先在本地建立独立虚拟环境：

第一步：创建并激活 conda 环境

conda create -n modelopt python=3.12 pip conda activate modelopt

官方文档以 Python 3.12 为例，它在 3.10～3.14 的支持范围内，且pyproject.toml的文档构建与测试体系也以 Python >= 3.12 为主线，是一个稳妥的选择。

第二步（可选）：安装指定版本的 PyTorch

默认情况下会安装 pip 上最新的 PyTorch。如需为特定 CUDA 版本安装特定 PyTorch，请先按照 PyTorch 官方"本地安装"指引安装对应版本，再继续安装 Model Optimizer。

第三步（可选）：安装其他 NVIDIA 依赖库

如果想与 TensorRT、TensorRT-LLM、Megatron-Bridge、Megatron-LM、Triton 等其他 NVIDIA 库搭配使用，请先确认这些库在本地环境中的安装难度。若遇到依赖冲突问题，官方建议改用 Docker 镜像以获得无缝体验。同时，也可以采用混合工作流：在本地仅用 Model Optimizer 完成 HuggingFace 模型量化，再进入 Docker 镜像完成部署环节。

三、安装 Model Optimizer：主包与可选依赖的精确组合

Model Optimizer 在安装过程中会下载并安装额外的第三方开源软件，使用前请先审阅这些开源项目的许可条款。

3.1 一键全量安装

如果使用官方 Docker 镜像（已含 ModelOpt 及全部可选依赖），可跳过安装步骤；若使用其他建议的镜像，ModelOpt 可能只预装了部分可选依赖，请按需用 pip 升级。常规安装命令为：

pip install -U "nvidia-modelopt[all]"

其中[all]在 pyproject.toml 中定义为nvidia-modelopt[onnx,hf,puzzletron]，即一次安装 ONNX、Hugging Face、Puzzletron 三组可选依赖。

3.2 按模块精确选择 partial dependencies

如果不加任何可选依赖，安装的nvidia-modelopt仅包含modelopt.torch包所需的基础依赖，其他模块必须搭配对应的可选依赖（或[all]）才能正常工作。官方文档给出的模块与可选依赖对应关系如下：

可见 ONNX 相关能力（modelopt/onnx 模块及其 ONNX 导出/量化管线）与部署工具链modelopt.torch._deploy（modelopt/torch/_deploy）都依赖[onnx]组。此外还支持为第三方包安装依赖：

[hf]组在pyproject.toml中涵盖了accelerate、datasets、diffusers、transformers、peft、deepspeed等库，是运行 examples/hf_ptq、examples/llm_qat 等 Hugging Face 工作流的前提。

典型安装组合示例：

# 仅量化 ONNX 模型 pip install -U "nvidia-modelopt[onnx]" # 量化 Hugging Face 模型 pip install -U "nvidia-modelopt[hf]" # 全量安装（ONNX + HF + Puzzletron） pip install -U "nvidia-modelopt[all]"

3.3 CUDA 专属依赖：cupy 的版本匹配

默认情况下，[onnx]依赖会安装cupy-cuda12x以支撑 INT4 ONNX 量化。若你的环境是 CUDA 13，则需要在安装nvidia-modelopt[onnx]之后执行：

pip uninstall -y cupy-cuda12x pip install cupy-cuda13x

这一点与系统要求表中 CUDA 12.x / 13.x 的支持范围相呼应——cupy 的 CUDA 绑定必须与本地 CUDA 版本一致，否则 INT4 ONNX 量化链路可能无法正确加载内核。

四、加速量化：Triton Kernels 的启用条件

ModelOpt 内置了基于 Triton 语言实现的优化量化内核，可将量化运算速度相比默认实现提升约 40%，对 AWQ（INT4 权重仅量化） 和量化感知训练（QAT）工作流尤其有价值。

从源码看，内核的可用性由 modelopt/torch/kernels/quantization/gemm/init.py 统一探测：当torch.cuda.is_available()且能成功导入triton时，会自动加载 FP4、FP8 等 Triton 内核，其中fp4_kernel_hopper额外要求 GPU 计算能力 >= 8.9（因为它使用了tl.float8e4nv）。官方文档给出的启用条件为：

• CUDA 设备计算能力 >= 8.9，例如 RTX 40 系列、RTX 6000、NVIDIA L40 及更新型号；
• 安装 Triton：pip install triton。

无需额外配置——只要硬件与量化格式满足条件，优化内核会被自动选用。当前 Triton 内核支持 NVFP4 量化格式，后续版本会扩展更多格式。需要留意的是：Triton 内核主要加速量化模拟/前向过程，与上文的本地依赖安装是两个独立的维度。

五、检查安装：预编译 CUDA 扩展

首次使用 ModelOpt 的 PyTorch 量化 API 时，它会利用本机已安装的 torch 与 CUDA 编译快速量化内核，编译可能需要几分钟，但后续量化调用会显著加快。编译过程由 modelopt/torch/quantization/extensions.py 驱动，其底层load_cpp_extension实现（见 modelopt/torch/utils/cpp_extension.py）会根据torch.version.cuda与 CUDA 版本约束做匹配检查，并依据设备计算能力自动设置TORCH_CUDA_ARCH_LIST，再调用torch.utils.cpp_extension.load()完成编译。

为了触发编译、验证是否成功，或在构建 Docker 镜像时预先完成编译，请运行：

python -c "import modelopt.torch.quantization.extensions as ext; ext.precompile()"

precompile()会依次编译并打印四组扩展：modelopt_cuda_ext（tensor_quant 通用内核）、modelopt_cuda_ext_fp8（FP8 量化内核）、modelopt_cuda_ext_mx（MX 格式内核）以及modelopt_cuda_ext_ggml（GGML 兼容 IQ 打包内核）。所有扩展均采用懒加载缓存（首次访问后缓存在函数属性上），因此预编译一次后，后续量化调用可直接命中已编译产物。

六、安装后的下一步

安装完成并核验通过后，可基于本仓库继续深入：

• 量化指南：docs/source/guides/1_quantization.rst 与 docs/source/guides/_pytorch_quantization.rst 介绍 PTQ 的具体 API 用法；
• 方法选型：docs/source/guides/_choosing_quant_methods.rst 提供 FP8、INT8 SmoothQuant、INT4 AWQ 等方法的精度/性能取舍对照，可帮助判断哪种量化格式需要 Triton 加速；
• 实战示例：examples/hf_ptq/README.md（Hugging Face PTQ）、examples/onnx_ptq/README.md（ONNX 量化）均附带各自的requirements.txt，安装后即可按示例脚本复现完整流程。

本文结论：在 Linux 上使用 Model Optimizer 的完整路径可概括为——确认系统要求（Linux + x86_64/aarch64 + Python 3.10–3.14 + CUDA 12/13）→ 选择 Docker 或 Conda 本地环境 → 按目标模块选择[onnx]/[hf]/[all]可选依赖（CUDA 13 用户需替换 cupy）→ 如需 40% 量化加速则确保计算能力 >= 8.9 并安装 Triton → 最后通过ext.precompile()验证内核编译，即可进入量化实战。