UniPEFT

🚀 Universal Parameter-Efficient Fine-Tuning Framework

一个模块化且可扩展的大语言模型微调框架，使用PEFT（参数高效微调）技术如LoRA进行训练。

🇺🇸 English README | 🇨🇳 中文文档

✨ 主要特性

• 🎯 多格式支持: 支持Alpaca、对话、自定义、HuggingFace等多种数据集格式
• ⚙️ 简单配置: 通过YAML文件轻松配置所有训练参数
• 🚄 高效训练: DeepSpeed集成，支持单机多卡和分布式训练
• 📊 完整监控: Weights & Biases集成，实时监控训练过程
• 🔧 模块化设计: 易于扩展和自定义，支持快速添加新数据集类型
• 💾 内存优化: 支持梯度检查点、混合精度、模型分片等优化技术
• 🔄 双模式训练: 支持LoRA参数高效微调和全参数增量训练

🏗️ 项目结构

UniPEFT/
├── README.md                          # 🇨🇳 中文文档
├── README_EN.md                       # 🇺🇸 英文文档
├── LICENSE                            # MIT许可证
├── requirements.txt                   # 项目依赖
├── pyproject.toml                     # 项目配置
├── 
├── src/                              # 📦 源代码目录
│   ├── __init__.py
│   ├── lora.py                       # 🎯 LoRA训练主程序
│   ├── incremental_sft.py            # 🔄 增量SFT训练主程序
│   ├── data/                         # 📊 数据处理模块
│   │   ├── __init__.py
│   │   └── data_processor.py         # 数据处理器工厂
│   ├── utils/                        # 🛠️ 工具模块
│   │   ├── __init__.py
│   │   └── logger.py                 # 日志工具
│   └── model/                        # 🤖 模型相关工具
│       ├── model_utils.py            # 模型加载工具
│       ├── merge_lora_weights.py     # LoRA权重合并脚本
│       └── simple_merge_lora.py      # 简单合并脚本
│
├── scripts/                          # 📜 启动脚本
│   ├── launch_lora.sh                # LoRA训练启动脚本
│   └── launch_incremental.sh         # 增量训练启动脚本
│
├── examples/                         # 📝 配置示例
│   ├── sample_data.json              # 样本数据
│   ├── lora/                         # LoRA配置示例
│   │   ├── config_small.yaml         # 小规模训练配置
│   │   ├── config_multi_gpu.yaml     # 多GPU训练配置
│   │   ├── config_hf_alpaca.yaml     # HuggingFace Alpaca数据集
│   │   ├── config_hf_dolly.yaml      # HuggingFace Dolly数据集
│   │   ├── config_custom_csv.yaml    # 自定义CSV数据
│   │   └── config_custom_street.yaml # 自定义街道推理数据
│   └── incremental/                  # 增量训练配置示例
│       ├── config_incremental_sft.yaml     # 基础增量SFT配置
│       ├── config_incremental_street.yaml  # 街道推理增量训练
│       └── config_incremental_resume.yaml  # 恢复训练配置
│
├── docs/                             # 📚 详细文档
│   ├── INCREMENTAL_SFT.md            # 增量训练指南
│   └── FREEZE_LAYERS_GUIDE.md        # 层冻结指南
│
├── ds_config/                        # ⚡ DeepSpeed配置
│   ├── deepspeed_stage2.json         # Stage 2 ZeRO配置
│   ├── deepspeed_stage3.json         # Stage 3 ZeRO配置
│   └── deepspeed_incremental_sft.json # 增量训练专用配置
│
├── output/                           # 💾 训练输出目录
├── cache/                            # 🗄️ 缓存目录
├── logs/                             # 📝 日志文件
└── wandb/                            # 📈 Weights & Biases日志

🚀 快速开始

📋 环境要求

• Python = 3.11
• CUDA >= 12.1 (推荐)
• torch = 2.6.0
• 8GB+ GPU显存 (最小配置)

📦 安装

# 克隆项目
git clone https://github.com/BiNLP/UniPEFT.git
cd UniPEFT

# 安装依赖
pip install torch==2.6.0 torchvision==0.21.0 torchaudio==2.6.0 --index-url https://download.pytorch.org/whl/cu124
wget https://github.com/Dao-AILab/flash-attention/releases/download/v2.7.4.post1/flash_attn-2.7.4.post1+cu12torch2.6cxx11abiFALSE-cp311-cp311-linux_x86_64.whl
pip install flash_attn-2.7.4.post1+cu12torch2.6cxx11abiFALSE-cp311-cp311-linux_x86_64.whl
pip install -r requirements.txt

