Model-Optimizer 量化模型 vLLM 部署参考：Realquant 与 Fakequant 两条路径的完整实战指南-开发者社区

人工智能
大模型
模型优化
模型量化
模型压缩

【免费下载链接】Model-Optimizer

A 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

点击查看免费下载

导读

本文是 NVIDIA Model-Optimizer 仓库中面向 vLLM 的部署速查文档（原文档位于plugins/modelopt/skills/deployment/references/vllm.md），它回答了这样一个核心问题：经过 Model-Optimizer（简称 ModelOpt）量化并导出的 checkpoint，如何以最高性能或最高灵活度的方式在 vLLM 中启动、调用与评测。阅读本文后，你将掌握两条互补的部署路径——面向生产性能的Realquant（专用量化 kernel）与面向研究与新量化方案验证的Fakequant——并能够完成从环境准备、服务启动、Python/OpenAI 兼容接口调用、校准配置、基准测试到常见问题排障的完整闭环。

一、环境要求与前置准备

原文档给出的唯一硬性门槛是：

vLLM >= 0.10.1
安装命令：pip install vllm

0.10.1是--quantization modelopt与modelopt_fp4这两种量化标记被 vLLM 原生识别的版本下限；低于该版本启动时会直接报quantization="modelopt" not recognized（详见本文第六节故障表）。

如果需要从 ModelOpt 仓库根目录直接安装测试环境，可以参考 examples/vllm_serve/README.md 中验证过的组合：先安装测试过的 vLLM 发行版，再安装 ModelOpt 的完整依赖集：

python3 -m pip install "vllm==0.28.0" python3 -m pip install -e ".[all,mlflow]"

其中mlflow是可选的实验追踪依赖（用于下面第三节的 MLflow 记录功能）。该 README 同时给出了用 Docker 复现环境的方案——使用仓库自带的 examples/vllm_serve/Dockerfile 构建镜像，并可通过构建参数切换 vLLM 版本：

docker build -f examples/vllm_serve/Dockerfile -t vllm-modelopt:v0.28.0 . docker build --build-arg VLLM_VERSION=0.26.0 \ -f examples/vllm_serve/Dockerfile -t vllm-modelopt:v0.26.0 .

说明：示例代码在 vLLM 0.9.0、0.19.1、0.26.0、0.28.0 上均经过测试（见 examples/vllm_serve/README.md）；其中部分进阶特性（如紧凑 NVFP4 attention worker）要求 vLLM 0.15.0 或更新版本。

二、Realquant 部署（推荐路径）：开箱即用的高性能路线

2.1 什么是 Realquant

Realquant 使用专用量化 kernel获得最大推理性能，是 ModelOpt 导出 checkpoint 的默认部署路径。ModelOpt 在导出时会把权重量化为真实低位格式（如 FP8、NVFP4），vLLM 加载这类 checkpoint 时无需再执行逐层 fakequant 前向，直接走底层量化算子即可。

2.2 以 OpenAI 兼容服务器方式启动

原文档给出的标准启动命令：

python -m vllm.entrypoints.openai.api_server \ --model <checkpoint_path> \ --quantization modelopt \ --tensor-parallel-size <num_gpus> \ --host 0.0.0.0 --port 8000 \ --served-model-name <model_name>

参数要点：

--model：ModelOpt 导出的 checkpoint 目录或 Hub 模型名；
--quantization modelopt：告知 vLLM 使用 ModelOpt 导出的量化格式（该格式携带在 checkpoint 元数据中）；
--tensor-parallel-size：GPU 张量并行数，按显存与--max-model-len综合决定（启动 OOM 时优先调整它，见故障表）；
--served-model-name：对外暴露的模型名，供下游请求方引用。

NVFP4 checkpoint 的差异：需要将量化标记换成--quantization modelopt_fp4。这是 NVFP4 4-bit 浮点格式在 vLLM 侧的专用入口，混用 FP8 的modelopt标记会加载失败。

2.3 以 Python API 方式调用

from vllm import LLM, SamplingParams llm = LLM(model="<checkpoint_path>", quantization="modelopt") # For FP4: quantization="modelopt_fp4" sampling_params = SamplingParams(temperature=0.8, top_p=0.95) outputs = llm.generate(["Hello, my name is"], sampling_params) for output in outputs: print(f"Prompt: {output.prompt!r}, Generated: {output.outputs[0].text!r}")

