FineTuneX - 大模型微调框架

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

🌟 特性

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

📦 安装

环境要求

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

安装步骤

# 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

验证安装

python scripts/check_env.py

🚀 快速开始

运行微调示例

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

这个脚本会：

下载 Qwen3.5-0.5B 模型
加载示例数据集
使用 LoRA 进行微调
保存微调后的模型
进行推理测试

使用自己的数据

准备数据文件 data.json:

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

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

📚 文档

快速开始 - 5 分钟上手
使用文档 - 详细使用指南
安装指南 - 安装和配置
项目总结 - 完整功能说明

🛠️ 工具

数据预处理

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

模型推理

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

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

模型评估

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

API 服务

python scripts/start_api.py --port 8000

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

📖 示例

代码方式微调

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()

配置说明

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/                 # 输出目录

🔧 命令行工具

# 环境检查
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
其他: 可扩展支持更多模型

🧪 测试

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

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

🤝 贡献

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

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

📄 许可证

MIT License - 详见 LICENSE 文件

🙏 致谢

📬 联系方式

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

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

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

版本: 0.1.0

创建日期: 2026-03-27

README_FINAL.md 7.0 KB История Исходник