🎯 准备数据

UniPEFT支持多种数据源和格式，包括本地文件和HuggingFace在线数据集。

📁 本地数据源

Alpaca格式 (dataset_name: "alpaca"):

[
    {
        "instruction": "解释机器学习的概念",
        "input": "",
        "output": "机器学习是一种人工智能技术..."
    }
]

对话格式 (dataset_name: "conversation"):

[
    {
        "conversations": [
            {"from": "human", "value": "你好"},
            {"from": "gpt", "value": "你好！有什么可以帮助你的吗？"}
        ]
    }
]

CSV格式 (dataset_name: "custom"):

question,context,answer
"什么是深度学习?","","深度学习是机器学习的一个分支..."

JSONL格式 (dataset_name: "conversation"):

dataset_name: "conversation"
data_path: "./data/conversations.jsonl"

🤗 HuggingFace数据源

热门预配置数据集:

# Alpaca GPT-4 (高质量指令数据)
dataset_name: "alpaca-gpt4"
data_path: "vicgalle/alpaca-gpt4"

# Databricks Dolly (商业友好)
dataset_name: "dolly" 
data_path: "databricks/databricks-dolly-15k"

# WizardLM (代码生成能力强)
dataset_name: "wizardlm"
data_path: "WizardLM/WizardLM_evol_instruct_V2_196k"

# OpenAssistant (多轮对话)
dataset_name: "oasst1"
data_path: "OpenAssistant/oasst1"

自定义HuggingFace数据集:

dataset_name: "huggingface"
data_path: "your-username/your-dataset" 
dataset_config: "en"  # 可选配置
cache_dir: "./cache"
token: true  # 私有数据集需要

🔧 高级配置

多语言数据集:

dataset_name: "huggingface"
data_path: "Helsinki-NLP/opus-100"
dataset_config: "en-zh"  # 英中翻译

私有数据集访问:

# 设置HuggingFace token
export HUGGINGFACE_TOKEN="your_token_here"

token: true

缓存管理:

cache_dir: "./cache/my_dataset"  # 自定义缓存位置
# 清理缓存: rm -rf ./cache/my_dataset

📊 数据集推荐

通用指令遵循:

• alpaca-gpt4: 高质量，适合通用任务
• dolly: 商业友好，无版权问题
• wizardlm: 代码和推理能力强

对话系统:

• oasst1: 多轮对话数据
• 自定义conversation格式数据

特定领域:

• 使用自定义CSV文件
• 特定领域的HuggingFace数据集

💡 数据准备最佳实践

1. 数据质量: 优先选择高质量标注数据
2. 数据量: 1K-10K样本通常足够微调
3. 格式统一: 确保指令格式一致
4. 缓存利用: 使用cache_dir避免重复下载
5. 混合数据: 可以组合多个数据源

⚙️ 配置训练参数

编辑 config.yaml 文件：

# 模型配置
model_name: "Qwen/Qwen2.5-7B-Instruct"
max_length: 2048

# LoRA配置
lora_r: 16
lora_alpha: 32
lora_dropout: 0.1

# 训练配置
num_train_epochs: 3
per_device_train_batch_size: 4
learning_rate: 2.0e-4

# 数据配置
dataset_name: "alpaca"
data_path: "./data/train.json"

# HuggingFace数据集示例
# dataset_name: "alpaca-gpt4"  
# data_path: "vicgalle/alpaca-gpt4"

🏃‍♂️ 启动训练

单GPU训练:

python src/main.py --config config.yaml

多GPU训练:

# 使用启动脚本
./launch.sh config.yaml 4  # 4张GPU

# 或直接使用DeepSpeed
deepspeed src/main.py --config config.yaml

📋 详细配置

🤖 模型配置

• model_name: HuggingFace模型名称
• model_path: 本地模型路径（可选）
• max_length: 最大序列长度

🎯 LoRA配置

• lora_r: LoRA rank（通常8-64）
• lora_alpha: LoRA alpha参数（通常是rank的2倍）
• lora_dropout: LoRA dropout率
• lora_target_modules: 目标模块列表

