ModelOpt Launcher 完整指南：用 Slurm 与 Docker 统一提交量化、训练与评估任务

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

ModelOpt Launcher 是 Model-Optimizer 仓库内置的一套任务提交框架（位于tools/launcher），它把 PTQ 量化、训练、推理评估、投机解码（EAGLE3/DFLASH）等实验封装为 YAML 声明式流水线，一条命令即可在本地 Docker 环境或远程 Slurm 集群上运行，并自动完成代码打包、容器挂载、版本记录与结果元数据落盘。读完本文，你将掌握 launcher 的安装与快速上手、YAML 流水线的全部编写形式（typed task / raw script / inline 命令）、CLI 覆盖与调试技巧、hf_local模型缓存机制，以及基于core.py的工厂系统与打包挂载原理，可直接复制示例跑通第一个端到端量化任务。

ModelOpt Launcher 是什么

Model-Optimizer 是一个模型优化库，覆盖量化、蒸馏、剪枝、NAS、投机解码等方向；而tools/launcher是这个库的“任务编排层”：通过 launch.py 入口，将一条由多个任务组成的流水线提交到两种执行环境：

• Slurm 集群：经 SSH 隧道连接登录节点，PatternPackager将源码打成 tar.gz 并 rsync 到远端，通过srun/sbatch调度 GPU 容器任务；
• 本地 Docker：使用 NVIDIA 容器运行时在单机单卡上跑，适合快速调试。

启动器基于 nemo_run（pyproject.toml中声明依赖nemo-run>=0.8.0）构建实验、执行器与依赖关系，并在其上封装了统一的SandboxTask/SandboxPipeline抽象与工厂注册机制。README 中将定位概括为“Submit ModelOpt quantization, training, and evaluation jobs to Slurm clusters or run them locally with Docker”，即量化、训练、评估三类任务的一键提交。

快速上手：安装与首次运行

环境准备

# 安装 uv 包管理器 curl -LsSf https://astral.sh/uv/install.sh | sh # 初始化子模块（Megatron-LM 等依赖仓库） git submodule update --init --recursive

git submodule update会拉取tools/launcher/modules/下的依赖子模块（如 Megatron-LM）。模型优化库本体则通过一个自动创建的符号链接挂载进来（见下文“Model-Optimizer Symlink”），无需重复克隆。

本地单卡运行（Docker）

cd Model-Optimizer/tools/launcher uv run launch.py --yaml examples/Qwen/Qwen3-8B/megatron_lm_ptq_local.yaml hf_local=/mnt/hf-local --yes

• --yaml指定流水线配置文件；
• hf_local=/mnt/hf-local以 CLI 覆盖方式指定模型与数据集的本地根目录（会被挂载进容器为/hf-local）；
• --yes跳过提交前的确认提示。

hf_local一旦指定，launch.py会走 Docker 执行器分支，并把 job 产物目录自动改为当前目录下的local_experiments（见 launch.py 中if hf_local is not None: job_dir = os.path.join(os.getcwd(), "local_experiments")）。

Slurm 集群运行

export SLURM_HOST=login-node.example.com export SLURM_ACCOUNT=my_account export SLURM_HF_LOCAL=/mnt/hf-local export SLURM_JOB_DIR=/shared/experiments uv run launch.py --yaml examples/Qwen/Qwen3-8B/megatron_lm_ptq.yaml --yes

四个环境变量分别提供：登录节点主机名、计费账户、集群侧 HuggingFace 缓存路径（作为容器挂载源）、远端产物目录。

本地 vs 集群：README 中提示megatron_lm_ptq.yaml面向多卡 Slurm、megatron_lm_ptq_local.yaml面向单卡本地 Docker。以当前仓库实际文件为准，两个示例的slurm_config均为 1 节点 / 1 GPU（nodes: 1、gpus_per_node: 1），并行度TP=PP=EP=ETP=1；多卡运行时可在 YAML 或命令行中调大这些字段（见下文 CLI Overrides）。

