NPU（昇腾）开箱指南

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

环境要求

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

组件	版本要求	说明
Python	>= 3.11, < 3.13	Twinkle 框架要求
昇腾固件驱动（HDK）	推荐最新版本	硬件驱动和固件
CANN 工具包	8.5.1 或更高	异构计算架构
PyTorch	2.7.1	深度学习框架
torch_npu	2.7.1	昇腾 PyTorch 适配插件

重要说明：

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')"

快速开始

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

SFT LoRA 微调

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

GRPO 强化学习训练

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

并行策略

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

并行类型	说明	NPU 支持	验证状态
DP (Data Parallel)	数据并行	✅	暂无对应 cookbook 示例
FSDP (Fully Sharded Data Parallel)	完全分片数据并行	✅	暂无对应 cookbook 示例
TP (Tensor Parallel)	张量并行（Megatron）	✅	已验证（见 `cookbook/megatron/ascend/tp_npu.py`）
PP (Pipeline Parallel)	流水线并行（Megatron）	✅	已验证（见 `cookbook/megatron/ascend/tp_npu.py`）
CP (Context Parallel)	上下文并行	✅	已验证（见 `cookbook/megatron/ascend/tp_moe_cp_npu.py`）
EP (Expert Parallel)	专家并行（MoE）	✅	已验证（见 `cookbook/megatron/ascend/tp_moe_npu.py`）

图例说明：

✅ 已验证：有实际运行示例代码
🚧 待验证：理论上支持但暂无 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 不兼容。