LlamaFactory使用教程

一招定胜负

123人浏览 · 2026-03-31 11:23:04

一招定胜负 · 2026-03-31 11:23:04 发布

安装LLaMA Factory

git clone --depth 1 https://github.com/hiyouga/LlamaFactory.git
cd LlamaFactory
pip install -e .
pip install -r requirements/metrics.txt

安装监控显卡工具

pip install nvitop
pip install nvidia-ml-py -U
nvitop -m auto
nvitop -m compact
nvitop -m full

快速开始

下面三行命令分别对 Qwen3-4B-Instruct 模型进行 LoRA 微调、推理和合并。

llamafactory-cli train examples/train_lora/qwen3_lora_sft.yaml
llamafactory-cli chat examples/inference/qwen3_lora_sft.yaml
llamafactory-cli export examples/merge_lora/qwen3_lora_sft.yaml

下载模型

https://modelscope.cn/models/Qwen/Qwen3-4B-Instruct-2507

关键文件介绍

这三个文件是 LLaMA-Factory 工作流中最核心的“三驾马车”。它们分别对应了大模型微调项目的三个关键阶段：训练、体验和部署。

简单来说，这是一个从“教模型”到“考模型”再到“带模型出门”的完整闭环。

以下是详细的介绍：

1. 训练阶段：`examples/train_lora/qwen3_lora_sft.yaml`

对应命令：llamafactory-cli train ...
核心作用：“教模型”。这是整个流程的起点。这个文件定义了怎么学。

关键配置

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

### dataset
dataset: identity,alpaca_en_demo
template: qwen3_nothink
cutoff_len: 2048
max_samples: 1000
preprocessing_num_workers: 16
dataloader_num_workers: 4

### output
output_dir: saves/qwen3-4b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
save_only_model: false
report_to: none  # choices: [none, wandb, tensorboard, swanlab, mlflow]

### train
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
resume_from_checkpoint: null

### eval
# eval_dataset: alpaca_en_demo
# val_size: 0.1
# per_device_eval_batch_size: 1
# eval_strategy: steps
# eval_steps: 500

- 学什么：指定数据集（dataset: sft_data）和对话模板（template: qwen3）。
- 怎么学：设定学习率（learning_rate）、训练轮数（num_train_epochs）、批次大小（per_device_train_batch_size）。
- 学多少：配置 LoRA 的参数，比如秩（lora_rank: 8）和目标模块（lora_target: all）。
产出：运行后，你会得到一个新的文件夹（通常在 saves/ 目录下），里面包含训练好的 LoRA 权重文件（adapter_model.bin）。

2. 体验/验证阶段：`examples/inference/qwen3_lora_sft.yaml`

对应命令：llamafactory-cli chat ...
核心作用：“考模型”。训练完后，你不需要把模型部署到服务器，而是想先在命令行里跟它聊聊天，看看效果好不好。这个文件定义了怎么聊。
关键配置
```
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
adapter_name_or_path: saves/qwen3-4b/lora/sft
template: qwen3_nothink
infer_backend: huggingface  # choices: [huggingface, vllm, sglang, ktransformers]
trust_remote_code: true
```
- 加载谁：它需要同时指定基础模型（model_name_or_path）和刚才训练出来的 LoRA 权重（adapter_name_or_path）。
- 用什么引擎：这里就是你刚才问到的 infer_backend: huggingface 或 vllm。
- 格式：必须保持和训练时一样的对话模板（template: qwen3），否则模型会听不懂人话。
产出：一个交互式的命令行界面，你可以输入问题，模型实时回答。

3. 部署/导出阶段：`examples/merge_lora/qwen3_lora_sft.yaml`

对应命令：llamafactory-cli export ...
核心作用：“打包模型”。 LoRA 权重只是一个“补丁”，不能独立运行。如果你要把模型发给别人，或者部署到生产环境，通常希望它是一个独立的、完整的模型文件。这个文件定义了怎么合。

关键配置

### Note: DO NOT use quantized model or quantization_bit when merging lora adapters

### model
model_name_or_path: Qwen/Qwen3-4B-Instruct-2507
adapter_name_or_path: saves/qwen3-4b/lora/sft
template: qwen3_nothink
trust_remote_code: true

