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

docs/agent-workflow.md

View on GitHub
# Agent Workflow

## 1. 目标

`CPU Affinity Advisor Agent` 负责把用户的性能问题转化为可采集、可诊断、可验证、可低风险执行和可回滚的 CPU 绑核优化流程。它不是简单地输出命令,而是要完成:

```text
澄清目标 -> 确认输入 -> 触发采集 -> 读取 Snapshot -> 运行诊断规则 -> 生成 HTML 报告 -> 给出方案 -> 用户确认后调用执行后端绑核 -> 保存回滚状态 -> 支持安全回滚 -> 设计验证 -> 沉淀规则
```

MVP 阶段 Agent 以“诊断 + HTML 展示 + 优化建议”为主,并允许在用户明确确认后通过可配置执行后端执行低风险临时绑核。执行后端可以是系统 `taskset`,也可以是内部经过验证的成熟绑核脚本。中高风险动作只生成建议和回滚方式,不自动执行。

## 2. 工作流总览

```text
用户描述问题
  │
  ▼
Step 1: 场景澄清
  │  训练/推理、NPU/PyTorch、PID、优化目标、环境类型
  ▼
Step 2: 输入完整性检查
  │  是否有 PID、rank 映射、NPU 映射、性能基线
  ▼
Step 3: 生成采集计划
  │  给出当前原型命令、未来完整 collector 命令或调用 MCP 采集工具
  ▼
Step 4: 获取 Host CPU Snapshot
  │  读取 snapshot.json,检查 availability
  ▼
Step 5: 执行诊断规则
  │  匹配 diagnosis-rules.md 中的规则
  ▼
Step 6: 生成 HTML 诊断报告
  │  使用 report-template.md 和 html-report-design.md 输出结论、证据、建议、风险、验证
  ▼
Step 7: 给出保守/进阶方案
  │  taskset / numactl / PyTorch 线程池 / DataLoader 配置建议
  ▼
Step 8: 用户确认后执行低风险绑核
  │  保存 rollback-state,调用 taskset 或内部绑核脚本,执行后验证 affinity
  ▼
Step 9: 支持安全回滚
  │  检查 PID、进程启动时间和当前 affinity,确认后恢复原始 affinity
  ▼
Step 10: 设计验证计划
  │  before/after 指标、采集时长、成功标准、回滚方式
  ▼
Step 11: 规则和案例沉淀
     将真实 case 的问题、证据、收益反馈给规则库
```

## 3. Agent 输入

Agent 应接受三类输入。

### 3.1 用户显式输入

```text
- 场景:训练 / 推理
- 框架:PyTorch / vLLM-Ascend / SGLang
- 设备:NPU
- 当前问题:吞吐低 / step time 抖动 / TTFT 高 / TPOT 高 / p99 高 / NPU 利用率低
- 运行环境:裸机 / Docker / K8s / Slurm
- 优化目标:throughput / latency / stability / isolation
- 是否允许执行只读发现命令:是 / 否
```

目标 PID、rank、worker、instance 到 NPU 的映射优先由只读发现命令生成候选,用户通常只需要确认候选,而不是手工填写完整映射。

### 3.2 采集器输入

来自 `snapshot-schema.md`:

```text
- CPU / NPU / NUMA topology
- NPU topology and NUMA locality
- process / thread affinity
- cgroup / cpuset / CPU quota
- PyTorch / Runtime / Serving threading and environment
- runtime CPU usage sample
- availability / missing fields
```

### 3.3 用户补充的性能基线

```text
训练:
- samples/s
- step time avg / p50 / p90 / p99
- NPU utilization

推理:
- QPS
- latency p50 / p90 / p99
- NPU utilization
- error rate
```

## 4. Step 1:场景澄清

Agent 首先判断信息是否足以开始采集。提问遵循分层 + 分支协议,完整规范见 `question-flow.md`。

核心要点:

- 每轮只问一个问题,优先用选择题,不批量要求用户回答 3-5 个问题。
- 只问阻塞采集的必问项:工作负载场景、问题目标、运行位置、是否允许只读发现、目标候选确认。
- 强烈建议项缺失时给默认值并标记待确认:优化目标、运行环境、rank/worker/instance -> NPU 映射。
- 可选项缺失不阻塞,进入 `availability.missing`。
- 不询问采集器能自取的信息:CPU/NUMA 拓扑、当前 affinity、cgroup、NPU locality。
- 不把 TTFT、TPOT、QPS、p99、TP rank、NUMA、cgroup、OMP、MKL 等术语作为第一层问题;第一层使用“首字响应慢、单个 token 生成慢、吞吐低、延迟抖动”等用户语言。

### 澄清原则

