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)。
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.1 KB |
| references/checks.md | markdown | 1.4 KB |
| references/framework-profiles.md | markdown | 5.1 KB |
| references/mechanisms.md | markdown | 2.8 KB |
| references/permissions.md | markdown | 5.4 KB |
| references/process-roles.md | markdown | 2.8 KB |
| resources/plan_template.json | config | 4.7 KB |
| resources/report.css | other | 7.6 KB |
| resources/report_template.html | other | 3.9 KB |
| scripts/apply_plan.py | script | 11.8 KB |
| scripts/cpu_list.py | script | 1.4 KB |
| scripts/discover.py | script | 16.8 KB |
| scripts/emit_plan.py | script | 19.8 KB |
| scripts/feasibility.py | script | 4.7 KB |
| scripts/model.py | script | 9.5 KB |
| scripts/npu_query.py | script | 16.2 KB |
| scripts/plan.py | script | 10.7 KB |
| scripts/preflight.py | script | 5.0 KB |
| scripts/procfs.py | script | 9.0 KB |
| scripts/report.py | script | 31.0 KB |
| scripts/roles.py | script | 1.5 KB |
| scripts/topology.py | script | 16.8 KB |
| scripts/unit_alloc.py | script | 8.2 KB |
| scripts/verify_config.py | script | 5.7 KB |
| scripts/workspace.py | script | 2.5 KB |
| scripts/zone_alloc.py | script | 3.7 KB |
references/mechanisms.md
View on GitHub# 绑核机制与命令
> 与旧技能 `mindstudio-cpu-binding` 的分工:旧技能输出绑核诊断与建议(报告式),
> 本技能负责采集与可执行方案(plan / 命令 / 回滚 / 验证);Host CPU 场景后续由
> `msagent-perf-cpu-*` 系列替代旧技能,迁移期两者并存。
## 机制选型
| 机制 | 时机 | 适用 | 说明 |
| --- | --- | --- | --- |
| `taskset -pc` | 进程已存在(事中) | 单机排障、事后修正 | 立即生效;pid 可能复用,执行前需校验 |
| 启动包装 | 进程诞生前(事前) | 单机/容器 | `taskset` 前缀 + OMP env(`OMP_PROC_BIND` / `OMP_PLACES`) |
| cgroup cpuset | 容器创建时 | 容器/集群 | 进程/线程 fork 均受限,天然批量 |
| 调度器级 | 调度时 | 集群 | k8s CPU Manager / slurm --cpu-bind;本期只出清单,不生成模板 |
## 时机
```text
t0 容器创建 -> cgroup cpuset 圈定容器 CPU 集
t1 entrypoint -> 启动包装:taskset 前缀 + OMP_PROC_BIND
t2 进程 spawn -> 线程继承 affinity
t3 特殊线程 -> 仅对通信/IO 线程按 comm 匹配二次细绑
```
## 命令契约
> 版本说明:`apply_plan.py` / `verify_config.py` 属求解层脚本。仅合入采集层时这些脚本不存在,
> 下列命令只作契约参考,待求解层提供后可直接执行。
```bash
# 执行(plan-only 只生成该命令,不执行;需主会话确认)
python3 <skill>/scripts/apply_plan.py <plan.json> --roles comm,io
python3 <skill>/scripts/apply_plan.py <plan.json> --roles comm,io --bind-compute
python3 <skill>/scripts/apply_plan.py <plan.json> --dry-run
# 回滚(按 before.Cpus_allowed_list 恢复主线程与全部线程)
python3 <skill>/scripts/apply_plan.py <plan.json> --rollback
# 校验(apply 前后均可;plan-only 时预期 FAIL)
python3 <skill>/scripts/verify_config.py <plan.json> --threads
```
- Linux 只有线程级亲和:`main` 绑 `tid==pid`;`comm`/`io` 在执行时枚举 `/proc/<pid>/task` 并按 comm 匹配;
- `compute` 默认按 plan 的 `apply=exec` 绑定到 compute 核集(与 `OMP_NUM_THREADS` 一致);
旧计划标 `inherit` 时用 `--bind-compute` 强制绑定;
- 目标核先与 cgroup `cpuset.cpus.effective` 取交集,越界部分不会生效;
- plan 不保存 tid 快照,避免执行时线程重建导致绑错;
- 不按 pid 做集群批量;集群走 cpuset/启动包装,避免 pid 复用误绑。
## 验证
- 配置生效:`verify_config.py <plan.json> --threads`(主线程 + 按 comm 枚举线程,与 cgroup 裁剪后的期望比对)
- 单点核对:`awk '/^Cpus_allowed_list:/{print $2}' /proc/<pid>/status`、`/proc/<pid>/task/<tid>/status`
- 运行落核:`tracing --plan <plan.json>`
- 效果:`sched_delay_p99_us`、`remote_page_ratio`、`migration_per_s`
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: 472k | 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: 472k | 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: 472k | 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: 194k | Updated | Claude CodeCodex | Verified | Install |