企业官网建设流程全解析

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

导读

本指南围绕 Model-Optimizer 仓库中modelopt-model-quantizer这一 AI Agent 定义展开，说明它如何在一个已选定的 Day 0 量化方案（recipe）约束下，端到端地产出一个通过验证的 PTQ 量化检查点（checkpoint）。你将掌握该 Agent 的职责边界与协作分工、其必须加载的三份指令（PTQ 执行、任务监控、工作区管理）、校准前必须完成的 recipe 覆盖率核查，以及作为强制门禁的四组后量化验证与九个固定标题的交接报告格式。文中所有流程均可在本仓库对应的技能文档与源码中直接查证与复用。

一、Agent 定位：谁负责执行单个 PTQ 候选方案

modelopt-model-quantizer是 Model-Optimizer 仓库中一组协作式 Agent 的成员，其定义文件位于 plugins/modelopt/agents/modelopt-model-quantizer.md。它的触发场景非常明确：当父级流程选定了一个需要验证的 PTQ 检查点时（例如用户要求"用某个 recipe 量化模型"，或搜索循环选出了下一个候选方案），由本 Agent 负责产出该检查点。

与之配套的 Agent 定义还包括：

• modelopt-model-quantize-recipe-searcher.md：负责量化策略与下一个候选方案的决策（属于搜索/选型环节）；
• modelopt-model-deployer.md：负责部署；
• modelopt-model-evaluator.md：负责评估；
• modelopt-model-performance-benchmarker.md：负责性能基准测试；
• modelopt-model-downloader.md：负责模型下载。

1.1 严格职责边界

该 Agent 的职责定义只有一句，但边界极严："You are responsible for one PTQ candidate selected by the parent. Do not search a recipe portfolio, deploy, evaluate, benchmark, or publish."即：

• ✅ 只负责一个由父级选定的 PTQ 候选方案；
• ❌ 不搜索 recipe 组合（那是 recipe-searcher 的事）；
• ❌ 不部署、不评估、不做基准测试、不发布。

这种单一职责设计使得"选型"与"执行"两个环节解耦：搜索循环可以并行评估多个候选，而每个候选由独立的 quantizer 实例负责，互不干扰。

1.2 行动前必须加载的三份指令

Agent 在采取任何行动前，必须先加载以下指令（原文对应路径为本仓库内的技能文档）：

二、执行前置：工作区、环境与任务监控

2.1 会话级工作区约定

workspace-management.md 规定了跨 PTQ → Deploy → Eval 全流水线复用的工作区规范：

• 每个 Agent 以其会话 ID 为命名空间：Claude Code 使用$CLAUDE_CODE_SESSION_ID，Codex 使用$CODEX_THREAD_ID，否则自建稳定 ID；
• 每个模型/变体一个工作区目录，目录名要有语义而非时间戳，例如workspaces/<session_id>/qwen3-0.6b-nvfp4/而不是ptq-20260318-143022/；
• 输出、日志、脚本分目录存放：output/（量化检查点）、logs/（任务日志）、scripts/（自定义 PTQ 脚本）；
• workspaces/在 gitignore 中，属于临时区（scratch），不入库；密钥（.env）也应放在这里而非技能树下；
• 远程执行时本地与远端各建同名工作区，模型下载放在远端以避免传输大文件，并用remote_sync_to同步 Model-Optimizer 源码与自定义脚本。

2.2 任务监控

PTQ 校准属于长任务。提交后 Agent 需按 monitor/SKILL.md 执行：

1. 在.claude/agents/<session_id>/active_jobs.json注册任务（记录type、id、host、user、submitted、description、owner）；
2. 启动一个持续的监视器轮询会话注册表，直至所有任务进入终态；
3. 按任务类型使用各自的状态词汇表：NEL 任务用nel status（终态 SUCCESS/FAILED/KILLED/ERROR/NOT FOUND），Launcher 任务用后台输出文件追踪关键事件，裸 SLURM 任务用sacct判断终态（COMPLETED/FAILED/CANCELLED/TIMEOUT/NODE_FAIL/OUT_OF_MEMORY/PREEMPTED/BOOT_FAIL/DEADLINE）。

注意该文档特别强调：不同检查方法的状态词不同，混用会导致终态转换永远不触发（例如用 SLURM 的COMPLETED正则去匹配nel status的输出会静默失效）。

三、PTQ 执行核心流程（ptq/SKILL.md）

plugins/modelopt/skills/ptq/SKILL.md 是 quantizer Agent 的主执行手册，其流程分为五个步骤。

3.1 Step 1 — 环境准备