- 每轮只问一个问题;下一问取决于上一轮回答。
- 每个选择题都应包含“不确定 / 先帮我看 / 使用默认值”兜底选项。
- 能从 Snapshot 得到的信息,不要求用户手动提供。
- 缺少 NPU topology 时,不猜测 NUMA locality。
- 如果用户只想先看报告模板或架构,不进入采集流程。

## 5. Step 2:输入完整性检查

Agent 使用完整性检查表判断能否进入采集,详见 `question-flow.md` 的检查表与答案映射。关键判定:

| 检查项 | 必需级别 | 缺失时动作 |
|--------|----------|------------|
| 场景 PyTorch training / PyTorch offline inference / LLM serving | 必需 | 从用户描述推断;无法推断时询问 |
| 目标 PID | 必需 | 用户不知道时,先说明并提供只读 `process_discovery.py` 命令生成候选,用户确认后进入采集 |
| 优化目标 | 推荐 | 从用户选择的问题目标推断;无法推断时默认 `stability` 并标记待确认 |
| rank / worker / instance -> NPU 映射 | 多卡、多 worker、多实例时必需 | 优先从只读发现候选生成,用户确认;发现不足时再标记缺失或请求补充 |
| NPU -> NUMA 映射 | 诊断 locality 时必需 | 通过采集器获取 |
| PyTorch / Runtime / Serving 线程配置 | 推荐 | 采集 env,缺失则标记 |
| 性能基线 | 验证时必需 | 报告中标记缺失 |

## 6. Step 3:生成采集计划

当前阶段优先直接给出可执行的只读命令,解释命令意义,并让用户选择是否执行;不要要求用户先推导 PID / rank / worker / instance 到 NPU 的完整映射。以下命令默认在 Skill 目录执行。

如果用户不知道 PID 或 NPU 映射,先说明“下面这个命令只会读取 `ps` 和 `npu-smi`,用于列出 API server、scheduler、engine/worker、rank、NPU 候选;用户确认后才进入采集”。

离线示例命令:

```bash
cd skills/mindstudio-cpu-binding
python scripts/cli.py discover-processes \
  --ps-file samples/ps.sample.txt \
  --npu-smi-info-file samples/npu-smi-info.sample.txt \
  --out out/processes.json

python scripts/cli.py collect-topology \
  --lscpu-file samples/lscpu.sample.txt \
  --npu-smi-topo-file samples/npu-smi-topo.sample.txt \
  --out out/topology.json
```

真实 Linux NPU 设备上的只读 live 命令:

```bash
cd skills/mindstudio-cpu-binding
python scripts/process_discovery.py --out out/processes.json
python scripts/topology_collect.py --out out/topology.json
```

当前完整 Snapshot 采集原型命令:

```bash
cd skills/mindstudio-cpu-binding
python scripts/cli.py collect \
  --pid <pid> \
  --scenario <training|inference> \
  --framework pytorch \
  --device-type npu \
  --optimization-goal <throughput|latency|stability|isolation> \
  --sample-seconds 10 \
  --out out/snapshot.json
```

这条命令的意义是:在不修改系统状态的前提下,把指定进程的 CPU / NUMA / NPU / cgroup / runtime 证据收集成 Snapshot。若用户不确定 PID,先执行只读进程发现命令并让用户确认候选,再回到这一步。

多 rank 示例:

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

如果后续改为 MCP,Agent 调用顺序应等价于:

```text
collect_cpu_topology
collect_npu_topology
collect_process_affinity
collect_cgroup_limits
collect_runtime_config
collect_cpu_runtime_sample
```

## 7. Step 4:Snapshot 读取与质量检查

Agent 读取 Snapshot 后,先检查 `availability`,再进入诊断。

### 质量检查

```text
- schema_version 是否支持?
- target_pids 是否与 processes 对齐?
- CPU/NUMA topology 是否存在?
- NPU topology 是否存在?如果不存在,哪些诊断不能做?
- cgroup 是否 partial?
- PyTorch threading 字段是否缺失?
- runtime_sample 是否有 top_threads?
```

### 输出行为

如果缺少关键字段,Agent 不应中断整个流程,而是:

1. 继续执行可执行的规则。
2. 把不可执行的规则列入“信息缺口”。
3. 在报告中明确哪些结论无法下。

示例:

```text
当前 Snapshot 缺少 NPU -> NUMA 映射,因此本次报告不能判断 Rank/NPU/NUMA 是否匹配;但仍可判断进程是否未绑核、是否受 cgroup 限制、PyTorch 线程数是否超过可用 CPU。
```

## 8. Step 5:诊断规则执行顺序

建议按以下顺序执行规则:

