08_NVIDIA_ModelOpt-测试与示例

happyprince2026-07-12 9:52

08 · 测试与示例详解

本文深入剖析 `tests/`(file:///workspace/tests/) 测试体系与 `examples/`(file:///workspace/examples/) 端到端示例集。ModelOpt 通过分层测试金字塔保证质量，通过 25+ 顶层示例覆盖全场景。

目录

  1. 总览：测试与示例全景
  2. [tests/ 测试体系](#tests/ 测试体系)
  3. [examples/ 端到端示例](#examples/ 端到端示例)
  4. 本篇使用指南
  5. 本篇效果对比

1. 总览：测试与示例全景

1.1 测试金字塔

ModelOpt 采用经典测试金字塔，从下到上递增集成度、递减数量：

层级 路径 数量 目的 运行环境
单元测试 `tests/unit/`(file:///workspace/tests/unit/) ~200 文件 验证单个函数 / 类 / 模块 CPU
GPU 测试 `tests/gpu/`(file:///workspace/tests/gpu/) ~100 文件 CUDA 路径验证 单 GPU
Megatron 集成 `tests/gpu_megatron/`(file:///workspace/tests/gpu_megatron/) ~30 文件 Megatron-LM 集成 多 GPU + Megatron
TRT-LLM 后端 `tests/gpu_trtllm/`(file:///workspace/tests/gpu_trtllm/) ~5 文件 TensorRT-LLM 后端 GPU + TRT-LLM
vLLM 后端 `tests/gpu_vllm/`(file:///workspace/tests/gpu_vllm/) ~5 文件 vLLM 后端 GPU + vLLM
回归测试 `tests/regression/`(file:///workspace/tests/regression/) ~5 文件 关键路径回归 GPU
示例测试 `tests/examples/`(file:///workspace/tests/examples/) ~30 文件 端到端示例 GPU + 各框架

1.2 examples 体系

25+ 顶层目录，按使用场景分类：

类别 示例目录
PTQ hf_ptq/ / vlm_ptq/ / onnx_ptq/ / torch_onnx/ / windows/onnx_ptq/
QAT/QAD llm_qat/ / llm_qad/ / gpt-oss/ / cnn_qat/
剪枝 pruning/minitron/ / pruning/puzzletron/ / pruning/minitron_vs_puzzletron/
蒸馏 llm_distill/ / megatron_bridge/distill.py / diffusers/distillation/
稀疏 llm_sparsity/attention_sparsity/ / llm_sparsity/weight_sparsity/ / diffusers/sparsity/
Speculative speculative_decoding/ / specdec_bench/
Puzzletron puzzletron/
Diffusion FastGen diffusers/fastgen/
部署 model_hub/ / vllm_serve/ / torch_trt/
数据集 dataset/ / deepseek/
评测 llm_eval/ / researcher_guide/
Windows windows/

配图 1：测试与示例全景图

#mermaid-svg-TsEnQgDR5lA0a5fd{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-TsEnQgDR5lA0a5fd .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-TsEnQgDR5lA0a5fd .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-TsEnQgDR5lA0a5fd .error-icon{fill:#552222;}#mermaid-svg-TsEnQgDR5lA0a5fd .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-TsEnQgDR5lA0a5fd .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-TsEnQgDR5lA0a5fd .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-TsEnQgDR5lA0a5fd .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-TsEnQgDR5lA0a5fd .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-TsEnQgDR5lA0a5fd .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-TsEnQgDR5lA0a5fd .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-TsEnQgDR5lA0a5fd .marker{fill:#333333;stroke:#333333;}#mermaid-svg-TsEnQgDR5lA0a5fd .marker.cross{stroke:#333333;}#mermaid-svg-TsEnQgDR5lA0a5fd svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-TsEnQgDR5lA0a5fd p{margin:0;}#mermaid-svg-TsEnQgDR5lA0a5fd .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-TsEnQgDR5lA0a5fd .cluster-label text{fill:#333;}#mermaid-svg-TsEnQgDR5lA0a5fd .cluster-label span{color:#333;}#mermaid-svg-TsEnQgDR5lA0a5fd .cluster-label span p{background-color:transparent;}#mermaid-svg-TsEnQgDR5lA0a5fd .label text,#mermaid-svg-TsEnQgDR5lA0a5fd span{fill:#333;color:#333;}#mermaid-svg-TsEnQgDR5lA0a5fd .node rect,#mermaid-svg-TsEnQgDR5lA0a5fd .node circle,#mermaid-svg-TsEnQgDR5lA0a5fd .node ellipse,#mermaid-svg-TsEnQgDR5lA0a5fd .node polygon,#mermaid-svg-TsEnQgDR5lA0a5fd .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-TsEnQgDR5lA0a5fd .rough-node .label text,#mermaid-svg-TsEnQgDR5lA0a5fd .node .label text,#mermaid-svg-TsEnQgDR5lA0a5fd .image-shape .label,#mermaid-svg-TsEnQgDR5lA0a5fd .icon-shape .label{text-anchor:middle;}#mermaid-svg-TsEnQgDR5lA0a5fd .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-TsEnQgDR5lA0a5fd .rough-node .label,#mermaid-svg-TsEnQgDR5lA0a5fd .node .label,#mermaid-svg-TsEnQgDR5lA0a5fd .image-shape .label,#mermaid-svg-TsEnQgDR5lA0a5fd .icon-shape .label{text-align:center;}#mermaid-svg-TsEnQgDR5lA0a5fd .node.clickable{cursor:pointer;}#mermaid-svg-TsEnQgDR5lA0a5fd .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-TsEnQgDR5lA0a5fd .arrowheadPath{fill:#333333;}#mermaid-svg-TsEnQgDR5lA0a5fd .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-TsEnQgDR5lA0a5fd .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-TsEnQgDR5lA0a5fd .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-TsEnQgDR5lA0a5fd .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-TsEnQgDR5lA0a5fd .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-TsEnQgDR5lA0a5fd .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-TsEnQgDR5lA0a5fd .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-TsEnQgDR5lA0a5fd .cluster text{fill:#333;}#mermaid-svg-TsEnQgDR5lA0a5fd .cluster span{color:#333;}#mermaid-svg-TsEnQgDR5lA0a5fd div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-TsEnQgDR5lA0a5fd .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-TsEnQgDR5lA0a5fd rect.text{fill:none;stroke-width:0;}#mermaid-svg-TsEnQgDR5lA0a5fd .icon-shape,#mermaid-svg-TsEnQgDR5lA0a5fd .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-TsEnQgDR5lA0a5fd .icon-shape p,#mermaid-svg-TsEnQgDR5lA0a5fd .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-TsEnQgDR5lA0a5fd .icon-shape .label rect,#mermaid-svg-TsEnQgDR5lA0a5fd .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-TsEnQgDR5lA0a5fd .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-TsEnQgDR5lA0a5fd .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-TsEnQgDR5lA0a5fd :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} examples 体系
测试金字塔
驱动
驱动
驱动
驱动
单元测试

tests/unit/

~200 文件

CPU
GPU 测试

tests/gpu/

~100 文件

单 GPU
Megatron 集成

tests/gpu_megatron/

~30 文件

多 GPU
TRT-LLM 后端

tests/gpu_trtllm/

~5 文件
vLLM 后端

tests/gpu_vllm/

~5 文件
回归测试

tests/regression/

~5 文件
示例测试

tests/examples/

~30 文件

端到端
PTQ 示例
QAT/QAD 示例
剪枝示例
蒸馏示例
稀疏示例
Speculative 示例
Puzzletron 示例
FastGen 示例
部署示例

说明 ：测试金字塔从下到上集成度递增、数量递减、运行时间递增。tests/examples/ 是最顶层------直接驱动 examples/ 中的端到端示例，确保用户示例可正常运行。

2. tests/ 测试体系

2.1 tests/_test_utils/ --- 通用工具

tests/_test_utils/torch/ --- 模型工厂

提供测试用的小模型，避免在 CI 中加载大模型：

文件 用途
`models.py`(file:///workspace/tests/_test_utils/torch/models.py) 通用 nn.Module 测试模型
`transformers_models.py`(file:///workspace/tests/_test_utils/torch/transformers_models.py) HuggingFace transformers 测试模型
`vision_models.py`(file:///workspace/tests/_test_utils/torch/vision_models.py) Vision 测试模型（ResNet / ViT）
`diffusers_models.py`(file:///workspace/tests/_test_utils/torch/diffusers_models.py) Diffusers 测试模型
`megatron/models.py`(file:///workspace/tests/_test_utils/torch/megatron/models.py) Megatron 测试模型
`nas_prune/models.py`(file:///workspace/tests/_test_utils/torch/nas_prune/models.py) NAS / Prune 测试模型
`quantization/models.py`(file:///workspace/tests/_test_utils/torch/quantization/models.py) 量化测试模型
`puzzletron/utils.py`(file:///workspace/tests/_test_utils/torch/puzzletron/utils.py) Puzzletron 测试工具
tests/_test_utils/examples/ --- 示例测试工具
文件 用途
`hf_ptq_utils.py`(file:///workspace/tests/_test_utils/examples/hf_ptq_utils.py) HF PTQ 示例测试工具
`run_command.py`(file:///workspace/tests/_test_utils/examples/run_command.py) 子进程运行命令工具

2.2 tests/unit/ --- 单元测试

按子系统组织，纯 CPU 运行：

复制代码 
tests/unit/
├── onnx/
│   ├── autocast/           # autocast 单元测试
│   ├── quantization/
│   │   ├── autotune/        # autotune 单元测试
│   │   └── ...
│   └── ...
├── recipe/                 # recipe 单元测试
│   ├── test_loader.py
│   └── test_presets.py
└── torch/
    ├── deploy/
    ├── distill/            # 蒸馏单元测试
    ├── export/             # 导出单元测试
    ├── fastgen/            # FastGen 单元测试
    ├── kernels/            # Triton kernel 单元测试
    ├── nas/                # NAS 单元测试
    ├── opt/                # opt 框架单元测试
    ├── peft/               # PEFT 单元测试
    ├── prune/              # 剪枝单元测试
    ├── puzzletron/         # Puzzletron 单元测试
    ├── quantization/       # 量化单元测试（~30 文件）
    ├── sparsity/           # 稀疏单元测试
    ├── speculative/        # Speculative 单元测试
    ├── trace/              # trace 单元测试
    └── utils/              # utils 单元测试
quantization/ 关键测试
测试文件 验证内容
test_quantize_cpu.py 基础量化 API
test_tensor_quantizer_cpu.py TensorQuantizer 行为
test_calibrator.py 校准器实现
test_calib.py 校准流程
test_autoquant.py AutoQuantize 搜索
test_gptq.py GPTQ 算法
test_local_hessian.py local_hessian 算法
test_mse_calibrator.py MSE 校准器
test_nvfp4_*.py (4 个) NVFP4 相关
test_quant_*.py (10 个) 各层类型量化
test_config_validation.py 配置校验
opt/ 关键测试
测试文件 验证内容
test_chaining.py mode 链式调用
test_dynamic.py DynamicModule 行为
test_load_modelopt_state.py state 加载
test_mode_registry.py mode 注册
test_config.py 配置系统
plugins/test_*.py (5 个) 插件集成
recipe/ 测试
测试文件 验证内容
test_loader.py 加载器（含 $import、dotlist）
test_presets.py 预设管理

2.3 tests/gpu/ --- GPU 测试

镜像 tests/unit/ 但运行在 CUDA 上，验证 GPU 路径：

复制代码 
tests/gpu/
├── _extensions/           # C++/Triton 扩展测试
├── onnx/
│   └── quantization/      # ONNX 量化 GPU 测试
├── torch/
│   ├── deploy/            # 部署 GPU 测试
│   ├── export/            # 导出 GPU 测试
│   ├── kernels/           # Triton kernel GPU 测试
│   ├── nas/               # NAS GPU 测试
│   ├── opt/               # opt GPU 测试
│   ├── prune/             # 剪枝 GPU 测试
│   ├── puzzletron/        # Puzzletron GPU 测试
│   ├── quantization/      # 量化 GPU 测试
│   ├── sparsity/          # 稀疏 GPU 测试
│   ├── speculative/       # Speculative GPU 测试
│   └── utils/             # utils GPU 测试
└── conftest.py

2.4 tests/gpu_megatron/ --- Megatron 集成测试

专门测试 Megatron-LM 集成：

复制代码 
tests/gpu_megatron/torch/
├── distill/plugins/test_distill_megatron.py
├── export/
│   ├── test_megatron_importer.py
│   ├── test_unified_export_megatron.py
│   └── test_vllm_fakequant_megatron_export.py
├── nas/plugins/
│   ├── test_megatron_gpt_dynamic_modules.py
│   ├── test_megatron_mamba_dynamic_modules.py
│   └── test_megatron_model_stats.py
├── opt/plugins/test_megatron_chaining.py
├── peft/plugins/test_megatron_peft.py
├── prune/plugins/
│   ├── test_mcore_gpt_minitron_pruning.py
│   └── test_mcore_mamba_minitron_pruning.py
├── quantization/plugins/
│   ├── test_apex.py
│   ├── test_megatron.py
│   └── test_transformer_engine.py
├── sparsity/weight_sparsity/plugins/test_megatron_sparsity.py
├── speculative/plugins/test_speculative_megatron_modules.py
└── utils/plugins/test_utils_megatron.py

2.5 tests/gpu_trtllm/ 与 tests/gpu_vllm/ --- 后端测试

TRT-LLM 后端
复制代码 
tests/gpu_trtllm/torch/quantization/backends/
├── test_fp8_per_tensor_gemm.py
├── test_gemm_common.py
├── test_gemm_registry.py
└── test_nvfp4_gemm.py
vLLM 后端
复制代码 
tests/gpu_vllm/torch/
├── puzzletron/test_calc_runtime_stats.py
├── quantization/test_vllm_dynamic_modules.py
└── sparsity/attention_sparsity/
    ├── test_sparse_attn_worker.py
    └── test_vllm_plugin.py

2.6 tests/regression/ --- 回归测试

复制代码 
tests/regression/torch/speculative/
├── test_dflash.py
└── test_dflash_offline.py

回归测试针对关键路径（如 DFlash speculative decoding）做端到端验证，防止性能或精度回归。

2.7 tests/examples/ --- 端到端示例测试

按 examples/ 目录组织，每个示例都有对应测试：

复制代码 
tests/examples/
├── hf_ptq/
│   ├── test_llm_ptq.py
│   ├── test_vlm_ptq.py
│   ├── test_cast_mxfp4_to_nvfp4.py
│   ├── test_deploy.py
│   ├── test_hf_ptq_args.py
│   └── test_example_utils.py
├── llm_qat/
│   ├── test_llm_qat.py
│   ├── test_assistant_mask.py
│   └── test_dataset_tokenization.py
├── megatron_bridge/
│   ├── test_distill.py
│   ├── test_prune_minitron.py
│   ├── test_qad.py
│   └── test_quantize_export.py
├── speculative_decoding/
│   ├── test_eagle.py
│   └── test_eagle_offline_ptq.py
├── diffusers/
│   ├── test_diffusers.py
│   ├── test_cache_diffusion.py
│   └── test_export_diffusers_hf_ckpt.py
├── ... 等

2.8 pytest 配置

  • `tests/conftest.py`(file:///workspace/tests/conftest.py)：全局 fixture
  • 各子目录 conftest.py：子目录级 fixture
  • 通过 pytest 命令运行，支持 marker 分类（如 @pytest.mark.gpu）

配图 2：测试金字塔与运行环境矩阵

#mermaid-svg-wZNcyD1d27WoDFy9{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-wZNcyD1d27WoDFy9 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-wZNcyD1d27WoDFy9 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-wZNcyD1d27WoDFy9 .error-icon{fill:#552222;}#mermaid-svg-wZNcyD1d27WoDFy9 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-wZNcyD1d27WoDFy9 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-wZNcyD1d27WoDFy9 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-wZNcyD1d27WoDFy9 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-wZNcyD1d27WoDFy9 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-wZNcyD1d27WoDFy9 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-wZNcyD1d27WoDFy9 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-wZNcyD1d27WoDFy9 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-wZNcyD1d27WoDFy9 .marker.cross{stroke:#333333;}#mermaid-svg-wZNcyD1d27WoDFy9 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-wZNcyD1d27WoDFy9 p{margin:0;}#mermaid-svg-wZNcyD1d27WoDFy9 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-wZNcyD1d27WoDFy9 .cluster-label text{fill:#333;}#mermaid-svg-wZNcyD1d27WoDFy9 .cluster-label span{color:#333;}#mermaid-svg-wZNcyD1d27WoDFy9 .cluster-label span p{background-color:transparent;}#mermaid-svg-wZNcyD1d27WoDFy9 .label text,#mermaid-svg-wZNcyD1d27WoDFy9 span{fill:#333;color:#333;}#mermaid-svg-wZNcyD1d27WoDFy9 .node rect,#mermaid-svg-wZNcyD1d27WoDFy9 .node circle,#mermaid-svg-wZNcyD1d27WoDFy9 .node ellipse,#mermaid-svg-wZNcyD1d27WoDFy9 .node polygon,#mermaid-svg-wZNcyD1d27WoDFy9 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-wZNcyD1d27WoDFy9 .rough-node .label text,#mermaid-svg-wZNcyD1d27WoDFy9 .node .label text,#mermaid-svg-wZNcyD1d27WoDFy9 .image-shape .label,#mermaid-svg-wZNcyD1d27WoDFy9 .icon-shape .label{text-anchor:middle;}#mermaid-svg-wZNcyD1d27WoDFy9 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-wZNcyD1d27WoDFy9 .rough-node .label,#mermaid-svg-wZNcyD1d27WoDFy9 .node .label,#mermaid-svg-wZNcyD1d27WoDFy9 .image-shape .label,#mermaid-svg-wZNcyD1d27WoDFy9 .icon-shape .label{text-align:center;}#mermaid-svg-wZNcyD1d27WoDFy9 .node.clickable{cursor:pointer;}#mermaid-svg-wZNcyD1d27WoDFy9 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-wZNcyD1d27WoDFy9 .arrowheadPath{fill:#333333;}#mermaid-svg-wZNcyD1d27WoDFy9 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-wZNcyD1d27WoDFy9 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-wZNcyD1d27WoDFy9 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-wZNcyD1d27WoDFy9 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-wZNcyD1d27WoDFy9 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-wZNcyD1d27WoDFy9 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-wZNcyD1d27WoDFy9 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-wZNcyD1d27WoDFy9 .cluster text{fill:#333;}#mermaid-svg-wZNcyD1d27WoDFy9 .cluster span{color:#333;}#mermaid-svg-wZNcyD1d27WoDFy9 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-wZNcyD1d27WoDFy9 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-wZNcyD1d27WoDFy9 rect.text{fill:none;stroke-width:0;}#mermaid-svg-wZNcyD1d27WoDFy9 .icon-shape,#mermaid-svg-wZNcyD1d27WoDFy9 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-wZNcyD1d27WoDFy9 .icon-shape p,#mermaid-svg-wZNcyD1d27WoDFy9 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-wZNcyD1d27WoDFy9 .icon-shape .label rect,#mermaid-svg-wZNcyD1d27WoDFy9 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-wZNcyD1d27WoDFy9 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-wZNcyD1d27WoDFy9 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-wZNcyD1d27WoDFy9 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 运行环境矩阵
测试金字塔
运行于
运行于
运行于
运行于
运行于
运行于
运行于
运行于
单元测试 unit/

~200 文件

CPU only
GPU 测试 gpu/

~100 文件

单 GPU + CUDA
Megatron 集成 gpu_megatron/

~30 文件

多 GPU + Megatron-LM
TRT-LLM gpu_trtllm/

~5 文件

GPU + TensorRT-LLM
vLLM gpu_vllm/

~5 文件

GPU + vLLM
回归 regression/

~5 文件

关键路径
示例 examples/

~30 文件

端到端
CPU
CUDA
Megatron-LM
TensorRT-LLM
vLLM
SGLang

说明：测试金字塔的运行环境矩阵从单一（CPU）逐步扩展到完整推理栈。CI 流水线通常按层级分阶段运行：unit 先跑（快速反馈），GPU / Megatron 后跑（慢但覆盖广），examples 最后跑（端到端）。

3. examples/ 端到端示例

3.1 PTQ 示例

examples/hf_ptq/ --- HuggingFace LLM/VLM PTQ

`examples/hf_ptq/`(file:///workspace/examples/hf_ptq/) 是 ModelOpt 最核心的 PTQ 示例：

文件 用途
`hf_ptq.py`(file:///workspace/examples/hf_ptq/hf_ptq.py) 主入口脚本
`example_utils.py`(file:///workspace/examples/hf_ptq/example_utils.py) 通用工具
`multinode_ptq.py`(file:///workspace/examples/hf_ptq/multinode_ptq.py) 多节点 PTQ
`nemotron_vl_calib.py`(file:///workspace/examples/hf_ptq/nemotron_vl_calib.py) Nemotron VL 校准
`vlm_utils.py`(file:///workspace/examples/hf_ptq/vlm_utils.py) VLM 工具
`cast_mxfp4_to_nvfp4.py`(file:///workspace/examples/hf_ptq/cast_mxfp4_to_nvfp4.py) MXFP4 → NVFP4 转换
`run_tensorrt_llm.py`(file:///workspace/examples/hf_ptq/run_tensorrt_llm.py) TRT-LLM 部署验证
notebooks/ (3 个) 交互式教程（FP4-FP8 / AWQ / AutoQuant）
scripts/ Bash 启动脚本
examples/vlm_ptq/ --- VLM PTQ 简化版

`examples/vlm_ptq/`(file:///workspace/examples/vlm_ptq/) 提供更简单的 VLM PTQ 入口。

examples/onnx_ptq/ --- ONNX PTQ
子目录 用途
`autotune/`(file:///workspace/examples/onnx_ptq/autotune/) autotune 调优示例
`custom_op_plugin/`(file:///workspace/examples/onnx_ptq/custom_op_plugin/) 自定义算子插件
evaluate.py / evaluation.py 精度评估
image_prep.py 图像预处理
download_example_onnx.py 下载示例 ONNX 模型
examples/torch_onnx/ --- PyTorch → ONNX 转换

`examples/torch_onnx/torch_quant_to_onnx.py`(file:///workspace/examples/torch_onnx/torch_quant_to_onnx.py) 把 PyTorch 量化模型转为 ONNX 量化模型。

examples/windows/ --- Windows 平台

支持 Windows 部署，含：

  • diffusers/（含 QAD 示例）
  • onnx_ptq/（genai_llm / sam2 / whisper）
  • torch_onnx/diffusers/
  • accuracy_benchmark/（mmlu / perplexity / kl_divergence / fvd_metrics）

3.2 QAT/QAD 示例

examples/llm_qat/ --- LLM QAT

完整 QAT 训练流程：

文件 / 目录 用途
`simple_qat_train.py`(file:///workspace/examples/llm_qat/simple_qat_train.py) 简化版 QAT 入口
`train.py`(file:///workspace/examples/llm_qat/train.py) 完整训练入口
`arguments.py`(file:///workspace/examples/llm_qat/arguments.py) 参数定义
`dataset_utils.py`(file:///workspace/examples/llm_qat/dataset_utils.py) 数据集工具
`export.py`(file:///workspace/examples/llm_qat/export.py) 导出工具
`quantize.py`(file:///workspace/examples/llm_qat/quantize.py) 量化工具
configs/accelerate/ DDP / DeepSpeed / FSDP2 配置
configs/dataset/ 数据集 blend 配置
configs/train/ 训练配置（qat_nvfp4 / qad_nvfp4 / qlora_nvfp4）
llama_factory/ LLaMA-Factory 集成
notebooks/ 交互式教程
ARGUMENTS.md / README.md 文档
examples/llm_qad/ --- QAD（PTQ + 微调）

`examples/llm_qad/`(file:///workspace/examples/llm_qad/) 提供量化感知部署（QAD）工作流。

examples/gpt-oss/ --- gpt-oss QAT

`examples/gpt-oss/`(file:///workspace/examples/gpt-oss/) 针对 OpenAI gpt-oss 模型的 QAT：

  • sft.py：SFT 训练
  • convert_oai_mxfp4_weight_only.py：MXFP4 权重转换
  • notebooks/qat-finetune-transformers.ipynb：交互式教程
examples/cnn_qat/ --- CNN QAT

`examples/cnn_qat/torchvision_qat.py`(file:///workspace/examples/cnn_qat/torchvision_qat.py) 针对 torchvision 模型（如 ResNet50）的 QAT。

examples/alpamayo/ --- 校准数据集

`examples/alpamayo/`(file:///workspace/examples/alpamayo/) 提供用于校准的小数据集。

3.3 剪枝示例

examples/pruning/minitron/ --- Minitron 端到端

`examples/pruning/minitron/`(file:///workspace/pruning/minitron/) 是 Minitron 工作流的核心示例，包含：

  • NVIDIA-Nemotron-3-Nano-30B-A3B-BF16/：30B 模型端到端
  • NVIDIA-Nemotron-Nano-9B-v2/：9B 模型端到端
  • 含 README.md / ABLATIONS.md / nemo_evaluator.yaml / figures/
examples/pruning/puzzletron/ --- Puzzletron 单独示例

`examples/pruning/puzzletron/`(file:///workspace/examples/pruning/puzzletron/) 提供 Llama-3.1-8B-Instruct 的 Puzzletron 应用示例。

examples/pruning/minitron_vs_puzzletron/ --- 对比实验

`examples/pruning/minitron_vs_puzzletron/`(file:///workspace/examples/pruning/minitron_vs_puzzletron/) 提供 4 个对比场景：

  • scenario1_minitron.ipynb
  • scenario1_puzzletron.ipynb
  • scenario2_minitron.ipynb
  • scenario2_puzzletron.ipynb
  • 含 figures/（distillation_curves / memory_sweep / summary_chart 等对比图）
  • advanced_compression_experiments.md
examples/pruning/cifar_resnet.ipynb --- CNN 剪枝入门

简单 CIFAR + ResNet 剪枝示例，适合学习 NAS API。

3.4 蒸馏示例

examples/llm_distill/ --- HuggingFace 蒸馏

`examples/llm_distill/`(file:///workspace/examples/llm_distill/) 基于 HuggingFace + accelerate：

  • main.py：主入口
  • accelerate_config/fsdp2.yaml：FSDP2 分布式配置
examples/megatron_bridge/distill.py --- Megatron 蒸馏

`examples/megatron_bridge/distill.py`(file:///workspace/examples/megatron_bridge/distill.py) 在 Megatron-Bridge 中执行蒸馏。

examples/diffusers/distillation/ --- 扩散模型蒸馏

`examples/diffusers/distillation/`(file:///workspace/examples/diffusers/distillation/) 提供扩散模型蒸馏示例（含 distillation_trainer.py）。

3.5 稀疏示例

examples/llm_sparsity/attention_sparsity/ --- Attention 稀疏

`examples/llm_sparsity/attention_sparsity/`(file:///workspace/examples/llm_sparsity/attention_sparsity/) 提供 attention 稀疏化端到端示例：

  • hf_sa.py：HuggingFace attention 稀疏化
  • download_ruler_data.sh：下载 RULER 长上下文基准数据
examples/llm_sparsity/weight_sparsity/ --- 权重稀疏

`examples/llm_sparsity/weight_sparsity/`(file:///workspace/examples/llm_sparsity/weight_sparsity/) 提供权重稀疏端到端：

  • data_prep.py：数据准备
  • hf_pts.py：HF 权重稀疏化（PTS = Post-Training Sparsification）
  • finetune.py：稀疏后微调
  • eval.py：评估
  • export_trtllm_ckpt.py：TRT-LLM 检查点导出
  • launch_finetune.sh：启动脚本
examples/diffusers/sparsity/ --- 扩散模型稀疏

`examples/diffusers/sparsity/wan22_skip_softmax.py`(file:///workspace/examples/diffusers/sparsity/wan22_skip_softmax.py) 针对 Wan2.2 扩散模型的 attention 稀疏化。

3.6 Speculative 示例

examples/speculative_decoding/ --- EAGLE3 训练全流程

`examples/speculative_decoding/`(file:///workspace/examples/speculative_decoding/) 是 EAGLE3 完整训练流程：

文件 / 目录 用途
main.py 训练主入口
eagle_utils.py / medusa_utils.py 算法工具
example.ipynb 交互式教程
launch_train.sh / slurm.sh 启动脚本
collect_hidden_states/ hidden states 收集（HF / TRT-LLM / vLLM 三种）
distributed_generate/ 分布式生成
pipeline/eagle3/ EAGLE3 专用 pipeline
recipes/ 训练配置（CR2 / Nemotron mapping）
scripts/ 辅助脚本（export / merge_lora / eval_lora 等）
doc/dflash.md DFlash 文档
examples/specdec_bench/ --- Speculative Benchmark

`examples/specdec_bench/`(file:///workspace/examples/specdec_bench/) 提供完整的 speculative decoding benchmark 框架：

  • specdec_bench/models/：支持 vLLM / SGLang / TRT-LLM / SpecBench Medusa
  • specdec_bench/datasets/：mtbench / specbench / speed / random_token
  • specdec_bench/metrics/：acceptance_rate / timing / aa_timing

3.7 Puzzletron 示例

`examples/puzzletron/`(file:///workspace/examples/puzzletron/) 提供 8 种模型的 Puzzletron 配置：

模型 配置目录
GPT-OSS-20B configs/gptoss-20b_remove_experts_memory/
Llama-3.1-8B configs/llama-3_1-8B_pruneffn_memory/ + llama-3_1-8B_pruneffn_runtime/
Llama-3.2-3B configs/llama-3_2-3B_pruneffn_memory/
Mistral-Small-24B configs/mistral-small-24b-instruct-2501_pruneffn_memory/
Nemotron-Nano-12B-v2 configs/nemotron-nano-12b-v2/
Nemotron-Nano-30B-A3B-v3 configs/nemotron-nano-30b-A3b-v3/
Qwen2.5-7B configs/qwen2_5_7b_instruct_pruneffn_memory/
Qwen3-8B configs/qwen3-8b_pruneffn_memory/

主入口 `examples/puzzletron/main.py`(file:///workspace/examples/puzzletron/main.py)，含 evaluation/hf_deployable_anymodel.py。

3.8 Diffusion FastGen 示例

`examples/diffusers/fastgen/`(file:///workspace/examples/diffusers/fastgen/) 提供 DMD2 + Qwen-Image 端到端：

文件 用途
dmd2_finetune.py DMD2 训练
dmd2_recipe.py 训练配方
fastgen_checkpoint.py checkpoint 管理
inference_dmd2_qwen_image.py 推理
export_diffusers_qwen_image.py 导出
preprocess_qwen_image.py 数据预处理
make_negative_prompt_embedding.py 负提示词 embedding
configs/dmd2_qwen_image.yaml 配置

3.9 部署示例

examples/model_hub/ --- 模型中心

`examples/model_hub/`(file:///workspace/examples/model_hub/) 提供三种部署框架的统一示例：

  • run_llama_fp8_vllm.py
  • run_llama_fp8_sglang.py
  • run_llama_fp8_trtllm.py
examples/vllm_serve/ --- vLLM 服务

`examples/vllm_serve/`(file:///workspace/examples/vllm_serve/) 含：

  • vllm_serve_fakequant.py：fakequant worker
  • vllm_serve_sparse_attn.py：sparse attention worker
  • vllm_ptq_utils.py / vllm_reload_utils.py：工具
examples/torch_trt/ --- Torch-TRT PTQ

`examples/torch_trt/torch_tensorrt_ptq.py`(file:///workspace/examples/torch_trt/torch_tensorrt_ptq.py) 提供 Torch-TensorRT PTQ 示例。

3.10 数据集与评测

examples/dataset/ --- 数据集工具

`examples/dataset/`(file:///workspace/examples/dataset/) 提供数据集制作工具，含 Nemotron PT v2/v3 数据集制作（make_nemotron_ptv2_dataset.py / make_nemotron_ptv3_dataset.py）。

examples/deepseek/ --- DeepSeek 量化

`examples/deepseek/`(file:///workspace/examples/deepseek/) 提供 DeepSeek-V3 / V4 的 NVFP4 量化示例。

examples/llm_eval/ --- 评测

`examples/llm_eval/`(file:///workspace/examples/llm_eval/) 提供多种评测：

  • mmlu.py：MMLU 评测
  • livecodebench.py：LiveCodeBench
  • simple_evals.py：简单评测集
  • lm_eval_hf.py / lm_eval_tensorrt_llm.py：基于 lm-eval 的评测
  • run_lm_eval_vllm.sh / run_simple_eval.sh / run_livecodebench.sh：启动脚本
examples/researcher_guide/

`examples/researcher_guide/`(file:///workspace/examples/researcher_guide/) 为研究人员提供的指南。

配图 3：examples 目录树状图

#mermaid-svg-zWzxxp5883OEHWrz{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-zWzxxp5883OEHWrz .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-zWzxxp5883OEHWrz .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-zWzxxp5883OEHWrz .error-icon{fill:#552222;}#mermaid-svg-zWzxxp5883OEHWrz .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-zWzxxp5883OEHWrz .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-zWzxxp5883OEHWrz .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-zWzxxp5883OEHWrz .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-zWzxxp5883OEHWrz .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-zWzxxp5883OEHWrz .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-zWzxxp5883OEHWrz .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-zWzxxp5883OEHWrz .marker{fill:#333333;stroke:#333333;}#mermaid-svg-zWzxxp5883OEHWrz .marker.cross{stroke:#333333;}#mermaid-svg-zWzxxp5883OEHWrz svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-zWzxxp5883OEHWrz p{margin:0;}#mermaid-svg-zWzxxp5883OEHWrz .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-zWzxxp5883OEHWrz .cluster-label text{fill:#333;}#mermaid-svg-zWzxxp5883OEHWrz .cluster-label span{color:#333;}#mermaid-svg-zWzxxp5883OEHWrz .cluster-label span p{background-color:transparent;}#mermaid-svg-zWzxxp5883OEHWrz .label text,#mermaid-svg-zWzxxp5883OEHWrz span{fill:#333;color:#333;}#mermaid-svg-zWzxxp5883OEHWrz .node rect,#mermaid-svg-zWzxxp5883OEHWrz .node circle,#mermaid-svg-zWzxxp5883OEHWrz .node ellipse,#mermaid-svg-zWzxxp5883OEHWrz .node polygon,#mermaid-svg-zWzxxp5883OEHWrz .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-zWzxxp5883OEHWrz .rough-node .label text,#mermaid-svg-zWzxxp5883OEHWrz .node .label text,#mermaid-svg-zWzxxp5883OEHWrz .image-shape .label,#mermaid-svg-zWzxxp5883OEHWrz .icon-shape .label{text-anchor:middle;}#mermaid-svg-zWzxxp5883OEHWrz .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-zWzxxp5883OEHWrz .rough-node .label,#mermaid-svg-zWzxxp5883OEHWrz .node .label,#mermaid-svg-zWzxxp5883OEHWrz .image-shape .label,#mermaid-svg-zWzxxp5883OEHWrz .icon-shape .label{text-align:center;}#mermaid-svg-zWzxxp5883OEHWrz .node.clickable{cursor:pointer;}#mermaid-svg-zWzxxp5883OEHWrz .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-zWzxxp5883OEHWrz .arrowheadPath{fill:#333333;}#mermaid-svg-zWzxxp5883OEHWrz .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-zWzxxp5883OEHWrz .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-zWzxxp5883OEHWrz .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zWzxxp5883OEHWrz .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-zWzxxp5883OEHWrz .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zWzxxp5883OEHWrz .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-zWzxxp5883OEHWrz .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-zWzxxp5883OEHWrz .cluster text{fill:#333;}#mermaid-svg-zWzxxp5883OEHWrz .cluster span{color:#333;}#mermaid-svg-zWzxxp5883OEHWrz div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-zWzxxp5883OEHWrz .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-zWzxxp5883OEHWrz rect.text{fill:none;stroke-width:0;}#mermaid-svg-zWzxxp5883OEHWrz .icon-shape,#mermaid-svg-zWzxxp5883OEHWrz .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zWzxxp5883OEHWrz .icon-shape p,#mermaid-svg-zWzxxp5883OEHWrz .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-zWzxxp5883OEHWrz .icon-shape .label rect,#mermaid-svg-zWzxxp5883OEHWrz .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zWzxxp5883OEHWrz .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-zWzxxp5883OEHWrz .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-zWzxxp5883OEHWrz :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} examples/
PTQ
hf_ptq/
vlm_ptq/
onnx_ptq/
torch_onnx/
windows/
QAT/QAD
llm_qat/
llm_qad/
gpt-oss/
cnn_qat/
alpamayo/
剪枝
pruning/minitron/
pruning/puzzletron/
pruning/minitron_vs_puzzletron/
蒸馏
llm_distill/
megatron_bridge/distill.py
diffusers/distillation/
稀疏
llm_sparsity/attention_sparsity/
llm_sparsity/weight_sparsity/
diffusers/sparsity/
Speculative
speculative_decoding/
specdec_bench/
Puzzletron
puzzletron/
FastGen
diffusers/fastgen/
部署
model_hub/
vllm_serve/
torch_trt/
工具
dataset/
deepseek/
llm_eval/
researcher_guide/
benchmark.md

说明 ：examples 按「技术 + 场景」双维度组织。每个示例都对应 tests/examples/ 中的测试，确保示例可正常运行。

4. 本篇使用指南

4.1 如何运行单元测试

bash 复制代码 
# 运行所有单元测试（CPU）
pytest tests/unit/

# 运行特定子系统的单元测试
pytest tests/unit/torch/quantization/test_quantize_cpu.py
pytest tests/unit/recipe/

# 运行特定测试
pytest tests/unit/torch/quantization/test_calibrator.py::test_max_calibrator

# 用 marker 筛选
pytest tests/unit/ -m "not slow"

4.2 如何运行 GPU 测试

bash 复制代码 
# 需 CUDA 环境
pytest tests/gpu/torch/quantization/

# 运行 NVFP4 相关 GPU 测试
pytest tests/gpu/torch/quantization/test_nvfp4_*.py

# 运行 kernel 测试
pytest tests/gpu/torch/kernels/

4.3 如何运行 Megatron 集成测试

bash 复制代码 
# 需多 GPU + Megatron-LM 安装
pytest tests/gpu_megatron/torch/prune/plugins/test_mcore_gpt_minitron_pruning.py

# 分布式运行（用 torchrun）
torchrun --nproc_per_node=8 -m pytest tests/gpu_megatron/torch/quantization/plugins/test_megatron.py

4.4 如何运行端到端示例

bash 复制代码 
# HF PTQ 示例（最常用）
cd examples/hf_ptq
bash scripts/huggingface_example.sh \
    --model.meta-llama/Llama-3.1-8B-Instruct \
    --qformat nvfp4 \
    --calib-size 512

# QAT 示例
cd examples/llm_qat
python train.py configs/train/qat_nvfp4.yaml

# EAGLE3 训练示例
cd examples/speculative_decoding
bash launch_train.sh recipes/CR2_eagle_config.json

4.5 如何为新功能添加测试

添加单元测试
  1. 在 tests/unit/torch/<subsystem>/ 下创建 test_<feature>.py
  2. 使用 _test_utils 中的模型工厂
  3. 遵循 AAA 模式（Arrange-Act-Assert）
python 复制代码 
# tests/unit/torch/quantization/test_my_feature.py
import pytest
import torch
from _test_utils.torch.quantization.models import SmallModel
import modelopt.torch.quantization as mtq

def test_my_quantization():
    # Arrange
    model = SmallModel()
    calib_loader = get_calib_loader()

    # Act
    model = mtq.quantize(model, quant_cfg="nvfp4", calibration_data=calib_loader)

    # Assert
    assert isinstance(model, torch.nn.Module)
    # ... 更具体的断言
添加示例测试
  1. 在 tests/examples/<example_name>/ 下创建 test_<scenario>.py
  2. 用 _test_utils/examples/run_command.py 运行示例
  3. 验证输出
python 复制代码 
# tests/examples/hf_ptq/test_my_scenario.py
from _test_utils.examples import run_command

def test_my_quantization_scenario(tmp_path):
    cmd = f"python examples/hf_ptq/hf_ptq.py --model tiny-llama --qformat nvfp4 --output {tmp_path}"
    run_command(cmd)
    assert (tmp_path / "config.json").exists()

5. 本篇效果对比

表 1：测试覆盖度（按子系统）

子系统 unit 测试数 gpu 测试数 megatron 测试数 后端测试数 总计
quantization ~30 ~25 ~5 TRT-LLM 4 + vLLM 1 ~65
opt ~10 ~5 ~3 --- ~18
export ~10 ~10 ~5 --- ~25
distill ~5 --- ~2 --- ~7
prune ~3 ~3 ~5 --- ~11
nas ~12 ~5 ~5 --- ~22
speculative ~5 ~3 ~3 vLLM 1 ~12
peft ~3 --- ~2 --- ~5
sparsity ~10 ~10 ~3 vLLM 2 ~25
puzzletron ~15 ~5 --- vLLM 1 ~21
fastgen ~5 ~5 --- --- ~10
recipe ~3 --- --- --- ~3
onnx ~25 ~15 --- --- ~40
utils/trace ~10 ~3 --- --- ~13
deploy ~5 ~5 --- TRT 5 ~15
总计 ~150 ~90 ~30 ~15 ~295

表 2：示例丰富度（按技术分类）

技术 示例数 含 notebook 含脚本 含文档
PTQ 5+ 3 5+ 5+
QAT/QAD 4 2 4 4
剪枝 4 5 1 4
蒸馏 3 --- 1 3
稀疏 3 --- 1 3
Speculative 2 1 5 2
Puzzletron 1 --- --- 2
FastGen 1 --- --- 1
部署 3 --- 3 3
数据/评测 3 --- 4 3
总计 29+ 11 24 29+

表 3：部署框架支持矩阵

部署框架 量化格式支持 性能 易用性 推荐场景 示例
vLLM FP8 / INT8 / INT4 AWQ / NVFP4 / MXFP4 / MXFP8 高 高 LLM 通用部署 model_hub/run_llama_fp8_vllm.py
SGLang FP8 / INT4 AWQ / NVFP4 高 高 高并发场景 model_hub/run_llama_fp8_sglang.py
TensorRT-LLM 全格式（含 NVFP4 静态） 极高 中 极致性能 model_hub/run_llama_fp8_trtllm.py / hf_ptq/run_tensorrt_llm.py
TensorRT INT8 / FP8 / INT4 / NVFP4 极高 中 ONNX 模型部署 torch_trt/torch_tensorrt_ptq.py
ONNX Runtime INT8 / FP8 中 高 跨平台兼容 windows/onnx_ptq/

表 4：测试运行时长（参考值）

测试层级 文件数 单文件平均耗时 总耗时（顺序） 总耗时（8 并行）
unit ~150 1--5 秒 ~10 分钟 ~1.5 分钟
gpu ~90 5--30 秒 ~30 分钟 ~5 分钟
gpu_megatron ~30 1--5 分钟 ~2 小时 ~20 分钟
gpu_trtllm ~5 1--3 分钟 ~10 分钟 ~3 分钟
gpu_vllm ~5 1--3 分钟 ~10 分钟 ~3 分钟
examples ~30 5--30 分钟 ~5 小时 ~1 小时
总计 ~310 --- ~8 小时 ~1.5 小时

注：耗时为参考值，实际取决于硬件（CPU / GPU 型号）、模型大小、校准数据量。

表 5：CI 流水线分阶段

阶段 触发 运行测试 通过条件 失败处理
Stage 1: Lint + Unit 每次 push tests/unit/ + 代码检查 100% 通过 阻塞合并
Stage 2: GPU PR 提交 tests/gpu/ 100% 通过 阻塞合并
Stage 3: Megatron 主分支变更 tests/gpu_megatron/ 关键路径通过 通知作者
Stage 4: Examples Release 前 tests/examples/ 100% 通过 阻塞发布
Stage 5: Regression Release 前 tests/regression/ 100% 通过 阻塞发布

下一篇：09 总览：使用指南与效果对比(file:///workspace/ReadCode/09_总览_使用指南与效果对比.md)

热门推荐
01GitHub 镜像站点02AI科技热点日报 | 2026年07月01日032026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？042026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf05幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南062026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片07AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路082026 年 AI 大模型 & AI 编程工具实战全总结09【AI】2026 年具身智能模型和世界模型总结102026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？