LLaMA-Factory 大模型微调实战：Qwen3 + 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

# ===================== 核心修复：屏蔽警告 + 强制锁定 GPU =====================
warnings.filterwarnings('ignore', category=UserWarning, module='torch.cuda')
torch.cuda.set_device(0)
device = "cuda:0" if torch.cuda.is_available() else "cpu"
# ===============================================================================
# ===================== 4bit 量化配置（补装库后正常生效） =====================
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
    bnb_4bit_quant_type="nf4"
)
# ===============================================================================
# ===================== 加载模型和 Tokenizer =====================
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
)
# ===============================================================================
# 验证 GPU 加载
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("\n===== 🏴‍☠️ 海盗机器人回答 🏴‍☠️ =====")
print(response)

• 测试 WebUI

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webchat \
    --model_name_or_path /workspace/Meta-Llama-3-8B-Instruct \
    --template llama3
# Running on local URL: http://0.0.0.0:7860
telnet localhost 7860

参数说明：

• 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
# Running on local URL: http://0.0.0.0:7860

魔搭社区集成了相当丰富的中文数据集，有很多分类可选。 参考链接：https://www.modelscope.cn/datasets

找一个角色扮演的数据集来微调（方便查看效果）。 参考链接：https://www.modelscope.cn/datasets/kmno4zx/huanhuan-chat

在数据预览这里查看详细数据。

注意，Llama-Factory 目前只支持两种格式的数据集：Alpaca 和 Sharegpt 格式。 参考文档：https://github.com/hiyouga/LlamaFactory/tree/v0.9.1/data

切换到数据集文件这边，打开 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 适配器路径。

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

$ ps -ef
UID PID PPID C STIME TTY TIME CMD
root 437212019:59 pts/1 00:00:56 /usr/bin/python /usr/local/bin/llamafactory-cli webui
root 502437521:38 pts/1 00:00:23 /usr/bin/python /usr/local/bin/llamafactory-cli train saves/Qwen3-1.7B-Base/lora/train_2026-01-02-19-59-30/training_args.yam

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

[INFO|2026-01-02 21:38:43] llamafactory.hparams.parser:465 >> Process rank: 0, world size: 1, device: cuda:0, distributed training: False, compute dtype: torch.bfloat16
Downloading Model from https://www.modelscope.cn to directory: /root/.cache/modelscope/hub/models/Qwen/Qwen3-1.7B-Base

开始训练后可以查看进度条和损失值曲线。 看到类似下面'训练完毕'就代表微调成功。

微调成功后，我们得到了一个 Checkpoint 记录，下拉可以选择刚刚微调好的模型。 Checkpoint 在后台的存储位置是 saves/Qwen3-1.7B-Base/lora/：

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

$ ll saves/Qwen3-1.7B-Base/lora/train_2026-01-02-06-01-20/
total 50012
drwxr-xr-x 17 root root 4096 Jan 222:16 ./
drwxr-xr-x 5 root root 4096 Jan 2240 ../
-rw-r--r-- 1 root root 1518 Jan 222:16 README.md
-rw-r--r-- 1 root root 966 Jan 222:16 adapter_config.json
-rw-r--r-- 1 root root 34916720 Jan 222:16 adapter_model.safetensors
...

把窗口切换到 chat，可以点击加载模型。加载好之后就可以在输入框发送问题，测试微调模型的效果。

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

--finetuning_type lora \
--adapter_name_or_path saves/Qwen3-1.7B-Base/lora/train_2026-01-02-06-01-20 \