确认 Model-Optimizer 源码可用、执行环境类型（SLURM / Docker+GPU / 裸 GPU）、Launcher 是否可用以及使用哪个工作区。对应的环境与工作区文档位于 plugins/modelopt/skills/common/。

3.2 Step 2 — 模型支持检查

对照 examples/hf_ptq/README.md 中的支持矩阵判断目标模型：

• 已列出→ 走标准路径，使用examples/hf_ptq/hf_ptq.py（下述 4A/4B）；
• 未列出→ 阅读 references/unsupported-models.md，判断hf_ptq.py是否仍可工作，或需要自定义脚本（下述 4C）。

支持矩阵节选（来源：examples/hf_ptq/README.md）：LLAMA 3.x 支持 fp8/int4_awq/nvfp4；LLAMA 4、Mixtral、QWen3/3.5-MOE、DeepSeek V3/R1 等支持 nvfp4；T5、Phi-3/4 支持 int8_smoothquant；VLM（Llava、Qwen-VL、Nemotron VL 等）默认只量化语言模型、视觉编码器保持高精度。

3.3 Step 2.5 — 模型特定依赖检查

若模型使用trust_remote_code（检查config.json的auto_map），需审查其自定义 Python 文件的导入是否超出容器环境：

grep -h "^from \|^import " <model_path>/modeling_*.py | sort -u

已知依赖模式：发现from mamba_ssm/from causal_conv1d时，需安装mamba-ssm causal-conv1d（Mamba/混合模型如 NemotronH、Jamba）。使用 Launcher 时通过任务 environment 的EXTRA_PIP_DEPS注入（ptq.sh会自动安装）；手动执行时先unset PIP_CONSTRAINT && pip install <deps>再运行。

3.4 Step 3 — 选择量化格式与 recipe 覆盖率核查

这是 quantizer 区别于一般脚本执行的关键环节。选择顺序：

1. 优先查找模型特定 recipe：

   ls modelopt_recipes/models/ 2>/dev/null ls modelopt_recipes/model_type/<model_type>/ptq/ 2>/dev/null

   若存在，优先--recipe <path>，但必须实际检查其 include/exclude 模式（对 VLM 要确认视觉塔确实被排除）；

2. 无模型特定 recipe 时按 GPU 选格式：
   • Blackwell（B100/B200/GB200）→nvfp4系列（--qformat nvfp4）；
   • Hopper（H100/H200）及更早 →fp8或int4_awq。

格式定义位于 modelopt/torch/quantization/config.py，通用 PTQ recipe 位于 modelopt_recipes/general/ptq/，--qformat是使用它们的更简方式。

校准前覆盖率核查（mandatory）：将所选 qformat/recipe 的 include/exclude 模式与模型结构对照，总结哪些层组会被量化、大约匹配多少模块（attention 投影、MLP 投影、experts 等）。若匹配数为 0 或远小于预期，必须停下来修正 recipe 或询问用户，不得直接启动校准。

VLM 的陷阱：泛化的*mlp*/*experts*模式会同时匹配视觉塔（model.visual.*），量化 ViT 会静默破坏图像基准测试（文本表现正常）。应使用model_type/<model_type>/ptq/的 recipe 或显式加入*visual*/*vision_tower*排除，并在 Step 5 验证。

另一条重要约束：如果源检查点本身已量化（如 FP8），而 recipe 又排除了某些层使其回退到 BF16，需先与用户确认这种 FP8→BF16 回退是否有意。此外NVFP4 可在 Hopper 上校准，但推理必须 Blackwell。

3.5 Step 4 — 运行 PTQ

目标：在磁盘上得到检查点（.safetensors+config.json）。

校准数据集（来自examples/hf_ptq/README.md与 SKILL.md）：

• 纯文本 LLM：优先使用代表性混合数据集nemotron-post-training-v3（由 modelopt/torch/utils/dataset_utils.py 展开为七个已注册的 Nemotron SFT 域）：

  python examples/hf_ptq/hf_ptq.py ... --dataset nemotron-post-training-v3

• VLM：加--calib_with_images，走nemotron_vlm_dataset_v2（默认子集sparsetables、plotqa_cot、wiki_en），真源在examples/hf_ptq/hf_ptq.py与modelopt/torch/utils/vlm_dataset_utils.py；
• --dataset cnn_dailymail仅在受限环境（无 gated 数据访问、仅本地公共缓存）下作为 fallback。

三条执行路径（按决策树选择）：

In README table? ─→ YES ─→ SLURM (local or remote)? ─→ LAUNCHER (4B) │ Local Docker + GPU? ────────→ LAUNCHER (4B) │ Remote Docker (no SLURM)? ──→ MANUAL (4A) │ Bare GPU (local or remote)? → MANUAL (4A) │ └→ NOT LISTED ──→ UNLISTED MODEL (4C)

4A — 直接手动执行（支持矩阵内的模型）：

pip install --no-build-isolation "nvidia-modelopt[hf]" pip install -r examples/hf_ptq/requirements.txt python examples/hf_ptq/hf_ptq.py \ --pyt_ckpt_path <model> \ --qformat <format> \ --calib_size 512 \ --export_path <output>

--help可查看全部参数。

4B — Launcher 路径（SLURM 或本地 Docker）：

cd tools/launcher # SLURM (remote or local): SLURM_HOST=<host> SLURM_ACCOUNT=<acct> uv run launch.py --yaml <config.yaml> user=<ssh_user> identity=<ssh_key> --yes # Local Docker: uv run launch.py --yaml <config.yaml> hf_local=<hf_cache> --yes

Launcher 会阻塞并 tail 日志直到任务结束；若 Launcher 失败则回退到 4A。完整模板见 references/launcher-guide.md。

4C — 未列出模型：按 references/unsupported-models.md 排查，必要时对 ModelOpt 打最小补丁，手动运行hf_ptq.py（便于监控调试）。先做冒烟测试（--calib_size 4）成功后再全量校准（--calib_size 512）。

监控：任务提交后按 monitor skill 注册并监控（见本文 2.2）。

3.6 Key API Rules 与常见陷阱

执行时需遵守的 API 规则（来源：ptq/SKILL.md）：

• mtq.register()注册的类必须定义_setup()并在__init__中调用；
• 量化前必须先调用mto.enable_huggingface_checkpointing()；
• 通配符*gate*匹配过宽，应使用*mlp.gate*或*router*；
• VLM 场景下hf_ptq.py通过extract_and_prepare_language_model_from_vl()自动抽取语言模型，多数情况无需手工处理 VLM；
• FP8 检查点优先用_QuantFP8Linear（惰性反量化），避免FineGrainedFP8Config(dequantize=True)约 2 倍的内存浪费；
• 自定义 quantizer 名称必须以_input_quantizer或_weight_quantizer结尾。

常见陷阱包括：trust_remote_code模型的容器外依赖（如mamba-ssm）；新模型需要比容器内更新的 transformers（检查config.json的transformers_version，注意容器中PIP_CONSTRAINT会阻止升级）；gated 校准集需要HF_TOKEN；NFS root_squash + Docker 组合问题。

四、强制验证门禁：四组后量化检查

这是 quantizer 最核心的职责之一。Agent 定义明确要求："Treat the PTQ checkpoint-validation gate as mandatory"——未通过输出、覆盖率、元数据或服务就绪性验证的检查点不得交接。完整规范见 plugins/modelopt/skills/ptq/references/checkpoint-validation.md，该文档强调"这是门禁而非建议"：在四组检查全部通过且验证报告被记录之前，不得提交评估、不得启动生产级服务、不得将检查点标记为就绪。

四组验证（针对将要部署/评估的确切检查点路径执行）：

1. 大小与每权重位数：量化检查点磁盘占用应小于基线/源检查点，估算的每权重位数更低；记录源大小、输出大小及输出/源比率。
2. 量化权重覆盖率：实际被量化的权重必须与请求的 qformat/recipe/config 目标一致；按实际/声明精度分组记录层精度计数（NVFP4、FP8、INT4、BF16/未量化排除、意外未量化、声明不匹配）。非标准命名可能导致配置模式静默漏层，最终在部署框架按量化权重加载 BF16 权重时才暴露为故障。
3. 元数据一致性：生成设置、tokenizer 文件、聊天模板、模型架构字段、max positions/上下文长度、特殊 token 必须与基线一致；量化只应改变权重与量化元数据，不得静默改变提示词或生成行为。每个 diff 都要记录并分类为预期或阻塞。
4. 下游就绪性与服务 canary：记录确切的检查点工作区与路径（供 deploy/eval 技能继承），盘点 PTQ 期间所有模型兼容性改动（依赖升级、源码补丁、自定义代码、环境变量、Launcher/容器变更，无则写none），然后调用 deployment 技能在同一路径以记录的兼容性清单启动服务，运行 canary 查询（如What is the capital of France?，要求给出有效回答），记录目标环境、服务框架与启动配置、查询与响应，验证后停止服务（除非用户要求保留）。

4.1 门禁报告表

验证后必须输出如下形状的表格：

阻塞条件（满足任一即停止，不得继续）：

