用途:该技能面向将 PyTorch 框架的 VLA 模型适配到昇腾(Ascend)NPU 的场景,包括修复 CUDA 相关问题与优化 NPU 性能,覆盖扫描、打补丁、修复、验证到启动训练的完整流程。
主要能力: 运行时补丁(零配置、默认生效):将 runtime_patches.py 复制到 migrate_to_cloudrobo/ 目录后,由入口的 build_vla_patcher() 激活以下补丁:
- Float64To32:模块级 torch.float64→float32 替换,含 copyreg.pickle 修复及 from_numpy/as_tensor/Tensor.to 钩子;
- TensorNumpySafe:NPU 张量调用 .numpy() 前自动插入 .cpu();
- NanToNumSafe:torch.nan_to_num() 前自动将半精度转为 float32;
- TensorIndexDevice:自动将索引张量对齐到被索引张量的设备;
- TorchTensorSafe:拦截 torch.tensor(),处理 0 维 NPU 张量元素;
- BuiltinMinMaxNPU:Python min/max 作用于 NPU 张量时改用 torch.minimum/maximum;
- PowFloatSafe:torch.pow 分数指数结果自动 .float();
- SdpaMaskBroadcast:修复 NPU SDPA 掩码广播错误(aclnnFlashAttentionScore error 561103),将 (B,N,1,Skv) 广播掩码显式扩展为 (B,N,Sq,Skv)。 可选补丁 AdamWFused:需通过 build_vla_patcher(fused_adamw=True) 启用,将 AdamW 重定向为 NpuFusedAdamW 以提升 NPU 吞吐,但要求连续大块内存,大模型或内存紧张时可能 OOM。
语义级问题(需人工/代理判断修复):扫描器将问题分类为 DEVICE(NPU 张量设备不匹配,P_RND)、OPERATOR(CUDA 扩展→NPU API,P_FLA)、STRUCTURE(循环、初始化、入口点,P_ENT、P_VEC)、FRAMEWORK(pytorch_lightning,P_LTM)、SEMANTIC(优化,P_TGT),每类在 references/fix-templates/ 下对应修复模板。
使用方式: 前置条件:Python ≥ 3.10;待适配的 PyTorch VLA 模型项目;装有 torch_npu 的 conda 环境;至少一张昇腾 NPU 卡(通过 ASCEND_RT_VISIBLE_DEVICES 选择)。 工作流程:
- 创建 migrate_to_cloudrobo/ 并复制模板文件;
- 运行 scan.py 扫描模型代码库生成 issues.json;
- 按“问题修复流程”修复所有问题;
- 运行 progress.py --check-complete 确认完成;
- 运行 verify.py --runtime --pipeline --config <config> 验证运行时与流水线;
- 运行 verify.py --data --config <config> 验证真实数据加载;
- 启动训练;
- 编写 NPU 适配总结(migrate_to_cloudrobo/ADAPTATION_SUMMARY.md)。 问题修复流程:用 progress.py --next 获取下一个待处理问题;按模板 ID 阅读对应修复模板;按模板修复(或将误报标记跳过,性能问题不可跳过);用 progress.py --fixed 或 --skip 更新进度;重复直至无待处理问题。流程要求在主会话中人工判断完成,不委托子代理,也不直接读取 issues.json 内容。 训练启动:在项目根目录创建 migrate_to_cloudrobo/,复制 env_npu.sh、train.sh 与 runtime_patches.py,然后以 ASCEND_RT_VISIBLE_DEVICES=0,1 bash migrate_to_cloudrobo/train.sh bash <launch command...> 启动。train.sh 是透传包装器,原样转发 $@ 给项目自身启动命令,仅加载 env_npu.sh、设置 PYTHONPATH 并重定向日志。
核心命令:scan.py 扫描生成 issues.json;progress.py 的 --next/--fixed/--skip/--check-complete 管理问题状态;verify.py 验证运行时与数据;train.sh 启动训练。
参考文档:P_ENT、P_FLA、P_LTM、P_RND、P_TGT、P_VEC 六类修复模板,以及 ADAPTATION_SUMMARY.md、env_npu.sh、train.sh 模板。
适用场景:PyTorch VLA 模型迁移至昇腾 NPU、CUDA 代码适配 NPU、NPU 训练前代码扫描与修复、NPU 运行时与数据加载验证。
限制:需 Python 3.10+、torch_npu 环境与昇腾 NPU 卡;AdamWFused 需连续大块内存,可能 OOM;性能类问题不可跳过;语义级问题需人工判断,不适合完全自动批处理。