企业官网建设流程全解析

amct 大模型量化 Agent 编排入口 quant-workflow 实战指南：阶段化全生命周期、human-in-the-loop 确认门与 progress 状态协议

【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct

导读

quant-workflow是 CANN amct 仓库（.agents/）中面向大模型（LLM）量化的唯一端到端编排入口：输入模型路径与工作目录，即可按「适配 → 量化实验 → deploy 交付 → 归档」六个阶段推进全生命周期，具备重入安全、复用已有结果不重跑、关键决策处强制人类确认（human-in-the-loop）等特性。本文以 quant-workflow/SKILL.md 为主体，结合其委派的三个子代理、六个叶子 skill、casebook 知识库与 amct_pytorch 实际 CLI 源码，完整讲解其阶段模型、编排原则、交互硬门、量化实验环、单段分流、progress.md 机读状态协议与 deploy 交付边界，帮助你在多 agent 集成或日常量化研发中正确使用这一入口。

一、定位：为什么需要「唯一编排入口」

quant-workflow被定位为 amct 大模型量化的唯一编排入口，多 agent / 上游集成只需对接这一个入口（黑盒），无需感知内部子代理与叶子技能的路由细节。其核心设计约束是：

不重写叶子 skill 的规则，只负责：查现状 → 判阶段 → 串联/分流 → 复用已有结果 → deploy 后补交付文档。

这意味着编排本身是「薄」的——领域逻辑全部下沉到叶子技能，编排只做状态判断、路由、汇总与交互确认，避免多入口路由歧义与规则漂移。整套分层结构在 .agents/docs/architecture.md 中有完整描述：