1. `R010 信息不足`
2. `R007 cgroup/cpuset 与应用绑核冲突`
3. `R001 进程未绑定 CPU`
4. `R003 Rank / NPU / NUMA 不匹配`
5. `R002 跨 NUMA 运行`
6. `R004 绑核范围过宽`
7. `R005 绑核范围过窄`
8. `R006 PyTorch 线程池过载`
9. `R008 多 rank / 多实例 CPU range 重叠`
10. `R009 SMT 使用策略与目标不匹配`

排序原因:

- 先处理信息缺口,避免过度结论。
- 先处理 cgroup,因为它决定真实可用 CPU 边界。
- 再处理 locality、range、线程数和 SMT 策略。

## 9. Step 6:报告生成策略

Agent 使用 `../templates/report-template.md` 生成报告。

### 报告优先级

报告不应平铺所有系统信息,而应按价值排序:

1. 摘要结论。
2. 最高严重程度问题。
3. 支撑证据。
4. 推荐方案。
5. 风险与回滚。
6. 验证计划。
7. 信息缺口。

### 结论表达规则

应该写:

```text
根据 Snapshot 中 PID 12345 的 Cpus_allowed_list=0-127,且机器存在 NUMA 0/1 两个节点,当前进程未进行有效 CPU 绑定。
```

不应该写:

```text
这肯定导致性能差。
```

应该写:

```text
如果该进程只服务 NPU 0,且 NPU 0 位于 NUMA 0,则建议优先绑定到 NUMA 0 的 CPU;当前 Snapshot 缺少 NPU -> NUMA 映射,因此该建议需要补充确认。
```

不应该写:

```text
直接绑到 NUMA 0。
```

## 10. Step 7:推荐方案生成

每次报告至少给出两个方案。

### 10.1 保守方案

特点:

- 不修改系统级配置。
- 只针对目标进程或下次启动命令。
- 可回滚。
- 适合先验证。

示例:

```text
保守方案:
- 将 Rank 0 绑定到 NPU 0 本地 NUMA 的 CPU 子集。
- 使用 taskset 临时调整,或在下次启动时用 numactl。
- 不修改 IRQ affinity、CPU governor、K8s 节点配置。
```

### 10.2 进阶方案

特点:

- 同时调整 CPU range、PyTorch 线程池、DataLoader worker。
- 通常需要重启业务。
- 必须有回滚方式。

示例:

```text
进阶方案:
- 每个 rank 独占一组本地 NUMA physical cores。
- OMP_NUM_THREADS 设置为该 rank 分配的 physical core 数或略小。
- DataLoader num_workers 根据输入 pipeline 压力调整。
```

## 11. Step 8:验证计划

Agent 必须要求优化前后使用相同 workload、相同时长、相同采集方式。

### 训练验证指标

```text
- samples/s
- step time avg / p50 / p90 / p99
- NPU utilization avg / min
- Host CPU utilization by NUMA
- context switch
- CPU migration
- rank 间 step time 方差
```

### 推理验证指标

```text
- QPS
- latency p50 / p90 / p99
- NPU utilization
- Host CPU utilization by NUMA
- error rate
- 实例间 p99 latency 方差
```

### 成功标准示例

```text
本次优化视为有效需要满足至少一项:
- throughput 提升 >= 3%。
- step time p99 下降 >= 5%。
- 推理 p99 latency 下降 >= 5%。
- NPU utilization 波动降低。
- CPU migration 或 context switch 明显下降。
```

阈值只是建议,最终应由业务场景定义。

## 12. Step 9:回滚与安全确认

Agent 输出任何可能改变运行状态的命令时,必须同时输出回滚方式。

### 低风险执行后端

```text
后端一:taskset
- taskset -cp <cpu-list> <pid>

后端二:internal-script
- 内部经过验证的绑核脚本
- 由 BindingExecutor 适配,不绕过 mindstudio-cpu-binding 的前置校验和回滚状态保存
```

回滚:

```bash
taskset -cp <original-cpu-list> <pid>
```

回滚依赖执行前保存的 `rollback-state.json`。回滚前必须检查 PID 是否仍存在,并尽量校验 `/proc/<pid>/stat` starttime,避免 PID 复用导致误回滚。详细机制见 `binding-rollback-design.md`。

### 中风险变更

```bash
OMP_NUM_THREADS=... numactl --cpunodebind=... --membind=... python train.py ...
```

回滚:

```text
恢复原启动命令和原环境变量,重新启动任务。
```

### MVP 禁止自动执行

```text
- 修改 IRQ affinity
- 修改 CPU governor
- 修改 kernel boot 参数
- 修改 K8s 节点级 CPU Manager
- 自动重启线上服务
```

## 13. Agent 状态机

```text
INIT
  -> NEED_USER_INPUT
  -> READY_TO_COLLECT
  -> SNAPSHOT_AVAILABLE
  -> DIAGNOSIS_READY
  -> REPORT_READY
  -> PLAN_READY
  -> WAITING_FOR_APPLY_CONFIRMATION
  -> APPLIED
  -> ROLLBACK_AVAILABLE
  -> WAITING_FOR_VALIDATION
  -> VALIDATION_REPORTED
  -> CASE_ARCHIVED
```

