NVIDIA Model Optimizer 安装指南：Linux 与 Windows 全平台环境搭建与验证实战

【免费下载链接】Model-OptimizerA unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.项目地址https://gitcode.com/GitHub_Trending/te/Model-Optimizer点击查看免费下载导读本文是 Model Optimizernvidia-modelopt官方安装文档docs/source/getting_started/2_installation.rst的完整中文讲解。Model Optimizer 是统一的大模型优化库支持量化、剪枝、蒸馏、NAS、投机解码等技术其量化产物可部署到 TensorRT-LLM、TensorRT、vLLM、ONNX Runtime 等推理框架。读完本文你将掌握在 Linux 与 Windows 上从零搭建 ModelOpt 环境、按需选择可选依赖、配置 CUDA/ONNX Runtime 执行提供商并通过预编译与冒烟测试验证安装是否成功的完整实战流程。一、系统要求先确认环境是否达标Linux 系统要求根据 docs/source/getting_started/_installation_for_Linux.rst最新版nvidia-modelopt的 Linux 系统要求如下组件要求操作系统Linux架构x86_64、aarch64 (SBSA)Python 3.10, 3.15CUDA12.x、13.xPyTorch 2.8TensorRT-LLM可选 1.0ONNX Runtime可选1.24TensorRT可选 10.0从 pyproject.toml 的核心依赖定义可以看到torch2.8是硬性约束同时核心包还依赖PyYAML、omegaconf2.3.0、pydantic2.0、safetensors、scipy等库。这些要求意味着请务必在安装前核对 Python 与 CUDA 版本避免在旧版本 PyTorch 上强行安装导致二进制不兼容。Windows 系统要求根据 docs/source/getting_started/windows/_installation_for_Windows.rstWindows 版本的约束如下组件要求操作系统Windows架构amd64 (x86_64)、ARM64*Python 3.10, 3.14CUDA 12.0ONNX Runtime1.20.0NVIDIA 驱动565.90 或更新NVIDIA GPURTX 40 与 50 系列官方对 Windows 有几个明确限制需要注意必须使用与 GPU 兼容的驱动和依赖例如 Blackwell GPU 可能需要 NVIDIA 570 驱动与 CUDA 12.8当前仅支持单 GPU配置Windows ARM64 支持为实验性功能要求使用原生 ARM64 依赖具体参见 Windows on Arm 安装指南。安装前提醒Model Optimizer 会下载并安装额外的第三方开源软件项目请在使用前审阅这些开源项目的许可证条款。二、Linux 环境搭建Docker 与本地环境两条路径路径 ADocker 镜像官方推荐如果需要使用完整的依赖例如 TensorRT / TensorRT-LLM 部署官方推荐直接使用预装了 Model Optimizer 的TensorRT-LLM Docker 镜像例如nvcr.io/nvidia/tensorrt-llm/release:version。使用镜像后仍需按下一节的方法用pip将 Model Optimizer 升级到最新版本。如果需要为 TensorRT 二进制文件配置环境变量官方给出的参考配置如下export PIP_CONSTRAINT export LD_LIBRARY_PATH${LD_LIBRARY_PATH}:/usr/include:/usr/lib/x86_64-linux-gnu除此之外官方还提供了其他替代镜像均预装 Model Optizer使用前需确认已是最新版本NVIDIA NGC PyTorch 容器nvcr.io/nvidia/pytorch:version-py3适合纯 PyTorch 工作流NeMo 容器nvcr.io/nvidia/nemo:version适合 NVIDIA Megatron-Bridge 或 Megatron-LM 框架TensorRT 容器nvcr.io/nvidia/tensorrt:version-py3适合 ONNX / TensorRT 场景官方说明其在性能上优于 PyTorch 容器。拉取和使用容器镜像前请审阅其对应的许可证条款。部分示例还需要安装其各自的requirements.txt中额外的依赖可参考仓库中 examples 目录下各示例的说明。路径 B本地环境PIP / Conda如果尚未创建虚拟环境官方推荐用 conda 创建名为modelopt、Python 3.12 的环境conda create -n modelopt python3.12 pip conda activate modelopt可选安装指定 PyTorch 版本默认会安装 pip 上最新版 PyTorch。若需要为特定 CUDA 版本安装指定 PyTorch请先按 PyTorch 官方安装指引完成 PyTorch 安装再安装 Model Optimizer。可选安装其他 NVIDIA 依赖如果希望 ModelOpt 与 TensorRT、TensorRT-LLM、Megatron-Bridge、Megatron-LM、Triton 等 NVIDIA 库协同使用请先确认这些库在本地环境的可安装性遇到问题建议改用 Docker 镜像。一个常见的混合用法是本地完成 HuggingFace 模型的量化再用 Docker 镜像进行部署这样可以规避本地安装完整部署栈的复杂度。三、安装 Model Optimizerpip 安装与可选依赖详解一键安装全部依赖在 Python 3.12 环境中执行pip install -U nvidia-modelopt[all]-U会升级到最新版本。如果你使用的是 ModelOpt 官方 Docker 镜像可以跳过此步镜像已预装全部可选依赖如果使用其他镜像则需要按需用 pip 升级到最新版本。按需安装部分依赖如果不加任何可选依赖pip install nvidia-modelopt只安装modelopt.torch包的依赖其他模块可能无法工作。官方给出的可选依赖与模块对应关系如下模块需要的可选依赖modelopt.onnx[onnx]modelopt.torch._deploy[onnx]此外还支持第三方包的依赖第三方包可选依赖Hugging Facetransformers、diffusers等[hf]从 pyproject.toml 源码可以看清各 extra 的具体内容帮助你判断取舍[onnx]包含onnx~1.21.0、onnx-graphsurgeon0.6.1、onnxconverter-common~1.16.0、onnxscript、onnxslim0.1.76、polygraphy0.53.4、cppimport、lief、ml_dtypes以及按平台/版本区分的onnxruntime/onnxruntime-gpuPython 3.10 时 ORT 约 1.24.2Python 3.10 时约 1.22.0cupy-cuda12x只在非 aarch64/ARM64/macOS 平台安装[hf]包含accelerate1.0.0、datasets3.0.0、diffusers0.32.2、huggingface_hub0.24.0、peft0.17.0、transformers4.57,5.15、sentencepiece、tiktoken、nltk、wonderwords等deepspeed仅在非 macOS/Windows 平台安装[all]在 pyproject.toml 中定义为nvidia-modelopt[onnx,hf,puzzletron]即onnx、hf与puzzletron三者的并集puzzletron包含fire、hydra-core、pandas、typeguard等。CUDA 特定依赖CuPy 版本切换默认情况下INT4 ONNX 量化依赖cupy-cuda12x。如果使用 CUDA 13在安装nvidia-modelopt[onnx]后需要手动切换 CuPy 包pip uninstall -y cupy-cuda12x pip install cupy-cuda13xCuPy 是 ModelOpt 用于加速 INT4 ONNX 量化的关键 GPU 工具库版本必须与宿主机 CUDA 主版本严格对应。可选加速Triton 量化内核ModelOpt 内置了基于 Triton 语言实现的优化量化内核相比默认实现可将量化操作加速约 40%对AWQ与QAT量化感知训练工作流尤其受益。当前 Triton 内核支持NVFP4量化格式更多格式将在未来版本支持。启用条件CUDA 设备计算能力 8.9如 RTX 40 系列、RTX 6000、NVIDIA L40 或更新安装 Tritonpip install triton。无需额外配置——当硬件与量化格式满足条件时优化内核会被自动启用。四、验证安装预编译快速量化内核官方提示首次使用 ModelOpt 的 PyTorch 量化 API 时它会用已安装的 torch 与 CUDA 编译快速量化内核这个过程可能需要几分钟但后续的量化调用会明显加快。执行以下命令触发编译并确认是否成功也常用于 Docker 构建时预编译python -c import modelopt.torch.quantization.extensions as ext; ext.precompile()从源码看modelopt/torch/quantization/extensions.py 中的precompile()会依次实例化并打印四组 CUDA 扩展对象get_cuda_ext()通用量化内核、get_cuda_ext_fp8()FP8 内核、get_cuda_ext_mx()MX 格式内核与get_cuda_ext_ggml()GGML IQ CUDA 打包内核编译依赖 CUDA 版本 11.8。只要该命令不报错并输出扩展对象即代表内核编译成功安装链路torch CUDA 工具链工作正常。五、Windows 安装独立工具包完整流程Windows 端 ModelOptModelOpt-Windows可以作为独立工具包用于 ONNX 模型量化详细步骤记录在 docs/source/getting_started/windows/_installation_standalone.rst。其典型工作流是在 Windows RTX PC 上本地量化 ONNX 模型产物可用于 DirectML 与 TensorRT-RTX 后端。步骤 1准备前置条件NVIDIA GPU 与显卡驱动Python 3.10 且 3.14Visual Studio 2022 / MSVC / C/C Build ToolsCUDA Toolkit 与匹配的 cuDNN用于校准阶段走 CUDA 路径例如onnxruntime-gpu或 CUDA EP。根据需要更新PATH环境变量。步骤 2创建虚拟环境可选但推荐推荐使用 conda 或 Python 内置venv。venv 示例mkdir myEnv python -m venv .\myEnv .\myEnv\Scripts\activate新环境不会预装 onnx、onnxruntime、onnxruntime-directml、onnxruntime-gpu、nvidia-modelopt 等包。步骤 3安装 ModelOpt-Windows wheelpip install nvidia-modelopt[onnx]不加[onnx]时只安装核心最小依赖与 PyTorch 模块torchONNX 模型量化必须使用[onnx]。Windows ARM64 用户请走 ARM64 指南标准onnxextra 中的部分 x64 依赖不适用于 ARM64需替换为原生包。步骤 4为校准配置 ONNX Runtime 执行提供商EPONNX 的 PTQ训练后量化通常需要校准——用用户提供的输入校准数据运行基础模型。校准必须借助合适的 ONNX Runtime 执行提供商EP不同 EP 对应不同安装包执行提供商安装包DirectML EPonnxruntime-directmlTensorRT-RTX EPonnxruntime-trt-rtxTensorRT-RTX EP ABI 插件onnxruntime-ep-nv-tensorrt-rtx-cu13CUDA EPonnxruntime-gpuCPU EPonnxruntime默认情况下ModelOpt-Windows x64 安装的是onnxruntime-gpu自 v1.19.0 起默认对应 CUDA 12.x。CUDA EP 需要 CUDA 与 cuDNN 依赖请按 ONNX Runtime 官方文档安装兼容版本。如需切换到其他 EP先卸载现有onnxruntime-gpu再安装对应包例如切换 DirectML EPpip uninstall onnxruntime-gpu pip install onnxruntime-directml对于 Windows ARM64CUDA EP 暂不可用应改用 TensorRT-RTX EP ABI 插件该插件已包含在nvidia-modelopt[onnx]中。步骤 5配置量化 GPU 加速工具ModelOpt 使用CuPy加速 INT4 ONNX 量化nvidia-modelopt[onnx]默认安装cupy-cuda12x与 CUDA 12 兼容的onnxruntime-gpu。CUDA 13.x 场景假定宿主机已装好 CUDA 13.x Toolkit、兼容 cuDNN 与驱动替换默认的 CUDA 依赖包python -m pip uninstall -y cupy-cuda12x onnxruntime-gpu python -m pip install cupy-cuda13x onnxruntime-gpu1.27ONNX Runtime 1.27 及以后在 PyPI 发布的 GPU 包默认使用 CUDA 13.x。还需确保宿主机有 CUDA 13 的 cuDNN 9 构建可通过 NVIDIA Windows 安装包/zip或nvidia-cudnn-cu13Python wheel 获得并让CUDA_PATH、CUDA_HOME、PATH指向 CUDA 13.x 安装位置。步骤 6验证安装任务管理器确认 GPU 出现在任务管理器中说明驱动正常Python 解释器命令行输入python能正常启动并显示版本onnxruntime 包确保只安装下列 EP 包中的一个——onnxruntime-directmlDirectML EP、onnxruntime-trt-rtxTensorRT-RTX EP、onnxruntime-gpuCUDA EP或onnxruntimeCPU EP。onnxruntime-ep-nv-tensorrt-rtx-cu13插件是伴随所选 ORT 包安装的不替代onnxruntime-gpuCUDA Toolkit确认所选 Toolkit 被优先找到nvcc报告预期主版本where nvcc nvcc --versionONNX 与 ONNX Runtime 导入与 CUDA EP 可用性python -c import onnx; import onnxruntime as ort; print(ort.__version__, ort.get_available_providers())CuPy GPU 分配与执行CUDA 13.x 时runtimeGetVersion()应以13开头python -c import cupy; print(cupy.__version__, cupy.cuda.runtime.runtimeGetVersion(), cupy.arange(3).sum())环境变量确保CUDA_PATH、CUDA_PATH_V12_x或CUDA_PATH_V13_x指向目标 Toolkit修改持久化环境变量后需重开命令行ModelOpt-Windows 导入检查python -c import modelopt.onnx.quantization六、Windows ARM64 实验性安装要点Windows ARM64 的 ONNX 量化 API、格式与产出的 ONNX 模型与 x64 完全一致仅环境搭建不同详见 docs/source/getting_started/windows/_installation_windows_arm64.rst。由于部分第三方包尚未发布 Windows ARM64 wheel该支持为实验性。官方测试过的一组配置注意是已测试配置而非最低要求Python 3.13.14 ARM64、Visual Studio 2026 Community含 ARM64 C 工具、LLVM 22.1.8 Windows ARM64、CUDA 13.4 cupy-cuda13x14.2.0、ONNX Runtime 1.24.4 TensorRT RTX ABI EP 0.4.0、ModelOpt 0.47.0 开发树。核心步骤概览安装原生 ARM64 组件Python 3.13、NVIDIA GPU 驱动 CUDA 13 Toolkit、含 ARM64 C 构建工具的 Visual Studio、Git、LLVM for Windows ARM64在 PowerShell 中创建 Python 3.13 ARM64 虚拟环境从源码安装 ModelOpt 核心pip install -e .再显式安装 ARM64 兼容的 ONNX 依赖cppimport、cupy-cuda13x、lief、ml_dtypes、onnx~1.21.0、onnx-graphsurgeon、onnxscript、onnxruntime1.24.2、onnxruntime-ep-nv-tensorrt-rtx-cu13等从而避开 x64 的onnxruntime-gpu若所选工作流依赖 PyArrow如datasets而解析不到 ARM64 wheel需按 Apache Arrow 官方指南用 clang-cl Ninja 本地构建 Arrow C 与自包含 PyArrow wheel构建时禁用 bzip2 与 SIMD、关闭 Parquet 加密并可能需要对 xsimd 头文件做两处临时兼容调整用冒烟测试脚本验证架构arm64/aarch64、CuPy 可执行 GPU 计算、TensorRT RTX ABI EP 注册成功再运行pip check。已知限制本地构建的 wheel 仅适用于 CPython 3.13 Windows ARM64测试配置关闭了 Arrow SIMD不含 bzip2 与 Parquet 加密若捆绑 Thrift 报损坏补丁需按指引以 LF 行尾创建 Arrow 检出。七、通过 Olive 使用 ModelOpt-WindowsModelOpt-Windows 还可通过Microsoft Olive工作流进行量化详见 docs/source/getting_started/windows/_installation_with_olive.rst。安装与配置流程pip install olive-ai[nvmo]若走 CUDA EP 路径安装对应的 onnxruntime 与 onnxruntime-genai 包pip install onnxruntime-genai-cuda pip install onnxruntime-gpuOlive 新增了名为NVModelOptQuantization简称nvmo的 pass专门用于基于 ModelOpt-Windows 的模型量化。将其加入 Olive 配置文件并按需添加其他 pass即可启动优化olive run --config config json --setup olive run --config config json也可用 Python API 方式执行from olive.workflows import run as olive_run olive_run(config.json)注意目前 ModelOpt-Windows 在 Olive 工作流中仅支持基于 ONNX Runtime GenAI 的 LLM 模型。使用前请确保已满足本文第五节列出的 ModelOpt-Windows 全部依赖。八、安装后的下一步安装验证通过后即可开始使用 ModelOpt 的各类优化能力阅读 概览文档 了解量化NVFP4/FP8/INT8/INT4、SmoothQuant、AWQ、SVDQuant 等、蒸馏、剪枝、投机解码、稀疏化等全部技术栈量化入门可参考 量化指南 与 量化方法选型说明部署到 TensorRT-LLM、ONNX Runtime、Hugging Face 生态分别见 部署章节、docs/source/deployment/2_onnxruntime.rst、docs/source/deployment/3_unified_hf.rst仓库 examples 目录下提供了 QAT、PTQ、蒸馏、剪枝、投机解码等端到端示例脚本与配置modelopt_recipes 目录则内置了大量开箱即用的模型量化配方。最后再次强调安装时的三个关键决策点Python 版本必须落在官方要求区间、CUDA 主版本决定 CuPy 与 onnxruntime-gpu 的选型、是否安装[onnx]/[hf]等 extra 决定可用的模块范围。按本文流程逐步执行即可得到一个可用、可验证、可扩展的 Model Optimizer 开发环境。赞分享【免费下载链接】Model-OptimizerA unified library of SOTA model optimization techniques like quantization, distillation, pruning, neural architecture search, speculative decoding, etc. It compresses deep learning models for downstream deployment frameworks like TensorRT-LLM, TensorRT, vLLM, etc. to optimize inference speed.项目地址https://gitcode.com/GitHub_Trending/te/Model-Optimizer点击查看免费下载相关推荐FinRL 跨平台安装指南macOS、Ubuntu 与 Windows 环境搭建与验证全流程FinRL 跨平台安装指南macOS、Ubuntu 与 Windows 环境搭建与验证全流程 本文以 FinRL 官方安装文档 docs/source/sta金融科技强化学习人工智能Darknet环境搭建与编译指南Windows/Linux/macOS全平台Darknet环境搭建与编译指南Windows/Linux/macOS全平台 本指南详细介绍了Darknet深度学习框架在Windows、Linux和macO人工智能深度学习计算机视觉机器学习最全面的Darknet安装指南Windows与Linux系统环境搭建实战最全面的Darknet安装指南Windows与Linux系统环境搭建实战 你是否在安装Darknet时遇到过环境配置难题本文将帮助你在Windows和Lin人工智能深度学习计算机视觉机器学习创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考