企业官网建设流程全解析

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

本篇技术指南聚焦 NVIDIA Model-Optimizer 仓库中「Hugging Face 模型后训练量化（PTQ）」在 SLURM 集群上的完整落地路径，涵盖容器镜像准备（enroot/pyxis）、依赖管理与常见陷阱、基于device_map="auto"与 FSDP2 的 GPU 规模估算、多节点作业模板（sbatch与手动torchrun），以及提交前必做的冒烟测试流程。读完本文，你将能基于 examples/hf_ptq 的hf_ptq.py入口，在自己的 SLURM 集群上稳定、可复现地跑通从单卡 PTQ 到 200B+ 参数多节点 FSDP2 量化的完整作业。

一、背景：PTQ 为什么需要专门的 SLURM 配置

PTQ（Post-Training Quantization）用一小批校准样本（通常 128~512 条）确定量化缩放因子，从而把模型压缩到 NVFP4、FP8、INT8、INT4 等低精度格式。Model-Optimizer 仓库的 HF PTQ 流程统一由 examples/hf_ptq/hf_ptq.py 驱动，其加载模型时使用device_map="auto"自动填充可用 GPU，这决定了它与普通训练作业在集群规划上的差异：

• 单节点：device_map="auto"会自动把模型分层铺到本节点所有 GPU 上，因此申请的 GPU 数量只需「够用」，无需手动切分；
• 多节点（200B+ 参数）：需要--use_fsdp2走 PyTorch FSDP2 分布式分片，由 SLURM 逐节点拉起torchrun；
• 校准是前向过程：相比训练，显存与算力需求更低，但对容器内 Python 依赖的版本极其敏感（新架构模型往往需要更新的 transformers）。

仓库内为 PTQ skill 专门维护的 slurm-setup-ptq.md 与通用 skill 的 slurm-setup.md 共同构成了这套配置的知识体系，本文按「容器 → GPU 规模 → 冒烟测试」三条主线展开。

二、第一步：准备容器镜像（enroot / pyxis）

PTQ 校准必须运行在容器内（推荐使用 TensorRT-LLM 发布镜像），推荐的镜像版本号请以 examples/hf_ptq/README.md 为准（例如nvcr.io/nvidia/tensorrt-llm/release:<version>）。拿到版本号后，先检查集群上是否已有可复用的.sqsh镜像文件：

