LLaMA-Factory 大模型微调实战指南

如果遇到环境冲突，可尝试使用 pip install --no-deps -e . 跳过依赖检查。安装成功后，可通过以下命令校验：

llamafactory-cli version

启动 WebUI 界面：

CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=1 GRADIO_SERVER_PORT=7860 llamafactory-cli webui

3. 模型下载

训练前需要准备模型文件。可以从魔搭社区或其他源下载，例如：

git clone https://www.modelscope.cn/Qwen/Qwen2.5-0.5B-Instruct.git

将下载的模型路径填入后续配置中即可。

4. Windows 特殊配置

若需在 Windows 上启用量化 LoRA（QLoRA），请根据 CUDA 版本选择对应的 bitsandbytes 发行版进行安装。FlashAttention-2 在 Windows 上的支持也需匹配特定版本。

如需更多功能，可安装额外依赖，例如 DeepSpeed 用于分布式训练，BitsAndBytes 用于量化，VLLM 用于高速推理等。

三、数据微调

数据集定义位于 dataset_info.json 文件中。目前支持 Alpaca 格式和 ShareGPT 格式。自定义数据集时，务必在此文件中添加相应定义。

1. 指令监督微调数据集

这是最常见的微调类型。通过让模型学习指令和回答来优化表现。instruction 列对应人类指令，input 列对应人类输入，output 列对应模型回答。实际输入拼接为 instruction\ninput。

可选字段包括 system（系统提示词）和 history（历史对话记录）。多轮对话示例如下：

[
  {
    "instruction": "今天的天气怎么样？",
    "input": "",
    "output": "今天的天气不错，是晴天。",
    "history": [
      ["今天会下雨吗？", "今天不会下雨，是个好天气。"],
      ["今天适合出去玩吗？", "非常适合，空气质量很好。"]
    ]
  }
]

在 dataset_info.json 中描述该数据集：

"数据集名称": {
  "file_name": "data.json",
  "columns": {
    "prompt": "instruction",
    "query": "input",
    "response": "output",
    "system": "system",
    "history": "history"
  }
}

2. 预训练与偏好数据集

预训练数据集通常只包含文本内容，格式为 [ {"text": "document"} ]。

偏好数据集用于奖励模型、DPO 或 ORPO 训练，需提供更优回答 (chosen) 和更差回答 (rejected)。

KTO 数据集则只需一个 true/false 标签 (kto_tag) 表示人类反馈。

3. 多模态数据集

支持图像、视频和音频输入。需额外添加 images、videos 或 audios 列，并确保媒体数量与文本中的标记数量严格一致。

四、WebUI 操作

LLaMA-Factory 提供零代码微调界面。启动后需指定模型路径、训练阶段、微调方法、数据集、学习率、训练轮数等参数。

训练完成后，可在评估预测界面指定模型及适配器路径进行效果评估，或在对话界面直接测试生成效果。若对结果满意，可在导出界面配置分块大小、量化等级等参数导出模型。

五、SFT 训练

除了 WebUI，命令行方式更适合自动化流程。参考 examples/train_lora/llama3_lora_sft.yaml 配置文件：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
dataset: identity,alpaca_en_demo
template: llama3
cutoff_len: 1024
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16
output_dir: saves/llama3-8b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1.0e-4
num_train_epochs: 3.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500

重要参数说明：

• stage: 训练阶段，如 sft (监督微调), pt (预训练), rm (奖励建模)。
• finetuning_type: 微调方式，如 freeze, lora, full。
• lora_target: LoRA 目标模块，默认 all。
• bf16: 是否启用 bf16 混合精度。

执行命令：

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

六、LoRA 合并与量化

1. 模型合并

训练好的 LoRA 适配器需要与基座模型合并，以便推理时加载单一模型。使用 merge_config.yaml 配置合并参数：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
template: llama3
finetuning_type: lora
export_dir: models/llama3_lora_sft
export_size: 2
export_device: cpu
export_legacy_format: false

注意：合并时使用未量化的预训练模型，不要指定量化位数。

2. 模型量化

为了优化显存占用和推理速度，可对合并后的模型进行量化。LLaMA-Factory 支持 GPTQ、AWQ、QLoRA 等多种量化方案。

以 GPTQ 为例，配置示例如下：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
template: llama3
export_dir: models/llama3_gptq
export_quantization_bit: 4
export_quantization_dataset: data/c4_demo.json
export_size: 2
export_device: cpu
export_legacy_format: false

这里需要指定校准数据集 (export_quantization_dataset) 以保证量化精度。QLoRA 训练模式则不需要在合并时设置量化位数。

七、推理

LLaMA-Factory 支持多种推理方式。可使用 chat 或 webchat 命令进行对话，指定原始模型路径和模板。对于微调模型，还需指定适配器路径。

1. 配置示例

原始模型推理：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
template: llama3
infer_backend: huggingface

微调模型推理：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
template: llama3
finetuning_type: lora
infer_backend: huggingface

2. 批量推理与 API

如需处理大量数据，可启动 vLLM 推理引擎：

python scripts/vllm_infer.py --model_name_or_path path_to_merged_model --dataset alpaca_en_demo

也可以部署 API 服务，通过 OpenAI 兼容接口调用：

API_PORT=8000 CUDA_VISIBLE_DEVICES=0 llamafactory-cli api examples/inference/llama3_lora_sft.yaml

Python 调用示例：

from openai import OpenAI
client = OpenAI(api_key="0", base_url="http://0.0.0.0:8000/v1")
messages = [{"role": "user", "content": "Who are you?"}]
result = client.chat.completions.create(messages=messages, model="meta-llama/Meta-Llama-3-8B-Instruct")
print(result.choices[0].message)

八、评估

1. 通用能力评估

训练完成后，可使用 MMLU、C-Eval 等基准测试评估模型效果：

llamafactory-cli eval examples/train_lora/llama3_lora_eval.yaml

配置中包含任务名称 (task)、语言 (lang)、Few-shot 数量 (n_shot) 等参数。

2. NLG 评估

通过预测模式获取 BLEU 和 ROUGE 分数，评价生成质量：

llamafactory-cli train examples/extras/nlg_eval/llama3_lora_predict.yaml

关键参数包括 do_predict: true 和 predict_with_generate: true。

3. 常用评估参数

• task: 评估任务，如 mmlu_test, ceval_validation。
• batch_size: 每个 GPU 的批量大小。
• seed: 随机种子。
• lang: 评估语言，en 或 zh。
• save_dir: 保存结果的路径。

以上涵盖了从环境搭建到模型评估的全流程。实际使用中，根据硬件资源和具体需求调整参数，就能快速获得定制化的大模型。