LLaMA Factory 从安装到推理的完整记录

训练时直接用本地路径就行，比如从魔搭社区拉一个 Qwen 模型：

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

Windows 上的坑

如果在 Windows 上用 QLoRA，需要单独装 bitsandbytes：

pip install https://github.com/jllllll/bitsandbytes-windows-webui/releases/download/wheels/bitsandbytes-0.41.2.post2-py3-none-win_amd64.whl

FlashAttention-2 同理，去 这里 找对应版本。

数据该怎么准备

LLaMA Factory 支持多种数据集格式，所有定义都在 data/dataset_info.json 里。你要用它训练自己的数据，就得先在这个文件里注册一下。

指令监督微调（SFT）

最常用的格式是 alpaca，包含 instruction、input、output 三个字段，还可以带 history 和 system。例如：

[
  {
    "instruction": "计算这些物品的总费用。",
    "input": "汽车 - $3000，衣服 - $100，书 - $20。",
    "output": "总费用为 $3000 + $100 + $20 = $3120。"
  }
]

多轮对话加上 history：

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

在 dataset_info.json 里这样描述：

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

预训练

纯文本，一行一个 text 字段：

[
  {"text": "document1"},
  {"text": "document2"}
]

偏好数据集

用于 DPO/ORPO 训练，需要 chosen 和 rejected：

[
  {
    "instruction": "...",
    "input": "...",
    "chosen": "优质回答",
    "rejected": "劣质回答"
  }
]

KTO 数据集

加一个 kto_tag 字段，true/false 表示反馈好坏：

[
  {
    "instruction": "...",
    "input": "...",
    "output": "...",
    "kto_tag": "true"
  }
]

多模态数据

图像数据集，images 字段里写路径，注意和文本中 <image> 数量一致：

[
  {
    "instruction": "描述这张图片",
    "output": "...",
    "images": ["path/to/img.jpg"]
  }
]

视频和音频也类似，用 videos 和 audios 字段。

用 YAML 启动训练

SFT 训练既可以用 WebUI，也可以直接用命令行。我自己更习惯 YAML 配置，调参方便。

一个典型的 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
overwrite_output_dir: 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
ddp_timeout: 180000000
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500

然后运行：

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 训练完会生成一个适配器权重，每次推理都要同时加载基座和适配器，很麻烦。可以把它俩合并成一个完整模型。

合并配置 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

执行合并：

llamafactory-cli export merge_config.yaml

一个容易踩的坑：合并时不要用量化模型或指定量化位数，否则会报错。 一定要用原始的未量化基座。

合并后如果想进一步压缩，可以用 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

量化需要提供校准数据集，位数越高保存的质量越好，但体积也越大。4-bit 是常见的折中选择。

如果用的 QLoRA 训练，导出时不需要再量化，直接用合并方式导出即可。

推理几种方式

推理分为交互式对话和批量处理，底层可以选 Huggingface 或 vLLM 引擎。

原始模型推理

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

启动命令：

llamafactory-cli chat inference_config.yaml
# 或 Web 聊天
llamafactory-cli webchat inference_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
infer_backend: huggingface

多模态模型

例如 llava：

llamafactory-cli webchat examples/inference/llava1_5.yaml

批量推理

用 vLLM 引擎处理整个数据集：

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

还可以启动 API 服务：

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

调用示例：

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)

评估模型效果

训练完了总得看看效果。LLaMA Factory 内置了 MMLU、C-Eval 等评测。

llamafactory-cli eval examples/train_lora/llama3_lora_eval.yaml

配置示例：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
finetuning_type: lora
task: mmlu_test
template: fewshot
lang: en
n_shot: 5
save_dir: saves/llama3-8b/lora/eval
batch_size: 4

还可以评估 NLG 指标（BLEU、ROUGE），配置：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
stage: sft
do_predict: true
finetuning_type: lora
eval_dataset: identity,alpaca_en_demo
template: llama3
cutoff_len: 2048
max_samples: 50
overwrite_cache: true
preprocessing_num_workers: 16
output_dir: saves/llama3-8b/lora/predict
overwrite_output_dir: true
per_device_eval_batch_size: 1
predict_with_generate: true
ddp_timeout: 180000000

运行后会在输出目录生成预测结果和分数。

评估常用参数：

整个流程走下来，LLaMA Factory 确实能省很多事，尤其是 WebUI 对新手很友好。不过命令行 YAML 更可控，适合批量实验。建议先从 WebUI 上手，再切到命令行。