目录结构：入口、核心与任务脚本

tools/launcher/ ├── launch.py # 主入口（nemo_run CLI entrypoint） ├── core.py # 核心逻辑（dataclasses、执行器构造、run loop） ├── slurm_config.py # SlurmConfig dataclass 与 slurm_factory ├── common/ # 脚本与类型化任务 │ ├── megatron_lm/quantize/ │ │ ├── quantize.sh # PTQ 量化 + MMLU 评估 + HF 导出 │ │ └── task.py # MegatronLMQuantizeTask（类型化配置） │ ├── tensorrt_llm/query.sh # TRT-LLM 服务 + 查询 │ ├── vllm/query.sh # vLLM 服务 + 查询 │ ├── eagle3/ # EAGLE3 投机解码脚本 │ └── specdec_bench/ # 投机解码基准测试 ├── examples/ # 示例配置 │ └── Qwen/Qwen3-8B/ │ ├── megatron_lm_ptq.yaml # PTQ（多卡/Slurm） │ ├── megatron_lm_ptq_local.yaml # PTQ（单卡/Docker） │ └── hf_offline_eagle3.yaml # EAGLE3 离线流水线 ├── tests/ # 单元测试 ├── modules/ # 依赖 │ ├── Megatron-LM/ # Git 子模块 │ └── Model-Optimizer -> ../.. # 符号链接（自动创建） └── docs/ # 文档 ├── configuration.md # YAML 格式、覆盖、hf_local ├── architecture.md # 设计、工厂系统、类型化任务 ├── testing.md # 测试与 CI ├── claude_code.md # Claude Code 工作流 └── contributing.md # 添加模型、Bug 报告

除 README 中列举的目录外，仓库实际还包含：common/hf/（HuggingFace PTQ 脚本）、common/megatron_bridge/、common/megatron_lm/train/sft.sh、common/megatron_lm/export/export.sh、common/smoke/（hostname.sh、nvidia_smi.sh冒烟测试）、common/specdec/等，以及覆盖 MiniMax、Qwen、Kimi、Nemotron、Gemma、gpt-oss 等多个模型的示例配置（examples）。tests/下现有 8 个测试模块（含test_examples_resolve.py、test_slurm_executor.py等），对应约 64 个单元测试。

配置体系：环境变量与三类 YAML 任务

环境变量一览

此外，launch.py 的 docstring 还补充了SLURM_USER（远端 SSH 用户名，默认本机登录名）、SLURM_PARTITION、SLURM_QOS、SLURM_MEM（均被 slurm_factory 读取为SlurmConfig默认值）。

形式一：类型化任务配置（推荐形态）

通过_target_引用类型化任务类，使用具名字段：

job_name: Qwen3-8B_NVFP4_DEFAULT_CFG pipeline: task_0: _target_: common.megatron_lm.quantize.task.MegatronLMQuantizeTask config: model: Qwen/Qwen3-8B quant_cfg: NVFP4_DEFAULT_CFG tp: 4 calib_size: 32 hf_local: /hf-local/ slurm_config: _factory_: "slurm_factory" nodes: 1 ntasks_per_node: 4 gpus_per_node: 4

MegatronLMQuantizeConfig的字段默认值（task.py）包括：model="Qwen/Qwen3-8B"、quant_cfg="NVFP4_DEFAULT_CFG"、tp=4、pp=1、ep=1、etp=1、calib_dataset="abisee/cnn_dailymail"、calib_size=32、calib_max_sequence_length=512、mmlu_dataset="cais/mmlu"、mmlu_fraction=0.01、mmlu_lower_bound=0.38、hf_local="/hf-local/"。materialize_from_config()会把类型化配置展开为底层script/args/environment字段。

