一个把「昇腾迁移经验」沉淀成 Skill 的开源仓库,让 Claude Code / OpenCode / Cursor / Trae / Codex 直接帮你完成从 CUDA 到 NPU 的迁移、精度对齐与性能调优。

仓库地址:https://gitcode.com/AI4Science/AscendSkills

📌 如果你的模型已经能跑、只想跑得更快,可直接跳到 第七章:性能优化专题。


作者:昇腾实战派

知识地图:https://blog.csdn.net/Lumos_Lovegood/article/details/161601003

一、AI4S + 昇腾,难在哪?

做 AI for Science 的人,这两年大概率会遇到同一个场景:

  • 论文代码 / 模型权重只有 CUDA 版本,实验室机器却换成了昇腾 910B;
  • torch.cuda.xxx 报一堆错,flash_attn、torch_scatter、cuequivariance 编译不过;
  • 好不容易跑起来,精度对不上,又不知道该从哪一层开始 dump 排查;
  • 能跑通了却慢得离谱,profiling 图看得头大,不知道瓶颈在 host、device 还是通信。

昇腾生态本身很完整,但迁移经验高度分散:散落在官方文档、issue、个人笔记和各团队的踩坑记录里。每来一个新模型,几乎都要把同样的流程再走一遍。

AscendSkills 想解决的,就是这件事:把「迁移方法论」变成 AI Agent 能直接读取、按需加载、自动执行的 Skill。


二、AscendSkills 是什么?

AscendSkills 是面向 AI4S 模型在华为昇腾 NPU 上迁移、精度对齐、性能分析与调优的能力集合。它不提供运行时框架,而是提供一整套结构化的操作知识,以 Skill 形式组织,可被多种 AI 编程工具识别和加载。

它的设计有三个关键点:

  1. Skill 承载步骤:每个能力都是一个 SKILL.md,写清楚前置条件、操作流程、代码改法和验证标准,Agent 跟着做即可。
  2. 渐进式披露(Progressive Disclosure):入口 skill 只做路由,把细节拆到 references/ 里,Agent 按需加载,避免一次性把上下文塞满。
  3. 多工具兼容:目录结构同时适配 Claude Code、OpenCode、Cursor、Trae、Codex 等,不绑定单一平台。

目前已覆盖 20 个 skill,横跨通用迁移、精度对齐、profiling、系统级调优、算子级优化,以及 9 个模型专属 skill 和 3 条框架路线。


三、安装:四种方式,三十秒上手

方式一:让 Agent 自己装(最省事)

把仓库地址直接发给你的 AI 编程助手:

帮我安装这个 skill 仓库:https://gitcode.com/AI4Science/AscendSkills

Agent 会自动克隆仓库,并把各 skill 目录复制到当前项目对应的 skills 路径下(Claude Code 为 .claude/skills/,OpenCode 为 .opencode/skills/,Cursor 为 .cursor/skills/)。

方式二:项目级手动安装

git clone https://gitcode.com/AI4Science/AscendSkills.git
cp -r AscendSkills/ai4s-main AscendSkills/ai4s-migration-base \
    AscendSkills/ai4s-npu-deploy-verify \
    AscendSkills/ai4s-precision-alignment \
    AscendSkills/ai4s-profiling AscendSkills/ai4s-perf-tuning \
    AscendSkills/ai4s-op-optimization AscendSkills/ai4s-biomolecular-perf \
    AscendSkills/models AscendSkills/tf-framework AscendSkills/pl-framework \
    your-project/.claude/skills/
mkdir -p your-project/.claude-plugin
cp AscendSkills/.claude-plugin/marketplace.json your-project/.claude-plugin/

方式三:只装单个子 skill

比如只想给 Boltz2 用:

git clone https://gitcode.com/AI4Science/AscendSkills.git
cp -r AscendSkills/models/boltz2 your-project/.claude/skills/

方式四:Claude Code Plugin 一键安装