### export
export_dir: saves/qwen3_sft_merged
export_size: 5
export_device: cpu  # choices: [cpu, auto]
export_legacy_format: false

源文件：指定基础模型路径和 LoRA 权重路径。
去向：指定合并后的模型保存路径（export_dir）。
注意：这里通常要求基础模型必须是 FP16/BF16 格式，不能是量化过的（如 INT4/INT8），否则合并会失败或精度受损。

产出：一个全新的、独立的模型文件夹。这个文件夹里包含了所有权重，不再依赖 LoRA 插件，可以直接被任何支持该架构的工具加载。

文件名关键词	角色	动作	你的操作
train	老师	训练	修改它来调整学习策略，跑完得到“补丁包”。
inference	考官	测试	修改它来加载“补丁包”，跑完进行对话测试。
merge	打包员	合并	修改它来指定输出位置，跑完得到“完整版模型”。

参数介绍

safetesnsors 是什么？

Safetensors 是一种用于安全存储张量（如模型权重）的新型文件格式，由 Hugging Face 团队开发，旨在解决传统格式（如 .pth 或 .bin）在安全性和加载效率上的不足。它不包含可执行代码，仅存储张量数据，因此在加载来自不可信来源的模型时更安全，且支持零拷贝加载，速度极快。

使用方法

!pip install safetensors

from safetensors import safe_open

with safe_open("adapter_model.safetensors", framework="pt", device=0) as f:
    for key in f.keys():
        tensor = f.get_tensor(key)
        # 处理 tensor查看
        print(tensor)

interence参数介绍

infer_backend: huggingface # choices: [huggingface, vllm, sglang, ktransformers]

指定模型在推理（运行/对话）时，底层使用哪个“引擎”来驱动。

选项	特点描述	适用场景
huggingface	默认选项。兼容性最强，几乎支持所有模型，无需额外安装复杂依赖source_group_web_4。但推理速度相对较慢，显存利用率一般。	调试、开发、快速验证。
vllm	高性能。通过 PagedAttention 技术极大提升吞吐量，推理速度极快，显存占用更低source_group_web_6。	生产环境、批量处理。
sglang	极速/新架构。比 vLLM 更新，针对复杂提示词（如多轮对话、Agent）有专门优化，速度往往更快source_group_web_8。	追求极致速度、复杂 Agent 应用。适合对延迟极其敏感的场景。
ktransformers	特定优化。通常指针对特定硬件或架构优化的内核版本（较少见，视具体版本而定）。	特定硬件优化场景。

使用API进行批量推理

准备 API 配置文件api_config.yaml，用于告诉服务加载哪个模型、使用哪个推理后端以及端口是多少。

### model
# 这里填入你的本地绝对路径
model_name_or_path: /mnt/workspace/.cache/modelscope/models/Qwen/Qwen3-4B-Instruct-2507

# 如果有 LoRA 权重，也填入路径；如果是合并模型则留空或注释掉
# adapter_name_or_path: saves/qwen3-4b/lora/sft 

template: qwen3_nothink
trust_remote_code: true
infer_backend: vllm  # 推荐使用 vllm 以获得更快的推理速度

在根目录下使用命令行启动

若出现报错


# 指定端口为 8000，使用第 0 号 GPU
API_PORT=8000 CUDA_VISIBLE_DEVICES=0 DISABLE_VERSION_CHECK=1 llamafactory-cli api examples/batch_infer/API_config.yaml

使用脚本进行批量推理

from openai import OpenAI

# 初始化客户端
client = OpenAI(
    api_key="0", 
    base_url="http://localhost:8000/v1"
)

# 1. 定义批量问题列表
questions = [
    "你好，请介绍一下你自己",
    "量子力学是什么？",
    "如何用 Python 写一个冒泡排序？"
]

print(f"开始批量推理，共 {len(questions)} 个问题...\n" + "-"*30)

# 2. 循环发送请求
for i, question in enumerate(questions):
    try:
        response = client.chat.completions.create(
            model="Qwen3-4B", 
            messages=[
                {"role": "user", "content": question}
            ],
            temperature=0.7
        )
        
        # 获取回答内容
        answer = response.choices[0].message.content
        
        # 打印结果
        print(f"[问题 {i+1}]: {question}")
        print(f"[回答]: {answer}")
        print("-" * 30)
        
    except Exception as e:
        print(f"请求 {i+1} 失败: {e}")

