从HuggingFace到昇腾平台：MindSpeed/Qwen3-8B-Base权重转换完全教程

【免费下载链接】Qwen3-8B-Base 项目地址: https://ai.gitcode.com/hf_mirrors/MindSpeed/Qwen3-8B-Base

MindSpeed/Qwen3-8B-Base是专为昇腾平台优化的大语言模型，本教程将详细介绍如何将HuggingFace格式的Qwen3-8B-Base权重高效转换为昇腾平台支持的格式，帮助开发者快速部署和应用这一强大模型。

为什么需要权重转换？

在昇腾NPU平台上运行Qwen3-8B-Base模型时，直接使用HuggingFace格式的权重文件会面临兼容性和性能问题。权重转换是连接HuggingFace模型生态与昇腾AI硬件的关键桥梁，通过转换可以：

• 实现模型与昇腾NPU硬件的深度适配
• 优化模型存储结构，提升加载速度
• 为后续的训练和推理任务奠定基础
• 充分发挥昇腾平台的计算优势

准备工作：环境配置

硬件要求

Qwen3-8B-Base在昇腾平台上的推荐硬件配置如下：

类型	硬件	配置
全参微调	NPU	8 x Ascend NPUs

软件依赖

成功进行权重转换需要以下软件环境支持：

依赖软件	版本
昇腾NPU驱动	商发版本
昇腾NPU固件	商发版本
CANN Toolkit	商发版本
CANN Kernel	商发版本
CANN NNAL	商发版本
Python	>=3.10
PyTorch	2.1.0
torch_npu插件	2.1.0
apex	商发版本
transformers	4.51.3

仓库部署

首先需要克隆相关仓库并进行基础环境配置：

git clone https://gitcode.com/hf_mirrors/MindSpeed/Qwen3-8B-Base
git clone https://gitee.com/ascend/MindSpeed-LLM.git
git clone https://github.com/NVIDIA/Megatron-LM.git
cd Megatron-LM
git checkout core_r0.8.0
cp -r megatron ../MindSpeed-LLM/
cd ..
cd MindSpeed-LLM
mkdir logs
mkdir dataset
mkdir ckpt

环境搭建

创建并激活conda环境，安装必要依赖：

conda create -n qwen3_env python=3.10
conda activate qwen3_env

# 安装PyTorch和昇腾相关插件
pip install torch-2.1.0-cp310-cp310m-manylinux2014_aarch64.whl
pip install torch_npu-2.1.0*-cp310-cp310m-linux_aarch64.whl

# 安装MindSpeed加速库
git clone https://gitee.com/ascend/MindSpeed.git
cd MindSpeed
git checkout 2c085cc9
pip install -r requirements.txt
pip3 install -e .
cd ../MindSpeed-LLM

# 安装其余依赖库
pip install -r requirements.txt
pip install transformers==4.51.3

权重转换全流程

1. 权重下载

从HuggingFace或魔乐社区获取Qwen3-8B-Base原始权重：

• HuggingFace地址：https://huggingface.co/Qwen/Qwen3-8B-Base
• 魔乐社区地址：https://modelers.cn/models/Models_Ecosystem/Qwen3-8B-Base

下载完成后，确保权重文件结构如下：

Qwen3-8B-Base/
├── config.json
├── generation_config.json
├── model-00001-of-00002.safetensors
├── model-00002-of-00002.safetensors
├── model.safetensors.index.json
├── special_tokens_map.json
├── tokenizer_config.json
└── tokenizer.model

2. 转换脚本准备

MindSpeed-LLM提供了专门的权重转换脚本ckpt_convert_qwen3_8b_hf2mcore.sh，该脚本位于MindSpeed-LLM仓库的tests/0day/qwen3/qwen3-8b/目录下。

3. 脚本参数配置

在运行转换脚本前，需要根据实际环境修改以下关键参数：

参数	说明
HF_MODEL_PATH	HuggingFace格式权重的存放路径
OUTPUT_PATH	转换后权重的输出路径
TP_SIZE	张量并行度，根据硬件配置调整
PP_SIZE	流水线并行度，根据硬件配置调整
DISTRIBUTED_ARGS	分布式环境参数

4. 执行权重转换

运行以下命令执行权重转换：

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-8b/ckpt_convert_qwen3_8b_hf2mcore.sh

转换过程中，脚本会执行以下操作：

1. 加载HuggingFace格式的权重文件
2. 进行张量并行和流水线并行切分
3. 转换权重数据类型以适应昇腾NPU
4. 生成昇腾平台支持的权重文件结构
5. 保存转换后的权重到指定目录

5. 转换结果验证

转换成功后，在输出目录会生成以下文件：

output/
├── 0/
│   ├── model_00001-of-00002.pt
│   └── model_00002-of-00002.pt
├── 1/
│   ├── model_00001-of-00002.pt
│   └── model_00002-of-00002.pt
├── ...
└── config.json

可以通过以下命令验证转换结果：

import torch
from mindspore import Tensor

# 加载转换后的权重
weight = torch.load("output/0/model_00001-of-00002.pt")
print("权重加载成功，类型:", type(weight))
print("权重形状:", weight.shape)

常见问题解决

转换过程中内存不足

如果遇到内存不足错误，可以尝试：

• 降低并行度参数TP_SIZE和PP_SIZE
• 增加swap交换空间
• 使用更高配置的硬件环境

转换后模型无法加载

若模型加载失败，可能原因：

• 权重文件路径配置错误
• 转换脚本版本不匹配
• 昇腾CANN版本不兼容

解决方法：检查路径配置，确保使用最新版本的转换脚本，升级CANN工具包到最新商发版本。

转换速度慢

提升转换速度的方法：

• 使用多卡并行转换
• 关闭不必要的后台进程
• 确保NPU驱动和固件为最新版本

后续步骤：模型应用

权重转换完成后，您可以继续进行以下操作：

数据预处理

使用MindSpeed-LLM提供的数据预处理脚本准备训练数据：

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-8b/data_convert_qwen3_8b_pretrain.sh

模型训练

启动模型训练：

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-8b/pretrain_qwen3_8b_ptd.sh

推理部署

进行模型推理：

cd MindSpeed-LLM
bash tests/0day/qwen3/qwen3-8b/generate_qwen3_8b_ptd.sh

总结

本教程详细介绍了将HuggingFace格式的Qwen3-8B-Base权重转换为昇腾平台支持格式的完整流程，包括环境配置、权重下载、脚本配置、转换执行及结果验证等关键步骤。通过正确的权重转换，开发者可以充分利用昇腾NPU的强大计算能力，实现Qwen3-8B-Base模型的高效部署和应用。

如果您在权重转换过程中遇到任何问题，欢迎查阅项目官方文档或提交issue寻求帮助。祝您在昇腾平台上使用Qwen3-8B-Base模型取得成功！

【免费下载链接】Qwen3-8B-Base 项目地址: https://ai.gitcode.com/hf_mirrors/MindSpeed/Qwen3-8B-Base