LLM构造器的quantization参数与命令行--quantization完全对应，SamplingParams控制温度、top-p 等采样行为，适合脚本化、批量化集成。

2.4 直接从 HuggingFace Hub 加载

ModelOpt 导出的 FP8 权重也会发布到 HuggingFace Hub（如 NVIDIA 官方账号下的*-FP8系列模型），此时只需传模型名：

from vllm import LLM, SamplingParams llm = LLM(model="nvidia/Llama-3.1-8B-Instruct-FP8", quantization="modelopt") outputs = llm.generate(["What is AI?"], SamplingParams(temperature=0.8))

仓库中另有完整的脚本化参考：examples/model_hub/run_llama_fp8_vllm.py 展示了用 vLLM 拉起 FP8 Hub 模型的服务端流程。

2.5 从源码看 Realquant 的格式支撑

Realquant 依赖 ModelOpt 在导出侧生成 vLLM 可识别的量化配置。仓库源码中，ModelOpt 的量化预设均以*_DEFAULT_CFG形式在 modelopt/torch/quantization/config.py 中定义（如第 1682 行的FP8_DEFAULT_CFG、第 1716 行的NVFP4_DEFAULT_CFG，以及第 1741/1744 行的 KV-cache 专用NVFP4_AFFINE_KV_CFG、NVFP4_KV_CFG），并在modelopt/torch/quantization/__init__.py中导出为mtq.NVFP4_DEFAULT_CFG等公共符号，供量化与导出流程统一引用。这些 preset 就是 Fakequant 路径下QUANT_CFG环境变量可引用的取值来源。

三、Fakequant 部署（研究路径）：无需专用 kernel 的灵活方案

3.1 什么是 Fakequant 及其适用场景

Fakequant比 Realquant 慢约 2–5 倍，但不要求 vLLM 提供专用 kernel 支持，因此非常适合两类用途：研究新的量化方案、在正式落 kernel 前验证量化策略的正确性与精度。原文档明确将其定位为 research 用途，并指向仓库示例目录 examples/vllm_serve/。

3.2 核心启动命令

原文档给出的最小启动方式：

# Environment variables for configuration export QUANT_CFG=NVFP4_DEFAULT_CFG # Quantization format export QUANT_CALIB_SIZE=512 # Calibration samples export QUANT_DATASET=cnn_dailymail # Calibration dataset python examples/vllm_serve/vllm_serve_fakequant.py <model_path> \ -tp <num_gpus> --host 0.0.0.0 --port 8000

该入口脚本 examples/vllm_serve/vllm_serve_fakequant.py 的本质是 vLLM 的启动器包装：它复用 vLLM 自身的参数解析器（make_arg_parser），把默认 worker 替换为fakequant_worker.FakeQuantWorker，从而在模型加载时完成"校准 → 量化 → 替换算子"的整条链。从源码看，启动器会把上述量化环境变量通过 Ray 的ADDITIONAL_ENV_VARS或VLLM_RAY_EXTRA_ENV_VARS_TO_COPY同步给分布式 worker（见 vllm_serve_fakequant.py 第 71–97 行），保证多卡环境下每个 worker 拿到一致的量化配置。

3.3 校准相关环境变量全表

原文档只列出了三个变量；examples/vllm_serve/README.md 给出了完整集合，这里一次性补全：

变量	作用	默认值
`QUANT_DATASET`	校准数据集名称	`cnn_dailymail`
`QUANT_CALIB_SIZE`	校准样本数	`512`
`QUANT_CFG`	模型量化配置（对应`mtq.*_CFG`预设名，如`NVFP4_DEFAULT_CFG`、`FP8_DEFAULT_CFG`）	无
`KV_QUANT_CFG`	KV-cache 量化配置（如`NVFP4_KV_CFG`、`NVFP4_AFFINE_KV_CFG`）	无
`QUANT_FILE_PATH`	导出的量化器状态文件`quantizer_state.pth`（MCore 导出产物）	无
`MODELOPT_STATE_PATH`	导出的`vllm_fq_modelopt_state.pth`（HF 导出产物，恢复量化器状态与参数）	无
`CALIB_BATCH_SIZE`	校准 batch 大小	`1`
`RECIPE_PATH`	ModelOpt PTQ recipe YAML 路径	无