print("所有推理完成！")

训练轮数怎么计算的

总轮数 (Total Steps) = (数据集总样本数 × 训练轮次) / (单卡批次大小 × 梯度累积步数)

对于这一份yaml文件

### model
model_name_or_path: /mnt/workspace/.cache/modelscope/models/Qwen/Qwen3-4B-Instruct-2507
trust_remote_code: true

### method
stage: sft
do_train: true
finetuning_type: lora
lora_rank: 8
lora_target: all

### dataset
dataset: identity,alpaca_en_demo
template: qwen3_nothink
cutoff_len: 2048
max_samples: 1000
preprocessing_num_workers: 16
dataloader_num_workers: 4

### output
output_dir: saves/qwen3-4b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
save_only_model: false
report_to: none  # choices: [none, wandb, tensorboard, swanlab, mlflow]

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 8
learning_rate: 1.0e-4
num_train_epochs: 1.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000
resume_from_checkpoint: null

## eval
# eval_dataset: alpaca_en_demo
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500

计算过程

确定关键参数
- 数据集总样本数: 您在配置中设置了 max_samples: 1000，因此用于训练的样本总数为 1000 个。
- 训练轮次 (Epochs): num_train_epochs: 1.0，表示整个数据集会训练 1 遍。
- 单卡批次大小 (Batch Size): per_device_train_batch_size: 1，表示每张卡每次处理 1 个样本。
- 梯度累积步数 (Gradient Accumulation Steps): gradient_accumulation_steps: 8，表示每累积 8 个批次后才进行一次参数更新。
代入公式计算
- 总轮数 = (1000 × 1.0) / (1 × 8)
- 总轮数 = 1000 / 8
- 总轮数 = 125

三种微调方式

在大模型微调中，通常所说的“三种微调方式”主要指全量微调、LoRA微调和QLoRA微调。它们的核心区别在于更新参数量、资源消耗（尤其是显存）和适用场景。

你可以把它们想象成对一辆汽车进行改装：

全量微调：如同重装整个引擎和所有系统。效果最彻底，但成本极高。
LoRA微调：如同加装一个高性能外挂。不改动原车核心，成本低，效果显著，还能随时拆下。
QLoRA微调：如同在压缩过的引擎上再装外挂。成本最低，让普通用户也能玩得起大模型。

下面是这三种方式的详细对比：

微调方式	更新参数量	显存需求	适用场景
全量微调	100% 所有参数	极高 (约4倍模型大小)	资源充足的巨头，追求极致性能
LoRA微调	极少 (0.1%-1%)	中等 (约1.2倍模型大小)	绝大多数应用场景，个人开发者
QLoRA微调	极少 (0.1%-1%)	很低 (约0.3倍模型大小)	资源有限的个人或小团队

1. 全量微调 (Full Fine-tuning)

这是最传统、最彻底的微调方式。

原理：在训练过程中，更新模型的全部参数。模型的所有权重都会根据你的新数据进行调整。
优点：理论上能达到最好的效果，因为模型可以完全适应新任务。
缺点：资源消耗巨大。训练一个70亿（7B）参数的模型，可能需要80GB甚至更多的显存，对硬件要求极高，训练速度也慢。

2. LoRA微调 (Low-Rank Adaptation)

这是一种“参数高效微调”（PEFT）技术，是目前最主流的微调方法。

原理：冻结原始模型的所有参数，只在模型的特定层旁边注入并训练一些非常小的“适配器”矩阵（即LoRA模块）。训练时只更新这些小模块的参数。
优点：
- 显存占用低：只需训练极少量参数（通常不到原模型的1%），大大降低了显存需求。
- 训练速度快：因为要计算的参数少，训练效率非常高。
- 灵活切换：可以为不同任务训练多个LoRA模块，使用时像“插件”一样按需加载，非常灵活。
缺点：性能上限理论上略低于全量微调，但在绝大多数任务中，效果已经非常接近。

3. QLoRA微调 (Quantized LoRA)

这是在LoRA基础上的进一步创新，旨在将资源消耗降到最低。

原理