ls *.sqsh ../*.sqsh ~/containers/*.sqsh 2>/dev/null

• 如果存在.sqsh：直接使用--container-image=<path>，跳过导入步骤。这是最快的路径，也避免后续每次 smoke test / 重跑都重新拉取镜像。
• 如果不存在.sqsh：用 enroot 导入（导入产物会缓存，供后续冒烟测试与重跑复用）：

export ENROOT_CACHE_PATH=/path/to/writable/enroot-cache export ENROOT_DATA_PATH=/path/to/writable/enroot-data mkdir -p "$ENROOT_CACHE_PATH" "$ENROOT_DATA_PATH" enroot import --output /path/to/container.sqsh docker://nvcr.io#nvidia/tensorrt-llm/release:<version>

ENROOT_CACHE_PATH与ENROOT_DATA_PATH必须指向可写目录（尤其当你的工作目录位于 lustre 等并行文件系统时，权限问题很常见）。

pyxis 内联拉取作为兜底：若 enroot import 失败（例如 lustre 上的权限错误），可退化为 pyxis 内联拉取——直接把 NGC URI 传给--container-image="nvcr.io/nvidia/tensorrt-llm/release:<version>"。注意：这种方式的代价是每次作业都会重新拉取镜像，不产生本地缓存。

容器认证前置检查

pyxis 在计算节点拉取私有仓库（如nvcr.io）镜像时，需要集群上存在对应注册中心的凭据（~/.config/enroot/.credentials），否则srun会在拉取阶段报401 Unauthorized。提交任何会拉取镜像的作业前，建议先按 slurm-setup.md 第 6 节的步骤核对：

grep -E '^\s*machine\s+' ~/.config/enroot/.credentials 2>/dev/null

并预检镜像可拉性（凭据存在不代表镜像可访问）：

enroot import --output /dev/null docker://<registry>#<image> 2>&1 | head -10

三、容器内的依赖管理：三个关键陷阱

镜像就绪只是第一步，PTQ 作业的稳定性往往取决于容器内的 Python 依赖版本。以下是 slurm-setup-ptq.md 强调的三类高频问题。

1. 新模型需要更新的 transformers

TensorRT-LLM 容器内预装的 transformers 版本通常落后于最新模型架构的要求（检查模型的config.json中transformers_version字段即可确认）：

pip install -U transformers

对于未在支持列表中、且需要未发布版 transformers（如直接来自 transformers 仓库 git 源码）的模型，请参照 unsupported-models.md 的 Step A 处理。

2. 优先 editable install，而非 PYTHONPATH

在容器内让 Model-Optimizer 源码可导入，首选在仓库根目录执行：

pip install -e ".[hf]" --no-build-isolation

这正是 multinode_fsdp2_ptq.slurm 所采用的作业初始化方式。与PYTHONPATH相比，editable install 能在安装阶段暴露打包/编译问题，而不是把问题掩盖到 import 时才爆发。避免从 PyPI 执行pip install -U nvidia-modelopt[hf]，它可能连带升级 PyTorch 从而破坏容器内其他包。

若确实需要保持容器内已装包不被改动（例如绕开依赖冲突），才退回PYTHONPATH——但要清楚它的代价：跳过了 editable install，缺失的编译扩展只会在 import 时报错：

export PYTHONPATH=/path/to/Model-Optimizer:$PYTHONPATH

3. NGC 容器的 PIP_CONSTRAINT 会引发ResolutionImpossible

NGC 容器通常通过环境变量PIP_CONSTRAINT钉住一组版本，导致 pip 无法自由解析新依赖、直接报ResolutionImpossible。解决办法是先解除约束：

unset PIP_CONSTRAINT pip install -U transformers # 现在升级与解析都带上新依赖

若仍冲突，再退化为--no-deps（跳过新依赖，可能需要手动补装缺失项）：

pip install -U transformers --no-deps

依赖排查时的判读技巧（源自 unsupported-models.md）：ResolutionImpossible是依赖冲突而非网络故障，先看日志里有没有Connection refused/Name resolution failed再下结论。

四、GPU 规模估算：从单节点到 200B+ 多节点

单节点：让device_map="auto"自动填充

hf_ptq.py使用device_map="auto"（相关实现见 hf_ptq.py 中get_model的加载路径），因此只需申请恰好够用的 GPU 数量，不要多申请浪费配额。显存压力大时，脚本还提供了这些缓解手段：

多节点：--use_fsdp2的取舍

对于200B+ 参数的模型，单节点放不下时启用 FSDP2 分布式分片（world_size = 节点数 × 每节点 GPU 数）。多节点启动命令（sbatch与手动torchrun）以及--recipe格式，请参见 examples/hf_ptq/README.md 的Multi-Node Post-Training Quantization with FSDP2一节。

PTQ 路径上特有的规模判断依据：

• 当每 rank 的解码器分片逼近单卡容量（低 rank 数下的 200B+ 模型），二选一：增加节点数（更多 rank → 每个 rank 分片更小），或加--cpu_offload（把 decoder 分片在前向间隙留在 CPU，换取 GPU 显存，代价是 PCIe 流量增加——该参数定义见 hf_ptq.py）；
• 层检测是自动的：FSDP2 分片不需要写任何 YAML 层配置；
• --cpu_offload必须与--use_fsdp2组合使用，否则脚本直接报错（hf_ptq.py 的参数校验逻辑）；同时--use_fsdp2要求以torchrun启动，且不支持 KV-cache AutoQuantize recipe、sparsity、--cast_mxfp4_to_nvfp4等组合（脚本在加载模型前就会拒绝，见parse_args与load_model中的校验）。

性能提示：FSDP2 本身面向训练设计，校准与导出的耗时会比单节点更久；想提速就尽量放大--batch_size并选合适的 GPU 数以减少不必要的通信（见 examples/hf_ptq/README.md）。

五、多节点 FSDP2 作业模板逐行解析

仓库提供了开箱即用的多节点作业脚本 slurm/multinode_fsdp2_ptq.slurm，默认将nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16量化为 NVFP4 + FP8 KV cache。其核心结构如下：

#SBATCH --job-name=fsdp2-ptq #SBATCH --account={account} #SBATCH --partition={partition} #SBATCH --nodes=2 #SBATCH --ntasks-per-node=1 # 每节点一个 torchrun 启动器，再由它按 GPU 数展开进程 #SBATCH --gpus-per-node=8 #SBATCH --exclusive #SBATCH --time=04:00:00 #SBATCH --output=%x_%j.log set -euo pipefail # CONFIG 区：容器镜像、仓库路径、模型路径、导出目录、HF 缓存、recipe 与校准规模 export CONTAINER_IMAGE={container_image} export MODELOPT_PATH={path_to_modelopt_repo} export MODEL_PATH=nvidia/NVIDIA-Nemotron-3-Super-120B-A12B-BF16 export EXPORT_PATH={path_to_export_dir} export HF_HOME={path_to_hf_cache} export RECIPE=general/ptq/nvfp4_default-kv_fp8_cast export CALIB_SIZE=512 export BATCH_SIZE=4 # Rendezvous：节点 0 为主节点，所有 rank 汇聚到 MASTER_ADDR:MASTER_PORT export MASTER_ADDR=$(scontrol show hostnames "$SLURM_JOB_NODELIST" | head -1) export MASTER_PORT=29531

其中关键点：

1. --ntasks-per-node=1+srun --container-image：容器相关标志（--container-image、--container-mounts）必须放在srun行上，写成#SBATCH指令不生效（这是通用模板中反复强调的硬性规则，见 slurm-setup.md）；
2. srun启动的 bash 内再调用torchrun：--nnodes/--node_rank/--nproc_per_node分别取自 SLURM 环境变量，实现每个节点按本节点 GPU 数展开进程；
3. 容器挂载：仓库、导出目录、HF 缓存全部挂入容器，模型若为本地路径则额外挂载；HF_HOME持久化可避免 repo id 每次重新下载；
4. 容器内初始化：pip install -e "/modelopt[hf]" --no-build-isolation（即上文推荐的 editable install 方式）+pip install -r requirements.txt，然后执行校准命令；
5. 校准命令：hf_ptq.py --pyt_ckpt_path ... --recipe general/ptq/nvfp4_default-kv_fp8_cast --calib_size 512 --batch_size 4 --export_path ... --use_fsdp2，其中--recipe指向内置 recipe 名或自定义 YAML 路径。

**手动启动（无 SLURM）**时，在每台节点上自行执行等价的torchrun：

torchrun \ --nnodes=<num_nodes> --node_rank=<current_node_rank> \ --master_addr=<node0_ip_addr> --master_port=<port> \ --nproc_per_node=<num_gpus_per_node> \ hf_ptq.py \ --pyt_ckpt_path <path_to_model> \ --recipe general/ptq/nvfp4_default-kv_fp8_cast \ --batch_size <calib_batch_size> \ --calib_size <num_calib_samples> \ --export_path <export_path> \ --use_fsdp2

多节点作业的外层 wrapper建议直接复用通用 skill slurm-setup.md 第 4 节的 multi-node 模板。另外注意：--use_fsdp2要求每个srun任务保持 SLURM 分布式环境变量（与单进程脚本不同），因此不要像单节点脚本那样在容器内unset WORLD_SIZE/LOCAL_RANK/RANK——单节点device_map="auto"路径才需要 unset，否则 PyTorch 会误初始化进程组并把张量包装成 DTensor，破坏 NVFP4 导出。

六、提交前必做：冒烟测试

在正式校准作业（默认--calib_size 512）之前，务必先提交一个冒烟测试，用小代价提前暴露脚本错误，避免浪费 GPU 配额：

# 冒烟测试：极小校准规模 + 短时限 sbatch --time=00:30:00 ... # 作业内使用 --calib_size 4

冒烟测试的具体做法（通用 skill slurm-setup.md 第 2 节）：

• 使用逗号分隔的分区列表（如--partition=interactive,batch_short,batch_block1），SLURM 会优先分配先可用者；
• 时限设为--time=00:30:00；
• 注意 interactive/short 分区可能限制节点数，若冒烟测试需要多节点，把可容纳多节点的分区放在列表末尾作为兜底；
• 只有冒烟测试干净退出后，才提交完整校准作业。

这一「先 4 条样本、后 512 条样本」的节奏，在 SKILL.md 与 unsupported-models.md 中同样被列为标准流程（未在支持表中的模型尤其必须走这一步）。

七、作业提交、监控与结果核验

提交与轮询监控

mkdir -p <log_dir> JOBID=$(sbatch <script>.sh | awk '{print $4}') echo "Submitted job $JOBID" # 轮询直至完成（sleep 式轮询，避免后台任务/cron，保持输出在当前会话） while squeue -j $JOBID -h 2>/dev/null | grep -q .; do echo "$(date): job $JOBID still running..."; sleep 60 done echo "Job $JOBID finished" sacct -j $JOBID --format=JobID,State,ExitCode,Elapsed

作业结束后，tail 日志最后 50 行核验结果，再向用户报告。

结果核验

ls -lh <output_path>/ # 期望：config.json、tokenizer 文件、model-*.safetensors

若使用了--recipe（PTQ recipe 或 AutoQuantize recipe），hf_ptq.py会以 recipe 为准（recipe 与--qformat同时存在时 recipe 优先，KV cache 行为也取决于 recipe 类型，详见 examples/hf_ptq/README.md 的 Recipe-based Quantization 一节）。校准数据集默认使用cnn_dailymail+ nemotron 后训练数据混合（hf_ptq.py中cnn_nemotron_v2_mix），也可用--dataset切换为代表性更强的nemotron-post-training-v3混合集。

八、集群环境常见故障与规避

九、总结：一条可复用的 PTQ 上集群路径

把本指南浓缩为可执行清单：

1. 镜像：确认推荐镜像版本 → 优先复用已有.sqsh，否则 enroot import 并设好可写缓存目录；import 失败退化为 pyxis 内联 URI；
2. 依赖：容器内pip install -e ".[hf]" --no-build-isolation安装仓库源码；unset PIP_CONSTRAINT后按需升级 transformers；避免从 PyPI 升级nvidia-modelopt[hf]；
3. 规模：单节点靠device_map="auto"自动填充，只申请够用的卡；200B+ 用--use_fsdp2（必要时叠加--cpu_offload或加节点），直接用 multinode_fsdp2_ptq.slurm 改 CONFIG 后sbatch；
4. 冒烟：先以--calib_size 4+--time=00:30:00提交冒烟测试（用逗号分隔分区列表），干净退出后再跑--calib_size 512正式校准；
5. 核验：轮询至完成、tail 日志、检查导出目录产物。

这套流程覆盖了从容器到规模估算、从模板到排障的完整闭环，可以让 PTQ 校准作业在 SLURM 集群上稳定运行。关于更多 PTQ 本身的格式选择（NVFP4/FP8/INT4-AWQ 等）、支持矩阵与精度建议，请继续阅读 examples/hf_ptq/README.md。

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