# 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 系列模型。