Skip to content

kali20gakki/msAgent / skills/profiler/mindstudio-cpu-binding

mindstudio-cpu-binding

Verified

Use when diagnosing NPU + PyTorch or LLM Serving Host CPU affinity, NUMA locality, cgroup/cpuset constraints, CPU range conflicts, PyTorch/runtime threading, DataLoader, tokenizer, scheduler, vLLM-Ascend, SGLang, TTFT, TPOT, tokens/s, QPS, or multi-rank/multi-worker CPU binding issues.

FileKindSize
README.mdmarkdown8.6 KB
SKILL.mdskill md16.4 KB
assets/architecture-overview.mmdother1.3 KB
assets/component-class-diagram.mmdother2.4 KB
assets/data-flow-diagram.mmdother732 B
assets/use-case-diagram.mmdother640 B
docs/agent-workflow.mdmarkdown16.7 KB
docs/architecture.mdmarkdown4.1 KB
docs/binding-rollback-design.mdmarkdown6.1 KB
docs/collector-design.mdmarkdown10.9 KB
docs/diagnosis-rules.mdmarkdown13.5 KB
docs/html-report-design.mdmarkdown7.6 KB
docs/question-flow.mdmarkdown15.4 KB
docs/snapshot-schema.mdmarkdown13.2 KB
scripts/__init__.pyscript805 B
scripts/cli.pyscript10.4 KB
scripts/collect.pyscript13.5 KB
scripts/collectors/__init__.pyscript744 B
scripts/collectors/availability.pyscript2.7 KB
scripts/collectors/key_processes.pyscript8.0 KB
scripts/collectors/linux_cgroup.pyscript9.2 KB
scripts/collectors/linux_cpu.pyscript5.8 KB
scripts/collectors/linux_proc.pyscript8.2 KB
scripts/collectors/npu_topology.pyscript8.0 KB
scripts/collectors/runtime_env.pyscript4.6 KB
scripts/collectors/runtime_sample.pyscript7.2 KB
scripts/collectors/sanitize.pyscript2.0 KB
scripts/cpulist.pyscript3.5 KB
scripts/diagnose.pyscript17.5 KB
scripts/executors/__init__.pyscript754 B
scripts/executors/base.pyscript1.1 KB
scripts/executors/dry_run.pyscript1.6 KB
scripts/executors/internal_script.pyscript1.4 KB
scripts/executors/taskset.pyscript1.2 KB
scripts/planner.pyscript5.4 KB
scripts/process_discovery.pyscript6.3 KB
scripts/report.pyscript12.1 KB
scripts/script_utils.pyscript1.7 KB
scripts/snapshot.pyscript3.0 KB
scripts/topology_collect.pyscript8.6 KB
scripts/topology_view.pyscript19.2 KB
templates/report-template.mdmarkdown9.7 KB
# mindstudio-cpu-binding

`mindstudio-cpu-binding` 是一个面向 **NPU + PyTorch / LLM Serving Host CPU 亲和性优化** 的通用 Agent Skill。它关注的不是单一框架或单一运行时,而是帮助任何支持读取 Skill 目录的 Agent Runtime,围绕以下问题做证据化分析:

- Host CPU affinity 是否合理
- NUMA locality 是否匹配 NPU
- cgroup / cpuset 是否限制了真实可用 CPU
- PyTorch / serving runtime 线程配置是否与 CPU 资源冲突
- 多 rank / 多 worker / 多实例是否存在 CPU range 冲突

## 角色分工

- **SKILL.md**:给 Agent 读取的指令入口,定义交互、边界和工作流。
- **README.md**:给人看的总览文档,说明价值、安装方式、使用场景、CLI 流程和开发入口。

## 目录约定

建议保持如下可移植布局,便于不同 Agent Runtime 直接挂载和识别:

```text
skills/
├── mindstudio-cpu-binding/
│   ├── SKILL.md
│   ├── README.md
│   ├── scripts/
│   ├── docs/
│   └── templates/
└── tests/
```

其中 `skills/tests/` 是仓库内用于保障脚本正确性的测试目录,不属于用户安装 Skill 时必须携带的运行内容。`skills/profiler/mindstudio-cpu-binding/samples/` 可作为本地开发验证数据目录存在,用于离线示例验证;它不是运行真实节点诊断的必需内容。

