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

测试验证

确认安装正常及 GPU 环境：

# 确认安装正常
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)}")

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)

运行结果应显示模型成功加载至 GPU 且显存占用合理。

WebUI 测试

启动 Web 界面进行交互：

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 的模型名称，也可以是本地绝对路径。template 参数至关重要，不同模型需使用各自的 Prompt 模板（如 Meta-Llama-3-8B 对应 llama3），否则会导致回答重复或格式错误。

准备数据集

打开 WebUI 后，在数据管理模块添加数据集。魔搭社区（ModelScope）集成了丰富的中文数据集，可按分类筛选。

LLaMA-Factory 目前主要支持两种格式的数据集：Alpaca 和 ShareGpt。确保你的数据文件符合这两种结构之一。例如，将下载的 huanhuan.json 放入 data 目录下，并在配置文件 dataset_info.json 中添加一条记录，这样 WebUI 才能识别新数据集。

保存配置后，WebUI 通常会自动刷新，无需重启服务。

执行微调

我们以 Qwen3-1.7B-Base 基础模型为例，采用 LoRA 方法进行指令监督微调（SFT）。

Base 模型特点：

• 未经过指令微调。
• 适合继续预训练或指令微调。
• 输出质量通常不如 Instruct 版本，但灵活性更高。

关键参数设置建议：

• Epochs：先训练 1 轮观察效果。若 SFT 样本较少，可设置较大 Epoch；若样本量在十万以上，一般 2 个 Epoch 即可收敛。需注意过拟合风险。
• Learning Rate：LoRA 经验值通常在 1e-5 ~ 2e-5 之间。
• Cutoff Len：短问答数据集可将截断长度设为 1024（默认 2048）。
• Gradient Accumulation：设置为 4 以平衡显存与 Batch Size。
• Compute Type：选择 BF16，暂不支持 FP4。
• Warmup Steps：学习率预热步数，通常 2-8 之间，这里设为 4。
• LoRA Rank：代表学习广度，设为 8 较为稳妥，过大易过拟合。
• LoRA Alpha：缩放系数，设为 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（有监督指令微调）。
• finetuning_type：微调类型，此处为 lora。
• output_dir：Checkpoint 保存位置。
• adapter_name_or_path：LoRA 适配器路径。

训练过程中会启动新进程，若本地无模型则自动从 ModelScope 下载。可通过日志查看 Loss 曲线和进度条。训练完成后，Checkpoints 位于 saves/Qwen3-1.7B-Base/lora/ 目录下，包含 adapter_model.safetensors 等文件。

在 WebUI 的 Chat 页面加载微调后的 Checkpoint 进行测试。注意，LoRA 推理需要指定 --finetuning_type lora 和 --adapter_name_or_path 路径。若效果不佳，可增加 Epoch 重新训练。

批量推理和训练效果评估

人工交互测试不够严谨，建议使用自动化指标进行评估，如 BLEU 和 ROUGE。

安装评估工具：

pip install jieba rouge-chinese nltk

预测命令：

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：分别衡量一元、二元词序列及最长公共子序列的匹配度。对于开放问答任务，ROUGE-1 通常在 8-15 区间属于标准水平。
• 性能指标：包括模型加载耗时、总推理耗时及吞吐量（samples/s）。

对比不同 Epoch 的训练结果，通常多轮训练后效果更优。评估结果会保存在 output_dir 下的 generated_predictions.jsonl 和 predict_results.json 中。

LoRA 模型合并导出

当训练效果满意后，可将 LoRA 权重与原始 Base 模型融合，导出完整模型文件。

在 WebUI 切换到 Export 页面，选择微调好的 Checkpoint，填写导出目录（如 output/qwen3-1.7b-huanhuan）。导出完成后，该目录下将包含完整的 model.safetensors 及其他配置文件。

部署运行微调后的大模型

最后一步是本地部署。推荐使用 Ollama 配合 GGUF 格式，便于高效压缩和推理。

转换格式：

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp/gguf-py
pip install --editable .
cd ../.. 
python convert_hf_to_gguf.py /workspace/LlamaFactory/output/Qwen3-1.7B-huanhuan/

这将生成 .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

至此，微调完成的大模型即可在本地环境中流畅运行。