状态说明:

| 状态 | 说明 |
|------|------|
| `INIT` | 用户刚提出问题。 |
| `NEED_USER_INPUT` | 缺少 PID、场景或目标。 |
| `READY_TO_COLLECT` | 已能生成采集命令。 |
| `SNAPSHOT_AVAILABLE` | 已获得 Snapshot。 |
| `DIAGNOSIS_READY` | 已执行诊断规则。 |
| `REPORT_READY` | 已生成 HTML 报告和文本摘要。 |
| `PLAN_READY` | 已生成保守/进阶方案、应用命令和回滚命令。 |
| `WAITING_FOR_APPLY_CONFIRMATION` | 等待用户确认是否通过选定执行后端执行低风险绑核。 |
| `APPLIED` | 已执行用户确认的临时绑核动作,并验证 affinity。 |
| `ROLLBACK_AVAILABLE` | 已保存 rollback-state,可安全回滚。 |
| `WAITING_FOR_VALIDATION` | 等待用户应用方案并采集优化后指标。 |
| `VALIDATION_REPORTED` | 已完成 before/after 对比。 |
| `CASE_ARCHIVED` | 规则或案例已沉淀。 |

## 14. 典型交互示例

### 14.1 信息不足

用户:

```text
这个 NPU 训练任务 Host 侧好像有 CPU 瓶颈,帮我看看。
```

Agent:

```text
你要分析的是哪类任务?

1. PyTorch 训练
2. PyTorch 离线/批量推理
3. vLLM / SGLang / OpenAI API 这类 LLM Serving
4. 不确定,先帮我自动发现
```

### 14.2 需要先发现候选

用户:

```text
训练,目标是吞吐,但我不确定哪些 PID 对应哪些 NPU。
```

Agent:

```text
可以先运行只读进程发现命令。它只读取 `ps` 和 `npu-smi`,用于列出可能的 rank/main 进程与 NPU 候选映射,不会修改系统状态。

是否执行?

1. 执行
2. 先不执行,我提供已有 snapshot
3. 先不执行,我手动提供 PID

命令:
cd skills/mindstudio-cpu-binding
python scripts/process_discovery.py --out out/processes.json
```

### 14.3 候选确认后可采集

用户:

```text
确认候选:rank0=12345:npu0,rank1=12346:npu1。
```

Agent:

```text
现在可以运行完整 Snapshot 只读采集。它会读取目标进程、线程、CPU/NUMA/NPU、cgroup 和 runtime 信息并生成 snapshot.json,不会修改系统状态。

是否执行?

1. 执行采集
2. 暂不执行
3. 改用已有 snapshot

命令:
cd skills/mindstudio-cpu-binding
python scripts/cli.py collect --pid 12345 --pid 12346 --scenario training --framework pytorch --device-type npu --optimization-goal throughput --rank-map rank0=12345:npu0,rank1=12346:npu1 --sample-seconds 10 --out out/snapshot.json
```

### 14.4 Snapshot 信息缺失

Agent:

```text
Snapshot 缺少 NPU -> NUMA 映射,因此不能判断 rank 是否绑定到 NPU 本地 NUMA;但可以确认 PID 12345 和 12346 都允许运行在 0-127 全部 CPU 上,当前没有有效 CPU 绑定。
```

### 14.5 输出建议

Agent:

```text
保守方案是先按 cgroup 有效 CPU 范围为两个 rank 切分不重叠 CPU range,并保持原 PyTorch 线程配置不变;进阶方案是在切分 CPU range 后同步调整 OMP_NUM_THREADS 和 DataLoader num_workers。建议先跑保守方案并对比 step time p99、NPU utilization 和 CPU migration。
```

## 15. 与后续形态的关系

### Skill 形态

`agent-workflow.md` 可直接转化为 Skill 的工作流说明。

### MCP 形态

Step 3 和 Step 4 可替换为 MCP 工具调用,Snapshot schema 不变。

### Plugin 形态

Plugin 可打包:

```text
- Agent workflow
- Diagnosis rules
- Report template
- Collector / MCP tools
- Example cases
```

## 16. MVP 验收标准

Agent 工作流 MVP 应满足:

1. 能从用户输入判断是否具备采集条件。
2. 能生成只读采集命令。
3. 能读取 Snapshot 并识别信息缺口。
4. 能按诊断规则输出问题、证据、建议、风险和验证方式。
5. 能区分保守方案和进阶方案。
6. 仅在用户确认后执行低风险临时绑核,且执行前保存 rollback-state。
7. 能设计 before/after 验证计划。
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: 197kUpdated 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