把 AI4S 模型迁到昇腾 NPU,不用再翻 20 篇文档:AscendSkills 来了
一个把「昇腾迁移经验」沉淀成 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 编程工具识别和加载。
它的设计有三个关键点:
- Skill 承载步骤:每个能力都是一个
SKILL.md,写清楚前置条件、操作流程、代码改法和验证标准,Agent 跟着做即可。 - 渐进式披露(Progressive Disclosure):入口 skill 只做路由,把细节拆到
references/里,Agent 按需加载,避免一次性把上下文塞满。 - 多工具兼容:目录结构同时适配 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-verify | NPU 部署与训推验证、指标记录 |
ai4s-precision-alignment | 训练 / 推理 / dump 精度对齐 |
性能优化
| Skill | 定位 |
|---|---|
ai4s-profiling | Profiling 采集(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 | 结构化药物设计扩散模型昇腾迁移 |
| GENERator | DNA 序列生成模型昇腾迁移 |
| Goedel-Prover | 基于 vLLM 的 Lean 4 自动定理证明模型昇腾迁移 |
| OligoFormer | siRNA 效能预测模型昇腾迁移 |
| ProteinBERT | TensorFlow/Keras 转 PyTorch 与 NPU 部署 |
框架路线
| 路线 | Skill | 说明 |
|---|---|---|
| TensorFlow | ascend-tf-community | TF 2.x 原生昇腾部署 |
| TF → PyTorch | tf-to-pytorch | TensorFlow/Keras 改写 PyTorch 通用流程 |
| PyTorch Lightning | ascend-pytorch-lightning | Lightning 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 给出了两级安装策略:
- 优先
pip install torch_scatter --no-build-isolation(复用已安装的 torch/torch_npu 编译); - 失败后回退
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 活动,最小膨胀 | 小 | 快速定位热点、整体耗时分布 |
| L1 | CPU + NPU + 算子详情 | 中 | 分析 Cube/Vector/MatMul/Conv 算子耗时 |
| L2 | L1 + 调用栈 + 内存 | 大 | 深度分析调用链、内存瓶颈 |
几个很实用的细节:
- 默认只采 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=2 | host-bound 网络 | NPU 内存峰值上升,OOM 可回退到 1 |
| 粗粒度绑核 | export CPU_AFFINITY_CONF=1 | CPU 瓶颈模型 | 需确认 NUMA 拓扑;vLLM 等框架可能负优化 |
| 细粒度绑核 | export CPU_AFFINITY_CONF=2 | CPU 瓶颈 + 核间切换 | 同上 |
| tcmalloc | LD_PRELOAD=...libtcmalloc.so | 频繁内存分配 | 需安装 gperftools |
| 编译优化(进阶) | 毕昇编译器 + LTO + PGO | Python / 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 | 访存更规整 |
| gather | torch.gather → 高级索引 / index_select | 间接寻址转直接寻址 |
| GatherV2 | npu_gather_sparse_index(需手写反向) | 规避 bank 冲突 |
| scatter 系列 | torch_scatter → mx_driving | 有适用边界,见下 |
| SwiGlu | → npu_swiglu | chunk+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 → NpuFusedAdam | optimizer.step 微基准约 4.7× |
| 大矩阵 CSV 导出 | pandas to_csv → pyarrow.csv.write_csv | 6.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 台账 × 跨模型可移植性矩阵,回答「哪类手段该去哪个模型上试」。
验证纪律(这套方法最值得学习的地方):
- 两级验证:真实 shape 微基准 → 同 seed 端到端配对;
- env 门控:每项优化挂在环境开关下(如
RFD3_HOIST_NPU,0 可完整还原 stock 路径),保证可 A/B、可回退、可逐项归因; - 生成式模型的终审是轨迹配对:单点误差经多步扩散混沌放大后会产出不同设计,所以 RFD3 做了 9 组交叉对拍,8/8 设计均为 0 Å;
- 负结果同样入档:例如 torchair/GE 图编译在 Free 仅 8% 的画像下,稳态反而慢 3.3× ——把量化数据记下来,防止下次重复踩坑。
7.6 一句话总结这条性能链路
先采集、再定界;先 device、后 host;先微基准、后端到端;每项 env 门控、逐项验证、负结果入档。
这套纪律让性能优化从「凭经验试」变成了可测量、可复现、可回退的工程流程——这正是科研模型最需要的。
八、一个真实例子:用 AscendSkills 迁移 Boltz2
以热门蛋白质结构预测模型 Boltz2 为例,它的专属 skill 把整条链路写得清清楚楚:
- 环境:Ascend 910/910B/910C,CANN 8.2.RC1,torch / torch_npu 2.5.1,Python 3.11;
- 权重准备:
~/.boltz/下放置boltz2_conf.ckpt、boltz2_aff.ckpt、ccd.pkl、mols.tar等,并附检查脚本; - 源码迁移:入口注入
transfer_to_npu;修复major属性;为 CUDA-only kernel(cuequivariance_torch的 triangle attention / triangular mult)提供 NPU 等价实现并做设备分发; - Lightning 适配:注册
npuaccelerator,处理bf16-mixed精度插件; - 验收:
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 只需要四步:
- 新建
<分类目录>/<skill 名>/SKILL.md,frontmatter 至少包含name、description、keywords; - 参考文档、脚本放入
references/、scripts/; - 若需要参与路由,在
ai4s-main/SKILL.md的路线表补充入口; - 在
.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 的人,少踩一个坑。
鲲鹏昇腾开发者社区是面向全社会开放的“联接全球计算开发者,聚合华为+生态”的社区,内容涵盖鲲鹏、昇腾资源,帮助开发者快速获取所需的知识、经验、软件、工具、算力,支撑开发者易学、好用、成功,成为核心开发者。
更多推荐



所有评论(0)