## 核心特色

- **聚焦 NPU 工作负载**:覆盖 PyTorch 训练、离线/批量推理,以及 vLLM-Ascend、SGLang 等 LLM Serving 场景。
- **证据化诊断**:先采集、再分析;结论必须能追溯到 Snapshot 和运行时证据。
- **只读优先**:默认先做只读发现和采集,不做状态修改;PID / worker / NPU 映射优先由命令生成候选,用户确认即可。
- **自包含报告**:在 Snapshot 信息足够时生成 `report.html`,信息不足时会明确标记缺口。
- **安全执行边界**:任何会改变状态的动作都必须先展示风险、回滚和验证方式,并等待显式确认。
- **Agent 友好**:交互、命令、产物、报告结构都按 Agent 工作流设计;提问一次一个、选项优先。

## 适用场景

当你遇到这些问题时,适合使用 `mindstudio-cpu-binding`:

- PyTorch 训练 step time 抖动、samples/s 低、rank 间不均衡
- PyTorch 离线/批量推理吞吐低、延迟高、CPU 争抢明显
- vLLM-Ascend、SGLang,或能提供 PID / 进程 / runtime 证据的其他 LLM Serving 的 TTFT、TPOT、tokens/s、QPS、p99 异常
- 多 rank / 多 worker / 多实例之间 CPU range 重叠
- Docker / K8s / Slurm / cgroup / cpuset 限制导致实际可用 CPU 与预期不一致
- 需要判断进程、worker、engine、scheduler、tokenizer 是否跨 NUMA 运行或绑核过宽/过窄

## 非目标与安全边界

默认不覆盖以下内容,除非用户明确要求扩展范围:

- ftrace / eBPF / perf 深度诊断
- IRQ affinity 调整
- CPU governor 调整
- kernel boot 参数修改
- K8s 节点级配置修改
- 自动重启服务
- 未经明确确认就执行任何状态变更命令

换句话说:`mindstudio-cpu-binding` 可以给建议,但不能擅自改环境。

## Generic 安装方式

任何**可以读取一个 skill 目录**的 Agent Runtime,都可以注册本目录作为 `mindstudio-cpu-binding`。

### 运行时要求

至少需要满足这些能力:

- 能读取 `SKILL.md`
- 能访问 `scripts/`
- 能运行 Python
- 能只读访问 `/proc`、`/sys`、cgroup、`lscpu`
- 如果节点上有 NPU,还能读取 `npu-smi`

### 注册方式

把整个 `skills/mindstudio-cpu-binding` 目录挂载进去最简单;最小运行内容是 `SKILL.md`、`scripts/`、`templates/` 和所需 `docs/`。`samples/` 仅用于离线示例验证,可选;`skills/tests/` 是仓库测试目录,不随 Skill 安装。

### Claude Code 示例

仅作为示例,`mindstudio-cpu-binding` 不是 Claude-only 方案。

项目级挂载(从仓库根目录执行,目标是 Claude Code 的 skills 发现目录 `.claude/skills/mindstudio-cpu-binding`,不是仓库内的包目录):

```bash
mkdir -p .claude/skills
ln -s /absolute/path/to/mindstudio-cpu-binding .claude/skills/mindstudio-cpu-binding
```

用户级挂载:

```bash
ln -s /absolute/path/to/mindstudio-cpu-binding ~/.claude/skills/mindstudio-cpu-binding
```

### 通用触发示例

以下提示适用于任何支持 Skill 的 Agent Runtime:

- “帮我分析这个 NPU 训练任务的 Host CPU 绑核问题。”
- “检查这个 vLLM-Ascend 服务是否存在 NUMA locality 冲突。”
- “分析多进程推理的 cgroup/cpuset 和 CPU range 是否互相冲突。”
- “读取已有 snapshot.json,给出保守和进阶优化方案。”

## Practical CLI 流程

`mindstudio-cpu-binding` 提供一组可直接跑的原型 CLI。以下命令默认从 Skill 目录执行:

```bash
cd skills/mindstudio-cpu-binding
```