如果想切换回微调之前的模型，只需先卸载模型，选择想要的 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%。如下，BLEU-4=0.8539 属于高分，说明模型生成的文本，和标准答案的语义贴合度极高、核心信息无遗漏、表达逻辑一致，对于 8B 量级的开源大模型，这个分数是优秀水平。
• predict_rouge-1（Recall-Oriented Understudy for Gisting Evaluation）：是一种用于评估自动摘要和文本生成模型性能的指标。ROUGE-1 表示一元 ROUGE 分数，衡量模型生成文本与参考文本之间的单个词序列的匹配程度，即：词汇层面的匹配度，看生成文本有没有用到标准答案里的核心词。值越高表示生成的文本与参考文本越相似，最大值为 100。如下，rouge-1=10.37 属于高分，模型能精准捕捉到标准答案里的核心关键词，生成内容不会偏离主题，这是优质模型的核心特征。
• predict_rouge-2：ROUGE-2 表示二元 ROUGE 分数，衡量模型生成文本与参考文本之间的双词序列的匹配程度，即：短语 / 短句层面的匹配度。同上，最大值为 100。如下，rouge-2=1.67 分数偏低，但这是正常现象，ROUGE-2 要求连续两个词和标准答案完全一致，而大模型的优势是语义一致但表达多样化的泛化能力。大模型使用不同的短语表达相同的意思，这是生成能力的体现，不是缺陷。如果 rouge-2 分数很高，反而说明模型在的泛化能力极差。
• predict_rouge-l：ROUGE-L 表示最长公共子序列匹配率，衡量模型生成文本与参考文本之间最长公共子序列（Longest Common Subsequence）的匹配程度，即：整句的语义连贯性和语序一致性。同上，最大值为 100。如下，rouge-L=4.10 中等分数，表示模型生成的文本语义完整、逻辑通顺，虽然句式和标准答案不同，但核心信息完整、语序合理，能准确回答问题。

如果是文本摘要任务，那么 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：表示模型加载和预热（显存初始化）的耗时。如下，0.002s 是优秀的数值。
• predict_runtime：本次批量推理的总耗时，单位为秒。如下，15356 秒 ≈ 4 小时 16 分钟。
• predict_samples_per_second：每秒推理生成的样本数量，推理吞吐量核心指标的核心指标，表示模型每秒钟能够生成的样本数量。用于评估模型的推理速度。如下，0.243 样本/秒，表示模型平均每 4.1 秒处理 1 条推理样本。
• predict_steps_per_second：每秒执行的 step 数量，模型每秒钟能够执行的 step 数量。模型每生成一个 token 就是一个 step。如下，0.061 step/s 表示每秒生成约 0.061 个 token。

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

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

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

$ ll saves/Qwen3-1.7B-Base/lora/eval_2026-01-02-19-59-30
-rw-r--r-- 1 root root 331 Jan 3 03:36 all_results.json
-rw-r--r-- 1 root root 8123325 Jan 3 03:36 generated_predictions.jsonl
-rw-r--r-- 1 root root 465 Jan 223:19 llamaboard_config.yaml
-rw-r--r-- 1 root root 331 Jan 3 03:36 predict_results.json
-rw-r--r-- 1 root root 7492 Jan 3 03:36 running_log.txt
-rw-r--r-- 1 root root 22264 Jan 3 03:35 trainer_log.jsonl
-rw-r--r-- 1 root root 566 Jan 223:19 training_args.yaml

LoRA 模型合并导出

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

检查点路径选择我们刚刚微调好的模型，切换到 export，填写导出目录 output/qwen3-1.7b-huanhuan。 导出完成之后就可以在 output 目录下看到 qwen3-1.7b-huanhuan 目录了。

$ cd LlamaFactory
$ ll -h output/Qwen3-1.7B-huanhuan/
total 3.3G
drwxr-xr-x 2 root root 4.0K Jan 222:27 ./
drwxr-xr-x 3 root root 4.0K Jan 222:27 ../
-rw-r--r-- 1 root root 381 Jan 222:27 Modelfile
-rw-r--r-- 1 root root 707 Jan 222:27 added_tokens.json
-rw-r--r-- 1 root root 4.1K Jan 222:27 chat_template.jinja
-rw-r--r-- 1 root root 1.4K Jan 222:27 config.json
-rw-r--r-- 1 root root 117 Jan 222:27 generation_config.json
-rw-r--r-- 1 root root 1.6M Jan 222:27 merges.txt
-rw-r--r-- 1 root root 3.3G Jan 222:27 model.safetensors
-rw-r--r-- 1 root root 613 Jan 222:27 special_tokens_map.json
-rw-r--r-- 1 root root 11M Jan 222:27 tokenizer.json
-rw-r--r-- 1 root root 5.4K Jan 222:27 tokenizer_config.json
-rw-r--r-- 1 root root 2.7M Jan 222:27 vocab.json

部署运行微调后的大模型

这里用 Ollama + GGUF 进行部署。

其中，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 格式文件。
$ ll /workspace/LlamaFactory/output/Qwen3-1.7B-huanhuan/
-rw-r--r-- 1 root root 381 Jan 222:27 Modelfile
-rw-r--r-- 1 root root 3447348896 Jan 3 05:13 Qwen3-1.7B-huanhuan-BF16.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