• 压缩 recipe 的输出/源比率>= 1.0（除非source_precision已解释，即源本身已达或低于 recipe 目标位宽，或用户明确接受解释）；
• 任何本应量化的层组覆盖率为零或异常低；
• 任何层的量化元数据与其声明精度不一致；
• 提示词、tokenizer、生成、架构、上下文长度或特殊 token 元数据意外变更；
• 确切检查点工作区/路径缺失或未保留给部署与评估；
• 任一 PTQ 兼容性类别被省略（须记录要求或none）；
• deployment 技能无法从记录的工作区/路径以记录的兼容性要求启动检查点；
• 服务 canary 未返回有效响应；
• VLM 专有：任何视觉塔权重（model.visual.*/vision_tower.*/vision_model.*）携带量化 scale（除非有意量化 ViT）。因为泛化*mlp*/*experts*recipe 会静默匹配 ViT MLP，导致图像嵌入变成垃圾数据（MMMU-Pro 约 0%），而文本侧看起来正常——精度脚本还会把这类权重计为合法 NVFP4，所以必须单独跑 VLM 检查。

4.2 各 qformat 的预期量化模式

4.3 仓库提供的验证脚本

checkpoint-validation.md 附带了可直接执行的 Python 脚本（单行python3 -c形式）：

• 大小检查：对比源与输出的*.safetensors字节总和，计算输出/源比率（Output/source ratio: <ratio>x），作为每权重位数的第一阶代理；
• 层覆盖率与精度脚本：读取model.safetensors.index.json与hf_quant_config.json，区分统一quant_algo导出与混合精度quantized_layers导出，逐一检查每个线性层要么以预期精度量化、要么被显式排除，输出层精度计数、意外未量化层清单（按模块类型分组：self_attn/mlp/experts/router/lm_head/embed_tokens/vision_tower）与声明不匹配清单；
• VLM 视觉塔检查：遍历 sharded（model.safetensors.index.json的weight_map）或单文件（读取 safetensors header）导出的全部张量名，统计带weight_scale/input_scale且路径含model.visual/vision_tower/vision_model的张量数量，期望为 0。

4.4 常见模式缺口

量化配置模式与模型命名不匹配导致静默漏层的已知案例：

警告出现时的处理：本应量化却漏掉的层（如nvfp4_mlp_only下的 MoE experts），修正量化配置模式后重跑 PTQ，并检查 ModelOpt 是否已有该模型的插件（modelopt/torch/quantization/plugins/huggingface.py）；有意不量化的层则应加入exclude_modules，若导出未自动添加，需手工同步写入检查点内的hf_quant_config.json与config.json的quantization_config.ignore，防止部署失败。

五、标准化交接报告

Agent 定义规定：只返回一个简洁的交接（handoff），包含以下九个固定标题，并包含请求/观察覆盖率、大小、job ID 与绝对路径；不得返回原始日志：

这份固定格式的交接报告是 quantizer 与下游 deployer/evaluator 之间的事实契约：精确的检查点路径、兼容性清单与 job 元数据使下游技能可以完全基于该报告继续工作，而不必重新探查。相应地，Agent 定义还要求"仅在模型支持确需时做最小化的 Model-Optimizer 源码修改，并逐一报告每个变更文件"——这保证了仓库源码的稳定性与可审计性。

六、与下游流水线的衔接

quantizer 的输出（通过验证的检查点 + 交接报告）会沿PTQ → Deploy → Eval流水线继续流转。工作区规范（workspace-management.md）为此设计了跨技能共享目录：

workspaces/<session_id>/model-name-format/ output/ ← PTQ：量化检查点 eval_results/ ← Evaluation：NEL 产物（每任务 results.yml） eval_config.yaml ← Evaluation：NEL 配置 scripts/ ← Deployment/PTQ：自定义运行脚本 logs/ ← All：SLURM 任务日志

配合 ptq/SKILL.md 的 References 表，quantizer 可按下表按需取用各参考文档：

七、总结

modelopt-model-quantizer的设计体现了"窄职责 + 强门禁 + 标准交接"的 Agent 工程思路：它不参与选型、部署、评估，只负责把一个已选定的 recipe 高质量地转化为经验证的量化检查点；它以校准前的 recipe 覆盖率核查挡住配置模式的静默漏层，以四组后量化验证挡住大小未压缩、覆盖不足、元数据漂移与无法服务化的检查点；最终以九个固定标题的交接报告把精确路径与兼容性清单传递给下游。对于希望以 Agent 方式编排 PTQ 流水线的开发者，本仓库的 agents 定义 与 skills 技能树 提供了完整、可落地的参考实现。

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