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

• 测试

# 确认安装正常
llamafactory-cli train -h
# 确认 GPU 和 CUDA 环境正常
python
import torch
torch.cuda.current_device()
torch.cuda.get_device_name(0)
torch.__version__

• 测试推理

pip install modelscope
modelscope download --model LLM-Research/Meta-Llama-3-8B-Instruct --local_dir /workspace/Meta-Llama-3-8B-Instruct
pip install -U bitsandbytes -i https://pypi.tuna.tsinghua.edu.cn/simple
vim test-inf.py

import torch
import warnings
from transformers import AutoTokenizer, AutoModelForCausalLM, BitsAndBytesConfig

warnings.filterwarnings('ignore', category=UserWarning, module='torch.cuda')
torch.cuda.set_device(0)
device = "cuda:0" if torch.cuda.is_available() else "cpu"

bnb_config = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16, bnb_4bit_use_double_quant=True, bnb_4bit_quant_type="nf4")

model_id = "/workspace/Meta-Llama-3-8B-Instruct"
tokenizer = AutoTokenizer.from_pretrained(model_id)
tokenizer.pad_token = tokenizer.eos_token

model = AutoModelForCausalLM.from_pretrained(
    model_id, quantization_config=bnb_config, torch_dtype=torch.bfloat16,
    device_map=device, trust_remote_code=True, low_cpu_mem_usage=True
)

assert next(model.parameters()).device == torch.device(device), "模型加载失败！未使用 GPU！"
print(f"✅ 模型已 100% 加载到 GPU → {torch.cuda.get_device_name(0)}")
print(f"✅ PyTorch 版本：{torch.__version__} | CUDA 版本：{torch.version.cuda}")
print(f"✅ 运行模式：4bit 无损量化 | 显存占用≈8.5GB (减半)")

messages = [{"role": "system", "content": "You are a pirate chatbot who always responds in pirate speak!"}, {"role": "user", "content": "Who are you?"}]
prompt = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
inputs = tokenizer(prompt, return_tensors="pt").to(device)
terminators = [tokenizer.eos_token_id, tokenizer.convert_tokens_to_ids("<|eot_id|")]
outputs = model.generate(**inputs, max_new_tokens=256, eos_token_id=terminators, do_sample=True, temperature=0.6, top_p=0.9, pad_token_id=tokenizer.eos_token_id)
response = tokenizer.decode(outputs[0][len(inputs["input_ids"][0]):], skip_special_tokens=True)
print("===== 🏴‍☠️ 海盗机器人回答 🏴‍☠️ =====")
print(response)

• 测试 WebUI

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

model_name_or_path：HuggingFace 或 ModelScope 的模型名称，如 meta-llama/Meta-Llama-3-8B-Instruct；或者是本地下载的绝对路径。

template：模型问答时所使用的 prompt 模板，不同模型使用各自的模版，否则会出现回答结果重复生成等奇怪现象。比如 Meta-Llama-3-8B 的 template 就是 llama3。

准备数据集

打开 WebUI：

cd LlamaFactory/
export USE_MODELSCOPE_HUB=1
llamafactory-cli webui

魔搭社区集成了相当丰富的中文数据集，有很多分类可以选。

找一个角色扮演的数据集来微调（方便查看效果）。

注意，Llama-Factory 目前只支持两种格式的数据集：Alpaca 和 ShareGPT 格式。

切换到数据集文件这边，打开 huanhuan.json 文件，看到它其实就是 Alpaca 格式的数据集，仅下载这一个文件即可。

在 Llama-Factory 添加数据集，不仅要把数据文件放到 data 目录下，还需要在配置文件 dataset_info.json 里面添加一条该数据集的记录。这样，新添加的数据集才能被 Llama-Factory 识别到。

这里保存之后，WebUI 那边会实时更新，不需要重启。

执行微调

微调 Qwen3-1.7B-Base 基础大模型，方法选用 LoRA。

• Base 基础预训练模型。

• 没有经过指令微调。

• 适合继续预训练或指令微调。

• Base 通常情况下输出质量不如 Instruct 版本。

• 使用 huanhuan 数据集。

• 先训练 1 轮看看效果，如果效果不理想再多训练几轮。如果 SFT 样本较少，可以设置较大 Epoch。较小 Epoch 的 loss 会不收敛，较大 Epoch 会容易导致过拟合，但过拟合要优于欠拟合。如果 SFT 样本数量较多，如在十万以上，一般 2 个 Epoch 即可收敛。

• 学习率控制模型权重更新步幅的参数，按照经验来讲，LoRA 选择在 1e-5 ~ 2e-5。

• 由于数据集都是一些短问答，可以把截断长度设置小一点，为 1024（默认是 2048）。

• 梯度累计设置为 4。