claude plugin marketplace add https://gitcode.com/AI4Science/AscendSkills.git
claude plugin install ai-for-science@ascendskills-ai-for-science --scope user

四、怎么用:遇到新模型,只需要三步

AscendSkills 把整个工作流设计成一条清晰的路线,入口 skill ai4s-main 负责判断你该走哪条路:

不确定走哪条路        → ai4s-main              (路由与分流)
通用迁移 / 新模型复现  → ai4s-migration-base    (新模型首选)
部署验证并记录指标     → ai4s-npu-deploy-verify
精度对齐、dump 定位    → ai4s-precision-alignment
性能热点采集           → ai4s-profiling
系统级调优             → ai4s-perf-tuning
瓶颈定界 + 算子优化    → ai4s-op-optimization
生物分子模型级优化     → ai4s-biomolecular-perf

典型用法:你只需要对 Agent 说一句「把这个模型迁到昇腾上跑通」,ai4s-main 会先路由,ai4s-migration-base 会带着 Agent 走完整流程——环境检查、CUDA 依赖扫描、transfer_to_npu 自动注入、手动适配、分布式改造、第三方库替换、验证。跑通后,还可以让 Agent 生成这个模型专属的迁移 skill,下次直接复用。


五、Skill 总览:20 个 skill 覆盖全链路

通用迁移与工程

Skill定位
ai4s-main总入口:模型路由与任务分流
ai4s-migration-base通用模型迁移与环境搭建(新模型首选)
ai4s-npu-deploy-verifyNPU 部署与训推验证、指标记录
ai4s-precision-alignment训练 / 推理 / dump 精度对齐

性能优化

Skill定位
ai4s-profilingProfiling 采集(L0/L1/L2)与预检
ai4s-perf-tuning系统级调优(流水、绑核、tcmalloc、编译优化)
ai4s-op-optimization算子/API 级优化(瓶颈定界、算子融合、亲和 API 替换)
ai4s-biomolecular-perf生物分子模型级优化(hoist 缓存、AiCpu 消除、gather/scatter 重写、图编译决策、bitwise 验证;含 AF3 家族专项与 lever 台账)

模型专属技能(models/)

模型说明
Boltz2蛋白质结构预测模型昇腾迁移与端到端复现
BoltzGen生成式蛋白设计与逆折叠流程昇腾部署
DeepFRI(转 PyTorch / 保留 TF)两种路线:TF→PyTorch 转换,或 TF 原生 NPU 迁移
DiffSBDD结构化药物设计扩散模型昇腾迁移
GENERatorDNA 序列生成模型昇腾迁移
Goedel-Prover基于 vLLM 的 Lean 4 自动定理证明模型昇腾迁移
OligoFormersiRNA 效能预测模型昇腾迁移
ProteinBERTTensorFlow/Keras 转 PyTorch 与 NPU 部署

框架路线

路线Skill说明
TensorFlowascend-tf-communityTF 2.x 原生昇腾部署
TF → PyTorchtf-to-pytorchTensorFlow/Keras 改写 PyTorch 通用流程
PyTorch Lightningascend-pytorch-lightningLightning Trainer 迁移昇腾 NPU

六、它到底帮你解决了哪些「真问题」?

迁移 AI4S 模型时最烦人的几类坑,AscendSkills 都给了成体系的处理方案。

1. CUDA API 兼容:先自动、再手动

入口处加两行就能自动映射大部分 CUDA 调用:

import torch_npu
from torch_npu.contrib import transfer_to_npu

transfer_to_npu 会自动把 torch.Tensor.cuda() → .npu()、torch.device('cuda') → 'npu'、DDP backend nccl → hccl 等。

对于它覆盖不了的场景,skill 里给出了逐个 API 的修复模板:torch.cuda.get_device_properties(...).major、torch.cuda.get_device_capability()、torch.cuda.amp、torch.cuda.mem_get_info()——全部附带 try-except 写法。

2. 第三方库:明确告诉你「不能用 wheel,必须源码编译」