重要事实说明：由于 nemo_run/Fiddle 在 YAML 加载时先于嵌套字段填充执行__post_init__，当前版本的类型化任务尚未重新接入SandboxPipeline（详见 task.py 的 NOTE 注释）。因此仓库内 Qwen3-8B 的实际示例 YAML 使用的是下面两种“raw”形式，类型化形态保留作未来启用参考——从源码结构看，这是当前唯一可直接跑通的写法。

形式二：Raw SandboxTask（当前示例实际采用的形态）

适用于无类型化任务类的脚本，直接指定脚本路径、参数与环境变量：

job_name: Qwen3-8B_NVFP4_DEFAULT_CFG pipeline: task_0: script: common/megatron_lm/quantize/quantize.sh args: - --calib-dataset-path-or-name /hf-local/abisee/cnn_dailymail - --calib-size 32 environment: - MLM_MODEL_CFG: Qwen/Qwen3-8B - QUANT_CFG: NVFP4_DEFAULT_CFG - TP: 4 slurm_config: _factory_: "slurm_factory" nodes: 1 ntasks_per_node: 4 gpus_per_node: 4

参考仓库中 megatron_lm_ptq.yaml：一个 3 步流水线——task_0用quantize.sh做 NVFP4 量化（含 MMLU 评估与导出，MMLU_LOWER_BOUND=0.68）、task_1做 FP8 量化（MMLU_LOWER_BOUND=0.75）、task_2用common/tensorrt_llm/eval.sh对导出 checkpoint 做 TRT-LLM 端侧 MMLU 评测（HF_MODEL_CKPT: /scratchspace/export）。quantize.sh内部依次调用 Megatron-LM 的quantize.sh→mmlu.sh→export.sh（脚本源码），并支持RUN_MMLU=false RUN_EXPORT=false关闭可选步骤、MLM_MODEL_SAVE指定 PTQ 产物持久化路径。

形式三：Inline 命令（无需包装脚本）

任务可直接携带inlineshell 命令（如 Megatron-Bridge 的torchrun单行任务），无需.sh包装脚本：

job_name: Qwen3-8B_mbridge_prune pipeline: global_vars: output_dir: /cicd/megatron-bridge task_0: environment: - LAUNCH_SCRIPT: torchrun --nproc_per_node 2 inline: >- $LAUNCH_SCRIPT modules/Model-Optimizer/examples/megatron_bridge/prune_minitron.py --hf_model_name_or_path Qwen/Qwen3-8B --pp_size 2 --prune_target_params 6e9 --output_hf_path <<global_vars.output_dir>>/Qwen3-8B-Pruned-6B slurm_config: _factory_: "slurm_factory" container: nvcr.io/nvidia/nemo:26.08 modelopt_install_path: /opt/venv/lib/python3.12/site-packages/modelopt nodes: 1 ntasks_per_node: 2 gpus_per_node: 2

使用约束（在 core.py 的run_jobs中有硬性校验）：

• inline必须为单行，CLI 层会拒绝多行值；YAML 中用折叠标量>-而非字面块|，命令间用&&串联；
• inline与args互斥，同时设置非空args会抛ValueError；
• 打包后的仓库位于modules/Model-Optimizer/...，运行目录即 CWD；
• 启动器在本地用torchrun、Slurm 上用python+srun，脚本内引用$LAUNCH_SCRIPT（普通$VAR，不要用${...}，否则与配置加载器冲突）；Slurm 上启动器会将其覆盖为python，因此需保证ntasks_per_node = gpus_per_node；
• <<global_vars.X>>会被解析替换为全局变量值。

容器内预装 pip 依赖（reqs/reqs_file）

任务可在容器内命令执行前先pip install（拼接为pip install [-r reqs_file] [reqs] && <command>）：

task_0: reqs: "transformers<5" # 或 "transformers<5 fire" 一次装多个 inline: >- python .../prune_minitron.py ... task_2: reqs_file: modules/Model-Optimizer/examples/llm_eval/requirements.txt inline: >- python .../lm_eval_hf.py ...

