# Unsloth_Qlora_Qwen3-32B_AWQ

**Repository Path**: kun_int/unsloth_qlora_qwen3-32b

## Basic Information

- **Project Name**: Unsloth_Qlora_Qwen3-32B_AWQ
- **Description**: 使用unsloth以qlora方式微调qwen3-32b的脚本，需求48g显存。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-08-14
- **Last Updated**: 2025-08-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🚀 Qwen3 32B 微调系统

基于 Unsloth + QLoRA 的高效 Qwen3 32B 模型微调解决方案，支持自动路径识别、配置驱动和一键部署。

## ✨ 特性

- 🎯 **一键启动**: 完整的微调流程自动化
- 🔧 **配置驱动**: 只需修改一处配置即可切换模型和数据集
- 📂 **智能路径**: 自动识别项目根目录，任意位置可运行
- 💾 **显存优化**: 支持 48GB 显卡运行 32B 模型（4bit 量化）
- 📊 **完整日志**: 训练过程和结果详细记录
- 🔄 **灵活配置**: 支持命令行参数覆盖默认配置

## 🛠️ 环境要求

### 硬件要求
- **GPU**: NVIDIA RTX 4090 (48GB) 或更高，推荐 48GB+ 显存
- **内存**: 32GB+ 系统内存推荐
- **存储**: 80GB+ 可用磁盘空间（注意：实际需求可能更大）

### 软件要求
- **操作系统**: Linux (Ubuntu 18.04+)
- **Python**: 3.8+
- **CUDA**: 11.7+ 或 12.0+

⚠️ **磁盘空间提醒**: 
- 模型约65GB，数据集约1GB，输出约5GB
- 总需求约71GB，确保有足够空间

## 📦 快速安装

### 1. 克隆项目
```bash
git clone <repository-url>
cd unsloth_-qlora_-qwen3-32-b_-awq
```

### 2. 安装依赖
```bash
# 安装 PyTorch (CUDA 12.1)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

# 安装 Unsloth
pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"

# 安装其他依赖
pip install transformers datasets accelerate peft bitsandbytes trl modelscope
```

### 3. 验证环境
```bash
python scripts/check_environment.py
```

## 🎬 快速演示

整个系统的运行流程如下图所示：

```
环境检查 ✅ → 配置显示 ✅ → 下载资源 ✅ → 模型训练 ✅ → 自动测试 ✅
```

**完整输出示例**：
```bash
$ ./scripts/quick_start.sh

🎯 Qwen3 32B 微调完整流程
项目根目录: /path/to/project

🔍 检查环境
✅ Python版本符合要求
✅ 检测到 1 个GPU: NVIDIA vGPU-48GB (47.4 GB)
✅ 所有Python库已安装
...

📥 下载资源
✅ 检测到本地模型，跳过下载
✅ 检测到本地数据集，跳过下载

🚀 开始训练
📜 日志文件: logs/20250814_234940__unsloth-Qwen3-32B-...
⏱️  训练时间: 8.69 分钟
💾 峰值显存使用: 39.604 GB
✅ 模型保存完成!

🧪 测试模型
测试用例 1: 请介绍一下人工智能的发展历史
回答: 人工智能（AI）的发展历史可以追溯到20世纪中叶...

🎉 流程完成！
```

## 🚀 快速开始

### 方式 1: 一键启动（推荐新手）
```bash
# 完整流程：检查环境 + 下载 + 训练 + 测试
./scripts/quick_start.sh

# 快速测试（10步训练）
./scripts/quick_start.sh --quick-test

# 查看所有选项
./scripts/quick_start.sh --help
```

### 方式 2: 分步执行（推荐进阶用户）
```bash
# 1. 查看当前配置
python scripts/finetune_qwen3.py --config

# 2. 下载模型和数据集
python scripts/finetune_qwen3.py --download_model --download_data

# 3. 开始微调
python scripts/finetune_qwen3.py

# 4. 测试模型
python scripts/test_model.py --mode chat
```

## ⚙️ 配置说明

### 核心配置文件：`scripts/config.py`

只需修改以下几行即可完成配置：