这是很多人踩过的坑:torch_scatter、torch_sparse、torch_cluster 直接 pip install 预编译包,在 aarch64 + NPU 下会 ABI 不兼容。

AscendSkills 给出了两级安装策略:

  1. 优先 pip install torch_scatter --no-build-isolation(复用已安装的 torch/torch_npu 编译);
  2. 失败后回退 git clone + setup.py bdist_wheel 源码编译。

DGL 同理,直接指向昇腾适配版 dgl-ascend 源码编译,还提醒了导入顺序必须是 torch → torch_npu → dgl。

3. 分布式:DP 必须改 DDP

昇腾 NPU 不支持 DataParallel。skill 里明确给出了 DP → DDP 的完整改法,包括 hccl backend 替换和 torchrun 启动命令。

4. 精度对齐:先确认基线,再谈对比

很多精度问题出在「拿 CPU 结果当基线」这种错误对比上。ai4s-precision-alignment 强制要求先确认官方 README / benchmark 基线,官方没给就先问清楚 GPU 基线来源,再进入训练对齐、推理对齐或 dump 排查流程。

5. 性能:告别「玄学调优」

性能是 AI4S 科研最关心的方向之一。AscendSkills 用 5 个 skill + 十余份 reference 把「从能跑到跑得快」拆成一条可执行、可复现、可回退的链路,详见下一章。


七、性能优化专题:从「能跑」到「跑得快」

科研模型往往最在意的就是性能——同样的实验,快 2 倍就能多跑一倍参数扫描。AscendSkills 把性能优化拆成 五个层次、一条主线:

采集 (ai4s-profiling)
  → 定界(host-bound / device-bound / 通信)
  → 系统级调优 (ai4s-perf-tuning)
  → 算子/API 级优化 (ai4s-op-optimization)
  → 模型级优化 (ai4s-biomolecular-perf)
  → 每项都做两级验证 + env 门控 + 负结果入档

它最重要的一个设计,是把**「先定界、再动手」写成了硬规则**:不先采 profiling、不先判断瓶颈类型,就不许改算子。

7.1 第一层:Profiling 采集(ai4s-profiling)

标准流程覆盖 L0 / L1 / L2 三个采集级别,以及训练、推理、多种框架的接入方式:

级别采集内容数据量典型用途
L0(默认)仅 NPU 活动,最小膨胀小快速定位热点、整体耗时分布
L1CPU + NPU + 算子详情中分析 Cube/Vector/MatMul/Conv 算子耗时
L2L1 + 调用栈 + 内存大深度分析调用链、内存瓶颈

几个很实用的细节:

  • 默认只采 L0:用户只说「采个 profiling」时默认最小膨胀级别,只有明确要算子/调用栈/内存分析时才升级到 L1/L2,避免数据爆炸;
  • 不要乱改业务代码:即使训练脚本里全是 cuda 字样也不需要改——自动迁移会在运行时处理,profiling 代码用 torch_npu.profiler 即可;
  • 训练用 schedule 控步:skip_first / wait / warmup / active / repeat 五参数只采稳态的那几步,典型配置 wait=1, warmup=1, active=1, repeat=1, skip_first=20;
  • 框架适配齐全:PyTorch Lightning 用 Callback、HuggingFace 用 TrainerCallback、DeepSpeed 只在 rank 0 采;
  • 采集环境变量:采集前设 CPU_AFFINITY_CONF=1 与 TASK_QUEUE_ENABLE=2,让数据更接近生产环境真实表现;
  • GPU 对比可选:用相同 schedule 在 GPU 上采一份,直接对比同一算子的耗时分布,判断某项在 NPU 上是否低效。

配套脚本 validate_profiling_env.py 可在采集前做环境预检。

7.2 第二层:瓶颈定界——这一步决定后面所有优化的成败

AscendSkills 把性能问题定界为三类,并给出明确的判定特征:

问题类型判定特征优化方向
下发问题(host-bound)timeline 中 host2device 连线呈垂直现象;freetime 占比过大(一般 >20%)减少下发次数、减轻 host 压力
计算问题(device-bound)timeline 呈 device-bound;某些算子明显耗时大替换/融合低效算子、重构布局
通信问题多卡集群下 communication 时间异常(快慢卡)或带宽偏低通信优化、计算-通信重叠

这里的核心纪律是 regime 依赖,也是很多「抄来的优化」失效的原因:

二级流水(TASK_QUEUE_ENABLE)、绑核(CPU_AFFINITY_CONF)、tcmalloc 三项都作用于 host 侧,只有在模型已经 host-bound 时才显性生效。如果 profiling 显示 device-bound,这三项实测可能完全无效。正确顺序是:先消除 device 侧瓶颈,转 host-bound 后再启用系统级项。

实测案例:同一组三项在 device-bound 基线上全部无效;消除 device 瓶颈转为 launch-bound 后,合计约 -20%。

工具侧还串联了 msprof-analyze 做详细对比、MindStudio Insight 做可视化定界。

7.3 第三层:系统级调优(ai4s-perf-tuning)

这一层是「一行环境变量」级的低风险收益,适用于已能跑通的模型:

优化项手段适用场景风险
流水优化export TASK_QUEUE_ENABLE=2host-bound 网络NPU 内存峰值上升,OOM 可回退到 1
粗粒度绑核export CPU_AFFINITY_CONF=1CPU 瓶颈模型需确认 NUMA 拓扑;vLLM 等框架可能负优化
细粒度绑核export CPU_AFFINITY_CONF=2CPU 瓶颈 + 核间切换同上
tcmallocLD_PRELOAD=...libtcmalloc.so频繁内存分配需安装 gperftools
编译优化(进阶)毕昇编译器 + LTO + PGOPython / PyTorch / torch_npu需从源码重编,耗时长

几个 AscendSkills 特别强调的「反直觉」点:

  • 渐进式调优 + 最优子集:三项手段要逐项开启、每次只变一个配置;如果叠加后性能不升反降,就去掉该项,用剩余组合重测。实测中「流水优化 + tcmalloc」(不绑核)往往优于三项全开。
  • 编译优化放在最后:从源码重编 Python,再按 PyTorch → torch_npu 的顺序做 LTO+PGO 两次编译(先插桩采 profile,再 -fprofile-use 正式编译),每一步都需用户确认后才执行。
  • 专项分流:AF3 类模型这一段收益有限,会自动转入模型级优化文档;GNN/dgl-ascend 则转入图模型专项(gnn-npu-tuning.md)。

7.4 第四层:算子 / API 级优化(ai4s-op-optimization)

这一层做的是语义等价的代码级改写,收益往往最直观。按瓶颈类型分成两组:

device-bound(计算)——替换低效算子 / 融合计算:

优化项改写方式备注 / 实测
index 操作tensor[indices] → F.embedding底层专用高效实现
repeat_interleave→ repeat / index_select访存更规整
gathertorch.gather → 高级索引 / index_select间接寻址转直接寻址
GatherV2npu_gather_sparse_index(需手写反向)规避 bank 冲突
scatter 系列torch_scatter → mx_driving有适用边界,见下
SwiGlu→ npu_swigluchunk+silu+mul 三算子融合
RmsNorm→ npu_rms_norm平方/均值/开方/缩放融合
ScaledMaskedSoftmax→ npu_scaled_masked_softmax缩放+掩码+softmax 融合
Nonzero→ torch.isinf + masked_fill避免不规则输出
MatmulAllReduce→ npu_mm_all_reduce_base计算-通信重叠
张量布局重构channel-first → channel-last消除转置,某模型端到端 73.4 → 22 s/epoch(约 3×),ReduceSum 11×
优化器融合torch.optim.Adam → NpuFusedAdamoptimizer.step 微基准约 4.7×
大矩阵 CSV 导出pandas to_csv → pyarrow.csv.write_csv6.4×;float_format 反而更慢