• reqs：原始pip install参数字符串，无需引号包裹版本符（启动器会对每个 token 做 shell 引号处理，<>=均安全）；
• reqs_file：指向运行目录（即modules/Model-Optimizer/...）下的 requirements.txt；
• 两者均可与inline、script任务搭配，并支持<<global_vars.X>>；
• Slurm 上安装只在每个节点的 local rank 0 执行一次（以 job/step/node ID 命名的文件系统屏障标记），多节点任务安全且避免同节点并发 pip 污染环境（run_jobs 中reqs_prefix的实现）。

多任务流水线：串行依赖与全局变量

任务按顺序执行，task_1只在task_0完成后启动；<<global_vars.X>>语法在任务间共享值（由SandboxPipeline.__post_init__用正则<<global_vars\.(\w+)>>替换解析）：

job_name: Qwen3-8B_quantize_export pipeline: global_vars: hf_model: /hf-local/Qwen/Qwen3-8B task_0: script: common/megatron_lm/quantize/quantize.sh environment: - HF_MODEL_CKPT: <<global_vars.hf_model>> slurm_config: _factory_: "slurm_factory" nodes: 1 task_1: script: common/megatron_lm/export/export.sh environment: - HF_MODEL_CKPT: <<global_vars.hf_model>> slurm_config: _factory_: "slurm_factory" nodes: 1

SandboxPipeline支持最多task_0到task_4五个槽位，另有global_vars、assets（提交前校验的 HF 仓库路径）、test_level、allow_to_fail、skip、note、task_configs等字段（core.py）。GlobalVariables内置hf_model、hf_data、hf_local、output_dir、draft_model（投机解码草稿模型路径，供 SPEED-bench 类 YAML 复用）等具名字段。若设置allow_to_fail: true，依赖类型会切换为afterany，前置任务失败也会继续执行下游任务。

两种配置入口：--yaml与pipeline=@

• --yaml config.yaml（推荐）：把顶层键映射为函数参数，包含job_name与pipeline：

uv run launch.py --yaml examples/Qwen/Qwen3-8B/megatron_lm_ptq.yaml --yes

• pipeline=@config.yaml：裸的SandboxPipeline（无job_name包装）：

uv run launch.py pipeline=@bare_pipeline.yaml job_name=my_job --yes

CLI 覆盖与常用 Flag

任意参数都可在命令行覆盖（点路径语法）：

# 修改节点数 uv run launch.py --yaml config.yaml pipeline.task_0.slurm_config.nodes=2 --yes # 修改容器镜像 uv run launch.py --yaml config.yaml \ pipeline.task_0.slurm_config.container=nvcr.io/nvidia/tensorrt-llm/release:1.2.0 --yes # 修改类型化配置字段 uv run launch.py --yaml config.yaml pipeline.task_0.config.tp=1 --yes

--dryrun是提交前的必备验证手段（见下文贡献指南），--to-yaml则可用于生成可复现的 Bug 报告配置。launch()入口还支持job_name、job_dir、user、identity（SSH 私钥）、detach、clean（对 examples 执行git clean -xdf）等参数（launch.py）。

hf_local：模型与数据集的自管理存储

流水线 YAML 用hf_local作为模型权重与数据集的路径前缀，它应是镜像 HuggingFace Hub 层级结构的自管理目录：

/hf-local/ ├── Qwen/Qwen3-8B/ ├── meta-llama/Llama-3.1-8B/ ├── abisee/cnn_dailymail/ └── cais/mmlu/

使用专用目录优于 HuggingFace 默认缓存（~/.cache/huggingface），可避免并发任务导致缓存损坏：

# 预下载 huggingface-cli download Qwen/Qwen3-8B --local-dir /hf-local/Qwen/Qwen3-8B # CLI 覆盖路径 uv run launch.py --yaml config.yaml pipeline.task_0.config.hf_local=/mnt/models/ --yes # 直接从 Hub 下载（不落本地缓存） uv run launch.py --yaml config.yaml pipeline.task_0.config.hf_local="" --yes

