昇腾 SuperKernel Auto Tune 编排指南证据门控的自动调优会话与阶段委派机制【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusionSuperKernel Auto Tune 是 CANN graph-autofusion 仓库中面向昇腾AscendSuperKernel 场景的自动调优编排 Skill它以单一控制 Agent 按阶段动态委派通用子 Agent 结构化交接与证据门控的方式完整驱动一次从环境确认、S0 基线、Stage A 框定方式选择、Stage O Option 调优、BASE profile 与源映射到最终 E2E 报告的全生命周期调优会话。本文基于.claude/skills/superkernel-auto-tune/SKILL.md及同目录下的脚本、Schema 与参考文献展开读者读完将掌握如何用auto_tune_session.py创建、推进、恢复并封存一次会话如何理解七个阶段逻辑工作者的职责边界以及为什么冻结会话、密封证据、拒绝口头交接是该编排器的核心纪律。编排器定位唯一控制器绝不亲自执行阶段superkernel-auto-tune是整个调优流程的唯一控制器sole controller。它的职责是冻结一个会话session及其产物根目录artifact root为每一个待处理阶段调度dispatch一个全新的宿主原生通用子 Agenthost-native generic subagent校验子 Agent 返回的结构化交接structured handoff无论调优成功、失败还是被阻塞都必须推进到最终报告Final report步骤。控制器自身从不执行任何调优阶段也不需要预先注册任何自定义 Agent 配置文件custom Agent profiles。这与传统主 Agent 自己做实验的编排方式形成鲜明对比所有测量、筛选、分析、实验全部由按阶段新建的通用子 Agent 完成控制器只负责调度、验证与记录。从源码可以印证这一设计auto_tune_session.py 中的run_agent_step()通过subprocess.run调用由宿主适配器--runner-command-json传入的命令指定的通用子 Agent而不是任何 Agent 注册表create_dispatch_task()也只生成结构化的phase-task并不包含任何阶段执行逻辑。会话支持两种进入方式完整入口full Intake从环境确认一路走到最终报告证据门控派生入口evidence-gated derived entries在父会话完成后基于已接受的证据派生新的可选实验会话。无论哪种方式都不允许重新打开一个已完成completed的会话也不允许把被跳过的阶段人为标记为已封存。会话创建、推进与恢复控制平面命令全景编排器把调优会话持久化为一个 JSON 文档schema 为superkernel-auto-tune-session-v1并暴露一组子命令作为可执行控制平面。初始化会话init创建会话时必须一次性地确定唯一的可选模式optional mode随后在整个会话中被冻结不允许中途更改python3 scripts/auto_tune_session.py init \ --session artifact-root/auto-tune-session.json \ --artifact-root artifact-root --session-id run-id \ --optional-mode none|multistream|source-range|both--optional-mode的四种取值对应不同的实验范围源码中由OPTIONAL_MODES {none, multistream, source-range, both}硬校验模式含义会话步骤影响none不执行任何可选实验可选实验步骤以not_requested状态封存multistream执行双流多流性能调优在 BASE/SMAP 之后追加 optional-multistream 步骤source-range执行 P/FINAL 源码区间优化分支需要匹配 digest 校验的source_scope_map_v2与exact_cover区间both先双流、再源码区间两种都要先执行 multistream接受后插入base-profile-derived再执行 source-range--artifact-root是冻结的产物根目录会话 JSON 就放在该根目录下会话 ID 仅需是非空字符串但派生会话的 ID 必须与父会话不同。查询下一步与派发任务next / dispatch每次派发之前都必须先查询会话的合法下一步python3 scripts/auto_tune_session.py next \ --session artifact-root/auto-tune-session.json python3 scripts/auto_tune_session.py dispatch \ --session artifact-root/auto-tune-session.json \ --output artifact-root/dispatch-task.jsonnext返回唯一合法的step_id、phase、agent_id与skilldispatch则据此生成一个superkernel-auto-tune-phase-task-v1任务文档。该任务绑定当前会话指纹session fingerprint、输入交接consumed handoffs、唯一合法步骤以及必需的返回结果 Schema。从源码看validate_dispatch_task() 会将待派发任务与create_dispatch_task()实时生成的当前任务逐字段比对session_id、session_path、artifact_root、session_fingerprint、step、evidence_import、consumed_handoffs任何一项不一致即判定为过期任务stale dispatch task并拒绝执行——这是防止旧任务被错误重放的关键机制。一步式运行run-next当宿主提供命令适配器command adapter时可用run-next一步完成派发 执行 验证 封存python3 scripts/auto_tune_session.py run-next \ --session artifact-root/auto-tune-session.json \ --runner-command-json agent-host-command.json \ --timeout-seconds 3600run-next会自动在dispatches/step-id-attempt-NNN/下创建尝试目录为子 Agent 命令追加--task path --result path参数捕获子 Agent 的标准输出/错误日志验证并封存seal返回的phase-result.json记录不可变的分派回执dispatch receipt并把回执路径与 digest 绑定进已封存的会话步骤。失败、超时或无效的尝试会保留在dispatches/目录下步骤保持 pending 状态可以随时进行可恢复的重试。源码中_next_dispatch_root()按step_id-attempt-001递增创建尝试目录直到找到空目录为止subprocess.TimeoutExpired会被捕获并写入runner_status: timed_out回执后重新抛出交由控制器决定重试策略。中断恢复resume编排器明确要求中断之后不得从聊天历史推断进度只能从持久化的会话文件恢复python3 scripts/auto_tune_session.py resume \ --session artifact-root/auto-tune-session.jsonresume会重新加载会话、执行完整验证然后返回当前next_step任何无法通过验证的会话都会拒绝恢复并给出错误列表。证据门控的派生会话导入父会话的可信证据当用户在完整会话父会话完成后又明确要求执行 multistream 或 P/FINAL 实验时不能直接开新会话重跑而必须从已完成的父会话派生新会话python3 scripts/auto_tune_session.py derive-session \ --parent-session parent-root/auto-tune-session.json \ --session new-root/auto-tune-session.json --artifact-root new-root \ --session-id new-run-id --optional-mode multistream|source-range|both \ --profiling-analysis parent-root/analysis.json \ --ledger parent-root/ledger.json \ --source-scope-map parent-root/source-scope-map.json \ --approve-imported-evidence派生会话的硬性前提源码derive_session()中逐条强制校验必须显式携带--approve-imported-evidence用户明确批准导入证据父会话必须状态为completed且整体验证通过新会话 ID 不能与父会话相同父与子的 artifact root 必须不相交disjoint防止产物互相污染导入的分析必须是schema 1.2且其analysis_content_fingerprint自校验通过导入的账本必须是schema 2实验账本且包含被分析的那一轮 BASE 记录source_revision与分析一致source-range与both模式还要求source_scope_map_v2schema 2.0 或 2.1的provenance.source_scope_map_content_fingerprint通过且其中至少存在一个relation exact_cover的可行动区间所有被导入的文件都必须已被父会话的 BASE/SMAP 交接声明为 consumed/produced artifacts。P/FINAL 专用路径也可用source-range-from-smap命令或独立的superkernel-source-range-from-smapSkill直接派生。派生任务会携带不可变的evidence_import引用指向imports/evidence-import.json每次派发前都必须重新验证该引用因为load_session()会按evidence_import.sha256重新计算清单 digest 并比对。both模式的派生顺序有讲究从 multistream 开始若 multistream 被接受seal时会在步骤列表中插入一个全新的base-profile-derivedBASE/SMAP 步骤源码_insert_derived_base()只有完成该派生 BASE 后才允许进入 source-range 步骤。动态原生委派一次阶段、一个全新子 Agent宿主通用子 Agent 映射控制器不依赖任何预注册的自定义 Agent 配置而是使用各宿主内置的通用子 Agent 机制宿主内置通用子 AgentCodexworker仅存在通用默认角色时用defaultClaude Codegeneral-purposeOpenCodegeneralagent_id是稳定的逻辑阶段/任务/审计标识也是用户可见的任务名但它不是某个注册 Agent profile 的名字。子 Agent 提示词必须包含的五要素控制器在派发每个阶段时必须在其子提示词中完整包含精确的phase-task.json路径及其step.agent_id、step.phase、step.skill显式指令加载并遵循step.skill——因为通用子 Agent不会继承控制器 Skill 的指令对应的阶段校验命令scripts/execute_phase.py --task phase-task.json必须在任何实验命令之前先跑精确的可写结果路径以及必需的superkernel-auto-tune-phase-result-v1Schema边界声明该子 Agent 只拥有当前这一个阶段不得派发或执行后续阶段。阶段清单与责任七个逻辑工作者的职责如下控制器一次只派发一个等待其完成、验证并封存后再next逻辑工作者 IDSkill用户可见职责sk-intake-preparationsuperkernel-intake-preparation环境确认与实验准备sk-s0-baselinesuperkernel-s0-baselineS0 基线性能测量sk-stage-a-scope-selectionsuperkernel-stage-a-scope-selectionStage A 框定方式选择sk-stage-o-option-tuningsuperkernel-stage-o-option-tuningStage O Option 调优sk-base-profile-source-mappingsuperkernel-base-profile-source-mappingBASE profile、独立分析与 SMAPsk-optional-experimentssuperkernel-optional-experiments双流与 P/FINAL 实验sk-final-e2e-reportsuperkernel-final-e2e-report最终 E2E 确认与报告对应关系在源码的PHASES字典中逐条硬编码且_validate_session()会校验每个步骤的agent_id与skill必须与阶段完全匹配杜绝张冠李戴。阶段工具白名单与 NPU 租约阶段入口会默认打印其所属的工具计划。要单独运行其中一个工具使用python3 scripts/execute_phase.py --task dispatch-task.json --tool listed-tool \ --lease-root lease-root --device-id id -- tool argsphase_entrypoint.py 会校验任务与当前会话一致复用validate_dispatch_task并核对任务中的phase/agent_id/skill与阶段清单匹配拒绝执行不在阶段白名单runtime_tools内的工具通过共享的 NPU 租约运行器device_lease_runner.run_command执行子命令把--lease-root、--device-id、超时与清单输出统一托管。封存、验证与短路规则让每一步都留下不可变证据子 Agent 返回唯一的superkernel-auto-tune-phase-result-v1文档后控制器必须先封存seal并验证verify才能继续nextpython3 scripts/auto_tune_session.py seal \ --session artifact-root/auto-tune-session.json --result handoff.json python3 scripts/auto_tune_session.py verify \ --session artifact-root/auto-tune-session.jsonseal写出不可变的phase-result.json与PHASE_REPORT.md位于phases/step-id/下并把result_path、result_sha256、outcome_status、sealed_at绑定回会话步骤封存最终交接时会渲染FINAL_E2E_REPORT.md。verify会重算每个已封存步骤的 result digest、核对PHASE_REPORT.md存在性、校验回执 digest并确认 completed 会话存在最终报告。会话验证器拒绝任何非规范阶段顺序或阶段无效状态。一个关键设计是短路short-circuit机制当 Intake、S0、Stage A、BASE 被阻塞或 Stage O 被阻塞/失败时后续不适用的阶段会自动生成not_run场景system_generated_by: superkernel-auto-tune只留下 Final 合法。源码_must_short_circuit()定义了触发条件Intake/S0 必须succeededStage A 必须acceptedStage O 必须是accepted或no_gainBASE 必须是succeeded或no_gain一旦触发_seal_not_run_steps()会为所有剩余 pending 步骤写出带阻塞原因的not_run结果——宁可不测也绝不伪造比较。另外每个步骤的结果状态都有合法集合限制源码PHASE_STATUSES例如final_e2e_report接受accepted/no_gain/blocked/failed/invalid/not_runoptional_experiments的状态还依赖分支——none分支只允许not_requested。最终结果的status还必须与 schema 2 账本final_e2e.classification严格对应beneficial→accepted、no_gain→no_gain、not_run→not_run等并由_validate_result()强制校验。支持委派五个只读/隔离的执行与诊断角色除了七个阶段工作者编排器还定义了五个**支持委派support delegation**ID。它们同样是逻辑任务/审计 ID每次需要时也要新建一个全新的宿主原生通用子 Agent以逻辑 ID 作为可见任务名并显式加载对应工具 Skill支持 ID加载的 Skill用途sk-fusion-performance-analysissuperkernel-fusion-performance-analysis不可变的逐 SKper-SK融合性能分析sk-multistream-tuning-executorsuperkernel-multistream-performance-tuning隔离的双流调优执行sk-source-range-experiment-executorsuperkernel-optional-experiments仅执行被显式授权的 P/FINAL source-range 分支sk-failure-isolation-analystsuperkernel-sk-failure-isolation修改失败范围前必须遵循的失败隔离分析sk-prof-timeline-analystsuperkernel-sk-prof-timeline聚焦的 Cube/Vector 调度时间线检查其中性能分析子 Agent 是只读的可以读不可变产物只能写自己的分析结果与中文报告不得运行推理、修改源码、变更范围或改动 Option。域契约与转移规则调优结果的唯一权威编排器明确声明保留的硬证据门禁、安全约束、Option 规则、profiling 规则与历史失败限制全部集中在 controller-legacy-contract.md每个阶段 Skill 都标识出它负责的精确小节schema 2 实验账本experiment ledger是实验证据的唯一权威。账本中结构化的final_e2e对象是唯一的终端性能判定记录分类classification、精确候选candidate、SK 框定方式scope strategy、Option map、证据、理由以及执行时的干净基线/候选指标。_validate_final_e2e()还会重新计算improvement_pct (baseline - candidate) / baseline * 100与声明值不一致相对误差 1e-6 内即判定无效——杜绝手工编造收益。Final 步骤绑定相对的ledger_path控制器校验状态一致性并为每个终端结果渲染FINAL_E2E_REPORT.md其report_summary采用 result-first 结构依据 report-summary.md。控制器的八条转移规则见 auto-tune-session.md可概括为Intake 冻结 optional mode关键环境阻塞直接进入最终报告并记 E2Enot_runS0 只有通过保留的五次运行稳定性门禁后置 warmup 的 TP worst-rank 均值离散度(max-min)/mean 5%才能推进Stage A 返回一个Sbest-SEED或无赢家终端结果无赢家直接进入最终报告不执行 Stage OStage O 必须先结算整个矩阵再返回Sbest-BASE单个失败/被拒试验仍是阶段证据不终止矩阵BASE profile/源映射返回合法现任incumbent或默认赢家失败只有既有的候选排名策略才允许对下一个 Stage A 候选重新进入 Stage Ooptional modenone记为not_requestedboth先执行 multistream接受则创建派生族并把旧 BASE 标记superseded在 P/FINAL 前回到 BASEP/FINAL 只接收当前已映射的 BASE 现任绝不改动冻结的 Option map最终报告阶段总是执行只有当保留的晋级门禁允许时才跑干净 E2E 对比否则以not_run记录决定性证据。会话文件结构一个可复现、可审计的编排索引会话 JSON 是编排索引而非账本的替代品。其核心字段auto-tune-session-v1.schema.json 有精确约束包括{ schema_version: superkernel-auto-tune-session-v1, session_id: SK-20260905-001, optional_mode: none|multistream|source-range|both, entrypoint: full|optional-from-base|source-range-from-smap, status: active|completed, artifact_root: /absolute/frozen/artifact/root, steps: [ { step_id: intake-preparation, phase: intake_preparation, agent_id: sk-intake-preparation, skill: superkernel-intake-preparation, state: pending|sealed } ] }关键约束非 full 会话还必须包含evidence_import.path与evidence_import.sha256sha256 必须是 64 位十六进制每个步骤的agent_id/skill与 phase 的映射被严格校验已封存步骤绑定不可变的result_path/result_sha256/outcome_status可选绑定dispatch_receipt_path/dispatch_receipt_sha256step_id必须匹配^[a-z][a-z0-9-]{1,63}$且不允许重复已封存步骤不能出现在 pending 步骤之后顺序完整性status: completed的会话不允许存在 pending 步骤。除此之外每次 load、resume、verify、dispatch 都会重新校验evidence_import引用的外部文件父会话 digest、BASE 交接 digest、导入 artifact 的 sha256 与 size_bytes确保派生态的每一步都锚定在真实存在的父证据上。阶段执行器子 Agent 的工具计划与租约托管阶段入口scripts/execute_phase.py即 phase_entrypoint.py是子 Agent 运行时的第一道闸门。它从阶段清单phase manifestschemasuperkernel-phase-manifest-v1加载phase、agent_id、skill与runtime_tools白名单然后无--tool参数时打印该阶段的工具计划每个工具一条--help命令与交接 Schema供子 Agent 决策带--tool参数时强制要求--lease-root与至少一个--device-id把工具命令经device_lease_runner.run_command提交并将执行清单输出到phase-executions/step-id/tool.json对非白名单工具直接拒绝。这样就把NPU 设备租约超时控制清单留存统一收口实验子 Agent 只需要关心自己的工具语义不需要自行管理设备占用。编排纪律四条不可逾越的边界综合 SKILL.md 与 controller-legacy-contract.md使用该编排器时有四条硬性纪律绝不手改会话不要手工编辑 session JSON 或已封存的phase-result.json所有状态迁移只能通过init/next/dispatch/seal/verify等命令完成。绝不以口头结果推进不能在子 Agent 口头汇报完成了之后就派发下一阶段必须等到它产出结构化的 phase result、控制器完成 seal 与 verify。绝不跨阶段复用子 Agent每个阶段必须新建一个全新的通用子 Agent等待其结束、验证并封存后再next查询下一步。宿主无法创建通用子 Agent 时绝不代劳如果宿主不支持原生通用子 Agent应保持步骤 pending、保留派发失败现场并上报阻塞原因控制器不得冒充阶段工作者自行执行阶段。结语一次可复现、可审计、可追溯的自动调优SuperKernel Auto Tune 编排器把昇腾 SuperKernel 调优从凭经验试参数转变为证据门控的编排流水线会话文件记录每一步的状态与 digest阶段任务绑定会话指纹与输入交接结果文档以统一 Schema 封存schema 2 账本持有最终判定的唯一权威。无论最终结论是beneficial、no_gain还是not_run都会生成结构化的最终报告使每一次调优尝试都可以被完整复现与审计。对于希望在昇腾 A2/A3 设备上对模型执行可复现的 SuperKernel 性能调优的开发者而言这套以.claude/skills/superkernel-auto-tune/为核心的编排体系是理解和使用 graph-autofusion 自动融合调优能力的重要入口。进一步阅读完整的八条转移规则与各阶段门禁见 auto-tune-session.md硬性安全约束与历史失败限制见 controller-legacy-contract.mdIntake 阶段的环境与实验信息采集模板见 intake-checklist.md控制平面实现可深入研读 auto_tune_session.py 与 phase_entrypoint.py。【免费下载链接】graph-autofusionGraph-autofusion 是一个面向昇腾Ascend芯片的轻量级、解耦式组件集合旨在通过自动融合技术加速模型执行。 目前已开源 SuperKernel 组件和 Autofuse 组件未来将持续开放更多自动融合相关模块。项目地址: https://gitcode.com/cann/graph-autofusion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考