host-bound(下发)——减少下发次数 / 减轻 host 压力:

优化项改写方式
rotary_mul 融合→ npu_rotary_mul 单算子
attention 融合多算子 → npu_fusion_attention(短序列先微测,可能负收益)
亲和替换A[:, :, None, :] → A.unsqueeze(2);transpose 后补 contiguous()
Linear 合并Q/K/V 三个 Linear → 一个 3 倍宽 Linear
冗余消除去 .item()、去 for 循环、矩阵化
DataLoader 线程爆炸worker_init_fn + threadpoolctl 限制 worker 线程(CPU 占用约 -95%)
推理逐批 empty_cache删除逐批全设备同步 + 逐样本模型判定后提升 batch
多 die 伪并行分块派发改异步 fire-and-collect,去除逐块 D2H 同步
图编译torch.compile(backend=torchair) / ACL graph(先看 Free 占比)

AscendSkills 在这里同样强调 两级验证缺一不可:先在真实 shape 上微基准(bitwise / 容差),再用同 seed 端到端配对复验。因为微基准 ≠ 端到端——实测中某 index_add_ 微基准快 56×,但整体跑零墙钟收益(不在关键路径)。

7.5 第五层:模型级优化(ai4s-biomolecular-perf)

生物分子 / 生命科学方向(结构预测、结构生成扩散、蛋白语言模型、GNN)有专门的模型级优化 skill,方法框架参考 Anthropic《How Claude is uplifting biomolecular modeling》,并结合昇腾 NPU 实测数据沉淀。

它先做画像定界,再按画像进入对应文档:

画像判定特征优化方向
跨步重复计算多步循环内相同 (算子, shape) 反复出现,值不随步变跨步不变量 hoist 缓存
AiCpu 回退算子名带 _AiCpu 后缀,跑在单线程 CPU 核上sort→topk、定长掩码化
索引搬运受限index/gather/scatter 家族占比 > 40%gather/scatter 语义等价重写
隐式同步碎片化 freetime,代码里有 .item()、标量 H2D 微拷贝去同步、缓存标量
CPU 流水/图构建NPU 很快但整跑被 CPU 段吃掉numpy 边数组、COO→CSR、gc 收敛
死计算结果恒定/与输入无关的计算仍被执行跳过退化计算
图编译诱惑想用 torch.compile 消小算子长尾先看 Free 占比,低时大概率负收益
AF3 家族AF3/Protenix/boltz/chai/openfold3…专项手册:attention/QKV/布局/采样改写

实测收益(数据来自仓库内 reference):

  • RFD3(结构扩散)端到端 2.66×,全程 bitwise 保持:stock 156.4 s → 58.9 s。画像显示 Computing 92% / Free 8%,其中 index/gather 家族约占 62.9%,Index_AiCpu 一项就占 16.8%(单线程 CPU 核回退)。手段是 hoist 缓存 + 索引预建 + sort→topk + AiCpu 消除 + gather/scatter 重写。
  • 某异构图模型:图构建 502 → 160 s(3.1×):numpy 边数组替代 .tolist() + gc 收敛,整跑 -10.1%,精度 4.27e-8 不变。
  • 某异构图模型:CPU 稀疏 SpMM(COO→CSR)401 → 44 s(9.1×):整跑 -21.8%,精度不变。
  • 还沉淀了 36 个 Anthropic kit 的 lever 台账 × 跨模型可移植性矩阵,回答「哪类手段该去哪个模型上试」。

验证纪律(这套方法最值得学习的地方):

  1. 两级验证:真实 shape 微基准 → 同 seed 端到端配对;
  2. env 门控:每项优化挂在环境开关下(如 RFD3_HOIST_NPU,0 可完整还原 stock 路径),保证可 A/B、可回退、可逐项归因;
  3. 生成式模型的终审是轨迹配对:单点误差经多步扩散混沌放大后会产出不同设计,所以 RFD3 做了 9 组交叉对拍,8/8 设计均为 0 Å;
  4. 负结果同样入档:例如 torchair/GE 图编译在 Free 仅 8% 的画像下,稳态反而慢 3.3× ——把量化数据记下来,防止下次重复踩坑。