对 Slurm 集群，SLURM_HF_LOCAL决定容器挂载路径：在 slurm_factory 中默认生成"{SLURM_HF_LOCAL}:/hf-local"挂载；而本地 Docker 分支由 build_docker_executor 无条件挂载f"{hf_local}:/hf-local"。

架构设计：core 共享核心、工厂系统与挂载机制

共享核心与入口职责

core.py 是全部逻辑所在：

core.py ├── Dataclasses: SandboxTask, SandboxPipeline, GlobalVariables ├── Executor builders: build_slurm_executor(), build_docker_executor() ├── Job runner: run_jobs() ├── Version reporter: report_versions() ├── Factory registry: register_factory(), set_slurm_config_type() └── Default env: get_default_env() launch.py ├── imports core.py ├── slurm_config.py (env-var driven) ├── registers: slurm_factory ├── packager (LAUNCHER_DIR relative) └── launch() entrypoint

set_slurm_config_type(SlurmConfig)会把task_0..task_4字段的slurm_config类型替换为具体类，让 nemo-run 的 CLI 解析器能识别；register_factory("slurm_factory", slurm_factory)注册工厂。run_jobs循环按test_level过滤任务、顺序构造run.Script与执行器、通过exp.add(..., dependencies=[dependency])建立串行依赖，最终写出metadata.json。

工厂系统（Factory System）

YAML 中通过_factory_按名引用工厂：

slurm_config: _factory_: "slurm_factory" nodes: 1

工厂在 import 时经register_factory()注册。slurm_factory（slurm_config.py）读取环境变量SLURM_HOST、SLURM_ACCOUNT、SLURM_PARTITION（默认batch）、SLURM_QOS、SLURM_MEM生成SlurmConfig。SandboxPipeline.__post_init__中还有一层“工厂回填”逻辑：当 nemo_run 直接由 YAML 构造SlurmConfig导致host=None时，会以注册的slurm_factory为基底、叠加 YAML 中显式书写的字段，避免 SSH 连接报TypeError。

SlurmConfig关键字段与默认值

代码打包（PatternPackager）

PatternPackager将源码打成 tar.gz 并 rsync 到集群，code/目录镜像 launcher 结构：

code/ ├── modules/ │ ├── Megatron-LM/megatron/... │ └── Model-Optimizer/modelopt/... └── common/ ├── megatron_lm/quantize/quantize.sh ├── tensorrt_llm/query.sh ├── vllm/query.sh ├── eagle3/ └── query.py

launch.py 把examples、common、modules/Megatron-LM/megatron、modules/Megatron-LM/examples、modules/Model-Optimizer/modelopt、modelopt_recipes、examples等路径加入 include pattern（在 dev 检出时生效）。

ModelOpt 挂载机制与符号链接

容器镜像自带预装的 ModelOpt，launcher 会把本地modelopt/目录 bind-mount 覆盖到镜像内安装路径，使本地改动无需重建容器即可生效：

• Slurm：{job_dir}/{experiment_title}/{exp_id}/{task}/code/modules/Model-Optimizer/modelopt→{modelopt_install_path}
• Docker：{LAUNCHER_DIR}/modules/Model-Optimizer/modelopt→{modelopt_install_path}

同理还会把modelopt_recipes挂载到安装路径的同级目录。查询某个容器内 ModelOpt 实际安装路径：

docker run --rm <image> python3 -c "import modelopt; print(modelopt.__file__)"

tools/launcher/modules/Model-Optimizer是指向仓库根（../../..）的符号链接而非子模块，从而避免递归嵌套：Git 原生跟踪符号链接（git clone后保留）、launch.py首次运行若缺失会自动创建、打包器的find会跟随符号链接展开内容。

版本报告与元数据

每次运行开始会打印版本报告（report_versions()读取 launcher 及各子模块的 git commit 与分支）：

