kali20gakki/msAgent / skills/host-cpu/msagent-perf-cpu-bind-tune
msagent-perf-cpu-bind-tune
Flagged昇腾 NPU 多卡任务的 Host CPU 绑核方案求解器:覆盖 PyTorch 训练/离线推理与 vLLM-Ascend、SGLang 推理服务的 rank/worker/engine 分核,基于 NUMA 拓扑与 卡↔进程映射输出可执行、可回滚、可验证的绑核计划(taskset 前缀 / cpuset / OMP 环境变量),自动判定事前(env 片段)与事中(在线 sched_setaffinity)双形态。 触发:绑核方案、核怎么分、per-rank 绑核、NUMA 绑定方案、cpuset 划分、多卡分核、 CPU range 冲突、TTFT 或吞吐受 CPU 影响。 不用于:绑核没生效/绑核异常诊断(→ perf-cpu-config-audit);运行期是否落核 (→ perf-cpu-tracing);变慢根因归因(→ perf-cpu-perf-triage)。
msagent-perf-cpu-bind-tune
粗粒度绑核与 NUMA 亲和求解:给定 NPU/CPU 拓扑(事中另含实际业务进程/线程), 输出每个 unit(训练 rank / 推理实例)及角色的核集、命令、回滚、验证脚本与 HTML 报告。
只出方案,不执行。taskset 等动作由主会话确认后执行;运行期落核验证交 tracing,
效果复检交 perf-triage / config-audit。
形态判定(自动,无需用户输入)
preflight只探测npu-smi可执行文件是否存在;npu_query调用npu-smi info,按“任一 NPU 有占用进程”判定:- 有任务 → 事中(主场景):按实际业务卡↔进程、进程树、线程角色、affinity/numa_maps 求解;
- 无任务 → 事前(兜底):按拓扑 + 框架画像预规划,进程级偏差标
not_observable; npu-smi不可用 / 调用失败 / 无 NPU 设备 → blocked:不执行绑核分析,不生成 plan/HTML。
- 同时判定 locality 模式:
npu-smi info -t topo是否带CPU Affinity列;/sys/bus/ub/devices可见则标记fabric=ub;超节点矩阵(SIO/HCCS_SW)标fabric=hccs_supernode。
快速开始
apply_plan.py/verify_config.py属求解层脚本;仅合入采集层时命令不可用,待求解层提供后执行。
# 事中:A2 上已有 VLLM Worker
# 默认输出到 <workspace>/workspaces/<host>/<timestamp>/
python3 scripts/plan.py
# 显式指定输出目录(旧行为 / CI)
python3 scripts/plan.py --out ./out
# 调预留核(默认 system 2 + interference 1)
python3 scripts/plan.py --irq-reserve 2 --interference-reserve 1
# 查看方案(plan-only,不执行;建议先 --dry-run)
python3 scripts/apply_plan.py <plan.json> --dry-run
# 确认后执行:主线程 + comm/io + compute(按 plan 的 apply 语义)
python3 scripts/apply_plan.py <plan.json> --roles comm,io
# 旧计划标 compute=inherit 时,需要才强制一起绑
python3 scripts/apply_plan.py <plan.json> --roles comm,io --bind-compute
# 回滚(按 before.Cpus_allowed_list 恢复)
python3 scripts/apply_plan.py <plan.json> --rollback
# 现状 vs 目标 gap 分析(plan-only 预期有 FAIL;apply 后应全 PASS)
python3 scripts/verify_config.py <plan.json> --threads
工作空间与输出
- skill 代码:本 SKILL.md 所在目录(
scripts/、references/、resources/)。 - 工作空间:Agent 运行时设置的工作路径(cwd),由宿主或远程执行插件决定;skill 不猜测自身安装位置。
- 运行产物:
<workspace>/workspaces/<host>/<timestamp>/,包含 plan / report / verify 脚本;skill 目录只放代码、references、resources,不写运行产物。 - 覆盖方式:
--out <dir>显式指定;HOSTCPU_WORKSPACE=<root>覆盖工作空间根。 - 远端执行:skill 拷贝到远端何处、以什么 cwd 执行,由远程执行插件控制;skill 只按传入的 cwd/参数落盘,不自行选择远端目录。
- 离线回归测试:仓库
tests/skills/msagent-perf-cpu-bind-tune/(开发期使用,不随 skill 分发)。
输出:
hostcpu_plan_<host>_<ts>.json:plan(units / roles / commands / before / rollback / verify / zones / deviations)hostcpu_verify_<host>_<ts>.sh:配置生效验证脚本hostcpu_report_<host>_<ts>.html:NUMA 拓扑与设备卡片、NUMA 亲和矩阵(NPU/NIC/存储 × node,本地/远端时延/不可观测)、node×node 时延矩阵、unit→核分配、角色核分配条、偏差与结论、验证与回滚
关键设计
- NPU 锚点:
npu-smi info的卡↔进程映射是权威锚点;同 pid 多卡条目按进程内存取 primary NPU,避免把 117MB 控制内存误判为主卡。 - 两种绑核策略(按能力自动选择,写入
fabric/locality_mode;命名对齐 vllm-ascend CPU Binding):topo_affinity:npu-smi info -t topo带CPU Affinity且可解析(A2 / A200T A3 Box8 等;A5 上 UB 与亲和列可同时存在)→ 按 NPU 主机口就近核组求解,per_npu每卡独占、group同组 unit 均分;global_slice:无CPU Affinity(超节点矩阵UB/HCCS_SW/SIO)或亲和不可用 → 按封装分组把可见 CPU 池均分到各 node(双 die 机型同封装 die 的 unit 锁定同一 node),切片对齐 NUMA 边界、unit 间不重叠;NIC/存储/IRQ 仍按各自 node 就近。
- 判定按能力而非代际:只依据 topo 的
CPU Affinity列、关系符号、亲和重复度,以及 sysfs 的numa_node/local_cpulist//sys/bus/ub/devices;A2/A3/A5 仅用于预期校验与文案,实测不符只告警、不切策略。不依赖npu-smi info -t product(部分产品/版本无此子命令)。 fabric与CPU Affinity是两条独立信号:fabric看关系符号(UB/HCCS*/SIO/PHB),描述 NPU 间平面;CPU Affinity描述 NPU 主机口到本机 CPU 组的就近关系。A5 可为fabric=ub且带亲和列,此时仍走topo_affinity。- 亲和粒度(
affinity_granularity):多个 NPU 共享同一核区间时为group(如 A5 的 NPU0/1/6/7→288-383、NPU2-5→96-191),绑核需在同组 unit 间再均分该区间,不能按单卡独占整段。 - NPU→CPU 亲和:直接使用
npu-smi info -t topo的CPU Affinity列(A2 实机为 0/1→144-167、2/3→96-119、4/5→0-23、6/7→48-71),不假设 NPU 与 node 顺序对应;Phy-ID矩阵按表头判断是否存在该列,不再视作解析失败。 - 按 node 划区:每个 node 预留 system_irq 与 interference,剩余业务区在同 node 的多个 unit 间均分。
- 角色分核:compute / comm / io / main;通信与 NPU runtime 独立核,ZMQ/tokenizer/dataloader 等 IO 独立核。
- local-first:优先把 unit 放到 NPU 所在 node;若 plan 核数少于当前亲和,标
capacity_gap,不静默扩到跨 node。 - 权限降级:
numa_maps不可读时标not_observable,不伪造远端页占比;npu-smi缺失直接 blocked。
权限降级 / 普通用户 / 沙箱
- 数据来源:拓扑与设备亲和全部取自 sysfs(
/sys/devices/system/node、CPUnode*、NIC/存储numa_node)+npu-smi info -t topo;NPU→CPU 降级顺序为topo CPU Affinity → PCI local_cpulist → PCI numa_node,不依赖任何额外安装的工具。 - 普通用户权限:
Cpus_allowed_list、Mems_allowed_list、cmdline、cgroup、线程comm/stat通常可读;他人进程numa_maps不可读时标view_limited,远端页占比not_observable,用last_cpu作弱证据。taskset他人进程需 sudo →execution_mode=delegated,plan 只出命令、不自动执行。 - apply 属主校验:
apply_plan.py实际执行(非--dry-run)前逐一校验目标进程属主——目标 uid 与当前用户不一致且当前非 root 时拒绝并提示 delegated 路径,防止 plan 生成后进程属主变化导致误绑他人进程;dry-run 放行用于展示动作清单。 - 沙箱与确认:R0 本机只读自动允许;R1 远端只读一次主机授权 + 只读白名单;R2 本地方案写自动允许;R3 远端临时写一次确认;R4
taskset/cgroup/sysctl 永不自动。推荐 SSH key +ControlMaster+ 单次批量采集 +plan.py --dry-run --print-plan,减少重复确认。
边界
- 不做配置审计/诊断 →
config-audit; - 不做运行期落核验证 →
tracing --plan; - 不做效果复检 →
perf-triage/config-audit; - 不做 IRQ 亲和、大页、频率、cgroup 配额 →
config-audit; - 不做 NPU 微架构分析、代码/算子改写;
- 与旧技能
mindstudio-cpu-binding的分工:旧技能输出诊断报告与保守/进阶建议,本技能负责采集与可执行方案(plan / 命令 / 回滚 / 验证);Host CPU 场景后续由msagent-perf-cpu-*系列替代旧技能,迁移期两者并存。
目录
scripts/
plan.py # 入口:参数校验 + 流程编排(形态判定在 preflight,可行性在 feasibility)
preflight.py # npu-smi 存在性 / 容器 / 工具探测
npu_query.py # npu-smi 唯一封装点:设备 / 卡↔进程 / topo
topology.py # NUMA / CPU / SMT / L3 / NPU / NIC / 存储
procfs.py # status / cmdline / cgroup / affinity / numa_maps / threads
roles.py # 线程角色规则唯一来源(comm 关键字 → comm/io/compute/main)
discover.py # units + 偏差
model.py # unit→node/L3 建模
zone_alloc.py # 按 node 划区与业务区均分
unit_alloc.py # unit 内角色分核 + thread_binding
feasibility.py # C1-C5
emit_plan.py # plan / 命令 / 回滚 / 验证脚本
apply_plan.py # 主会话确认后执行:按 comm 枚举线程 + cgroup 裁剪 + 回滚
verify_config.py # 现状 gap / 生效校验
report.py # HTML 报告
workspace.py # 工作空间/输出目录解析
references/
process-roles.md # 进程/线程分类规则
framework-profiles.md
mechanisms.md # taskset / 启动包装 / cgroup / 调度器
checks.md # C1-C5
permissions.md # 权限降级 / 普通用户 / 沙箱确认策略
resources/
plan_template.json
report_template.html # 页面骨架(占位符由 report.py 填充)
report.css # 报告样式
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 467k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |