FineTuneX 使用文档

安装

环境要求

Python 3.9+
PyTorch 2.0+
CUDA 11.7+ (推荐使用 GPU)

安装依赖

# 克隆项目
cd FineTuneX

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

# 或者以开发模式安装
pip install -e .

验证安装

python -c "import torch; print(f'PyTorch: {torch.__version__}')"
python -c "import transformers; print(f'Transformers: {transformers.__version__}')"

快速开始

1. 运行示例

# 微调 Qwen3.5 模型
python examples/qwen3.5_0.8b_finetune.py

2. 使用命令行工具

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

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

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

数据准备

数据格式

FineTuneX 支持标准的指令微调数据格式：

[
  {
    "instruction": "指令文本",
    "input": "输入文本（可选）",
    "output": "期望的输出文本"
  }
]

示例数据

项目已包含示例数据集：data/sample_dataset.json

数据预处理

# 转换为 Alpaca 格式
python scripts/preprocess_data.py \
  --input your_data.json \
  --output alpaca_data.json \
  --template alpaca

# 验证数据集
python scripts/preprocess_data.py \
  --input your_data.json \
  --validate

自定义数据加载

from finetunex.data import load_dataset, format_dataset

# 加载 JSON 数据
dataset = load_dataset("your_data.json", format="json")

# 加载 CSV 数据
dataset = load_dataset("your_data.csv", format="csv")

# 从 HuggingFace 加载
dataset = load_dataset("squad", split="train")

# 格式化数据集
formatted = format_dataset(
    dataset,
    instruction_column="question",
    output_column="answer",
)

模型微调

使用示例脚本

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

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

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

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

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

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

# 5. 创建训练器
trainer = FineTuneTrainer(model, tokenizer, config, train_dataset)

# 6. 设置训练
trainer.setup_training(output_dir="./outputs")

# 7. 开始训练
trainer.train()

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

训练配置说明

config = 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=[        # 目标模块
        "q_proj", "v_proj",
        "k_proj", "o_proj",
        "gate_proj", "up_proj", "down_proj",
    ],
    
    # 训练配置
    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 量化
)

显存优化

如果显存不足，可以调整以下参数：

config = QwenConfig(
    use_4bit=True,                      # 启用 4bit 量化
    per_device_train_batch_size=1,      # 减小批次大小
    gradient_accumulation_steps=8,      # 增加梯度累积
    max_seq_length=256,                 # 减小序列长度
)

模型推理

使用推理脚本

# 单次推理
python scripts/inference.py \
  --model_path ./outputs/qwen3.5-0.5b-finetuned \
  --prompt "请解释什么是机器学习" \
  --max_length 512

# 交互模式
python scripts/inference.py \
  --model_path ./outputs/qwen3.5-0.5b-finetuned \
  --interactive

编程方式推理

from transformers import AutoTokenizer
from peft import PeftModel
import torch

# 加载模型
tokenizer = AutoTokenizer.from_pretrained("./outputs/model")
base_model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen3.5-0.5B",
    device_map="auto",
    torch_dtype=torch.float16,
)
model = PeftModel.from_pretrained(base_model, "./outputs/model")

# 生成响应
prompt = "请解释什么是机器学习"
inputs = tokenizer(prompt, return_tensors="pt").to("cuda")

with torch.no_grad():
    outputs = model.generate(
        **inputs,
        max_new_tokens=100,
        temperature=0.7,
        do_sample=True,
    )

response = tokenizer.decode(outputs[0], skip_special_tokens=True)
print(response)

API 服务

启动服务

# 默认配置
python scripts/start_api.py

# 自定义端口
python scripts/start_api.py --port 8080

# 禁用自动重载
python scripts/start_api.py --reload false

API 端点

1. 健康检查

curl http://localhost:8000/health

2. 开始训练

