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匹配子代理类型职责权限边界quant-analyzer分析类适配性分析、方案 / 算法推荐只读不改代码 / 方案quant-implementer实施类执行全部量化命令统一走$quant-run、adapter 改造改 adapter、跑命令、导出quant-reviewer审查类精度 / 收益判读、与 casebook 对比只读quant-run结果判定不跑评测 / ptq、不改方案编排自身不直接改 adapter 代码或量化方案只做判阶段 / 路由 / 汇总 / 交互确认原则一「编排不动手」。叶子 / 子任务清单位于 .agents/skills/quant-tools/执行$quant-runquant-run/SKILL.md——implementer 的统一执行 skill直转评测 / 校准数据提取 / PTQ 训练 / PTQ 结果评测均按--algos参数化推荐$scheme-recommendationscheme-recommendation/SKILL.md、$algorithm-recommendation判读$direct-quant-evaldirect-quant-eval/SKILL.md、$algorithm-validation导出$deploy-exportdeploy-export/SKILL.md适配$model-adaptermodel-adapter/SKILL.md。子代理之间通过共享状态文件progress.md传递上下文analyzer 只读分析、implementer 写实施记录与命令结果、reviewer 写判读结论编排负责初始化与收尾更新。四、重要原则编排的行为底线quant-workflow明确五条不可违背的编排原则编排不动手编排只调度与确认不直接改 adapter 代码或量化方案该派 implementer 的不自己改。重入安全再次进入先读progress.md机读状态块复用已有结果不重跑。环境 fail-fast环境是调用方责任编排只暴露不排障前置自检任一不满足即写BLOCKED并停止详见第六节状态协议。评测口径统一所有通过 skill 触发的 Wikitext PPL 统一seq_len4096用户未显式指定即按 4096历史结果非 4096 默认不能与当前delta直接横比或当同口径复用仅当用户明确要求其他seq_len才允许偏离并在结论里标注本次口径不同。该口径与 metrics-and-thresholds.md 中「当前主指标 Wikitext PPL、边界量 delta ppl_quant - ppl_bf16、默认delta 0.2可接受」的判读规则保持一致。融合算子兼容性作参考输入graph_fusion报告 JSON 仅作方案选择的参考不单独评估、不增加确认环节——Pass 生效率 80% 可按标准方案、50%–80% 适当保守、50% 优先保守方案。其中第 4 条与第 3 条直接支撑了后续「交互门」与「BLOCKED 协议」的设计口径不一致的结果不可横比环境不满足时不臆造继续。五、交互门硬约束五道必须停下确认的门这是quant-workflow区别于全自动流水线的关键设计human-in-the-loop。以下每一处都是必须停下与用户确认的硬门无人机 / 批处理模式无法交互确认时一律fail-fast 写BLOCKED不得用 default 默默推进方案确认契约未确认绝不进实施层用户已显式指定方案quant_target / bits / quant_dtype / algos任一组合→ 视为「已确认」直接执行用户未指定 → 必须先$scheme-recommendation产出「量化方案推荐卡」、停下让用户确认后才委派 implementerCLI 的quant_target等 default 只能作为推荐卡里的建议值不得当作自动执行值默默起跑无头 / 批处理且方案未经用户确认 →fail-fast 写BLOCKED: 方案未确认拒绝用 default 执行。复用确认查到已有 BF16 / quant / deploy 结果先汇报足够回答则不默认重跑先确认。升级确认第一轮直转结果出来后不默认升级确认「接受 / 改方案重测 / 升级」。直转 → PTQ 确认先说明为何不能停在直转确认后再升级。deploy 精度门进 deploy 前必须已产出ppl_bf16 / ppl_quant / delta精度结论并由用户确认接受缺 PPL 精度结论不得进 deploy。「实验结束」不等同「自动 deploy」。「量化方案推荐卡」的完整字段见 scheme-recommendation/SKILL.md至少包含当前模型 / 任务口径 / 相似案例 / 候选方案保守 / 首推 / 激进至少 2~3 个/ 首推方案 / 推荐理由 / 风险点 / 升级条件 / 回退方案 / 证据强度。若评估依据不足必须明确写「弱推荐」或「待验证」不得装作确定。六、工作流程阶段判断、固定流程与量化实验环6.1 阶段判断与固定流程先把当前任务归入阶段 1–6 其一再按固定流程推进先查现有结果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 结果核对当前代码、模型版本、量化目标、口径是否一致。足够则复用并说明口径仅在变化时重跑。阶段 1 / 2 →$model-adapter。阶段 3 → 进入量化实验环见 6.2。阶段 4 →$deploy-export。阶段 5 →$deploy-export目标改为复核 deploy 产物 按模板生成deploy_quantization.md 与导出目录一一绑定。阶段 6 → 先整理复用已有结论再决定是否还要调子 skill。跨阶段按序推进$model-adapter→ 量化实验环 →$deploy-export。任一次进入 deploy权重导出 ≠ 全流程结束只有deploy_quantization.md已补齐并足以给 infer 仓使用deploy 才算闭环。6.2 量化实验环阶段 3 核心进入量化实验环前先按序读三份参考资料先读 metrics-and-thresholds.md指标与边界→ direct-quant.md直转量化实验设计需升级 PTQ 再读 ptq-escalation.mdPTQ 升级条件与最小范围原则。随后按固定步序执行无可执行的第一轮直转方案 →$scheme-recommendation产出「量化方案推荐卡」。implementer 跑$quant-run出第一轮直转ppl_bf16/ppl_quantreviewer 用$direct-quant-eval判delta。delta 0.2→ 可接受、可停止升级delta 0.2→ 未选算法走$algorithm-recommendation已选算法由 implementer 跑$quant-run含 ptq 带--algos的结果评测、reviewer 用$algorithm-validation判收益。直转 算法验证后仍不达标 → 做一轮粗粒度误差定位只有粗定位之后才允许在最小范围引入 PTQ。每轮结束必须输出下一步决策停止 / 补定位 / 小幅升级。默认取向先直转再 PTQ先整网方案再缩到 block / unit误差定位只做粗粒度PTQ 先最小范围。量化后 PPL 明显优于 BF16 很多时先查链路不直接当成功对应 direct-quant.md 的「结果异常」处理优先怀疑评测链路、wrapper 实现、forward / mask 逻辑、保存与加载不一致。关于直转判读与 PTQ 升级的关键口径可进一步印证第一轮判读direct-quant.mddelta 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 21 后台跑 多次短调用轮询ptq 被中断用--start_block_idx 下一未完成层续跑逐层存参不重复也可主动--start_block_idx/--end_block_idx分块控制每块在超时窗口内。6.3 单段分流用户只覆盖其中一段时直接转对应叶子 skill不默认走完整流程用户诉求路由目标只要方案$scheme-recommendation已指定方案、只看 deltaimplementer 跑$quant-run reviewer$direct-quant-eval判读只导出$deploy-export不在此重做评测 / PTQ / 精度判定只推荐算法$algorithm-recommendation只验证算法implementer 跑$quant-run含 ptq reviewer$algorithm-validation判读七、状态协议与交付progress.md 机读状态块7.1 机读状态块供轮询 / 多 agent 集成progress.md顶部维护一个机读状态块编排入口负责初始化与收尾更新子代理在各自轮次更新。上游 / 多 agent 集成只需轮询此块判断进度无需读全文。格式为逐行可解析的key: valueSTAGE: 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: BLOCKEDBLOCKED: 缺失项 — 回退 hint如数据不可达set HF_ENDPOINT 镜像 / 用 modelscope / 指本地路径并停止不臆造继续。终态达标可交付写STATUS: DONEDELTAARTIFACTS。7.2 两段式结构防上下文膨胀机读状态块之下分两段用标记分隔!-- 以上为常驻区不清除 -- !-- 以下为工作区阶段推进时归档并清空 --常驻区机读状态块 产物契约结论 阶段概览编排维护只追加不清空工作区各子代理按角色追加方案分析 / 实施记录 / 验证·判读 / 诊断阶段推进时由编排运行本 skill 自带的归档脚本 .agents/skills/quant-workflow/scripts/archive_progress.py注意脚本路径相对本 skill 目录、非仓库根把工作区归档到progress_history.md并清空历史只 Grepprogress_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 4096BF16 baseline 即把--eval_mode换成bf16。bit 配置--bit_config指向 amct_pytorch/configs/ 下的 yaml如w8a8.yaml/w4a8.yaml/w4a4.yaml/bf16.yaml顶层w_bits/a_bitsmoe.routed/sharedattn-cache的 q/k/p/v。量化目标与算法quant_target支持mlp/moe/attn-linear/attn-cache一次只聚焦一个角色、多角色分别跑并分别给参数目录算法只认 new-pathLLMALGO_REGISTRY当前 autoround / lac / lwc / let其中lwc let为完整的 omniquant 算法gptq/awq/mxfp 视分支移植。参数目录约定quant-run/SKILL.mdmlp / moe →--moe_mlp_param_dir二者共用无--mlp_param_dirattn-linear →--attn_linear_param_dirattn-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.jsonindex.json并补齐deploy_quantization.md。其关键边界与quant-workflow的阶段 4/5 语义一致导出模式判定用户期望直转 / PTQ / 未明确vs 实际直转 / PTQ / 混合不一致时必须在执行前说明本意 PTQ 但某 target 回退直转 → 结论必须显式指出不能静默继续。产物静态自检不碰 infer runtimeobject 级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_bits8/8W8A8 恰好正确但 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
amct 大模型量化 Agent 编排入口 quant-workflow 实战指南：阶段化全生命周期、human-in-the-loop 确认门与 progress 状态协议
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匹配子代理类型职责权限边界quant-analyzer分析类适配性分析、方案 / 算法推荐只读不改代码 / 方案quant-implementer实施类执行全部量化命令统一走$quant-run、adapter 改造改 adapter、跑命令、导出quant-reviewer审查类精度 / 收益判读、与 casebook 对比只读quant-run结果判定不跑评测 / ptq、不改方案编排自身不直接改 adapter 代码或量化方案只做判阶段 / 路由 / 汇总 / 交互确认原则一「编排不动手」。叶子 / 子任务清单位于 .agents/skills/quant-tools/执行$quant-runquant-run/SKILL.md——implementer 的统一执行 skill直转评测 / 校准数据提取 / PTQ 训练 / PTQ 结果评测均按--algos参数化推荐$scheme-recommendationscheme-recommendation/SKILL.md、$algorithm-recommendation判读$direct-quant-evaldirect-quant-eval/SKILL.md、$algorithm-validation导出$deploy-exportdeploy-export/SKILL.md适配$model-adaptermodel-adapter/SKILL.md。子代理之间通过共享状态文件progress.md传递上下文analyzer 只读分析、implementer 写实施记录与命令结果、reviewer 写判读结论编排负责初始化与收尾更新。四、重要原则编排的行为底线quant-workflow明确五条不可违背的编排原则编排不动手编排只调度与确认不直接改 adapter 代码或量化方案该派 implementer 的不自己改。重入安全再次进入先读progress.md机读状态块复用已有结果不重跑。环境 fail-fast环境是调用方责任编排只暴露不排障前置自检任一不满足即写BLOCKED并停止详见第六节状态协议。评测口径统一所有通过 skill 触发的 Wikitext PPL 统一seq_len4096用户未显式指定即按 4096历史结果非 4096 默认不能与当前delta直接横比或当同口径复用仅当用户明确要求其他seq_len才允许偏离并在结论里标注本次口径不同。该口径与 metrics-and-thresholds.md 中「当前主指标 Wikitext PPL、边界量 delta ppl_quant - ppl_bf16、默认delta 0.2可接受」的判读规则保持一致。融合算子兼容性作参考输入graph_fusion报告 JSON 仅作方案选择的参考不单独评估、不增加确认环节——Pass 生效率 80% 可按标准方案、50%–80% 适当保守、50% 优先保守方案。其中第 4 条与第 3 条直接支撑了后续「交互门」与「BLOCKED 协议」的设计口径不一致的结果不可横比环境不满足时不臆造继续。五、交互门硬约束五道必须停下确认的门这是quant-workflow区别于全自动流水线的关键设计human-in-the-loop。以下每一处都是必须停下与用户确认的硬门无人机 / 批处理模式无法交互确认时一律fail-fast 写BLOCKED不得用 default 默默推进方案确认契约未确认绝不进实施层用户已显式指定方案quant_target / bits / quant_dtype / algos任一组合→ 视为「已确认」直接执行用户未指定 → 必须先$scheme-recommendation产出「量化方案推荐卡」、停下让用户确认后才委派 implementerCLI 的quant_target等 default 只能作为推荐卡里的建议值不得当作自动执行值默默起跑无头 / 批处理且方案未经用户确认 →fail-fast 写BLOCKED: 方案未确认拒绝用 default 执行。复用确认查到已有 BF16 / quant / deploy 结果先汇报足够回答则不默认重跑先确认。升级确认第一轮直转结果出来后不默认升级确认「接受 / 改方案重测 / 升级」。直转 → PTQ 确认先说明为何不能停在直转确认后再升级。deploy 精度门进 deploy 前必须已产出ppl_bf16 / ppl_quant / delta精度结论并由用户确认接受缺 PPL 精度结论不得进 deploy。「实验结束」不等同「自动 deploy」。「量化方案推荐卡」的完整字段见 scheme-recommendation/SKILL.md至少包含当前模型 / 任务口径 / 相似案例 / 候选方案保守 / 首推 / 激进至少 2~3 个/ 首推方案 / 推荐理由 / 风险点 / 升级条件 / 回退方案 / 证据强度。若评估依据不足必须明确写「弱推荐」或「待验证」不得装作确定。六、工作流程阶段判断、固定流程与量化实验环6.1 阶段判断与固定流程先把当前任务归入阶段 1–6 其一再按固定流程推进先查现有结果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 结果核对当前代码、模型版本、量化目标、口径是否一致。足够则复用并说明口径仅在变化时重跑。阶段 1 / 2 →$model-adapter。阶段 3 → 进入量化实验环见 6.2。阶段 4 →$deploy-export。阶段 5 →$deploy-export目标改为复核 deploy 产物 按模板生成deploy_quantization.md 与导出目录一一绑定。阶段 6 → 先整理复用已有结论再决定是否还要调子 skill。跨阶段按序推进$model-adapter→ 量化实验环 →$deploy-export。任一次进入 deploy权重导出 ≠ 全流程结束只有deploy_quantization.md已补齐并足以给 infer 仓使用deploy 才算闭环。6.2 量化实验环阶段 3 核心进入量化实验环前先按序读三份参考资料先读 metrics-and-thresholds.md指标与边界→ direct-quant.md直转量化实验设计需升级 PTQ 再读 ptq-escalation.mdPTQ 升级条件与最小范围原则。随后按固定步序执行无可执行的第一轮直转方案 →$scheme-recommendation产出「量化方案推荐卡」。implementer 跑$quant-run出第一轮直转ppl_bf16/ppl_quantreviewer 用$direct-quant-eval判delta。delta 0.2→ 可接受、可停止升级delta 0.2→ 未选算法走$algorithm-recommendation已选算法由 implementer 跑$quant-run含 ptq 带--algos的结果评测、reviewer 用$algorithm-validation判收益。直转 算法验证后仍不达标 → 做一轮粗粒度误差定位只有粗定位之后才允许在最小范围引入 PTQ。每轮结束必须输出下一步决策停止 / 补定位 / 小幅升级。默认取向先直转再 PTQ先整网方案再缩到 block / unit误差定位只做粗粒度PTQ 先最小范围。量化后 PPL 明显优于 BF16 很多时先查链路不直接当成功对应 direct-quant.md 的「结果异常」处理优先怀疑评测链路、wrapper 实现、forward / mask 逻辑、保存与加载不一致。关于直转判读与 PTQ 升级的关键口径可进一步印证第一轮判读direct-quant.mddelta 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 21 后台跑 多次短调用轮询ptq 被中断用--start_block_idx 下一未完成层续跑逐层存参不重复也可主动--start_block_idx/--end_block_idx分块控制每块在超时窗口内。6.3 单段分流用户只覆盖其中一段时直接转对应叶子 skill不默认走完整流程用户诉求路由目标只要方案$scheme-recommendation已指定方案、只看 deltaimplementer 跑$quant-run reviewer$direct-quant-eval判读只导出$deploy-export不在此重做评测 / PTQ / 精度判定只推荐算法$algorithm-recommendation只验证算法implementer 跑$quant-run含 ptq reviewer$algorithm-validation判读七、状态协议与交付progress.md 机读状态块7.1 机读状态块供轮询 / 多 agent 集成progress.md顶部维护一个机读状态块编排入口负责初始化与收尾更新子代理在各自轮次更新。上游 / 多 agent 集成只需轮询此块判断进度无需读全文。格式为逐行可解析的key: valueSTAGE: 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: BLOCKEDBLOCKED: 缺失项 — 回退 hint如数据不可达set HF_ENDPOINT 镜像 / 用 modelscope / 指本地路径并停止不臆造继续。终态达标可交付写STATUS: DONEDELTAARTIFACTS。7.2 两段式结构防上下文膨胀机读状态块之下分两段用标记分隔!-- 以上为常驻区不清除 -- !-- 以下为工作区阶段推进时归档并清空 --常驻区机读状态块 产物契约结论 阶段概览编排维护只追加不清空工作区各子代理按角色追加方案分析 / 实施记录 / 验证·判读 / 诊断阶段推进时由编排运行本 skill 自带的归档脚本 .agents/skills/quant-workflow/scripts/archive_progress.py注意脚本路径相对本 skill 目录、非仓库根把工作区归档到progress_history.md并清空历史只 Grepprogress_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 4096BF16 baseline 即把--eval_mode换成bf16。bit 配置--bit_config指向 amct_pytorch/configs/ 下的 yaml如w8a8.yaml/w4a8.yaml/w4a4.yaml/bf16.yaml顶层w_bits/a_bitsmoe.routed/sharedattn-cache的 q/k/p/v。量化目标与算法quant_target支持mlp/moe/attn-linear/attn-cache一次只聚焦一个角色、多角色分别跑并分别给参数目录算法只认 new-pathLLMALGO_REGISTRY当前 autoround / lac / lwc / let其中lwc let为完整的 omniquant 算法gptq/awq/mxfp 视分支移植。参数目录约定quant-run/SKILL.mdmlp / moe →--moe_mlp_param_dir二者共用无--mlp_param_dirattn-linear →--attn_linear_param_dirattn-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.jsonindex.json并补齐deploy_quantization.md。其关键边界与quant-workflow的阶段 4/5 语义一致导出模式判定用户期望直转 / PTQ / 未明确vs 实际直转 / PTQ / 混合不一致时必须在执行前说明本意 PTQ 但某 target 回退直转 → 结论必须显式指出不能静默继续。产物静态自检不碰 infer runtimeobject 级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_bits8/8W8A8 恰好正确但 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