AGENTS.md / .agents/README.md 入口说明与路由 │ quant-workflow（唯一编排入口） 判阶段 → 串联/分流 → 复用 casebook → 汇总 │ 调度 quant-analyzer / quant-implementer / quant-reviewer 三类专职子代理（分析 / 实施 / 审查） │ 各自 skills: 挂载 quant-tools/*（含 model-adapter 等叶子技能，真正干活的最小单元） │ 消费 docs/casebook/ + docs/repo-map.md 知识层（适配经验 / 仓内导航）

其中.agents/是内容的唯一可信源（git tracked），通过符号链接投影到.claude/与.opencode/视图，clone 后即可使用（Windows 下的 symlink 退化处理见 .agents/README.md）。

二、六阶段生命周期模型

quant-workflow把一次端到端量化任务划分为 6 个阶段，每次进入先判阶段，再按阶段推进，每段达标确认后才进入下一段：

阶段 1 未适配（无模型注册 / block wrapper / 最小 PTQ 单元闭环） 阶段 2 已适配，未完成 BF16 闭环（baseline / 浮点等价 / 最小 PTQ smoke 未齐） 阶段 3 已适配，准备量化（BF16 闭环完成，准备直转 / 算法验证 / PTQ 升级） 阶段 4 已有量化结果，准备 deploy 阶段 5 deploy 已完成，待补交付文档（deploy_quantization.md 未补齐） 阶段 6 已有完整结果，准备归档或复核

阶段语义与量化研发的工程事实严格对应：阶段 1/2 属于适配范畴（无模型注册、无 block wrapper、无最小 PTQ 单元闭环），委派$model-adapter；阶段 3 进入量化实验环；阶段 4/5 进入deploy 交付；阶段 6 以归档与复核为主。阶段判断是编排一切工作的起点，其状态也以机读形式写入 progress.md（见第六节）。

三、编排为 supervisor：三层委派与叶子技能

quant-workflow采用 supervisor（编排者-工作者）模式，按职责将任务委派给三个子代理（定义见 .agents/agents/quant-analyzer.md、.agents/agents/quant-implementer.md、.agents/agents/quant-reviewer.md），并按各自 frontmatter 的description匹配：

编排自身不直接改 adapter 代码或量化方案，只做判阶段 / 路由 / 汇总 / 交互确认（原则一「编排不动手」）。

叶子 / 子任务清单（位于 .agents/skills/quant-tools/）：

• 执行：$quant-run（quant-run/SKILL.md）——implementer 的统一执行 skill，直转评测 / 校准数据提取 / PTQ 训练 / PTQ 结果评测均按--algos参数化；
• 推荐：$scheme-recommendation（scheme-recommendation/SKILL.md）、$algorithm-recommendation；
• 判读：$direct-quant-eval（direct-quant-eval/SKILL.md）、$algorithm-validation；
• 导出：$deploy-export（deploy-export/SKILL.md）；
• 适配：$model-adapter（model-adapter/SKILL.md）。

子代理之间通过共享状态文件progress.md传递上下文：analyzer 只读分析、implementer 写实施记录与命令结果、reviewer 写判读结论，编排负责初始化与收尾更新。

四、重要原则（编排的行为底线）

quant-workflow明确五条不可违背的编排原则：

1. 编排不动手：编排只调度与确认，不直接改 adapter 代码或量化方案；该派 implementer 的不自己改。
2. 重入安全：再次进入先读progress.md机读状态块，复用已有结果，不重跑。
3. 环境 fail-fast：环境是调用方责任，编排只暴露不排障；前置自检任一不满足即写BLOCKED并停止（详见第六节状态协议）。
4. 评测口径统一：所有通过 skill 触发的 Wikitext PPL 统一seq_len=4096，用户未显式指定即按 4096；历史结果非 4096 默认不能与当前delta直接横比或当同口径复用；仅当用户明确要求其他seq_len才允许偏离，并在结论里标注本次口径不同。该口径与 metrics-and-thresholds.md 中「当前主指标 = Wikitext PPL、边界量 =delta = ppl_quant - ppl_bf16、默认delta <= 0.2可接受」的判读规则保持一致。
5. 融合算子兼容性作参考输入：graph_fusion报告 JSON 仅作方案选择的参考，不单独评估、不增加确认环节——Pass 生效率 >80% 可按标准方案、50%–80% 适当保守、<50% 优先保守方案。

其中第 4 条与第 3 条直接支撑了后续「交互门」与「BLOCKED 协议」的设计：口径不一致的结果不可横比，环境不满足时不臆造继续。

五、交互门（硬约束）：五道必须停下确认的门

这是quant-workflow区别于全自动流水线的关键设计：human-in-the-loop。以下每一处都是必须停下与用户确认的硬门；无人机 / 批处理模式无法交互确认时，一律fail-fast 写BLOCKED，不得用 default 默默推进：

1. 方案确认契约（未确认绝不进实施层）
   • 用户已显式指定方案（quant_target / bits / quant_dtype / algos任一组合）→ 视为「已确认」，直接执行；
   • 用户未指定 → 必须先$scheme-recommendation产出「量化方案推荐卡」、停下让用户确认后才委派 implementer；CLI 的quant_target等 default 只能作为推荐卡里的建议值，不得当作自动执行值默默起跑；
   • 无头 / 批处理且方案未经用户确认 →fail-fast 写BLOCKED: 方案未确认，拒绝用 default 执行。
2. 复用确认：查到已有 BF16 / quant / deploy 结果，先汇报；足够回答则不默认重跑，先确认。
3. 升级确认：第一轮直转结果出来后，不默认升级，确认「接受 / 改方案重测 / 升级」。
4. 直转 → PTQ 确认：先说明为何不能停在直转，确认后再升级。
5. deploy 精度门：进 deploy 前必须已产出ppl_bf16 / ppl_quant / delta精度结论并由用户确认接受；缺 PPL 精度结论不得进 deploy。「实验结束」不等同「自动 deploy」。

「量化方案推荐卡」的完整字段见 scheme-recommendation/SKILL.md，至少包含：当前模型 / 任务口径 / 相似案例 / 候选方案（保守 / 首推 / 激进至少 2~3 个）/ 首推方案 / 推荐理由 / 风险点 / 升级条件 / 回退方案 / 证据强度。若评估依据不足，必须明确写「弱推荐」或「待验证」，不得装作确定。

六、工作流程：阶段判断、固定流程与量化实验环

6.1 阶段判断与固定流程

先把当前任务归入阶段 1–6 其一，再按固定流程推进：

1. 先查现有结果：casebook 按三层读——
   • L1 .agents/docs/casebook/cross-model-pitfalls.md（跨网络通用，先通读）；
   • 按 config/checkpoint 触发信号读 L2 .agents/docs/casebook/structure-family-pitfalls.md 命中的结构家族；
   • L3 .agents/docs/casebook/ 下<series>/<case>.md同模型/系列结论（现有案例含 deepseek、glm、hunyuan、longcat、qwen 等系列）；
   • 再查outputs/、日志、脚本目录的 BF16 / quant / deploy 结果；核对当前代码、模型版本、量化目标、口径是否一致。足够则复用并说明口径，仅在变化时重跑。
2. 阶段 1 / 2 →$model-adapter。
3. 阶段 3 → 进入量化实验环（见 6.2）。
4. 阶段 4 →$deploy-export。
5. 阶段 5 →$deploy-export，目标改为：复核 deploy 产物 + 按模板生成deploy_quantization.md+ 与导出目录一一绑定。
6. 阶段 6 → 先整理复用已有结论，再决定是否还要调子 skill。
7. 跨阶段按序推进：$model-adapter→ 量化实验环 →$deploy-export。
8. 任一次进入 deploy，权重导出 ≠ 全流程结束；只有deploy_quantization.md已补齐并足以给 infer 仓使用，deploy 才算闭环。

6.2 量化实验环（阶段 3 核心）

进入量化实验环前，先按序读三份参考资料：先读 metrics-and-thresholds.md（指标与边界）→ direct-quant.md（直转量化实验设计）；需升级 PTQ 再读 ptq-escalation.md（PTQ 升级条件与最小范围原则）。随后按固定步序执行：

1. 无可执行的第一轮直转方案 →$scheme-recommendation产出「量化方案推荐卡」。
2. implementer 跑$quant-run出第一轮直转ppl_bf16/ppl_quant，reviewer 用$direct-quant-eval判delta。
3. delta <= 0.2→ 可接受、可停止升级；delta > 0.2→ 未选算法走$algorithm-recommendation，已选算法由 implementer 跑$quant-run（含 ptq + 带--algos的结果评测）、reviewer 用$algorithm-validation判收益。
4. 直转 + 算法验证后仍不达标 → 做一轮粗粒度误差定位；只有粗定位之后才允许在最小范围引入 PTQ。
5. 每轮结束必须输出下一步决策：停止 / 补定位 / 小幅升级。
6. 默认取向：先直转再 PTQ；先整网方案再缩到 block / unit；误差定位只做粗粒度；PTQ 先最小范围。
7. 量化后 PPL 明显优于 BF16 很多时，先查链路，不直接当成功（对应 direct-quant.md 的「结果异常」处理：优先怀疑评测链路、wrapper 实现、forward / mask 逻辑、保存与加载不一致）。

关于直转判读与 PTQ 升级的关键口径，可进一步印证：

• 第一轮判读（direct-quant.md）：delta <= 0.2或已满足业务目标 → 可接受；delta > 0.2或掉点明显超预期 → 进入粗粒度误差定位；量化后 PPL 明显优于 BF16、掉点离谱且与经验不符、同方案多次复现不稳定 → 先查链路。每轮直转至少记录ppl_bf16、ppl_quant、delta与方案说明。
• PTQ 升级条件（ptq-escalation.md）：默认同时满足——直转结果不满足要求、已有 BF16 baseline、已确认关闭量化后保持浮点等价、已完成一轮粗粒度误差定位；且满足「BF16 baseline 稳定、wrapper 等价、实验提供新的定位信息、新增复杂度收益明显」时才有继续升级的意义。PTQ 引入原则是：先选最可能有收益的一类方法、先在最小范围试（一个 block / 一个 unit / 一种算法）、每轮只增加一档复杂度。
• 每轮 PTQ 后三选一决策：停止 / 补定位 / 小幅升级，不允许继续盲目叠复杂度。
• 长命令防超时：extract_ptq_data / ptq 在大模型上可能超过 agent 单条 Bash 超时上限（如 ~600s）被杀，必须nohup <命令> > run.log 2>&1 &后台跑 + 多次短调用轮询；ptq 被中断用--start_block_idx <下一未完成层>续跑（逐层存参不重复），也可主动--start_block_idx/--end_block_idx分块控制每块在超时窗口内。

6.3 单段分流

用户只覆盖其中一段时，直接转对应叶子 skill，不默认走完整流程：

七、状态协议与交付：progress.md 机读状态块

7.1 机读状态块（供轮询 / 多 agent 集成）

progress.md顶部维护一个机读状态块：编排入口负责初始化与收尾更新，子代理在各自轮次更新。上游 / 多 agent 集成只需轮询此块判断进度，无需读全文。格式为逐行可解析的key: value：

STAGE: <1-6 阶段号> STATUS: IN_PROGRESS | DONE | BLOCKED DELTA: ppl_bf16=<> ppl_quant=<> delta=<> # 拿到量化结果后 ARTIFACTS: <deploy 目录 / 关键产物路径> # DONE 时 BLOCKED: <原因> — <一行回退 hint> # 仅 BLOCKED 时 UPDATED_BY: orchestrator | analyzer | implementer | reviewer

配套两条硬规则：

• 前置自检（任一子代理启动即做）：amct_pytorch可导入、NPU device 由调用方--device指定且可用、模型与评测数据可达；任一不满足 → 写STATUS: BLOCKED+BLOCKED: <缺失项> — <回退 hint>（如数据不可达：set HF_ENDPOINT 镜像 / 用 modelscope / 指本地路径）并停止，不臆造继续。
• 终态：达标可交付写STATUS: DONE+DELTA+ARTIFACTS。

7.2 两段式结构（防上下文膨胀）

机读状态块之下分两段，用标记分隔：

<!-- ===== 以上为常驻区，不清除 ===== --> <!-- ===== 以下为工作区，阶段推进时归档并清空 ===== -->

• 常驻区（机读状态块 + 产物契约结论 + 阶段概览）：编排维护，只追加不清空；
• 工作区（各子代理按角色追加：方案分析 / 实施记录 / 验证·判读 / 诊断）：阶段推进时由编排运行本 skill 自带的归档脚本 .agents/skills/quant-workflow/scripts/archive_progress.py（注意：脚本路径相对本 skill 目录、非仓库根）把工作区归档到progress_history.md并清空；
• 历史只 Grep：progress_history.md禁止全文 Read，按关键字 Grep 取历史。

7.3 deploy 交付边界

• amct_pytorch/cli/llm/deploy.py 与 amct_pytorch/workflows/llm_deploy.py 只负责导出权重产物；
• deploy_quantization.md不由 deploy 代码自动生成，由$deploy-export按模板（deploy_quantization_template.md）生成、与本次导出目录绑定；
• deploy 阶段分两步：① 代码导出权重目录 ② skill 补齐交付说明文档；二者不混。

7.4 文档写回触发

触发条件与目标（系列 casebook README / 个案 / L1·L2 经验库、repo-map、Agent Docs，及默认不写）统一见 .agents/docs/README.md 的「文档写回触发」；编排在阶段收尾据此决定是否写回、写哪层。

7.5 输出要求

编排结束时至少说明：当前模型阶段；本轮复用了哪些已有结果；调用了哪些子 skill；本轮量化方案与ppl_bf16 / ppl_quant / delta；是否达标、是否粗定位、是否进 PTQ；下一步决策；若重跑为何旧结果不可复用；若进 deploy：权重是否导出、deploy_quantization.md是否补齐；是否更新 casebook / repo-map / Agent Docs（不更新需说明理由）。

八、与底层 CLI 的衔接：量化口径落地到真实命令

quant-workflow的编排语义最终通过$quant-run落到 amct_pytorch 的真实 CLI 上。理解下面这些口径，才能正确解读编排中「方案确认」「口径统一」等约束：

• 统一评测模板：以 examples/eval.sh 为权威评测模板（导出以 examples/deploy.sh 为权威），不凭空拼命令。直转评测命令形态为：

  python -m amct_pytorch.eval --model <path> --model_name <name> --device npu:N \ --granularity block --eval_mode quant --quant_target <mlp|moe|attn-linear|attn-cache> \ --quant_dtype <int|mxfp> --bit_config amct_pytorch/configs/<wXaY>.yaml --seq_len 4096

  BF16 baseline 即把--eval_mode换成bf16。

• bit 配置：--bit_config指向 amct_pytorch/configs/ 下的 yaml（如w8a8.yaml/w4a8.yaml/w4a4.yaml/bf16.yaml），顶层w_bits/a_bits+moe.routed/shared+attn-cache的 q/k/p/v。
• 量化目标与算法：quant_target支持mlp/moe/attn-linear/attn-cache，一次只聚焦一个角色、多角色分别跑并分别给参数目录；算法只认 new-path（LLM）ALGO_REGISTRY（当前 =autoround / lac / lwc / let，其中lwc + let为完整的 omniquant 算法；gptq/awq/mxfp 视分支移植）。
• 参数目录约定（quant-run/SKILL.md）：mlp / moe →--moe_mlp_param_dir（二者共用，无--mlp_param_dir）；attn-linear →--attn_linear_param_dir；attn-cache →--attn_cache_param_dir。
• PTQ 流程：extract_ptq_data（校准数据写--data_dir，产物block_<idx>_<target>_in.pkl，与ptq --data_dir必须是同一目录）→ptq（逐层layer_*_<target>.pt，核对层数 × expert 数齐全）→ 带--algos的 eval。
• 硬规则（易踩坑）：--model_name必填（缺失默认 deepseek 误用）；--granularity block必填（默认model不真量化、给假「无掉点」）；--quant_dtype在 quant 模式必填；加载 PTQ 参数时评测与 deploy 都必须带与 ptq 训练一致的--algos，否则load_module报KeyError: Submodule '...algorithms.<algo>' is not found。

这些约束正是编排中「delta ≈ 0 不能判达标」「量化后 PPL 优于 BF16 先查链路」「方案确认后再实施」等判断的底层依据：granularity默认值、quant_target是否落到算子、算法注册一致性，都直接影响delta数值的可信度（参见 direct-quant-eval/SKILL.md 中「delta ≈ 0或逐位相同 → 量化很可能未真正生效」的复核指引）。

九、deploy 交付闭环：产物自检与交付文档

$deploy-export负责把已接受的量化方案导出为 deploy-ready 模型目录（HuggingFace safetensors 权重 +config.json+index.json），并补齐deploy_quantization.md。其关键边界与quant-workflow的阶段 4/5 语义一致：

• 导出模式判定：用户期望（直转 / PTQ / 未明确）vs 实际（直转 / PTQ / 混合）不一致时必须在执行前说明；本意 PTQ 但某 target 回退直转 → 结论必须显式指出，不能静默继续。
• 产物静态自检（不碰 infer runtime）：object 级（quantization_config中format/num_bits非空、未误入ignore）、权重级对账（int 路径*.weight_scale/ mxfp 路径*.weight_packed键数匹配、index.json0 missing）、PTQ 参数核对（带--algos时 scale 非占位、deploy 与 ptq 的--algos一致）。
• 已知边界（deploy-export/SKILL.md 明确记录）：config.json刷新对 Linear group 硬编码num_bits=8/8，W8A8 恰好正确，但 int W4A8/W4A4 的num_bits会被错标成 w8——非 W8A8 的 int 路径必须在产物自检里核对num_bits与方案一致；缺attn_linear_param_dir/attn_cache_param_dir/moe_mlp_param_dir不应报错（意味着对应 target 按直转导出）。
• 交付文档模板：deploy_quantization_template.md 定义了 13 节完整规格，从「下游最小交付物检查」「模块目标映射表」「导出张量清单」「模块级运行时契约（输入/读取张量/执行顺序/输出）」「量化算法说明（无额外计算代价 / 有额外计算代价 / Cache 量化三类）」到「回退策略与不支持场景」，要求写到下游可据此实现量化推理为止，且基于本次实际导出产物书写、与导出目录一一绑定，不引用其它 run。

十、面向 agent 集成的黑盒契约

如果你是要把 amct 量化能力集成到自己的多 agent 系统，architecture.md 第 8 节给出了可直接对接的最小契约：

• 能力 + 触发：以quant-workflowfrontmatter 的description为机读接口（.agents/README.md 面向人）；
• 输入：模型路径 + 工作目录；可选quant_target / bits / device；
• 输出 / 状态面：progress.md顶部机读状态块（STAGE / STATUS / DELTA / ARTIFACTS / BLOCKED）可轮询；deploy 产物为终态交付物；
• 交互模式：human-in-the-loop——方案选择 / PTQ 升级 / 算法选择 / 是否导出四个强制确认门，非全自动；
• 前置：amct_pytorch可导入、NPU device 由调用方--device提供、模型与数据可达；不满足则 fail-fast 写BLOCKED（环境是调用方责任，agent 不自行排障）；
• 重入安全：重复对接先复用progress.md已有结果，不重跑。

整套入口的触发场景覆盖：端到端量化任意 amct 模型（「把 Qwen3-30B-A3B 量化到 W8A8 并导出部署权重」→ 全程编排含确认门），以及单段需求（只适配 / 只方案 / 只评测 / 只导出，自动分流到对应叶子 skill）。

小结

quant-workflow的价值在于把「适配 → 直转 → 误差定位 → PTQ → deploy → 归档」这一完整链路固化为可判阶段、可重入、可轮询、强制确认的工程化流程：六阶段模型让任何任务都能立即定位现状；supervisor 三层委派保证分析与实施职责隔离、编排不越权动手；五道交互硬门把方案选择、复用、升级、直转转 PTQ、deploy 精度等关键决策留给人类确认；progress.md机读状态块 + 两段式结构为多 agent 集成与长任务上下文管理提供了统一契约。对于需要在 amct 上完成任意 LLM 端到端量化的研发团队或 agent 系统，这一入口是值得优先对接的唯一编排层。

【免费下载链接】amctAMCT是CANN提供的昇腾AI处理器亲和的模型压缩工具仓。项目地址: https://gitcode.com/cann/amct