在代码层面，这些变量会汇入quant_config字典，并由 examples/vllm_serve/vllm_ptq_utils.py 的get_quant_config()统一解析：优先加载RECIPE_PATH指定的 recipe；否则从mtq模块按名取出QUANT_CFG/KV_QUANT_CFG预设并合并。同一个文件还处理了MLA（Multi-head Latent Attention）模型的 KV 量化配置补齐（update_kv_cfg_for_mla会把*[kv]_bmm_quantizer的配置复制到*kv_c_bmm_quantizer与*k_pe_bmm_quantizer），并利用 vLLM 调度器为校准分配独立的 KV-cache scratch blocks——这正是 README 中"校准使用专用 scratch KV-cache blocks，无需调低--max-num-batched-tokens防 NaN"的实现来源。

3.4 进阶：KV-cache 量化与混合架构模型

对于 Nemotron 3 Nano 这类 Attention/Mamba 混合架构模型（vLLM 0.26.0/0.28.0 支持），可以同时启用 NVFP4 的 KV-cache 量化：

KV_QUANT_CFG=NVFP4_KV_CFG QUANT_CALIB_SIZE=512 \ python examples/vllm_serve/vllm_serve_fakequant.py <nemotron3_nano_model_path> -tp 8 \ --max-model-len 8192 --enforce-eager --host 0.0.0.0 --port 8000

注意两个约束：一是--enforce-eager是必须的——NVFP4_KV_CFG/NVFP4_AFFINE_KV_CFG使用基于 Python 层 tensor shape 计算 grid 的动态 block Triton kernel，与 CUDA graph 捕获不兼容（见 examples/vllm_serve/README.md 的 Known Problems 第 3 条）；二是 vLLM 暴露--moe-backend时该启动器默认使用--moe-backend triton，因为 ModelOpt 的专家 fakequant 需要分解式 MoE 后端，让两个专家 GEMM 在校准期间都可见。

3.5 可选：用 MLflow 记录量化实验

Fakequant 服务支持把"这次服务到底量化了什么"完整记录下来，便于评测结果反查 recipe。启用方式：

RECIPE_PATH=<PATH_TO_RECIPE> python examples/vllm_serve/vllm_serve_fakequant.py <model_path> -tp 8 \ --host 0.0.0.0 --port 8000 \ --mlflow https://<your-mlflow-server>/

量化实际发生在 vLLMworker中，因此 run 也在 worker 侧记录：启动器负责校验 URI 并通过环境变量下发设置，rank 0 在加载权重之前打开 run（URI 或 token 有误会在几秒内失败，而不是等完整校准后）。记录的上传产物包括command.txt（脱敏后的完整启动命令）、version.txt（ModelOpt 版本）、recipe/resolved_recipe.yaml（展开$import后的独立 recipe）、logs/<script>.log与summary/quant_summary.txt等。需要先安装nvidia-modelopt[mlflow]客户端。细节见 examples/vllm_serve/README.md 的 "Tracking a serve with MLflow" 一节，其 MLflow 参数解析逻辑位于 examples/vllm_serve/vllm_mlflow_utils.py。

3.6 加载 QAT/PTQ 已量化模型（WIP）

若模型已通过 QAT/QAD 或 PTQ 量化（而非在服务时现场校准），可在导出阶段保存量化器状态、服务阶段直接恢复：

HF 模型：用 examples/hf_ptq/hf_ptq.py 加--vllm_fakequant_export导出：

python examples/hf_ptq/hf_ptq.py \ --pyt_ckpt_path <MODEL_PATH> \ --recipe <PATH_TO_RECIPE> \ --calib_size 512 \ --export_path <EXPORT_DIR> \ --vllm_fakequant_export \ --trust_remote_code

导出产物包括<EXPORT_DIR>/vllm_fq_modelopt_state.pth（供 vLLM fakequant 恢复量化器状态）与完整 HF 权重目录。该导出函数在源码中为 modelopt/torch/export/plugins/vllm_fakequant_hf.py 的export_hf_vllm_fq_checkpoint：它会将 fakequant 权重折叠进state_dict副本、从 HF 保存中剔除 quantizer 键、短暂禁用权重量化器以快照 ModelOpt/quantizer 状态后再恢复，并处理 MoE+AWQ 时pre_quant_scale跨专家的平均化。若输入 checkpoint 本身已量化，脚本会跳过重新量化、只导出恢复所需产物。

