190 lines
7.5 KiB
Markdown
190 lines
7.5 KiB
Markdown
# Qwen3-0.6B-Code-Expert 模型 LoRA 微调作业说明
|
||
## 项目简介
|
||
本项目是基于 **LLaMA Factory** 工具对阿里云通义千问的 **Qwen3-0.6B-Code-Expert** 小型代码大模型进行 **LoRA（Low-Rank Adaptation）轻量化微调** 的实践作业。核心目标是掌握大语言模型（LLM）的轻量化微调流程、训练检查点的恢复与管理、微调后模型的导出，以及通过 SSH 远程连接训练服务器完成模型下载、训练和文件传输的全流程操作。
|
||
|
||
项目针对 **CUDA 编程相关知识** 数据集（`cuda_train`）进行微调，最终得到适配 CUDA 知识问答的轻量化模型，同时实现了本地与远程训练服务器的协同操作。
|
||
|
||
### 核心技术栈
|
||
- 模型基座：Qwen3-0.6B-Code-Expert（代码领域轻量级大模型）
|
||
- 微调框架：LLaMA Factory（一站式大模型微调工具）
|
||
- 微调方法：LoRA（低秩适配，减少训练参数量）
|
||
- 远程操作：SSH/SCP/Paramiko（服务器登录与文件传输）
|
||
- 依赖库：Transformers、PyTorch、Safetensors、Paramiko 等
|
||
|
||
## 环境配置
|
||
### 1. 本地环境（开发机）
|
||
适用于 Windows/macOS/Linux，需安装 Python 3.8+，执行以下命令安装依赖：
|
||
```bash
|
||
# 基础依赖（模型加载与微调）
|
||
pip install torch==2.6.0 transformers==4.54.0 safetensors llama-factory
|
||
# 远程操作依赖（SSH 连接服务器）
|
||
pip install paramiko scp
|
||
```
|
||
|
||
### 2. 远程训练服务器（Seetacloud）
|
||
通过 SSH 登录服务器后，执行相同的依赖安装命令。若服务器无 GPU，需指定 CPU 版本依赖：
|
||
```bash
|
||
# 服务器无 GPU 时安装 CPU 版 PyTorch
|
||
pip install torch==2.6.0+cpu transformers==4.54.0 safetensors llama-factory --index-url https://download.pytorch.org/whl/cpu
|
||
```
|
||
|
||
## 快速开始
|
||
### 1. 模型下载
|
||
通过 `download_model.py` 脚本从 Hugging Face 下载 Qwen3-0.6B-Code-Expert 基座模型（或 Qwen2.5-0.5B 轻量化版本），支持本地/远程服务器下载。
|
||
|
||
#### 脚本使用
|
||
```python
|
||
# download_model.py
|
||
import os
|
||
os.environ["HF_ENDPOINT"] = "https://hf-mirror.com" # 国内镜像加速
|
||
from transformers import AutoModelForCausalLM, AutoTokenizer
|
||
|
||
model_name = "Qwen/Qwen3-0.6B-Code-Expert" # 基座模型名称
|
||
local_model_path = "./local-model" # 本地保存路径（服务器可改为 /root/local-model）
|
||
|
||
# 加载并保存模型
|
||
model = AutoModelForCausalLM.from_pretrained(model_name, trust_remote_code=True)
|
||
tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
|
||
model.save_pretrained(local_model_path)
|
||
tokenizer.save_pretrained(local_model_path)
|
||
print("模型下载完成！")
|
||
```
|
||
|
||
**运行脚本**：
|
||
- 本地：`python download_model.py`
|
||
- 远程服务器：先通过 SCP 上传脚本，再执行 `python /root/download_model.py`
|
||
|
||
### 2. 模型微调（LoRA）
|
||
使用 LLaMA Factory 的命令行工具进行 LoRA 微调，核心命令如下（可保存为 `train.sh` 脚本）：
|
||
```bash
|
||
#!/bin/bash
|
||
llamafactory-cli train \
|
||
--stage sft \
|
||
--do_train True \
|
||
--model_name_or_path /root/autodl-tmp/models/modelscope_cache/models/suayptalha/Qwen3-0.6B-Code-Expert \
|
||
--preprocessing_num_workers 16 \
|
||
--finetuning_type lora \
|
||
--template default \
|
||
--flash_attn auto \
|
||
--dataset_dir data \
|
||
--dataset cuda_train \
|
||
--cutoff_len 2048 \
|
||
--learning_rate 5e-05 \
|
||
--num_train_epochs 20.0 \
|
||
--max_samples 100000 \
|
||
--per_device_train_batch_size 2 \
|
||
--gradient_accumulation_steps 8 \
|
||
--lr_scheduler_type cosine \
|
||
--max_grad_norm 1.0 \
|
||
--logging_steps 5 \
|
||
--save_steps 100 \
|
||
--warmup_steps 0 \
|
||
--packing False \
|
||
--enable_thinking True \
|
||
--report_to none \
|
||
--output_dir saves/Qwen3-0.6B-Base/lora/train_2025-12-21-07-31-02 \
|
||
--bf16 True \
|
||
--plot_loss True \
|
||
--trust_remote_code True \
|
||
--ddp_timeout 180000000 \
|
||
--include_num_input_tokens_seen True \
|
||
--optim adamw_torch \
|
||
--lora_rank 8 \
|
||
--lora_alpha 16 \
|
||
--lora_dropout 0 \
|
||
--lora_target all \
|
||
--save_safetensors True
|
||
```
|
||
|
||
**关键参数说明**：
|
||
- `--finetuning_type lora`：指定 LoRA 轻量化微调；
|
||
- `--dataset cuda_train`：使用 CUDA 编程知识数据集；
|
||
- `--output_dir`：训练检查点保存路径；
|
||
- `--save_safetensors True`：使用 Safetensors 格式保存权重（规避 PyTorch 安全漏洞）。
|
||
|
||
**运行微调**：
|
||
```bash
|
||
# 赋予脚本执行权限
|
||
chmod +x train.sh
|
||
# 执行微调
|
||
./train.sh
|
||
```
|
||
|
||
### 3. 检查点恢复训练
|
||
若训练中断，可通过 `--resume_from_checkpoint` 参数恢复训练：
|
||
```bash
|
||
llamafactory-cli train \
|
||
# 保留原微调参数...
|
||
--resume_from_checkpoint saves/Qwen3-0.6B-Base/lora/train_2025-12-21-07-13-16 \
|
||
--save_safetensors True
|
||
```
|
||
|
||
> **注意**：恢复训练需保证 PyTorch 版本 ≥2.6（规避 `torch.load` 安全漏洞），若版本过低需执行 `pip install torch==2.6.0` 升级。
|
||
|
||
### 4. 模型导出
|
||
将 LoRA 微调权重与基座模型合并，导出为 Hugging Face 标准格式：
|
||
```bash
|
||
llamafactory-cli export \
|
||
--model_name_or_path /root/autodl-tmp/models/modelscope_cache/models/suayptalha/Qwen3-0.6B-Code-Expert \
|
||
--adapter_name_or_path saves/Qwen3-0.6B-Base/lora/train_2025-12-21-07-31-02 \
|
||
--template default \
|
||
--export_dir ./exported_qwen3_model \
|
||
--export_format huggingface \
|
||
--trust_remote_code True
|
||
```
|
||
|
||
导出后，`./exported_qwen3_model` 目录下为完整的可部署模型，可直接通过 `transformers` 加载使用。
|
||
|
||
## 远程服务器操作（Seetacloud）
|
||
本项目需通过 SSH 连接学校的 Seetacloud 训练服务器完成模型训练与文件传输，核心操作如下：
|
||
|
||
### 1. 手动 SSH 登录
|
||
```bash
|
||
# 连接服务器（端口 14788，输入密码即可登录）
|
||
ssh -p 14788 root@connect.sha1.seetacloud.com
|
||
```
|
||
|
||
### 2. 文件传输（SCP）
|
||
- **上传本地文件到服务器**：
|
||
```bash
|
||
scp -P 14788 download_model.py root@connect.sha1.seetacloud.com:/root/
|
||
```
|
||
- **下载服务器模型到本地**：
|
||
```bash
|
||
scp -P 14788 -r root@connect.sha1.seetacloud.com:/root/exported_qwen3_model ./
|
||
```
|
||
|
||
### 3. 自动 SSH 操作脚本
|
||
通过 `paramiko` 库实现自动化登录、执行命令与文件传输，脚本见 `ssh_model_operate.py`（需替换 SSH 密码）：
|
||
```bash
|
||
# 运行自动化脚本
|
||
python ssh_model_operate.py
|
||
```
|
||
|
||
## 项目结构
|
||
```
|
||
.
|
||
├── download_model.py # 基座模型下载脚本
|
||
├── train.sh # LoRA 微调脚本
|
||
├── ssh_model_operate.py # 远程服务器自动化操作脚本
|
||
├── data/ # 数据集目录（存放 cuda_train 数据集）
|
||
├── local-model/ # 本地下载的基座模型
|
||
├── saves/ # 训练检查点保存目录
|
||
├── exported_qwen3_model/ # 导出的微调后完整模型
|
||
└── README.md # 项目说明文档
|
||
```
|
||
|
||
## 注意事项
|
||
1. **PyTorch 版本**：恢复训练时需保证 PyTorch ≥2.6，否则会触发 `torch.load` 安全漏洞报错；
|
||
2. **服务器环境**：若服务器无 GPU，需在加载模型时指定 `device_map='cpu'`；
|
||
3. **大文件传输**：模型文件较大时，推荐使用 `rsync` 替代 SCP 以提升稳定性：
|
||
```bash
|
||
rsync -avz -e 'ssh -p 14788' root@connect.sha1.seetacloud.com:/root/exported_qwen3_model ./
|
||
```
|
||
4. **SSH 安全**：建议使用 SSH 密钥登录服务器，避免密码明文暴露。
|
||
|
||
## 致谢
|
||
1. 感谢学校提供的 Seetacloud 训练服务器资源；
|
||
2. 感谢 LLaMA Factory 团队提供的一站式大模型微调工具；
|
||
3. 感谢阿里云通义千问团队开源的 Qwen3 系列模型。
|