7.6 一句话总结这条性能链路

先采集、再定界;先 device、后 host;先微基准、后端到端;每项 env 门控、逐项验证、负结果入档。

这套纪律让性能优化从「凭经验试」变成了可测量、可复现、可回退的工程流程——这正是科研模型最需要的。


八、一个真实例子:用 AscendSkills 迁移 Boltz2

以热门蛋白质结构预测模型 Boltz2 为例,它的专属 skill 把整条链路写得清清楚楚:

  1. 环境:Ascend 910/910B/910C,CANN 8.2.RC1,torch / torch_npu 2.5.1,Python 3.11;
  2. 权重准备:~/.boltz/ 下放置 boltz2_conf.ckpt、boltz2_aff.ckpt、ccd.pkl、mols.tar 等,并附检查脚本;
  3. 源码迁移:入口注入 transfer_to_npu;修复 major 属性;为 CUDA-only kernel(cuequivariance_torch 的 triangle attention / triangular mult)提供 NPU 等价实现并做设备分发;
  4. Lightning 适配:注册 npu accelerator,处理 bf16-mixed 精度插件;
  5. 验收:boltz predict 跑通,Number of failed examples: 0,输出 CIF + pLDDT + PAE + PDE + confidence 文件。

每一步都有可直接复制的代码和命令,还有 4 条明确的「复现完成判定标准」。同一个流程,也适用于该仓库里其他 8 个模型。


九、为什么值得用(而不是每次重新问 AI)?

  • 经验被固化:这些坑是真实迁移过程中踩出来的,写进了 skill,不再依赖某个人的记忆;
  • 按需加载:渐进式披露让 Agent 不会被无关上下文淹没,回答更聚焦;
  • 可复现:环境版本、命令、验证标准都写死,换台机器、换个 Agent 也能重来一遍;
  • 可扩展:迁移完新模型,让 Agent 按统一格式生成专属 skill,经验就沉淀进了仓库。

十、一起贡献

仓库按 <分类目录>/<skill 名>/ 组织,每个 skill 一个目录,入口是 SKILL.md,配套内容放 references/、scripts/。

新增一个 skill 只需要四步:

  1. 新建 <分类目录>/<skill 名>/SKILL.md,frontmatter 至少包含 name、description、keywords;
  2. 参考文档、脚本放入 references/、scripts/;
  3. 若需要参与路由,在 ai4s-main/SKILL.md 的路线表补充入口;
  4. 在 .claude-plugin/marketplace.json 注册路径,并同步更新 README。

无论你是迁移了新的 AI4S 模型,还是发现了更优雅的算子替换方案,都欢迎提 PR 把它沉淀下来。

提交前记得按仓库校验清单检查:frontmatter 必填字段、Markdown 相对链接、marketplace 注册一致性、README 与实际目录同步。


十一、开始使用

git clone https://gitcode.com/AI4Science/AscendSkills.git

或者,直接把这句话丢给你的 AI 编程助手:

帮我安装这个 skill 仓库:https://gitcode.com/AI4Science/AscendSkills

然后就可以开始了:

帮我把 XXX 模型迁移到昇腾 NPU 上,跑通推理并验证精度。

仓库地址:https://gitcode.com/AI4Science/AscendSkills

如果它对你有帮助,欢迎 Star、Fork,也欢迎把你的迁移经验贡献回来——让下一个做 AI4S 的人,少踩一个坑。

Logo

鲲鹏昇腾开发者社区是面向全社会开放的“联接全球计算开发者,聚合华为+生态”的社区,内容涵盖鲲鹏、昇腾资源,帮助开发者快速获取所需的知识、经验、软件、工具、算力,支撑开发者易学、好用、成功,成为核心开发者。

更多推荐