LLaMA-Factory 实战指南：从环境搭建到模型微调与评测

ModelScope 下载（适合中国大陆网络环境）：

git clone https://www.modelscope.cn/LLM-Research/Meta-Llama-3-8B-Instruct.git

或者使用 Python 脚本下载：

from modelscope import snapshot_download
model_dir = snapshot_download('LLM-Research/Meta-Llama-3-8B-Instruct')

由于网络原因，下载后可能存在文件不完整的情况。建议先检查文件大小和数量是否与原始页面一致，再跑一下官方提供的推理 Demo 验证模型文件和 Transformers 库的可用性。

import transformers
import torch

# 切换为你下载的模型文件目录
model_id = "/path/to/Meta-Llama-3-8B-Instruct"

pipeline = transformers.pipeline(
    "text-generation",
    model=model_id,
    model_kwargs={"torch_dtype": torch.bfloat16},
    device_map="auto",
)

messages = [
    {"role": "system", "content": "You are a pirate chatbot who always responds in pirate speak!"},
    {"role": "user", "content": "Who are you?"}
]

prompt = pipeline.tokenizer.apply_chat_template(
    messages, tokenize=False, add_generation_prompt=True
)

terminators = [
    pipeline.tokenizer.eos_token_id,
    pipeline.tokenizer.convert_tokens_to_ids("<|eot_id|>")
]

outputs = pipeline(
    prompt,
    max_new_tokens=256,
    eos_token_id=terminators,
    do_sample=True,
    temperature=0.6,
    top_p=0.9,
)

print(outputs[0]["generated_text"][len(prompt):])

3.4 数据集部分放到后面一起说明

4. 原始模型直接推理

在进行后续环节之前，我们先使用推理模式验证 LLaMA-Factory 的推理部分是否正常。LLaMA-Factory 内置了基于 Gradio 开发的 ChatBot 推理页面，可用于模型效果的人工测试。

在 LLaMA-Factory 目录下执行以下命令：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
  --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
  --template llama3

CUDA_VISIBLE_DEVICES=0 指定程序使用第 0 张卡，这是全局变量设置，也可以不使用。需要注意的是，所有程序的入口都是 llamafactory-cli，通过不同参数控制功能。例如 webchat 表示前端版本纯推理的 Chat 页面。

关键参数解释如下：

你也可以将参数提前存在 YAML 文件中管理，例如 examples/inference/llama3.yaml：

model_name_or_path: /path/to/Meta-Llama-3-8B-Instruct
template: llama3

启动命令变为：

llamafactory-cli webchat examples/inference/llama3.yaml

效果如图，可通过 http://localhost:7860/ 访问。如果是云端用户，可能无法直接通过本地笔记本访问，需要联系云厂商配置域名和端口映射，例如阿里云用户可能需要配置环境变量：

export GRADIO_ROOT_PATH=/${JUPYTER_NAME}/proxy/7860/

5. 自定义数据集构建

数据集格式在不同阶段有所不同。本教程以 SFT 阶段为例，结合系统自带的 identity 数据集和自定义的商品文案生成数据集，介绍数据集的使用。更多详情可参考 data/README_zh.md。

目前支持 Alpaca 和 ShareGPT 两种数据格式。以 Alpaca 为例，整个数据集是一个 JSON 对象的列表：

[
  {
    "instruction": "用户指令（必填）",
    "input": "用户输入（选填）",
    "output": "模型回答（必填）",
    "system": "系统提示词（选填）",
    "history": [["第一轮指令", "第一轮回答"]]
  }
]

单轮示例（alpaca_data_zh_51k.json）：

{
  "instruction": "写一个有效的比较语句",
  "input": "篮球和足球",
  "output": "篮球和足球都是受欢迎的运动。"
}

多轮示例（oaast_sft_zh.json）：

{
  "instruction": "谢谢",
  "input": "",
  "output": "不用谢！很高兴我提供的信息能够帮助到你！",
  "history": [
    [
      "请你给我写一个面试准备计划...",
      "首先，你可以去微软官网寻找招聘信息..."
    ]
  ]
}

我们需要将训练数据转换成这种格式，并在 data/dataset_info.json 中注册。如果不做字段名称转换，则需要在注册时在 columns 字段中做映射配置。

下面用两个具体例子说明：

1. 系统自带 identity.json 数据集：已默认注册为 identity。我们可以通过文本编辑器替换其中的 NAME 和 AUTHOR 字段。

   • 替换前：I am NAME, an AI assistant developed by AUTHOR.
   • 替换后：I am PonyBot, an AI assistant developed by LLaMA Factory.

2. 商品文案生成数据集：假设原始格式为 content 和 summary。要将其放入系统使用，需执行两步操作：

   • 复制数据集到 data 目录下。
   • 修改 data/dataset_info.json 新增内容完成注册，定义数据集名称、文件位置及输入输出映射关系。

6. 基于 LoRA 的 SFT 指令微调

准备好数据集后，即可开始训练。我们的目标是让 LLaMA3 模型学会定义的'你是谁'以及商品文案的生成逻辑。这里先用命令行版本，更容易理解原理。