🏋️‍♂️ 训练配置

• num_train_epochs: 训练轮数
• per_device_train_batch_size: 每设备批大小
• gradient_accumulation_steps: 梯度累积步数
• learning_rate: 学习率

⚡ DeepSpeed配置

• deepspeed_stage2.json: 适用于中等大小模型
• deepspeed_stage3.json: 适用于大型模型，具有参数分片

🔧 扩展新数据集

方法1：使用本地自定义数据

# CSV文件
dataset_name: "custom"
data_path: "./data/my_data.csv"
instruction_key: "question"  # 指定问题列名
input_key: "context"         # 指定上下文列名  
output_key: "answer"         # 指定答案列名

方法2：使用HuggingFace数据集

# 现有热门数据集
dataset_name: "dolly"
data_path: "databricks/databricks-dolly-15k"

# 或自动检测
dataset_name: "huggingface"  
data_path: "any-huggingface-dataset"

方法3：继承BaseDataProcessor

class MyDataProcessor(BaseDataProcessor):
    def load_raw_data(self):
        # 支持本地文件或HuggingFace数据集
        if self.is_huggingface_dataset():
            return self.load_huggingface_dataset()
        else:
            return self.load_local_file()
    
    def format_example(self, example):
        # 实现示例格式化逻辑
        return {
            'instruction': example['question'],
            'input': example.get('context', ''),
            'output': example['answer']
        }

# 注册到工厂
DataProcessorFactory.register('my_dataset', MyDataProcessor)

🎯 支持的数据集类型

类型	数据源	示例	描述
alpaca	本地/HF	Alpaca格式的指令数据	标准指令-输入-输出格式
conversation	本地/HF	对话格式数据	多轮对话格式，支持human/gpt角色
custom	本地	自定义CSV/JSON文件	灵活的自定义格式，可指定列名
alpaca-gpt4	HF	vicgalle/alpaca-gpt4	高质量GPT-4生成的指令数据
dolly	HF	databricks/databricks-dolly-15k	商业友好的指令数据集
wizardlm	HF	WizardLM指令数据	代码生成和推理能力强
oasst1	HF	OpenAssistant/oasst1	多轮对话数据集
huggingface	HF	任意HF数据集	通用HF数据集处理器

📊 监控和日志

📈 Weights & Biases

use_wandb: true
wandb_project: "my-llm-finetune"
wandb_run_name: "experiment-1"

设置环境变量：

export WANDB_API_KEY="your-api-key"

📝 本地日志

训练日志会自动输出到控制台，包含：

• 训练进度
• 损失值
• 学习率变化
• 模型参数信息

⚡ 性能优化建议

💾 内存优化

1. 使用梯度检查点：自动启用
2. 使用DeepSpeed ZeRO：配置deepspeed_config
3. 减少批大小，增加梯度累积步数

🚀 速度优化

1. 使用bf16（新硬件）或fp16
2. 增加dataloader_num_workers
3. 使用Flash Attention（如果支持）

🖥️ 不同硬件配置建议

单卡24GB显存：

per_device_train_batch_size: 2
gradient_accumulation_steps: 8
fp16: true

多卡训练：

per_device_train_batch_size: 4
gradient_accumulation_steps: 4
deepspeed_config: "./configs/deepspeed_stage2.json"

大模型（>13B）：

per_device_train_batch_size: 1
gradient_accumulation_steps: 16
deepspeed_config: "./configs/deepspeed_stage3.json"

❓ 常见问题

Q: 内存不足怎么办？

A:

1. 减少批大小
2. 启用DeepSpeed ZeRO
3. 使用梯度检查点
4. 考虑使用量化

Q: 如何选择LoRA参数？

A:

• rank: 8-64，更大的rank表达能力更强但参数更多
• alpha: 通常设为rank的2倍
• target_modules: 包含所有线性层获得最佳效果

Q: 如何评估模型效果？

A:

1. 监控训练损失
2. 在验证集上评估
3. 手动测试生成质量

🤝 贡献指南

我们欢迎任何形式的贡献！请遵循以下步骤：

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 文件

🙏 致谢

• Hugging Face Transformers
• PEFT
• DeepSpeed
• Weights & Biases

📞 联系我们

如果您有任何问题或建议，请：

• 提交 Issue

---

⭐ 如果这个项目对您有帮助，请给我们一个星标！