推荐按下面顺序使用。Agent 应先说明每条命令的意义和安全边界,再让用户选择是否执行;用户通常不需要手工推导 PID / worker / NPU 的完整映射。

### 1. 分析已有 Snapshot

```bash
python scripts/cli.py analyze --snapshot out/snapshot.json --out out
```

输出会基于已有 Snapshot 生成诊断计划和 HTML 报告。

### 2. 发现进程与 NPU 候选映射

建议优先从只读进程发现开始,尤其是用户不确定目标 PID、TP worker、rank、instance 或 NPU 映射时。该命令只读取 `ps` 和 `npu-smi`,用于生成候选列表,不修改系统状态:

```bash
python scripts/process_discovery.py --out out/processes.json
```

Agent 应根据 `processes.json` 汇总候选,例如 API server、scheduler、engine/worker、TP rank、rank/main 进程和 NPU 占用关系,再让用户确认哪些候选进入下一步采集。

### 3. 候选确认后的只读采集

用户确认目标 PID 或候选映射后,再运行 Snapshot 采集。该命令只读访问 `/proc`、`/sys`、cgroup、NPU topology 和 runtime 信息,生成 `snapshot.json`,不修改 affinity、cgroup 或系统配置:

```bash
python scripts/cli.py collect --pid <pid> --scenario training --framework pytorch --device-type npu --optimization-goal stability --sample-seconds 10 --out out/snapshot.json
```

### 4. 多 rank 采集示例

```bash
python scripts/cli.py collect --pid 12345 --pid 12346 --scenario training --framework pytorch --device-type npu --optimization-goal stability --sample-seconds 10 --rank-map rank0=12345:npu0,rank1=12346:npu1 --out out/snapshot.json
python scripts/cli.py analyze --snapshot out/snapshot.json --out out
```

## 输出物说明

一次完整流程通常会产出以下文件:

- `snapshot.json`:只读采集结果,记录 CPU / NUMA / NPU / 进程 / cgroup / runtime 信息
- `plan.json`:诊断计划、建议、风险、回滚要点
- `report.html`:自包含 HTML 报告,便于分享和查看
- `raw/`:采集到的原始中间数据,便于排查解析和证据链

## report.html 包含什么

`report.html` 重点展示的是“结论 + 证据 + 建议”,常见结构包括:

1. 报告摘要
2. 当前 CPU 绑定状态
3. CPU / NPU / NUMA 拓扑关系
4. CPU / NUMA 逻辑 CPU 网格
5. 运行时 CPU 使用与竞争情况
6. 问题发现
7. 推荐绑核方案
8. 推荐 PyTorch / Runtime / Serving 线程配置
9. 验证计划
10. 风险与回滚
11. 信息缺口

其中拓扑关系部分会尽量把 Server -> NUMA -> NPU 的关系画清楚,避免只看一堆文本不容易定位。

## 开发者参考

### 数据流

```text
collect -> diagnose -> planner -> report
```

### 关键文件地图

- `scripts/collect.py`:采集入口,负责组织 Snapshot 数据
- `scripts/diagnose.py`:根据规则做问题诊断
- `scripts/planner.py`:把诊断结果整理成方案和建议
- `scripts/report.py`:生成 HTML 报告
- `scripts/topology_view.py`:渲染拓扑视图和关系展示

### 设计文档索引

建议按下面顺序阅读:

- `docs/agent-workflow.md`
- `docs/question-flow.md`
- `docs/snapshot-schema.md`
- `docs/diagnosis-rules.md`
- `docs/html-report-design.md`
- `docs/binding-rollback-design.md`

## 测试与检查

从仓库根目录执行:

```bash
pytest skills/tests/test_report.py skills/tests/test_topology_view.py -v
pytest skills/tests -v
```

从仓库根目录执行 README 检查:

```bash
pre-commit run --files skills/profiler/mindstudio-cpu-binding/README.md
```

## 说明与边界

- 本项目不保证性能一定提升;它提供的是诊断、建议和验证路径。
- 不会自动改写 Docker、K8s、Slurm 或节点级配置。
- 不以 Claude-only 为前提,可用于任何兼容的 Agent Runtime。
- 所有状态变更动作都必须先确认,再执行。

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall