NPU（昇腾）开箱指南

本文档介绍如何在华为昇腾 NPU 环境下安装和使用 Twinkle 框架。

环境要求

在开始之前，请确保您的系统满足以下要求：

重要说明：

• torch 和 torch_npu 版本必须完全一致（例如都为 2.7.1）
• 推荐使用 Python 3.11 以获得最佳兼容性
• CANN 工具包需要约 10GB+ 磁盘空间

支持的硬件

Twinkle 当前支持以下昇腾 NPU 设备：

• 昇腾 910 系列
• 其他兼容的昇腾加速卡

安装步骤

1. 安装 NPU 环境（驱动、CANN、torch_npu）

NPU 环境的安装包括昇腾驱动、CANN 工具包、PyTorch 和 torch_npu。

📖 完整安装教程：torch_npu 官方安装指南

该文档包含：

• 昇腾驱动（HDK）安装步骤
• CANN 工具包安装步骤
• PyTorch 和 torch_npu 安装步骤
• 版本配套说明

推荐版本配置：

• Python: 3.11
• PyTorch: 2.7.1
• torch_npu: 2.7.1
• CANN: 8.5.1 或更高

2. 安装 Twinkle

NPU 环境配置完成后，从源码安装 Twinkle 框架：

git clone https://github.com/modelscope/twinkle.git
cd twinkle
pip install -e ".[transformers,ray]"

3. 安装 vLLM 和 vLLM-Ascend（可选）

如果需要使用 vLLMSampler 进行高效推理，可以安装 vLLM 和 vLLM-Ascend。

安装步骤：

# 第一步：安装 vLLM
pip install vllm==0.14.0

# 第二步：安装 vLLM-Ascend
pip install vllm-ascend==0.14.0rc1

注意事项：

• 按照上述顺序安装，忽略可能的依赖冲突提示
• 安装前确保已激活 CANN 环境：source /usr/local/Ascend/ascend-toolkit/set_env.sh
• 推荐使用的版本为 vLLM 0.14.0 和 vLLM-Ascend 0.14.0rc1

4. 验证安装

创建测试脚本 verify_npu.py：

import torch
import torch_npu

print(f"PyTorch version: {torch.__version__}")
print(f"torch_npu version: {torch_npu.__version__}")
print(f"NPU available: {torch.npu.is_available()}")
print(f"NPU device count: {torch.npu.device_count()}")

if torch.npu.is_available():
    print(f"Current NPU device: {torch.npu.current_device()}")
    print(f"NPU device name: {torch.npu.get_device_name(0)}")

    # 简单测试
    x = torch.randn(3, 3).npu()
    y = torch.randn(3, 3).npu()
    z = x + y
    print(f"NPU computation test passed: {z.shape}")

运行验证：

python verify_npu.py

如果输出显示 NPU available: True 且没有报错，说明安装成功！

注意：目前 Twinkle 暂未提供 NPU 的 Docker 镜像，建议使用手动安装方式。如需容器化部署，请参考昇腾社区的官方镜像。

5. 安装 Megatron 后端依赖

推荐组合：

• Megatron-LM: v0.15.3
• MindSpeed: core_r0.15.3
• mcore-bridge: 主分支或当前 Twinkle 验证过的版本

安装步骤：

# 1. 获取 Megatron-LM，并切到 Twinkle 兼容版本
git clone https://github.com/NVIDIA/Megatron-LM.git
cd Megatron-LM
git checkout v0.15.3
cd ..

# 2. 获取并安装 MindSpeed
git clone https://gitcode.com/Ascend/MindSpeed.git
cd MindSpeed
git checkout core_r0.15.3
pip install -e .
cd ..

# 3. 获取并安装 mcore-bridge
git clone https://github.com/modelscope/mcore-bridge.git
cd mcore-bridge
pip install -e .
cd ..

# 4. 安装 Twinkle（如果还没有安装）
cd twinkle
pip install -e ".[transformers,ray]"

运行前环境变量：

export PYTHONPATH=$PYTHONPATH:<path/to/Megatron-LM>
export MEGATRON_LM_PATH=</path/to/Megatron-LM>
export ASCEND_RT_VISIBLE_DEVICES=0,1,2,3,4,5,6,7

验证方式：

先跑一个最小导入检查，确认 MindSpeed / Megatron-LM 可以被当前环境找到：

python -c "import mindspeed.megatron_adaptor; from twinkle.model.megatron._mindspeed_runtime import ensure_mindspeed_adaptor_patched; ensure_mindspeed_adaptor_patched(); print('✓ Megatron backend imports are ready')"

6. Qwen3.5/3.6 FLA 与 Triton-Ascend 版本配套

FLA 开启条件

Qwen3.5/3.6 在 transformers 后端使用 FLA（Flash Linear Attention）时，需要满足以下条件：

• 安装 triton-ascend
• mindspeed 版本为 26.0.0_core_r0.12.1

Triton-Ascend 版本与 CANN 配套

MindSpeed 版本与代码适配

当前验证的 MindSpeed 版本为 26.0.0_core_r0.12.1。MindSpeed 代码仓地址：https://gitcode.com/Ascend/MindSpeed

如使用更高版本 MindSpeed，需注意 src/twinkle/kernel/chunk_gated_delta_rule.py 中的以下导入路径可能需要对应 MindSpeed 实际代码位置进行修改：