：QLoRA = 量化 + LoRA
1. 量化：首先将原始模型的精度从16位（FP16）压缩到4位（NF4），这能让模型体积缩小约75%。
2. LoRA：然后在这个被压缩的模型上，再进行LoRA微调。
优点：显存需求极低。它使得在单张消费级显卡（如24GB显存的RTX 4090）上微调一个巨大的70B模型成为可能。
缺点：由于引入了量化，会带来微小的精度损失（通常小于1%），但换取的是巨大的资源节省。

所有示例训练方式

qwen3_lora_dpo.yaml
- 含义：基于 Qwen3 模型，使用 LoRA 技术进行 DPO 训练的配置。
- 技术点：DPO（Direct Preference Optimization）是一种对齐技术，让模型学会人类的偏好（比如回答得更友好、更真实）。这个配置文件是用于让模型变得“更听话”。
qwen3_lora_kto.yaml
- 含义：基于 Qwen3 模型，使用 LoRA 技术进行 KTO 训练的配置。
- 技术点：KTO（Knowledge Transfer Optimization）也是一种对齐算法，类似于 DPO，旨在通过偏好数据优化模型输出。
qwen3_lora_pretrain.yaml
- 含义：基于 Qwen3 模型，使用 LoRA 技术进行 预训练 的配置。
- 技术点：这通常用于让模型学习新知识或新语言，而不是微调回答风格。
qwen3_lora_reward.yaml
- 含义：基于 Qwen3 模型，使用 LoRA 技术训练 奖励模型 的配置。
- 技术点：奖励模型（Reward Model）不直接回答问题，而是给其他模型的回答打分（好评/差评），用于后续的强化学习（RLHF）。
qwen3_lora_sft_ds3.yaml
- 含义：基于 Qwen3 模型，使用 LoRA 技术进行 SFT 训练，且使用了 DeepSpeed Stage 3 的配置。
- 技术点：SFT（Supervised Fine-Tuning，监督微调）是让模型学会具体任务（如写代码、写文案）。ds3 代表使用了 DeepSpeed 的第三级优化，这意味着该配置是为了在显存有限的情况下训练非常大的模型。
qwen3_lora_sft_ray.yaml
- 含义：基于 Qwen3 模型，使用 LoRA 技术进行 SFT 训练，且使用了 Ray 框架的配置。
- 技术点：Ray 是一个用于分布式计算的框架。这个配置文件意味着训练任务被分布到了多台机器或多个节点上进行。
qwen3_lora_sft_ray.sh
- 含义：启动上述 qwen3_lora_sft_ray.yaml 配置的 Shell 脚本。
- 技术点：当你想运行分布式训练时，通常会执行这个 .sh 文件。
qwen3_lora_sft.yaml
- 含义：基于 Qwen3 模型，使用 LoRA 技术进行 SFT 训练的标准配置。
- 技术点：这是最常规的微调配置，不涉及复杂的分布式框架（如 Ray）或显存优化（如 DeepSpeed）。
qwen3_preprocess.yaml
- 含义：数据预处理 配置。
- 技术点：在训练开始前，需要对原始数据进行清洗、分词、格式转换。这个文件定义了数据处理的规则。
qwen3vl_lora_dpo.yaml
- 含义：基于 Qwen3VL 模型，使用 LoRA 技术进行 DPO 训练的配置。
- 技术点：VL 代表 Vision-Language（视觉语言）。这说明该配置是用于多模态模型（能看懂图片的模型）的训练。
qwen3vl_lora_sft.yaml
- 含义：基于 Qwen3VL 模型，使用 LoRA 技术进行 SFT 训练的配置。
- 技术点：这是多模态模型的标准微调配置。

量化

什么是模型量化

模型量化是一种模型压缩技术，其核心思想是将模型参数（如权重和激活值）从高精度数据类型（通常是 FP16 或 BF16，占用 16 位）转换为低精度数据类型（如 INT4 或 INT8，占用 4 位或 8 位）。

原理：类似于将高清图片压缩成低分辨率图片，虽然会有微小的信息损失，但整体效果依然可用。
目的：大幅减少模型所需的显存（VRAM）和内存（RAM），同时通常能提升推理速度。
效果：一个典型的 7B（70亿参数）模型，原生 FP16 格式可能需要约 14GB 显存，而经过 INT4 量化后，显存占用可降至约 4-6GB，使得在消费级显卡（如 RTX 3060/4060）上运行大模型成为可能。

LlamaFactory 支持的量化方法