============================================================ Version Report ============================================================ Launcher d28acd33 (main) Megatron-LM 1e064f361 (main) Model-Optimizer 69c0d479 (main) ============================================================

每个实验在experiments/<title>/<id>/下写入metadata.json：

{ "experiment_id": "cicd_1773420387", "job_name": "Qwen3-8B_NVFP4_DEFAULT_CFG", "allow_to_fail": false, "note": "" }

默认环境注入

get_default_env()为每个任务注入默认环境变量：TRITON_CACHE_DIR、HF_HOME（默认/{title}/hf-cache，Slurm 侧另有HF_TOKEN与LAUNCH_SCRIPT=python）、MLM_SKIP_INSTALL=1，以及SPECDEC_BENCH_S3_*三个上传凭据（用于common/specdec_bench/upload_to_s3.sh发布基准结果，凭据无需写进 YAML）。

测试与 CI

在 launcher 目录本地运行测试：

cd Model-Optimizer/tools/launcher uv pip install -e . pytest uv run pytest -v

64 个单元测试覆盖范围（统计来自 docs/testing.md）：

CI 侧在每次 PR 都会运行 launcher 测试（工作流要求submodules: recursive检出并安装 uv 后uv run pytest -v），该 job 为 required check，测试失败则无法合入。按设计不在单测覆盖范围（需真实基础设施、手工验证）的是：真实 SSH 隧道与 sbatch 提交、带 GPU 负载的 Docker 容器启动、PatternPackager 的 tar.gz 与 rsync、nemo 实验状态/日志轮询。

扩展与贡献指南

添加一个新模型

1. 创建examples/<Organization>/<ModelName>/目录；
2. 使用类型化任务类添加 YAML 配置：

job_name: MyModel_NVFP4 pipeline: task_0: _target_: common.megatron_lm.quantize.task.MegatronLMQuantizeTask config: model: org/my-model quant_cfg: NVFP4_DEFAULT_CFG tp: 4 slurm_config: _factory_: "slurm_factory" nodes: 1 ntasks_per_node: 4 gpus_per_node: 4

3. 用 dry run 验证：uv run launch.py --yaml <path> --dryrun --yes -v；
4. 创建_local.yaml变体（tp: 1）用于单卡测试。

添加一个新的类型化任务

1. 在它包装的 shell 脚本旁创建common/<workflow>/task.py；
2. 定义配置 dataclass：

@dataclass class MyWorkflowConfig: """Typed config with named fields and defaults.""" model: str = "default/model" param: int = 4 hf_local: str = "/hf-local/"

3. 继承SandboxTask，在__post_init__中把类型化配置转换为script/args/environment：

@dataclass class MyWorkflowTask(SandboxTask): config: MyWorkflowConfig = None def __post_init__(self): if self.config: self.script = "common/<workflow>/run.sh" self.args = [f"--param {self.config.param}"] self.environment = [{"MODEL": self.config.model}]

4. 在 YAML 中通过_target_引用：

task_0: _target_: common.<workflow>.task.MyWorkflowTask config: model: org/my-model

报告 Bug

提交 issue 时附带三样东西：

1. 版本汇总——每次运行开头打印的 Version Report（见上文）；
2. 可复现配置——用--to-yaml导出：

uv run launch.py --yaml <config> --to-yaml bug_report.yaml

3. 错误输出——job 日志中的相关 traceback。

深入阅读

从一条uv run launch.py --yaml ... --yes命令出发，launcher 串联了 YAML 声明 → 工厂解析 → 代码打包 → SSH/Docker 执行器 → 串行任务依赖 → 版本与元数据记录的全链路，是 Model-Optimizer 中把“量化/训练/评估实验从单机验证推进到集群规模化”的标准化入口。如果你需要快速验证某个 PTQ 配置，先用_local.yaml变体在本机跑通，再通过 CLI 覆盖并行度与容器镜像切换到大集群即可。

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