# 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. 配置环境变量：

```bash
# 添加以下行到 ~/.bashrc
source /usr/local/Ascend/ascend-toolkit/set_env.sh

# 重新加载环境变量
source ~/.bashrc
```

### 2.3 Python 依赖

```bash
# 使用 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](file:///f:/Workspace2016/FineTuneX/finetunex/models/qwen.py) 中：
- 自动检测并跳过不支持的 4bit 量化
- 使用 bf16/fp16 精度加载模型
- `device_map="auto"` 会自动映射到 NPU 设备

### 3.3 训练器

在 [finetunex/trainer/trainer.py](file:///f:/Workspace2016/FineTuneX/finetunex/trainer/trainer.py) 中：
- 增加 `check_device()` 方法，自动检测 CUDA/NPU/CPU
- 默认使用 `bf16` 混合精度训练（华为升腾推荐）
- 优化器自动切换为 `adamw_torch`（NPU 兼容）

### 3.4 设备检测

在 [finetunex/utils/helpers.py](file:///f:/Workspace2016/FineTuneX/finetunex/utils/helpers.py) 中：
- `get_gpu_info()` 现在支持 NPU 设备检测
- 随机种子设置自动适配 NPU

## 4. 使用方法

### 4.1 环境检查

```bash
python scripts/check_env.py
```

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

### 4.2 运行微调

#### 使用 HuggingFace 模型

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

#### 使用本地模型

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

### 4.3 关键配置说明

```python
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 环境变量：

```bash
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. 参考资源

- [华为昇腾文档](https://www.hiascend.com/document)
- [CANN 安装指南](https://www.hiascend.com/software/cann)
- [torch-npu 使用指南](https://gitee.com/ascend/pytorch)