```python
# ================================
# 主要配置项 - 只需修改这里！
# ================================

## 模型配置
MODEL_ID = "unsloth/Qwen3-32B-unsloth-bnb-4bit"

## 数据集配置  
DATASET_ID = "swift/Chinese-Qwen3-235B-2507-Distill-data-110k-SFT"
NUM_SAMPLES = 5000  # 训练样本数量

## 训练配置
MAX_STEPS = 100        # 训练步数
BATCH_SIZE = 1         # 批次大小
LEARNING_RATE = 2e-4   # 学习率
```

### 支持的模型
- `unsloth/Qwen3-32B-unsloth-bnb-4bit` (推荐)
- `unsloth/Qwen2.5-32B-unsloth-bnb-4bit`
- `unsloth/Llama-3.1-8B-bnb-4bit`

### 支持的数据集
- `swift/Chinese-Qwen3-235B-2507-Distill-data-110k-SFT` (中文高质量SFT，推荐)
- `silk-road/alpaca-data-gpt4-chinese` (中文Alpaca)
- `BelleGroup/train_2M_CN` (Belle中文数据集)
- `YeungNLP/firefly-train-1.1M` (Firefly数据集)

## 📁 项目结构

```
unsloth_-qlora_-qwen3-32-b_-awq/
├── README.md                    # 本文档
├── 使用指南.md                   # 详细使用指南
├── Qwen3_32B_微调指南.md         # 技术文档
├── 项目总结.md                   # 项目总结
├── scripts/                     # 脚本目录
│   ├── config.py               # 配置文件 ⭐
│   ├── quick_start.sh          # 一键启动脚本
│   ├── finetune_qwen3.py       # 主要微调脚本
│   ├── test_model.py           # 模型测试脚本
│   ├── prepare_dataset.py      # 数据集处理脚本
│   └── check_environment.py    # 环境检查脚本
├── model/                      # 模型存储目录
├── data/                       # 数据集存储目录
├── output/                     # 训练输出目录
└── logs/                       # 日志文件目录
```

## 🎯 使用场景

### 1. 快速验证（推荐首次使用）
```bash
# 修改 scripts/config.py 中的 NUM_SAMPLES = 100, MAX_STEPS = 10
./scripts/quick_start.sh --quick-test
```

### 2. 生产环境微调
```bash
# 修改 scripts/config.py 中的 NUM_SAMPLES = None, MAX_STEPS = 1000
./scripts/quick_start.sh --full-training
```

### 3. 自定义参数训练
```bash
python scripts/finetune_qwen3.py \
    --max_steps 500 \
    --batch_size 2 \
    --learning_rate 1e-4 \
    --num_samples 10000
```

### 4. 切换不同模型/数据集
```bash
# 使用不同模型
python scripts/finetune_qwen3.py \
    --model_id "unsloth/Qwen2.5-32B-unsloth-bnb-4bit"

# 使用不同数据集
python scripts/finetune_qwen3.py \
    --dataset_id "silk-road/alpaca-data-gpt4-chinese"
```

## 📊 性能参考

### 实际性能表现（基于 vGPU-48GB）

| 配置 | 批次大小 | 序列长度 | 显存使用 | 训练速度 | Loss收敛 |
|------|----------|----------|----------|----------|----------|
| 标准配置 | 1 | 2048 | ~39.6GB | ~5.2s/步 | 0.77 (100步) |
| 推理模式 | 1 | 2048 | ~37.2GB | 快速响应 | - |

### 显存使用详情
- **模型加载**: ~37.2GB
- **训练峰值**: ~39.6GB  
- **训练增量**: ~2.4GB
- **显存使用率**: ~84%

## 🧪 测试模型

微调完成后，系统会自动运行测试用例。你也可以手动测试：

### 运行测试用例
```bash
python scripts/test_model.py --mode test
```

**示例输出**（基于实际测试）：
```
测试用例 1:
指令: 请介绍一下人工智能的发展历史
回答: 人工智能（AI）的发展历史可以追溯到20世纪中叶...（详细的历史介绍）

测试用例 2:
指令: 如何学习Python编程？
回答: 学习Python编程是一个循序渐进的过程...（系统的学习建议）
```

### 交互式对话
```bash
python scripts/test_model.py --mode chat
```

### 性能基准测试
```bash
python scripts/test_model.py --mode benchmark
```

## 📋 常用命令

### 环境检查
```bash
python scripts/check_environment.py
```

### 查看配置
```bash
python scripts/finetune_qwen3.py --config
```

### 仅下载资源
```bash
python scripts/finetune_qwen3.py --download_model --download_data --download_only
```