LlamaFactory 主要支持两大类量化方法：后训练量化（PTQ）和量化感知训练（QAT）。在实际应用中，PTQ 更为常见，因为它不需要重新训练模型。

后训练量化

PTQ 是在模型预训练完成后进行的量化。LlamaFactory 集成了目前主流的 PTQ 算法：

GPTQ
- 原理：一种基于逐块（per-channel）的权重量化方法。它通过最小化量化前后权重的差异来优化量化参数。
- 特点：精度损失较小，兼容性较好，是目前应用最广泛的量化方法之一。
- 适用场景：适用于大多数需要快速部署且对精度有一定要求的场景。
AWQ
- 原理：激活感知权重量化。它不仅考虑权重，还考虑激活值的分布，通过保护重要的权重通道来减少精度损失。
- 特点：相比 GPTQ，AWQ 在低比特（如 2-bit 或 3-bit）量化时表现更优，推理速度通常更快，且对硬件的兼容性要求较低。
- 适用场景：追求极致推理速度和极低显存占用的场景。
AQLM
- 原理：一种更先进的量化方法，结合了矢量量化和标量量化的优势。
- 特点：在极低比特下（如 2-bit）能保持较好的性能，但计算开销可能略高。

量化感知训练

QAT 是在模型微调（SFT）过程中引入量化模拟。LlamaFactory 支持 QLoRA。

QLoRA：将 LoRA（低秩适应）微调与量化结合。它在微调时使用量化模型，但更新的是 LoRA 适配器的参数。
优势：可以在极低显存占用下（例如仅需 6GB 显存）对大模型进行微调，训练完成后可以合并 LoRA 权重并导出为纯量化模型。

LlamaFactory 中的量化配置

在 LlamaFactory 中，用户可以通过命令行参数或配置文件轻松启用量化。常见的配置选项包括：

--quantization_bit：指定量化的比特数。常见值有 0（不量化）、4（INT4）、8（INT8）。
--quantization_method：指定量化算法。常见值有 gptq、awq、aqlm。
--template：根据不同的量化模型，可能需要指定相应的对话模板（如 qwen、llama2 等），以确保输入格式正确。

量化带来的收益与权衡

收益

显存占用大幅降低：这是最直接的好处，使得在低端硬件上运行大模型成为可能。
推理速度提升：低精度计算通常比高精度计算更快，尤其是在支持 INT4 指令的现代 GPU（如 NVIDIA 的 Tensor Core）上。
部署成本降低：可以使用更便宜的硬件进行模型推理服务。

什么是模型量化

原理：类似于将高清图片压缩成低分辨率图片，虽然会有微小的信息损失，但整体效果依然可用。
目的：大幅减少模型所需的显存（VRAM）和内存（RAM），同时通常能提升推理速度。
效果：一个典型的 7B（70亿参数）模型，原生 FP16 格式可能需要约 14GB 显存，而经过 INT4 量化后，显存占用可降至约 4-6GB，使得在消费级显卡（如 RTX 3060/4060）上运行大模型成为可能。

LlamaFactory 支持的量化方法

LlamaFactory 主要支持两大类量化方法：后训练量化（PTQ）和量化感知训练（QAT）。在实际应用中，PTQ 更为常见，因为它不需要重新训练模型。

后训练量化

PTQ 是在模型预训练完成后进行的量化。LlamaFactory 集成了目前主流的 PTQ 算法：

GPTQ
- 原理：一种基于逐块（per-channel）的权重量化方法。它通过最小化量化前后权重的差异来优化量化参数。
- 特点：精度损失较小，兼容性较好，是目前应用最广泛的量化方法之一。
- 适用场景：适用于大多数需要快速部署且对精度有一定要求的场景。
AWQ
- 原理：激活感知权重量化。它不仅考虑权重，还考虑激活值的分布，通过保护重要的权重通道来减少精度损失。
- 特点：相比 GPTQ，AWQ 在低比特（如 2-bit 或 3-bit）量化时表现更优，推理速度通常更快，且对硬件的兼容性要求较低。
- 适用场景：追求极致推理速度和极低显存占用的场景。
AQLM
- 原理：一种更先进的量化方法，结合了矢量量化和标量量化的优势。
- 特点：在极低比特下（如 2-bit）能保持较好的性能，但计算开销可能略高。