LLaMA-Factory 微调入门与实战配置

配置文件怎么写

LLaMA-Factory 用 YAML 配训练任务，结构不复杂。下面这个 SFT 配置是比较典型的写法：

task_type: sft
model_name_or_path: Qwen/Qwen1.5-7B-Chat
dataset_dir: data/
dataset: custom_sft_dataset
eval_strategy: steps
eval_steps: 500
per_device_train_batch_size: 1
gradient_accumulation_steps: 4
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
fp16: true
output_dir: outputs/qwen-sft
logging_steps: 10
save_steps: 500
load_best_model_at_end: true
metric_for_best_model: loss

几个参数里，真正会影响体验的通常是这些：

• task_type：任务类型，比如 sft、pt、rm
• dataset_dir：数据集目录
• dataset：数据集名称，需要先在 data/datasets_info.json 里注册
• per_device_train_batch_size：单卡 batch size
• gradient_accumulation_steps：梯度累积步数，用来模拟更大的 batch
• learning_rate：学习率，LoRA 场景下通常会设得相对高一点
• fp16：是否启用混合精度
• output_dir：模型输出目录

Web UI 的用法

如果只是先验证流程，Web UI 比命令行顺手，尤其是第一次接触这类框架的时候。

1. 启动服务：

   python src/train_web.py
   

   默认监听 7860，浏览器打开 http://localhost:7860。

2. 选模型：在左侧菜单里指定模型名称，先确认本地权重是可用的。

3. 加数据：上传自定义数据集，或者选内置数据集。格式一般要满足 instruction、input、output 这类字段要求。

4. 调参数：学习率、Epoch、Batch Size 这些都能直接改。

5. 开始训练：点击'开始'后，右侧会显示 Loss 曲线和日志。

6. 导出模型：训练结束后可以导出成 HuggingFace 格式或 GGUF 格式，方便后续部署。

命令行训练示例

如果要接自动化流程，命令行更直接，也更容易复现。

python src/train.py \
    --stage sft \
    --do_train \
    --model_name_or_path Qwen/Qwen1.5-7B-Chat \
    --dataset custom_sft \
    --template qwen \
    --finetuning_type lora \
    --lora_target all \
    --output_dir ./checkpoints \
    --overwrite_cache \
    --per_device_train_batch_size 1 \
    --gradient_accumulation_steps 4 \
    --lr_scheduler_type cosine \
    --logging_steps 10 \
    --save_steps 1000 \
    --learning_rate 5e-5 \
    --num_train_epochs 3.0 \
    --plot_loss \
    --fp16

常用参数里，比较关键的是：

• --stage：训练阶段，常见有 sft、pt、rm
• --finetuning_type：微调方式，可选 lora、full、freeze
• --lora_target：LoRA 作用的目标模块，all 表示全部线性层
• --template：模型模板，比如 qwen、llama、chatglm
• --plot_loss：训练后生成 Loss 曲线

推理和部署

训练完的模型可以直接接推理服务。这里用 vLLM 起 API，会比自己拼一套推理脚本省心。

启动 API 服务

python src/api_server.py \
    --model_name_or_path ./outputs/checkpoint \
    --port 8000 \
    --backend vllm

调用示例

import requests

response = requests.post(
    "http://localhost:8000/v1/chat/completions",
    json={
        "model": "local-model",
        "messages": [{"role": "user", "content": "你好，请介绍一下你自己。"}],
        "temperature": 0.7
    }
)
print(response.json())

浏览器测试

也可以直接去 Web UI 的推理页输入提示词，适合快速看效果，尤其是想确认模板和 tokenizer 有没有接对的时候。

常见问题

显存不够

最常见的报错还是 CUDA out of memory。优先顺序我一般会这样调：先降 per_device_train_batch_size，再加 gradient_accumulation_steps，然后开 fp16 或 bf16。如果还是不行，就转 qlora，通常比硬撑全量训练靠谱。

数据集格式有问题

如果训练一启动就报 KeyError 或 ValueError，大概率是数据字段不对。先检查 JSON 里有没有 instruction、input、output，再看有没有空行、脏字符，以及数据集名是否已经在 datasets_info.json 注册。

模型加载失败

这种问题通常不是框架本身，而是下载和路径出了岔子。先确认网络能访问模型仓库，必要时换镜像源，比如 HF-Mirror；再检查模型名是否拼写正确，或者直接把权重下载到本地后改用本地路径。

结语

LLaMA-Factory 适合想把开源模型尽快跑起来的人。它不追求把每个细节都暴露给你，但把微调、评估、推理这些高频流程做得比较完整，实际用起来反而省时间。要是真准备上手，先用 Web UI 跑通一轮，再切到命令行做可复现配置，会顺很多。官方文档也值得顺手翻一下，很多参数默认值和兼容边界，最后还是得看它自己说得最准。