# FineTuneX - 大模型微调框架

[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c?logo=pytorch)](https://pytorch.org/)
[![Transformers](https://img.shields.io/badge/Transformers-4.40+-ff9d00?logo=huggingface)](https://huggingface.co/docs/transformers)

一个简单易用的大语言模型微调框架，支持 Qwen、Llama 等主流模型，提供完整的微调、推理和部署解决方案。

## 🌟 特性

- **🚀 快速上手**: 完整的示例代码和详细文档
- **💾 显存优化**: 支持 LoRA/QLoRA 和 4bit 量化
- **📊 数据处理**: 多格式数据加载和自动预处理
- **🎯 灵活配置**: 模块化设计，易于扩展
- **🖥️ API 服务**: 内置 RESTful API 和 Swagger 文档
- **📈 训练监控**: 完整的日志和回调系统

## 📦 安装

### 环境要求

- **Python**: 3.9 或更高版本
- **PyTorch**: 2.0 或更高版本
- **CUDA**: 11.7+ (推荐使用 GPU)

### 安装步骤

```bash
# 1. 克隆项目
git clone <your-repo-url>
cd FineTuneX

# 2. 创建虚拟环境 (推荐)
python -m venv venv
venv\Scripts\activate  # Windows
# 或
source venv/bin/activate  # Linux/Mac

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

### 验证安装

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

## 🚀 快速开始

### 运行微调示例

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

这个脚本会：
1. 下载 Qwen3.5-0.5B 模型
2. 加载示例数据集
3. 使用 LoRA 进行微调
4. 保存微调后的模型
5. 进行推理测试

### 使用自己的数据

准备数据文件 `data.json`:

```json
[
  {
    "instruction": "请解释什么是机器学习",
    "input": "",
    "output": "机器学习是人工智能的一个分支..."
  },
  {
    "instruction": "将以下中文翻译成英文",
    "input": "今天天气很好",
    "output": "The weather is very nice today."
  }
]
```

修改示例脚本中的数据集路径，然后运行即可。

## 📚 文档

- **[快速开始](QUICKSTART.md)** - 5 分钟上手
- **[使用文档](docs/usage.md)** - 详细使用指南
- **[安装指南](INSTALL.md)** - 安装和配置
- **[项目总结](PROJECT_SUMMARY.md)** - 完整功能说明

## 🛠️ 工具

### 数据预处理

```bash
python scripts/preprocess_data.py --input data.json --output data_processed.json
```

### 模型推理

```bash
# 单次推理
python scripts/inference.py --model_path ./outputs/model --prompt "你好"

# 交互模式
python scripts/inference.py --model_path ./outputs/model --base_model ./outputs/model --interactive
```

### 模型评估

```bash
python scripts/evaluate.py --model_path ./outputs/model --test_data test.json
```

### API 服务

```bash
python scripts/start_api.py --port 8000
```

访问 http://localhost:8000/docs 查看 API 文档。

## 📖 示例

### 代码方式微调

```python
from finetunex.models import QwenConfig, load_qwen_model
from finetunex.data import load_dataset, InstructionDataset
from finetunex.trainer import FineTuneTrainer

# 配置模型
config = QwenConfig(
    model_name="Qwen/Qwen3.5-0.5B",
    lora_r=16,
    lora_alpha=32,
    num_train_epochs=3,
)

# 加载数据
dataset = load_dataset("data.json")

# 加载模型
model, tokenizer, _ = load_qwen_model(config)

# 创建训练数据集
train_dataset = InstructionDataset(dataset, tokenizer)

# 创建训练器
trainer = FineTuneTrainer(model, tokenizer, config, train_dataset)
trainer.setup_training(output_dir="./outputs")

# 开始训练
trainer.train()

# 保存模型
trainer.save_model()
```

### 配置说明

```python
QwenConfig(
    # 模型配置
    model_name="Qwen/Qwen3.5-0.5B",
    
    # LoRA 配置
    lora_r=16,              # LoRA 秩
    lora_alpha=32,          # LoRA alpha
    lora_dropout=0.05,      # Dropout
    target_modules=[...],   # 目标模块
    
    # 训练配置
    per_device_train_batch_size=1,
    gradient_accumulation_steps=4,
    learning_rate=2e-4,
    num_train_epochs=3,
    max_seq_length=512,
    
    # 量化配置
    use_4bit=True,          # 4bit 量化
)
```

## 🏗️ 项目结构

```
FineTuneX/
├── src/finetunex/           # 核心代码
│   ├── models/              # 模型配置和加载
│   ├── data/                # 数据处理
│   ├── trainer/             # 训练器
│   ├── utils/               # 工具函数
│   └── api/                 # API 服务
├── examples/                # 示例脚本
├── scripts/                 # 工具脚本
├── tests/                   # 测试
├── configs/                 # 配置文件
├── data/                    # 数据目录
├── docs/                    # 文档
└── outputs/                 # 输出目录
```

## 🔧 命令行工具

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

# 项目初始化
python scripts/init_project.py

# 数据预处理
python scripts/preprocess_data.py --input data.json --template alpaca

# 模型推理
python scripts/inference.py --model_path ./outputs/model --interactive

# 模型评估
python scripts/evaluate.py --model_path ./outputs/model --test_data test.json

# 启动 API
python scripts/start_api.py --port 8000

# 运行测试
python tests/test_all.py
```

## 📊 显存需求

| 模型 | 量化 | 批次大小 | 显存需求 |
|------|------|----------|----------|
| Qwen-0.5B | 4bit | 1 | ~2GB |
| Qwen-0.5B | 16bit | 1 | ~4GB |
| Qwen-7B | 4bit | 1 | ~8GB |
| Qwen-7B | 16bit | 1 | ~16GB |

**显存优化技巧**:
- 使用 4bit 量化 (`use_4bit=True`)
- 减小批次大小 (`per_device_train_batch_size=1`)
- 增加梯度累积 (`gradient_accumulation_steps=8`)
- 减小序列长度 (`max_seq_length=256`)

## 🌐 支持的模型

- **Qwen 系列**: Qwen3.5-0.5B, Qwen2.5-0.5B, Qwen-7B
- **Llama 系列**: Llama-3.2-1B, Llama-2-7B
- **Baichuan 系列**: Baichuan2-7B
- **其他**: 可扩展支持更多模型

## 🧪 测试

```bash
# 运行所有测试
python tests/test_all.py

# 运行特定测试
python -m unittest tests.test_all.TestDataLoading
```

## 🤝 贡献

欢迎贡献代码、文档和建议！

1. Fork 项目
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🙏 致谢

- [Hugging Face Transformers](https://huggingface.co/docs/transformers)
- [PEFT](https://huggingface.co/docs/peft)
- [BitsAndBytes](https://github.com/TimDettmers/bitsandbytes)
- [Qwen](https://huggingface.co/Qwen)

## 📬 联系方式

- 问题反馈：提交 Issue
- 功能建议：提交 Issue

---

**注意**: 当前环境使用 Python 3.5.4，需要升级到 Python 3.9+ 才能运行。详见 [INSTALL.md](INSTALL.md)

**状态**: ✅ 项目已完成并可用

**版本**: 0.1.0

**创建日期**: 2026-03-27