文件最后提交记录最后更新时间
1 个月前
1 个月前
29 天前
29 天前
28 天前
22 天前
29 天前
29 天前
29 天前
29 天前
29 天前
README.md

msmodeling skills

本目录存放 msmodeling 项目专用的 Claude Code skills,用于把常见性能建模、设备建模和 profiling 辅助任务沉淀为可复用的执行流程。

使用提示:如需在 Claude Code 中启用这些 skills,请将本目录 .agents/skills 完整复制到 .claude/skills

AI agents 必读:请先阅读项目根目录的 AGENTS.md,了解项目规范和 Skill 体系。

Table of Contents

msmodeling-env-installer

msmodeling 环境安装器——将“安装 msmodeling 环境依赖”“创建 myenv”“安装当前仓库 requirements.txt”“配置 PYTHONPATH / HF_ENDPOINT”等明确指向 msmodeling 的请求转换为可执行、可验证、可回溯的环境安装流程。用户只说“安装环境”或“安装依赖”时,需要先确认是否安装 msmodeling 当前仓库的环境依赖。

What it does

引导 AI agent 按 RFC 中定义的流程完成开发环境初始化:

  1. 仓库根目录校验:确认当前目录包含 README.mdrequirements.txt
  2. Python 与 uv 检查:要求 Python 3.10+,缺少 uv 时按镜像安装并解析真实可执行路径。
  3. 安装路径选择:默认用 uv 新建 myenv;已有环境 fallback 前检查 torch_nputorch-npucudatoolkit
  4. 依赖安装与验证:安装 requirements.txt 后执行 uv pip check --python <venv-python>python -m pip check
  5. 环境变量配置:按需设置当前会话 PYTHONPATHHF_ENDPOINT=https://hf-mirror.com

File layout

File Purpose
msmodeling-env-installer/SKILL.md Skill 定义、触发场景、安装流程和安全规则
msmodeling-env-installer/scripts/install-current-project-deps.ps1 Windows PowerShell 自动化安装脚本
msmodeling-env-installer/scripts/install-current-project-deps.sh Linux/macOS/WSL/Git Bash 自动化安装脚本

Quick start

在对话中直接提出明确需求,例如“请帮我安装 msmodeling 环境依赖”“按 README 配置 msmodeling 环境”。如果只说“安装环境”,agent 需要先确认是否安装 msmodeling 当前仓库的环境依赖。

Windows PowerShell 可以从仓库根目录直接运行:

.\.agents\skills\msmodeling-env-installer\scripts\install-current-project-deps.ps1

Linux/macOS/WSL/Git Bash 可以从仓库根目录直接运行:

bash ./.agents/skills/msmodeling-env-installer/scripts/install-current-project-deps.sh

Key constraints

  • 不修改 requirements.txt、README 或项目源码。
  • 不默认覆盖已有 myenv,也不默认持久化系统级环境变量。
  • 网络安装需要用户确认和工具权限授权。
  • scripts/install-current-project-deps.ps1 当前仅适用于 Windows PowerShell;Linux/macOS 使用 README 通用命令。

model-adaptation

TensorCast 新模型接入流程 skill——从仿真命令和 MindStudio Insight raw profiling 出发,引导 agent 运行 model_adapter doctor、审阅 ModelProfile、处理 patch/bug AI task、导出 evidence.yaml 并运行 verify。

What it does

将新模型接入拆成确定性工具和人工 checkpoint:

  1. 收集两个必需输入:仿真命令和匹配的 raw profiling。
  2. 运行 doctor,审阅 candidate profile、evidence draft、human questions 和 ai tasks。
  3. 对需要人工确认的字段生成精确问题,并把确认结果写入 hints.yamlevidence.yaml
  4. 对 patch/bug 场景使用 ai_tasks[].prompt_text 驱动用户或用户的 AI 助手生成代码,并要求人工 review。
  5. 使用 export-evidence 导出 evidence.yaml,再运行 verify。

File layout

File Purpose
model-adaptation/SKILL.md 新模型接入的核心工作流、人工 checkpoint 和验证要求

Quick start

当用户说“接入新模型”“生成 ModelProfile”“根据 doctor report 继续适配”“处理 patch AI task”“从 doctor report 导出 evidence”时使用该 skill。

Key constraints

  • 不凭模型名猜 profile 字段。
  • doctor 不生成模型专属 patch 代码,只生成 AI task 和 prompt。
  • evidence.yamldoctor_after_profile.json.evidence_draft 导出后再人工审阅。
  • 不提交 raw profiling、本地 walkthrough、私人路径或临时材料。

device_config

设备画像自然语言导入器——通过渐进式对话引导用户将自然语言硬件描述转换为 TensorCast DeviceProfile

What it does

引导 AI agent 通过渐进式对话流程:

  1. 渐进收集信息:首轮只问硬件名称、资料来源和粒度偏好,每轮最多 2-3 个问题。
  2. 维护内部事实表confirmed / ambiguous / missing / needs calibration
  3. 生成可运行 profile:将用户确认的值、临时估值和兜底默认值全部写入 tensor_cast/device.py
  4. 验证 + 输出 CLI 命令:运行导入检查,输出 --device <PROFILE_NAME> 可执行命令。

File layout

File Purpose
device_config/SKILL.md Skill 定义、约束条件和执行流程

Quick start

在 Claude Code 对话中直接提出需求,例如"我要导入新的设备拓扑",遵循 agent 的渐进式提问,逐步提供硬件规格。