from mindspeed.lite.ops.triton.chunk_delta_h import chunk_gated_delta_rule_bwd_dhu, chunk_gated_delta_rule_fwd_h
from mindspeed.lite.ops.triton.chunk_o import chunk_bwd_dqkwg, chunk_bwd_dv_local, chunk_fwd_o
from mindspeed.lite.ops.triton.chunk_scaled_dot_kkt import chunk_scaled_dot_kkt_fwd
from mindspeed.lite.ops.triton.cumsum import chunk_local_cumsum
from mindspeed.lite.ops.triton.solve_tril import solve_tril
from mindspeed.lite.ops.triton.utils import autocast_custom_bwd, autocast_custom_fwd, input_guard
from mindspeed.lite.ops.triton.wy_fast import prepare_wy_repr_bwd, recompute_w_u_fwd

7. NPU Patch 环境变量配置

Twinkle 在 NPU 环境下默认启用模型层补丁，可通过以下环境变量进行细粒度控制：

使用示例：

# 关闭所有 NPU 优化，回退到 Transformers 原生实现
export TWINKLE_NPU_PATCH=0

# 仅关闭 FLA，保留其他融合算子
export TWINKLE_NPU_FLA=0

# 仅关闭 MoE 补丁
export TWINKLE_NPU_MOE_PATCH=0

快速开始

重要提示：以下示例均来自 cookbook/ 目录，已在实际 NPU 环境中验证通过。建议直接运行 cookbook 中的脚本，而不是复制粘贴代码片段。

SFT LoRA 微调

当前 NPU 文档不再提供这类 SFT cookbook 示例；这部分能力需要结合实际可用的 cookbook 示例或后续补充的 NPU 脚本来说明。

GRPO 强化学习训练

当前 NPU 文档不再提供这类 GRPO cookbook 示例；这部分能力需要结合实际可用的 cookbook 示例或后续补充的 NPU 脚本来说明。

更多示例

查看 cookbook/remote/tinker/ascend/ 目录了解远程训练服务端配置。

并行策略

Twinkle 在 NPU 上目前支持以下经过验证的并行策略：

图例说明：

• ✅ 已验证：有实际运行示例代码
• 🚧 待验证：理论上支持但暂无 NPU 验证示例
• ❌ 不支持：当前版本不可用

DP + FSDP 示例

当前 NPU 文档暂不提供对应的 cookbook 代码片段。

Megatron 后端说明：Twinkle 的 Megatron NPU 路径已经提供了可直接运行的 smoke 示例，安装和运行依赖请参考上面的 “Megatron 后端依赖” 小节。当前优先建议先验证 cookbook/megatron/ascend/tp_npu.py，再逐步切到 cookbook/megatron/ascend/tp_moe_npu.py 和 cookbook/megatron/ascend/tp_moe_cp_npu.py。

常见问题

1. torch_npu 版本不匹配

问题：安装 torch_npu 后出现版本不兼容警告或错误。

解决方案：

• 确保 torch 和 torch_npu 版本完全一致
• 检查 CANN 版本是否与 torch_npu 兼容

# 查看当前版本
python -c "import torch; import torch_npu; print(torch.__version__, torch_npu.__version__)"

# 重新安装匹配版本
pip uninstall torch torch_npu -y
pip install torch==2.7.1
pip install torch_npu-2.7.1-cp311-cp311-linux_aarch64.whl

2. CANN 工具包版本问题

问题：CANN 版本与 torch_npu 不兼容。

解决方案：

• 参考昇腾社区版本配套表
• 安装对应版本的 CANN 工具包

功能支持情况

基于实际代码验证的功能支持矩阵：

图例说明：

• ✅ 已验证：有实际运行示例，确认可用
• 🚧 待验证：理论上支持但暂无 NPU 环境验证
• ⚠️ 部分支持：可用但有限制或性能差异
• ❌ 不支持：当前版本不可用

使用建议：

1. 优先使用标记为“已验证”的功能，稳定性有保障
2. “待验证”功能可以尝试，但可能遇到兼容性问题
3. 遇到问题时，参考对应的示例代码进行配置

示例代码

Twinkle 在 NPU 上已验证的示例目前聚焦 Megatron smoke 路径；SFT 和 GRPO cookbook 示例暂无对应文件。

远程训练（Tinker 协议）

• 服务端配置：cookbook/remote/tinker/ascend/
  • 提供 HTTP API 接口
  • 支持远程训练和推理
  • 适用于生产环境部署

运行示例： 暂无对应命令示例。

参考资源

• 昇腾社区官网
• CANN 软件安装指南
• torch_npu GitHub
• Twinkle GitHub
• Twinkle 文档

获取帮助

如果您在使用过程中遇到问题：

1. 查看日志：设置环境变量 ASCEND_GLOBAL_LOG_LEVEL=1 获取详细日志
2. 提交 Issue：Twinkle GitHub Issues
3. 社区讨论：昇腾社区论坛

下一步

• 📖 阅读 快速开始 了解更多训练示例
• 📖 阅读 安装指南 了解其他平台的安装
• 🚀 浏览 cookbook/ 目录查看完整示例代码
• 💡 查看 Twinkle 文档 了解高级功能