本脚本参数改编自官方示例：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
  --stage sft \
  --do_train \
  --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
  --dataset alpaca_gpt4_zh,identity,adgen_local \
  --dataset_dir ./data \
  --template llama3 \
  --finetuning_type lora \
  --lora_target q_proj,v_proj \
  --output_dir ./saves/LLaMA3-8B/lora/sft \
  --overwrite_cache \
  --overwrite_output_dir \
  --cutoff_len 1024 \
  --preprocessing_num_workers 16 \
  --per_device_train_batch_size 2 \
  --per_device_eval_batch_size 1 \
  --gradient_accumulation_steps 8 \
  --lr_scheduler_type cosine \
  --logging_steps 50 \
  --warmup_steps 20 \
  --save_steps 100 \
  --eval_steps 50 \
  --evaluation_strategy steps \
  --load_best_model_at_end \
  --learning_rate 5e-5 \
  --num_train_epochs 5.0 \
  --max_samples 1000 \
  --val_size 0.1 \
  --plot_loss \
  --fp16

关键参数解释：

注意：精度相关参数还有 bf16 和 pure_bf16，但老显卡（如 V100）可能不支持 bf16，会导致报错。

训练过程中，系统会按 logging_steps 定时输出日志，包含当前 loss 和进度。训练完成后，在 output_dir 下会看到 adapter 开头的 LoRA 结果、training_loss 记录及其他参数备份。正常情况下，loss 会随着训练时间慢慢变小，最终下降到 1 以下会有较好效果。

7. 动态合并 LoRA 的推理

LoRA 训练结束后，如果想动态验证效果，可以在网页端与新模型对话。与原始模型推理相比，区别在于通过 finetuning_type 参数告知系统使用了 LoRA，并通过 adapter_name_or_path 指定 LoRA 模型位置。

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
  --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
  --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
  --template llama3 \
  --finetuning_type lora

此时模型已学习新数据知识。如果不加 LoRA 参数重启测试，模型仍会按通用方式回答。

不方便使用 WebUI 时，也可用命令行交互：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli chat \
  --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
  --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
  --template llama3 \
  --finetuning_type lora

8. 批量预测和训练效果评估

人工交互偏感性，批量预测可使用自动化的 BLEU 和 ROUGE 等指标评估。请先安装相关库：

pip install jieba rouge-chinese nltk

本脚本参数改编自官方预测示例：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli train \
  --stage sft \
  --do_predict \
  --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
  --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
  --dataset alpaca_gpt4_zh,identity,adgen_local \
  --dataset_dir ./data \
  --template llama3 \
  --finetuning_type lora \
  --output_dir ./saves/LLaMA3-8B/lora/predict \
  --overwrite_cache \
  --overwrite_output_dir \
  --cutoff_len 1024 \
  --preprocessing_num_workers 16 \
  --per_device_eval_batch_size 1 \
  --max_samples 20 \
  --predict_with_generate

主要区别在于 do_predict（预测模式）和 predict_with_generate（生成文本）。输出结果中，generated_predictions.jsonl 包含原始 Label 和模型预测结果，predict_results.json 则给出自动计算的指标。

常用指标含义：

9. LoRA 模型合并导出

若要将训练的 LoRA 与原始大模型融合，输出完整模型文件，可使用以下命令。合并后的模型可像原始模型一样应用，也可递归用于训练。

CUDA_VISIBLE_DEVICES=0 llamafactory-cli export \
  --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
  --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
  --template llama3 \
  --finetuning_type lora \
  --export_dir merged-model-path \
  --export_size 2 \
  --export_device cpu \
  --export_legacy_format False

10. 一站式 WebUI Board 的使用

除了命令行，LLaMA-Factory 还支持模型训练全链路的一站式 WebUI Board。它将主要链路和操作整合在一个页面中，参数可可视化编辑。

启动命令：

llamafactory-cli webui

*注意：目前 WebUI 版本只支持单机单卡，多卡请使用命令行版本。

WebUI 通过不同 Tab 整合了多个功能模块。在 Train 页面配置好参数后，可通过预览命令功能导出训练脚本，支持多 GPU 训练。点击开始按钮，网页端和服务器端会同步输出日志。训练完毕后，点击'刷新适配器'即可找到历史训练的 LoRA 模型文件，后续训练或聊天时会自动加载。

11. API Server 的启动与调用

训练好后，可将模型能力封装为网络接口，接入 LangChain 或其他业务。API 实现参考 OpenAI 协议，基于 Uvicorn 开发。

启动命令：

CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \
  --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
  --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \
  --template llama3 \
  --finetuning_type lora

项目也支持基于 vLLM 的推理后端，但需提前将 LoRA 模型 Merge。服务启动后，按 OpenAI API 格式远程访问，只需替换 base_url 指向部署机器 URL 和端口。

12. 进阶 - 大模型主流评测 Benchmark

对于更高要求的场景，如刷榜单或评估微调后通用知识的泛化能力，可使用本项目提供的 MMLU、CMMLU、Ceval 等自动评测脚本。

Chat 版本模型评测：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli eval \
  --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \
  --template llama3 \
  --task mmlu \
  --split validation \
  --lang en \
  --n_shot 5 \
  --batch_size 1

Base 版本模型，template 改为 fewshot 即可。输出结果包含各项任务的指标，具体定义可参考任务原始资料。