服务时通过MODELOPT_STATE_PATH传入：

MODELOPT_STATE_PATH=<vllm_fq_modelopt_state.pth> python examples/vllm_serve/vllm_serve_fakequant.py <model_path> -tp 8 --host 0.0.0.0 --port 8000

MCore（Megatron）模型：导出时使用--export-vllm-fq生成quantizer_state.pth，服务时用QUANT_FILE_PATH+QUANT_CFG指定：

QUANT_CFG=<quant_cfg> QUANT_FILE_PATH=<quantizer_state.pth> python examples/vllm_serve/vllm_serve_fakequant.py <model_path> -tp 8 --host 0.0.0.0 --port 8000

对应的 Megatron 导出实现位于 modelopt/torch/export/plugins/vllm_fakequant_megatron.py。注意：MCore 路径不使用MODELOPT_STATE_PATH，且 MCore 的 KV-cache 量化导出/恢复暂不支持（详见第六节）。

四、基准测试与精度评估

4.1 吞吐性能基准（vLLM 内置）

先启动服务，再运行 vLLM 自带的 serving benchmark：

python -m vllm.benchmark_serving \ --model <model_name> \ --port 8000 \ --num-prompts 100 \ --request-rate 10

--num-prompts控制请求总数、--request-rate控制每秒请求速率，两者共同决定压测负载形态。--model需与启动时的--served-model-name（或 checkpoint 路径）对应。

4.2 精度评估（lm_eval）

在服务运行的同时，用 lm_eval 通过local-completions桥接方式评测 OpenAI 兼容接口：

lm_eval --model local-completions \ --tasks gsm8k \ --model_args model=<model_name>,base_url=http://localhost:8000/v1/completions,num_concurrent=1,max_retries=3,tokenized_requests=False,batch_size=128

参数说明：base_url指向服务端点；num_concurrent/max_retries控制并发与重试；batch_size=128控制评测批大小。仓库的 examples/llm_eval/ 目录提供了更多评测工具（如 examples/llm_eval/lm_eval_trtllm.py、examples/llm_eval/lm_eval_hf.py）可供横向对比不同部署后端。

五、常见问题与排查

原文档的故障速查表如下，合并仓库 README 的 Known Problems 补充后完整呈现：

问题	解决方法
`quantization="modelopt"`not recognized	升级 vLLM 到 >= 0.10.1
启动时 OOM	增大`--tensor-parallel-size`或减小`--max-model-len`
AWQ checkpoint 无法加载	AWQ 不通过 vLLM 的 modelopt 路径支持；改用 FP8 或 NVFP4
Mixed precision 不生效	Fakequant 不支持混合精度
MCore 模型用`MODELOPT_STATE_PATH`无效	MCore 路径改用`QUANT_FILE_PATH`，且`QUANT_CFG`必须与原始 MCore 量化 recipe 一致，否则 quantizer 键/配置对不齐
KV-cache 量化配置（`NVFP4_KV_CFG`/`NVFP4_AFFINE_KV_CFG`）输出错误	必须加`--enforce-eager`：这类配置的动态 block Triton kernel 与 CUDA graph 捕获不兼容，捕获期会把 Python 层 shape 固化，批大小变化时 grid 计算错误
混合 Attention/Mamba 模型校准出现 NaN	校准走专用 scratch KV-cache blocks，一般无需调低`--max-num-batched-tokens`（若仍异常，检查 vLLM 版本是否为 0.26.0/0.28.0）

六、部署路径选型小结

生产环境优先 Realquant：--quantization modelopt（FP8）或--quantization modelopt_fp4（NVFP4），专用 kernel、吞吐最高，一条命令即可上线；
研究与方案验证用 Fakequant：借助 examples/vllm_serve/vllm_serve_fakequant.py 现场校准、现场量化，配合QUANT_CFG/KV_QUANT_CFG/RECIPE_PATH等环境变量快速试错；已量化的 QAT/PTQ 模型则通过MODELOPT_STATE_PATH（HF）或QUANT_FILE_PATH（MCore）恢复状态后部署；
验证闭环：无论哪条路径，均可用vllm.benchmark_serving测吞吐、lm_eval 测精度，Fakequant 场景还可叠加 MLflow 把量化配方与评测结果关联归档。