# fine-tune

**Repository Path**: kai_kai_chi/fine-tune

## Basic Information

- **Project Name**: fine-tune
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-16
- **Last Updated**: 2026-05-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Fine-Tune 微调框架

基于 LoRA 的 LLM 微调学习项目，适用于消费级显卡（8GB VRAM）。

## 特性

- LoRA 微调
- YAML 配置系统，预置多套配置
- 自动检测数据格式（Alpaca / ShareGPT / QA）
- 训练过程自动划分训练集/验证集，监控验证 loss
- TensorBoard 可视化 loss 曲线
- 推理脚本，支持基座模型对比
- 国内 HuggingFace 镜像自动加速
- 一键转换为 Ollama GGUF 格式

## 快速开始

```bash
# 1. 安装依赖
pip install -r requirements.txt

# 1.1 安装 CUDA 版 PyTorch（必须步骤）
# requirements.txt 安装的是 CPU 版 PyTorch，必须单独安装 CUDA 版才能使用 GPU 训练。
# RTX 5060Ti 等 Blackwell 架构显卡需要 CUDA 12.8+：
# 方式一：直接 pip 安装（国内下载慢，约 2.75GB）
pip install torch --index-url https://download.pytorch.org/whl/cu128
# 方式二：用 PowerShell 先下载再安装（推荐，更稳定）
powershell -Command "Invoke-WebRequest -Uri 'https://download.pytorch.org/whl/cu128/torch-2.11.0%2Bcu128-cp312-cp312-win_amd64.whl' -OutFile '$env:TEMP\torch-cu128.whl' -UseBasicParsing"
pip install "$env:TEMP\torch-cu128.whl"
# 安装后验证：python -c "import torch; print(torch.cuda.is_available())" 应输出 True

# 2. 下载模型（国内自动使用镜像）
python scripts/download_model.py --model Qwen/Qwen2-1.5B

# 3. 准备训练数据（放入 data/training_data.json，Alpaca 格式）

# 4. 开始训练
python src/train.py --config configs/lora/qwen2_1.5b_lora.yaml

# 5. 查看 loss 曲线
tensorboard --logdir ./output

# 6. 测试微调效果
python scripts/inference.py -m ./output/qwen2_1.5b_lora/final_model -b models/qwen2_1.5b --compare

# 7. 转换为 Ollama 可用的 GGUF 格式（可选）
# 7.1 下载 llama.cpp（国内推荐 Gitee 镜像）
git clone https://gitee.com/kai_kai_chi/llama.cpp.git llama_cpp
# 或者从 GitHub 下载
# git clone https://github.com/ggml-org/llama.cpp.git llama_cpp

# 7.2 运行转换脚本（自动合并 LoRA + 转换 GGUF + 导入 Ollama）
python scripts/convert_to_gguf_llamacpp.py -b models/qwen2_1.5b -l output/qwen2_1.5b_lora/final_model

# 7.3 测试 Ollama 模型
ollama run qwen2-finetuned
```

Windows 用户可直接运行 `train.bat` 交互式选择配置。

## 项目结构

```
fine-tune/
├── src/
│   ├── config/__init__.py    # 配置管理（dataclass + YAML）
│   ├── data/__init__.py      # 数据处理（格式检测、分词、划分）
│   ├── trainer/__init__.py   # 训练器（trl.SFTTrainer + LoRA）
│   └── train.py              # 训练入口
├── scripts/
│   ├── download_model.py     # 模型下载（支持HF镜像）
│   ├── inference.py          # 推理测试脚本
│   └── convert_to_gguf_llamacpp.py  # GGUF 转换（llama.cpp 方式）
├── llama_cpp/                # llama.cpp 仓库（需手动克隆）
├── configs/lora/
│   ├── qwen2_1.5b_lora.yaml  # Qwen2-1.5B LoRA
│   └── qwen2_1.5b_lora.yaml  # Qwen2-1.5B LoRA
├── data/
│   └── train_0001_of_0001_chatml_1200.json    # 训练数据（Alpaca格式）
├── models/                   # 本地模型（gitignored）
├── output/                   # 训练输出（gitignored）
├── train.bat                 # Windows 启动脚本
└── requirements.txt          # Python 依赖
```

## 可用配置

| 配置 | 模型 | 方法 | 说明 |
|------|------|------|------|
| `qwen2-1.5b-lora` | Qwen2-1.5B | LoRA | 推荐，8GB显存 |


```bash
# 使用预设名称
python src/train.py --config qwen2-1.5b-lora

# 使用配置文件路径
python src/train.py --config configs/lora/qwen2_1.5b_lora.yaml

# 列出所有配置
python src/train.py --list
```