计算类型选择 BF16，暂不支持 FP4。

预热步数是学习率预热采用的步数，通常设置范围在 2-8 之间，这里配置为 4。

继续设置 LoRA 微调参数：

• LoRA 秩：可以看作学习的广度，越大学习的东西越多，微调之后的效果可能会越好，但是也不是越大越好。太大的话容易造成过拟合（书呆子，照本宣科，不知变通），这里设置为 8。
• LoRA 缩放系数：可以看作学习强度，越大效果可能会越好，对于一些用于复杂场景的数据集可以设置更大一些，简单场景的数据集可以稍微小一点。这里设置 256。

预览训练指令并开始训练。

llamafactory-cli train \
    --stage sft \
    --do_train True \
    --model_name_or_path Qwen/Qwen3-1.7B-Base \
    --preprocessing_num_workers 16 \
    --finetuning_type lora \
    --template qwen3 \
    --flash_attn auto \
    --dataset_dir data \
    --dataset huanhuan \
    --cutoff_len 1024 \
    --learning_rate 5e-05 \
    --num_train_epochs 4.0 \
    --max_samples 100000 \
    --per_device_train_batch_size 2 \
    --gradient_accumulation_steps 4 \
    --lr_scheduler_type cosine \
    --max_grad_norm 1.0 \
    --logging_steps 5 \
    --save_steps 100 \
    --warmup_steps 4 \
    --packing False \
    --enable_thinking True \
    --report_to none \
    --output_dir saves/Qwen3-1.7B-Base/lora/train_2026-01-02-06-40-31 \
    --bf16 True \
    --plot_loss True \
    --trust_remote_code True \
    --ddp_timeout 180000000 \
    --include_num_input_tokens_seen True \
    --optim adamw_torch \
    --adapter_name_or_path saves/Qwen3-1.7B-Base/lora/train_2026-01-02-06-01-20 \
    --lora_rank 8 \
    --lora_alpha 256 \
    --lora_dropout 0 \
    --lora_target all

• stage：指示当前训练的阶段，枚举值 sft、pt、rm、ppo 等，这里我们是有监督指令微调，所以是 sft。
• do_train：是否是训练模式。
• dataset：使用的数据集。
• dataset_dir：数据集所在目录，这里是 data。
• finetuning_type：微调训练的类型，枚举值 lora、full、freeze 等，这里使用 lora。
• output_dir：训练 Checkpoint 保存的位置。
• cutoff_len：训练数据集的长度截断。
• per_device_train_batch_size：每个设备上的 batch size，最小是 1，如果 GPU 显存够大，可以适当增加。
• bf16：训练数据精度格式。
• max_samples：每个数据集采样多少数据。
• val_size：随机从数据集中抽取多少比例的数据作为验证集。
• logging_steps：定时输出训练日志，包含当前 loss，训练进度等。
• adapter_name_or_path：LoRA 适配器路径。

开始之后，会启动一个新的训练进程。

如果本地没有找到模型，会先自动下载模型。

开始训练后可以查看进度条和损失值曲线。

看到类似下面'训练完毕'就代表微调成功。

微调成功后，我们得到了一个 Checkpoint 记录，下拉可以选择刚刚微调好的模型。

Checkpoint 在后台的存储位置是 saves/Qwen3-1.7B-Base/lora/：

• adapter 开头的是 LoRA 适配器结果，后续用于模型推理融合。
• training_loss 和 trainer_log 等记录了训练过程中的指标。
• 其他是训练时各种参数的备份。

把窗口切换到 Chat，可以点击加载模型。

加载好之后就可以在输入框发送问题，测试微调模型的效果。

对 LoRA 微调模型进行推理，需要应用动态合并 LoRA 适配器的推理技术。需要通过 finetuning_type 参数告诉使用了 LoRA 训练，然后将 LoRA 的模型位置通过 adapter_name_or_path 参数即可。

但是渲染只训练了一次的效果很差。

如果想切换回微调之前的模型，只需先卸载模型，选择想要的 Checkpoint，然后再加载模型即可。

如果想重新微调，需要修改红框中的两个值。

在经过 3 个 Epoch 的训练之后，效果也越好越好了。

批量推理和训练效果评估

上文中的人工交互测试实际上并不严谨，通常我们需要进行自动化的批量测试。例如：使用自动化的 BLEU 和 ROUGE 等常用的文本生成指标来做评估。

pip install jieba
pip install rouge-chinese
pip install nltk

与训练脚本主要的参数区别如下 3 个：

• do_predict：现在是预测模式。
• predict_with_generate：现在用于生成文本。
• max_samples：每个数据集采样多少用于预测对比。