Key constraints

  • DeviceProfile.__post_init__ 会自动注册 profile,name 必须唯一。

  • 默认写入 tensor_cast/device.py,只有用户明确要求时才写入 tensor_cast/device_profiles/

  • 所有默认值、估值和假设必须对用户可见,列入 needs calibration


op_mapping

op_mapping.yaml 生成器——将 TensorCast 仿真算子映射到 NPU profiling 内核类型。

What it does

通过并行子 Agent 团队(每个算子一个 Agent)追踪完整的 vLLM→CANN 调用链,生成 op_mapping.yaml

File layout

File Purpose
op-mapping/SKILL.md 核心执行流程、六阶段工作流
op-mapping/op-mapping-template.yaml YAML 模板片段
op-mapping/single-op-worker-prompt.md 单算子 Worker Agent 指令
op-mapping/verifier-prompt.md 验证阶段指令
op-mapping/ref/shape_matching_catalog.md TC tensor 与 NPU profiling shape 的 10 种差异
op-mapping/ref/tc_input_count_rules.md tc_input_count 安全使用规则
op-mapping/ref/zero_cost_classification.md 零开销算子分类规则

Quick start

收集完所有输入(model、device、profiling CSV、repo 版本)后,agent 自动执行六阶段流程:GATHER → FORWARD MAPPING → REVERSE MAPPING → VERIFY → WRITE → COMMIT。

Key constraints

  • kernel_type 必须与 CSV 文件名完全一致(无 .csv 后缀)。

  • 三个映射路径:aten→op-plugin→aclnn、torch_npu.npu_*→op-plugin→aclnn、vllm-ascend 自定义/Triton。

  • alternate_kernel_types 必须在同一抽象层级,禁止用融合大 op 作为子 op 的备选。


microbench

Microbench Run Script 生成器——从 profiling CSV 生成可在 NPU 上重放的 <KernelType>_run.py

What it does

为 profiling 内核 CSV 生成可运行的 tools/perf_data_collection/op_replay/<KernelType>_run.py,用于 NPU 实测重放。

File layout

File Purpose
microbench/SKILL.md Skill 定义和 repo 搜索顺序

Quick start

用户提供 kernel_type、设备 profile、vllm_ascend 版本和 CSV 路径后,agent 生成可重放的 run script。

Key constraints

  • 优先使用本地已克隆的 repos,按指定路径搜索。

  • repo 缺失时按 SKILL.md 中提供的 clone 命令获取。

  • 生成的 run script 由 run_all_op.py / profile_and_update_db.py 调用。


text-generate-executor

text_generate 单点验证执行器。用于把用户关于 python -m cli.inference.text_generate 的验证诉求转换为可确认、可执行的 CLI 命令,并在确认后运行和总结结果。

What it does

面向已有模型、硬件、batch/query length、prefill 或 decode 模式、固定 TP/DP/EP/MOE 策略、profiling database、trace/debug 或 throughput optimizer 最优行复验的场景,生成单点仿真命令。

File layout

File Purpose
text-generate-executor/SKILL.md Skill 主说明、默认策略、校验规则和 handoff 规则
text-generate-executor/references/dialog-flow.md 渐进式问参流程
text-generate-executor/references/text-generate-params.md text_generate 参数速查

Quick start

提出“帮我跑 text_generate 验证”“把 throughput_optimizer 最优行转 text_generate 跑一下”“导出 chrome trace”等请求时,agent 会补齐缺失参数,展示命令和假设,并在用户确认后执行。

Key constraints

  • 执行前必须展示完整命令和关键假设,并要求显式确认。
  • Decode 模式必须确认 --context-length;profiling 模式必须提供 --profiling-database
  • text_generate 只验证固定候选,不执行 TP/EP/MOE-DP 搜索。

throughput-optimizer-executor

throughput_optimizer 部署规划执行器。用于把吞吐规划、硬件对比、并行搜索、PD 聚合/分离/配比优化等自然语言诉求转换为 python -m cli.inference.throughput_optimizer 命令。

What it does

面向搜索和规划场景,收集模型、硬件、设备数、输入/输出长度、SLO、部署模式和搜索空间,生成 optimizer 命令,在确认后运行并总结最佳并行策略、batch、concurrency、throughput、TTFT、TPOT 和 PD ratio 信息。

File layout

File Purpose
throughput-optimizer-executor/SKILL.md Skill 主说明、默认策略、校验规则和 handoff 规则
throughput-optimizer-executor/references/dialog-flow.md 部署模式识别和渐进式问参流程
throughput-optimizer-executor/references/throughput-optimizer-params.md throughput_optimizer 参数速查
throughput-optimizer-executor/scripts/extract_throughput_optimizer_result.py optimizer stdout 结构化摘要脚本

Quick start

提出“比较两种硬件”“搜索 Qwen 32B 最佳 TP”“做 PD 分离能力评估”“算 P/D 实例配比”等请求时,agent 会识别 aggregation、disagg 或 PD ratio 模式,补齐 SLO 和搜索空间,并在确认后执行。

Key constraints

  • --enable-optimize-prefill-decode-ratio 不能与 --disagg 同时使用。
  • 多硬件对比共用同一个 --num-devices,需要在执行前说明。
  • 执行前需要明确确认是否开启 prefix cache 和 MTP;开启后分别补齐 hit rate、MTP token 数和接受率假设。
  • 该 skill 做候选搜索和规划;单点复验应 handoff 到 text-generate-executor