curl -X POST http://localhost:8000/api/v1/train \
  -H "Content-Type: application/json" \
  -d '{
    "model_name": "Qwen/Qwen3.5-0.5B",
    "dataset_path": "data/sample_dataset.json",
    "output_dir": "./outputs",
    "num_train_epochs": 3
  }'

3. 查询训练状态

curl http://localhost:8000/api/v1/train/job_001

4. 模型推理

curl -X POST http://localhost:8000/api/v1/inference \
  -H "Content-Type: application/json" \
  -d '{
    "model_path": "./outputs/model",
    "prompt": "你好",
    "max_length": 512
  }'

API 文档

启动服务后访问：http://localhost:8000/docs

配置说明

完整配置示例

# configs/qwen3.5_config.py

# 模型配置
model_name = "Qwen/Qwen3.5-0.5B"

# 数据集配置
dataset_path = "data/sample_dataset.json"
instruction_column = "instruction"
input_column = "input"
output_column = "output"

# LoRA 配置
lora_r = 16
lora_alpha = 32
lora_dropout = 0.05
target_modules = [
    "q_proj", "k_proj", "v_proj",
    "o_proj", "gate_proj", "up_proj", "down_proj",
]

# 训练配置
per_device_train_batch_size = 1
gradient_accumulation_steps = 4
learning_rate = 2e-4
num_train_epochs = 3
max_seq_length = 512

# 优化器配置
warmup_ratio = 0.03
weight_decay = 0.01
lr_scheduler_type = "cosine"

# 量化配置
use_4bit = True
bnb_4bit_compute_dtype = "float16"
bnb_4bit_quant_type = "nf4"

# 输出配置
output_dir = "./outputs/qwen3.5-0.5b-finetuned"
logging_steps = 10
save_steps = 50

# 其他配置
seed = 42
fp16 = True

常见问题

1. 显存不足

问题: CUDA out of memory

解决方案:

启用 4bit 量化：use_4bit=True
减小批次大小：per_device_train_batch_size=1
增加梯度累积：gradient_accumulation_steps=8
减小序列长度：max_seq_length=256

2. 模型下载慢

问题: 从 HuggingFace 下载模型速度慢

解决方案:

# 使用镜像站
export HF_ENDPOINT=https://hf-mirror.com
python examples/qwen3.5_0.8b_finetune.py

3. 训练不收敛

问题: 训练 loss 不下降

解决方案:

调整学习率：尝试 1e-4 或 5e-5
增加训练轮数：num_train_epochs=5
检查数据质量
调整 LoRA 秩：lora_r=32

4. 推理结果不合理

问题: 生成结果不符合预期

解决方案:

调整 temperature：temperature=0.5 (更确定) 或 temperature=0.9 (更随机)
增加 max_new_tokens
检查 prompt 格式
确保训练数据质量

5. 依赖冲突

问题: pip install 报错

解决方案:

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 升级 pip
pip install --upgrade pip

# 重新安装
pip install -r requirements.txt

支持的平台

本地 GPU: CUDA 11.7+
云平台:
- Google Colab (免费 T4 GPU)
- Kaggle Kernels
- AWS SageMaker
- Azure ML

贡献

欢迎贡献代码！请遵循以下步骤：

Fork 项目
创建特性分支
提交更改
推送到分支
创建 Pull Request

许可证

MIT License

usage.md 8.3 KB Historie Surový

FineTuneX 使用文档

目录

安装

环境要求

安装依赖

验证安装

快速开始

1. 运行示例

2. 使用命令行工具

数据准备

数据格式

示例数据

数据预处理

自定义数据加载

模型微调

使用示例脚本

训练配置说明

显存优化

模型推理

使用推理脚本

编程方式推理

API 服务

启动服务

API 端点

1. 健康检查

2. 开始训练

3. 查询训练状态

4. 模型推理

API 文档

配置说明

完整配置示例

常见问题

1. 显存不足

2. 模型下载慢

3. 训练不收敛

4. 推理结果不合理

5. 依赖冲突

支持的平台

贡献

许可证

usage.md 8.3 KB

Historie Surový