llamafactory-cli train \
    --stage sft \
    --model_name_or_path Qwen/Qwen3-1.7B-Base \
    --preprocessing_num_workers 16 \
    --finetuning_type lora \
    --quantization_method bnb \
    --template qwen3 \
    --flash_attn auto \
    --dataset_dir data \
    --eval_dataset huanhuan \
    --cutoff_len 1024 \
    --max_samples 100000 \
    --per_device_eval_batch_size 4 \
    --predict_with_generate True \
    --report_to none \
    --max_new_tokens 512 \
    --top_p 0.7 \
    --temperature 0.95 \
    --output_dir saves/Qwen3-1.7B-Base/lora/eval_2026-01-02-19-59-30 \
    --trust_remote_code True \
    --ddp_timeout 180000000 \
    --do_predict True \
    --adapter_name_or_path saves/Qwen3-1.7B-Base/lora/train_2026-01-02-06-40-31

完成后查看微调质量评估结果，下面是训练效果评估指标。

质量类指标：BLEU-4 + ROUGE-1/2/L，衡量模型生成文本的好坏、和标准答案的匹配度、内容质量优劣。

• BLEU-4（Bilingual Evaluation Understudy）：是一种常用的用于评估机器翻译质量的指标。BLEU-4 表示四元语法 BLEU 分数，它衡量模型生成文本与参考文本之间的 n-gram 匹配程度，其中 n=4。值越高表示生成的文本与参考文本越相似，最大值为 100%。
• predict_rouge-1（Recall-Oriented Understudy for Gisting Evaluation）：是一种用于评估自动摘要和文本生成模型性能的指标。ROUGE-1 表示一元 ROUGE 分数，衡量模型生成文本与参考文本之间的单个词序列的匹配程度，即：词汇层面的匹配度，看生成文本有没有用到标准答案里的核心词。值越高表示生成的文本与参考文本越相似，最大值为 100。
• predict_rouge-2：ROUGE-2 表示二元 ROUGE 分数，衡量模型生成文本与参考文本之间的双词序列的匹配程度，即：短语 / 短句层面的匹配度。同上，最大值为 100。
• predict_rouge-l：ROUGE-L 表示最长公共子序列匹配率，衡量模型生成文本与参考文本之间最长公共子序列（Longest Common Subsequence）的匹配程度，即：整句的语义连贯性和语序一致性。同上，最大值为 100。

如果是文本摘要任务，那么 rouge-1 一般 20-40，rouge-2 5-15，rouge-L 10-25；如果是开放问答 / 对话 / 指令遵循任务，那么 rouge-1 8-15，rouge-2 1-3，rouge-L 3-6。

性能类指标：耗时 / 吞吐量 / 加载时间，衡量模型推理速度、效率、硬件利用率。

• predict_model_preparation_time：表示模型加载和预热（显存初始化）的耗时。
• predict_runtime：本次批量推理的总耗时，单位为秒。
• predict_samples_per_second：每秒推理生成的样本数量，推理吞吐量核心指标的核心指标，表示模型每秒钟能够生成的样本数量。用于评估模型的推理速度。
• predict_steps_per_second：每秒执行的 step 数量，模型每秒钟能够执行的 step 数量。模型每生成一个 token 就是一个 step。

通过对比 1 Epoch 和 3 Epoch 微调的结果可以看出，多轮训练后的效果会更好一些。

训练后也会在 output_dir 下看到如下新文件：

• generated_predictions.jsonl：输出了要预测的数据集的原始 label 和模型 predict 的结果。
• predict_results.json：给出了原始 label 和模型 predict 的结果，用自动计算的指标数据。

LoRA 模型合并导出

通过不断'炼丹'直到效果满意后就可以导出模型了。即：把训练的 LoRA 模型和原始 Base 模型进行融合，输出一个完整的模型文件。

检查点路径选择我们刚刚微调好的模型，切换到 Export，填写导出目录 output/qwen3-1.7b-huanhuan。

导出完成之后就可以在 output 目录下看到 qwen3-1.7b-huanhuan 目录了。

部署运行微调后的大模型

这里用 Ollama + GGUF 进行部署。

其中，GGUF 是大模型的存储格式，可以对模型进行高效的压缩，减少模型的大小与内存占用，从而提升模型的推理速度和效率。

git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp/gguf-py
pip install --editable .
cd llama.cpp
python convert_hf_to_gguf.py /workspace/LlamaFactory/output/Qwen3-1.7B-huanhuan/
# 生成 xxx.gguf 格式文件。

另外，Ollama 是大模型推理框架，适用于个人环境使用，简单而高效。

curl -fsSL https://ollama.com/install.sh | sh
ollama serve
ollama create qwen3-huanhuan -f /workspace/LlamaFactory/output/Qwen3-1.7B-huanhuan/Modelfile
ollama run qwen3-huanhuan