LLaMA-Factory 简介
LLaMA-Factory 是一个简单易用且高效的大型语言模型训练与微调平台。通过它，可以在无需编写大量代码的前提下，在本地完成上百种预训练模型的微调。其核心特性包括支持多种主流模型架构（如 LLaMA、Qwen、Yi、ChatGLM 等）、丰富的训练算法（SFT、DPO、PPO 等）以及灵活的精度控制（全参数、LoRA、QLoRA 等）。此外，框架还集成了 FlashAttention-2、Unsloth 等加速算子，并支持 TensorBoard、Wandb 等实验监控工具。
安装部署
CUDA 环境配置
CUDA 是 NVIDIA 提供的并行计算平台和编程模型。首先需确认 GPU 是否支持 CUDA，可通过官方文档查询兼容列表。在 Linux 环境下，建议先检查系统版本和编译器环境：
uname -m && cat /etc/*release
gcc --version
确保输出符合预期后，下载并安装 CUDA Toolkit（推荐 12.2 版本）。若之前已安装旧版本，需先卸载：
sudo /usr/local/cuda-12.1/bin/cuda-uninstaller
# 若命令不可用，可手动清理
sudo rm -r /usr/local/cuda-12.1/
sudo apt clean && sudo apt autoclean
安装完成后，运行 nvcc -V 验证版本号。注意在安装过程中，若不确定驱动兼容性，建议取消 Driver 的自动安装选项。
LLaMA-Factory 安装
基础环境建议如下：Ubuntu 22.04 + CUDA 12.x + Python 3.10 + PyTorch 2.2.2。
创建虚拟环境并安装依赖：
conda create -n llama_factory python=3.10 -y
conda activate llama_factory
conda install pytorch==2.2.2 torchvision==0.17.2 torchaudio==2.2.2 pytorch-cuda=11.8 -c pytorch -c nvidia
pip install llmtuner
克隆项目并安装依赖：
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics]"
若遇到依赖冲突，可尝试 pip install --no-deps -e . 跳过依赖检查。安装成功后，可通过以下命令校验：
llamafactory-cli version
启动 WebUI 界面：
CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=1 GRADIO_SERVER_PORT=7860 llamafactory-cli webui
如需使用离线模型，可从 ModelScope 等平台下载，例如：
git clone https://www.modelscope.cn/Qwen/Qwen2.5-0.5B-Instruct.git
Windows 用户注意事项
Windows 环境下启用 QLoRA 或 FlashAttention-2 可能需要特定版本的二进制包。请根据 CUDA 版本从 GitHub 发布页下载对应的 .whl 文件进行安装。此外，部分高级功能（如 DeepSpeed、vLLM）可能需要额外安装依赖项。
数据微调准备
LLaMA-Factory 支持多种数据集格式，主要包括 Alpaca 和 ShareGPT。自定义数据集需在 dataset_info.json 中注册。目前支持的指令监督微调、偏好数据集及多模态数据集格式如下：
指令监督微调
指令微调通过让模型学习指令与回答的配对来优化表现。数据集中通常包含 instruction（指令）、input（输入）、output（回答）三列。若指定了 system 列，将作为系统提示词；history 列则用于多轮对话历史。
示例格式：
[
{
"instruction": "计算这些物品的总费用。",
"input": "汽车 - $3000，衣服 - $100，书 - $20。",
"output": "汽车、衣服和书的总费用为 $3120。",
"history": []
}
]
在 dataset_info.json 中的配置需对应字段映射：
"数据集名称": {
"file_name": "data.json",
"columns": {
"prompt": "instruction",
"query": "input",
"response": "output",
"system": "system",
"history": "history"
}
}
其他数据集类型
- 预训练数据集：仅需
text列，用于无监督学习语言表征。 - 偏好数据集：包含
chosen（优质回答）和rejected（劣质回答），适用于 DPO 或奖励模型训练。 - KTO 数据集：包含
kto_tag（true/false），用于直接反馈优化。 - 多模态数据集：需额外添加
images、videos或audios列，路径数量必须与文本中的标记严格一致。
WebUI 操作指南
LLaMA-Factory 提供了友好的 Web 界面，支持零代码微调。启动服务后，主要操作流程如下：
- 模型选择：指定预训练模型名称或本地路径。
- 训练阶段：选择 SFT、RLHF 等任务类型。
- 微调方法：设定 LoRA、Full Fine-tuning 等策略。
- 数据集配置：加载已注册的本地或在线数据集。
- 超参数调整：设置学习率、Batch Size、Epochs 等关键参数。
- 输出管理：定义模型保存目录及日志路径。
配置完成后点击启动按钮即可开始训练。训练结束后，可在评估预测界面查看效果，或在对话界面测试模型响应。若对结果满意，可直接在导出界面合并模型并量化。
SFT 命令行训练
对于需要更精细控制的场景，推荐使用命令行配合 YAML 配置文件。以 LoRA 微调为例：
llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml
也可动态覆盖配置项：
llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml learning_rate=1e-5 logging_steps=1
核心配置参数说明：
| 参数 | 说明 |
|---|---|
model_name_or_path | 模型名称或路径 |
stage | 训练阶段 (pt/sft/rm/dpo/kto/orpo) |
finetuning_type | 微调方式 (freeze/lora/full) |
lora_target | LoRA 目标模块，默认 all |
dataset | 数据集名称，逗号分隔多个 |
template | 模型模板，需与模型匹配 |
learning_rate | 学习率 |
num_train_epochs | 训练轮数 |
bf16 | 是否启用 bf16 混合精度 |
LoRA 合并与量化
训练完成后，LoRA 适配器通常独立于基座模型存在。为了便于部署，可将两者合并为一个完整模型。合并时需指定基座模型路径、适配器路径及导出目录：
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
export_dir: models/merged_model
export_device: cpu
合并后的模型可根据需求进行量化压缩，以减少显存占用并提升推理速度。LLaMA-Factory 支持 GPTQ、AWQ、QLoRA 等多种量化方案。例如使用 GPTQ 量化至 4-bit：
export_quantization_bit: 4
export_quantization_dataset: data/c4_demo.json
注意：合并过程建议使用未量化的基座模型，避免精度损失累积。量化时务必提供校准数据集以保证效果。
推理与评估
推理配置
支持 Huggingface 和 vLLM 两种推理后端。原始模型推理只需指定模型路径和模板；微调模型推理则需额外传入适配器路径及微调类型。
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
finetuning_type: lora
infer_backend: vllm
批量推理可通过脚本调用 API 接口实现，适合大规模评测场景。
模型评估
训练完成后，可使用内置评估工具测试通用能力（如 MMLU、C-Eval）或生成质量（BLEU、ROUGE）。
通用能力评估示例：
llamafactory-cli eval examples/train_lora/llama3_lora_eval.yaml
NLG 评估示例：
llamafactory-cli train examples/extras/nlg_eval/llama3_lora_predict.yaml
评估参数包括任务类型、语言、Few-shot 数量及批次大小等，可根据实际需求灵活调整。
