FineTurnX/ASCEND_GUIDE.md

FineTuneX 华为升腾适配说明

本文档说明如何在华为升腾（Ascend）NPU 服务器上使用 FineTuneX 进行大模型微调。

1. 硬件要求

• 华为 Ascend 910B/910 Pro B 等 NPU 设备
• 推荐 64GB 以上内存
• 推荐 100GB 以上存储空间（用于模型和训练数据）

2. 软件环境要求

2.1 操作系统

• Ubuntu 20.04/22.04
• openEuler 22.03
• CentOS 7.6+

2.2 CANN 软件栈

华为升腾需要安装 CANN（Compute Architecture for Neural Networks）软件栈：

1. 下载并安装对应版本的 CANN Toolkit

2. 配置环境变量：

   # 添加以下行到 ~/.bashrc
   source /usr/local/Ascend/ascend-toolkit/set_env.sh
   
   # 重新加载环境变量
   source ~/.bashrc
   

2.3 Python 依赖

# 使用 conda 创建 Python 环境（推荐 Python 3.9+）
conda create -n finetunex python=3.9
conda activate finetunex

# 安装华为适配的 PyTorch 和 torch-npu
# 请参考华为官方文档获取对应版本的安装命令
pip install torch torch-npu

# 安装 FineTuneX 的其他依赖
pip install transformers>=4.40.0 datasets>=2.14.0 accelerate>=0.25.0
pip install peft>=0.7.0 trl>=0.7.0 sentencepiece>=0.1.99
pip install pandas>=2.0.0 numpy>=1.24.0 tqdm>=4.65.0

注意：华为升腾 NPU 不支持以下库：

• bitsandbytes（4bit/8bit 量化）
• autoawq（AWQ 量化）
• auto-gptq（GPTQ 量化）
• llama-cpp-python（GGUF 量化）

3. 项目配置改动

3.1 requirements.txt

华为升腾版本已调整依赖：

• 使用 torch-npu 替代标准 torch
• 移除了 bitsandbytes 等不兼容的量化库
• 将量化相关依赖注释掉（仅支持 NVIDIA GPU）

3.2 模型加载

在 finetunex/models/qwen.py 中：

• 自动检测并跳过不支持的 4bit 量化
• 使用 bf16/fp16 精度加载模型
• device_map="auto" 会自动映射到 NPU 设备

3.3 训练器

在 finetunex/trainer/trainer.py 中：

• 增加 check_device() 方法，自动检测 CUDA/NPU/CPU
• 默认使用 bf16 混合精度训练（华为升腾推荐）
• 优化器自动切换为 adamw_torch（NPU 兼容）

3.4 设备检测

在 finetunex/utils/helpers.py 中：

• get_gpu_info() 现在支持 NPU 设备检测
• 随机种子设置自动适配 NPU

4. 使用方法

4.1 环境检查

python scripts/check_env.py

会同时检测 CUDA 和 NPU 设备状态。

4.2 运行微调

使用 HuggingFace 模型

python examples/qwen3.5_0.8b_finetune.py

使用本地模型

# 修改 examples/qwen3.5_0.8b_local_finetune.py 中的模型路径
python examples/qwen3.5_0.8b_local_finetune.py

4.3 关键配置说明

config = QwenConfig(
    model_name="Qwen/Qwen3.5-0.5B",
    use_4bit=False,      # NPU 必须关闭 4bit 量化
    bnb_4bit_compute_dtype="bfloat16",  # 推荐 bf16
)

trainer.setup_training(
    bf16=True,           # NPU 推荐 bf16
    fp16=False,
)

5. 注意事项

5.1 显存要求

由于华为升腾不支持 4bit 量化，需要使用 bf16/fp16 加载模型：

• Qwen3.5-0.5B：约需 3-4GB 显存
• Qwen3.5-1.5B：约需 6-8GB 显存
• Qwen3.5-7B：约需 28-32GB 显存

5.2 训练速度

• NPU 训练速度与 NVIDIA GPU 相当或更快（取决于具体型号）
• 建议适当增大批次大小以充分利用 NPU 算力

5.3 已知限制

1. 不支持量化加载：无法使用 bitsandbytes 4bit/8bit 量化加载模型
2. 不支持部分量化工具：AWQ、GPTQ、GGUF 等格式转换工具不可用
3. 内存统计：torch.npu 不支持详细的内存统计 API

6. 常见问题

Q1: 找不到 torch.npu 模块

确保已正确安装 torch-npu 包并配置了 CANN 环境变量：

source /usr/local/Ascend/ascend-toolkit/set_env.sh
python -c "import torch; print(hasattr(torch, 'npu'))"

Q2: 训练报错 "NPU not available"

检查以下几点：

1. CANN Toolkit 是否安装正确
2. NPU 驱动是否安装
3. 环境变量是否配置
4. 使用 npu-smi info 检查 NPU 状态

Q3: 显存不足

由于无法使用 4bit 量化，如果显存不足：

1. 减小 max_seq_length
2. 减小 per_device_train_batch_size
3. 增大 gradient_accumulation_steps
4. 使用更小的模型版本

7. 参考资源

• 华为昇腾文档
• CANN 安装指南
• torch-npu 使用指南