### 数据集预览
```bash
python scripts/prepare_dataset.py --preview ./data/chinese-qwen-sft
```

### 查看训练日志
```bash
ls -la logs/
tail -f logs/最新日志文件.log
```

**日志文件命名规则**：
```
logs/YYYYmmdd_HHMMSS__模型ID__数据集ID__steps步数_bs批次_lr学习率.log
```

**示例**：
```
logs/20250814_234940__unsloth-Qwen3-32B-unsloth-bnb-4bit__swift-Chinese-Qwen3-235B-2507-Distill-data-110k-SFT__steps100_bs1_lr0.0002.log
```

## 🔧 自定义配置

### 显存优化配置
```python
# 适合显存较小的GPU
BATCH_SIZE = 1
MAX_SEQ_LENGTH = 1024
GRADIENT_ACCUMULATION_STEPS = 8
```

### 高性能配置
```python
# 适合显存充足的GPU
BATCH_SIZE = 2
MAX_SEQ_LENGTH = 4096
GRADIENT_ACCUMULATION_STEPS = 2
```

### LoRA 参数调优
```python
LORA_R = 32          # 提高LoRA秩以增强模型能力
LORA_ALPHA = 32      # 通常与LORA_R相等
LORA_DROPOUT = 0.1   # 增加dropout防止过拟合
```

## ❓ 故障排除

### 常见问题

#### 1. CUDA内存不足
```bash
# 解决方案：减少批次大小和序列长度
python scripts/finetune_qwen3.py --batch_size 1 --max_seq_length 1024
```

#### 2. 磁盘空间不足
```bash
# 检查当前磁盘使用
df -h

# 解决方案：使用较少样本或清理旧输出
python scripts/finetune_qwen3.py --num_samples 1000
rm -rf ./output/checkpoint-*

# 注意：确保至少有71GB可用空间
```

#### 3. 模型下载失败
```bash
# 解决方案：检查网络或使用代理
export HF_ENDPOINT=https://hf-mirror.com
python scripts/finetune_qwen3.py --download_model
```

#### 4. 数据集格式错误
```bash
# 解决方案：检查数据集格式并重新下载
python scripts/prepare_dataset.py --preview ./data/数据集目录
rm -rf ./data/problematic_dataset
python scripts/finetune_qwen3.py --download_data
```

### 获取帮助
1. 查看详细使用指南：`cat 使用指南.md`
2. 查看技术文档：`cat Qwen3_32B_微调指南.md`
3. 运行环境检查：`python scripts/check_environment.py`
4. 查看训练日志：`tail -f logs/最新日志.log`

## 📈 最佳实践

### 1. 首次使用流程
1. 运行环境检查确保依赖齐全
2. 使用快速测试验证流程
3. 逐步增加训练规模
4. 监控GPU显存和训练指标

### 2. 生产环境建议
- 使用高质量数据集（推荐 Chinese-Qwen3 SFT）
- 设置合理的训练步数（500-1000步）
- 定期保存检查点
- 监控验证集性能避免过拟合

### 3. 性能优化
- 启用混合精度训练（自动检测）
- 使用梯度累积增加有效批次大小
- 合理设置序列长度平衡性能和显存
- 使用数据并行处理加速数据加载

## 🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

### 提交 Issue
- 详细描述问题和复现步骤
- 提供环境信息和错误日志
- 包含相关的配置文件内容

### 提交 PR
- Fork 本仓库并创建特性分支
- 确保代码风格一致
- 添加必要的测试和文档
- 详细描述修改内容

## 📄 许可证

本项目采用 MIT 许可证 - 详见 [LICENSE](LICENSE) 文件。

## 🙏 致谢

- [Unsloth](https://github.com/unslothai/unsloth) - 高效微调框架
- [Qwen](https://github.com/QwenLM/Qwen) - 基础语言模型
- [ModelScope](https://modelscope.cn/) - 模型和数据集托管平台
- [Transformers](https://github.com/huggingface/transformers) - 模型库
- [PEFT](https://github.com/huggingface/peft) - 参数高效微调

## 📞 联系方式

- 项目维护者：[Amazcuter]
- 邮箱：amazcuter@outlook.com
- 技术交流群：[群号/878924874 - T10 技术交流]

---

**⭐ 如果这个项目对您有帮助，请考虑给个 Star！**

*最后更新：2025年8月15日*