## 数据格式

训练数据为 JSON 文件，支持三种格式（自动检测）：

**Alpaca 格式**（推荐）：
```json
[
  {
    "instruction": "你的指令",
    "input": "可选输入",
    "output": "期望输出"
  }
]
```

**ShareGPT 格式**：
```json
[
  {
    "conversations": [
      {"from": "human", "value": "问题"},
      {"from": "gpt", "value": "回答"}
    ]
  }
]
```

**QA 格式**：
```json
[
  {"question": "问题", "answer": "回答"}
]
```

## 训练输出

训练产物保存在 `./output/<配置名>/` 目录下：

```
output/qwen2_1.5b_lora/
├── final_model/          # LoRA 权重 + tokenizer
├── training_info.json    # 训练信息（loss、时间、超参）
├── checkpoint-*/         # 中间检查点
├── gguf/                 # GGUF 转换输出（转换后生成）
│   ├── merged_model/     # 合并后的模型
│   ├── *.gguf            # GGUF 模型文件
│   └── Modelfile         # Ollama 配置文件
└── events.out.*          # TensorBoard 日志
```

## 推理测试

```bash
# 加载 LoRA 模型推理
python scripts/inference.py -m ./output/qwen2_1.5b_lora/final_model -b models/qwen2_1.5b

# 对比基座模型 vs 微调模型
python scripts/inference.py -m ./output/qwen2_1.5b_lora/final_model -b models/qwen2_1.5b --compare
```

## 转换为 Ollama GGUF 格式

将微调模型转换为 Ollama 可用的 GGUF 格式，需要使用 llama.cpp。

### 前置条件

```bash
# 下载 llama.cpp（国内推荐 Gitee 镜像，速度更快）
git clone https://gitee.com/kai_kai_chi/llama.cpp.git llama_cpp
# 或者从 GitHub 下载
# git clone https://github.com/ggml-org/llama.cpp.git llama_cpp
```

### 基本用法

```bash
# 转换并导入 Ollama（默认模型名称：qwen2-finetuned）
python scripts/convert_to_gguf_llamacpp.py -b models/qwen2_1.5b -l output/qwen2_1.5b_lora/final_model

# 测试 Ollama 模型
ollama run qwen2-finetuned
```

### 高级选项

```bash
# 指定输出目录和模型名称
python scripts/convert_to_gguf_llamacpp.py -b models/qwen2_1.5b -l output/qwen2_1.5b_lora/final_model -o output/gguf -n my-model

# 转换后量化为 Q4_K_M（更小体积，适合部署）
python scripts/convert_to_gguf_llamacpp.py -b models/qwen2_1.5b -l output/qwen2_1.5b_lora/final_model -q Q4_K_M

# 跳过合并步骤（如果已合并）
python scripts/convert_to_gguf_llamacpp.py --skip-merge -m output/qwen2_1.5b_lora/gguf/merged_model

# 跳过 Ollama 导入（只生成 GGUF 文件）
python scripts/convert_to_gguf_llamacpp.py --skip-import
```

### 脚本参数说明

| 参数 | 说明 | 默认值 |
|------|------|--------|
| `--base-model`, `-b` | 基座模型路径 | `models/qwen2_1.5b` |
| `--lora-model`, `-l` | LoRA 适配器路径 | `output/qwen2_1.5b_lora/final_model` |
| `--output-dir`, `-o` | 输出目录 | `output/qwen2_1.5b_lora/gguf` |
| `--type`, `-t` | GGUF 数据类型 | `f16` |
| `--quant`, `-q` | 量化类型（Q4_K_M/Q5_K_M/Q8_0） | 无 |
| `--model-name`, `-n` | Ollama 模型名称 | `qwen2-finetuned` |
| `--skip-merge` | 跳过 LoRA 合并步骤 | `false` |
| `--merged-model`, `-m` | 已合并模型路径 | 无 |
| `--skip-import` | 跳过 Ollama 导入 | `false` |

## 硬件要求

- GPU：NVIDIA，至少 6GB 显存（推荐 8GB）
- 模型：Qwen2-1.5B fp16 约 3GB，LoRA 训练额外约 2-3GB
- 优化：gradient checkpointing、fp16、batch_size=2 + gradient_accumulation=4

## 依赖

```
torch (CUDA 版), transformers, peft, datasets, accelerate, pyyaml, tensorboard
```

> **注意**：`requirements.txt` 中的 `torch` 会安装 CPU 版本，必须按上方步骤单独安装 CUDA 版 PyTorch。