外观
135.LLaMA Factory模型量化
来源：语雀原文 | 整理日期：2026-09-22
示例代码
前言
随着人工智能技术的飞速发展，大型语言模型（LLM）在自然语言处理（NLP）领域扮演着越来越重要的角色。然而，预训练的模型往往需要针对特定任务进行微调，以提高其在特定领域的性能。因为预训练模型是在大量数据上训练得到的，它已经学习到了语言的基本规律和丰富的特征表示。然而，这些模型可能并不直接适用于特定的任务或领域，因为它们可能缺乏对特定领域知识的理解和适应性。
LLaMA Factory 介绍
项目地址：https://github.com/hiyouga/LLaMA-Factory/blob/main/README_zh.md
LLaMA Factory 是一个简单易用且高效的大型语言模型（Large Language Model）训练与微调平台。致力于简化大型的定制过程。它集成了多种训练策略和监控工具，提供了命令行和 WebUI 等多种交互方式，大幅降了模型微调的技术门槛。通过 LLaMA Factory，可以在无需编写任何代码的前提下，在本地完成上百种预训练模型的微调，框架特性包括：
- 模型种类：LLaMA、LLaVA、Mistral、Mixtral-MoE、Qwen、Yi、Gemma、Baichuan、ChatGLM、Phi 等等。
- 训练算法：（增量）预训练、（多模态）指令监督微调、奖励模型训练、PPO 训练、DPO 训练、KTO 训练、ORPO 训练等等。
- 运算精度：16 比特全参数微调、冻结微调、LoRA 微调和基于 AQLM/AWQ/GPTQ/LLM.int8/HQQ/EETQ 的 2/3/4/5/6/8 比特 QLoRA 微调。
- 优化算法：GaLore、BAdam、DoRA、LongLoRA、LLaMA Pro、Mixture-of-Depths、LoRA+、LoftQ 和 PiSSA。
- 加速算子：FlashAttention-2 和 Unsloth。
- 推理引擎：Transformers 和 vLLM。
- 实验监控：LlamaBoard、TensorBoard、Wandb、MLflow、SwanLab 等等。
LLaMA Factory 核心功能
- 多模型兼容：支持包括 LLama、Mistral、Falcon 在内的多种大型语言模型。
- 训练方法多样：涵盖全参数微调及 LoRA 等先进的微调技术。
- 用户界面友好：LLama Board 提供了一个直观的 Web 界面，使用户能够轻松调整模型设置。
- 监控工具集成：与 TensorBoard 等工具集成，便于监控和分析训练过程。
LLaMA Factory 特点
- 易用性：简化了机器学习算法的复杂性，通过图形界面即可控制模型微调。
- 微调效率：支持 DPO、ORPO、PPO 和 SFT 等技术，提升了模型微调的效率和效果。
- 参数调整灵活性：用户可根据需求轻松调整模型参数，如 dropout 率、epochs 等。
- 多语言支持：界面支持英语、俄语和中文，面向全球用户提供服务。
LLaMA Factory 使用场景
LLaMA-Factory 适用于广泛的 NLP 任务，包括但不限于：
- 文本分类：实现情感分析、主题识别等功能。
- 序列标注：如 NER、词性标注等任务。
- 文本生成：自动生成文本摘要、对话等。
- 机器翻译：优化特定语言对的翻译质量。
LLaMA-Factory 通过其强大的功能和易用性，助力用户在自然语言处理领域快速实现模型的定制和优化。
微调的过程
模型微调通过在特定任务的数据集上继续训练预训练模型来进行，使得模型能够学习到与任务相关的特定特征和知识。这个过程通常涉及到模型权重的微幅调整，而不是从头开始训练一个全新的模型。
微调过程主要包括以下几个步骤：
- 数据准备：收集和准备特定任务的数据集。
- 模型选择：选择一个预训练模型作为基础模型。
- 迁移学习：在新数据集上继续训练模型，同时保留预训练模型的知识。
- 参数调整：根据需要调整模型的参数，如学习率、批大小等。
- 模型评估：在验证集上评估模型的性能，并根据反馈进行调整。
微调的优势
微调技术带来了多方面的优势：资源效率：相比于从头开始训练模型，微调可以显著减少所需的数据量和计算资源。快速部署：微调可以快速适应新任务，加速模型的部署过程。性能提升：针对特定任务的微调可以提高模型的准确性和鲁棒性。领域适应性：微调可以帮助模型更好地理解和适应特定领域的语言特点。
通过微调，可以使得预训练模型在这些任务上取得更好的性能，更好地满足实际应用的需求。
环境准备
安装 LLaMA Factory
plain
git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics]"可选的额外依赖项：torch、torch-npu、metrics、deepspeed、liger-kernel、bitsandbytes、hqq、eetq、gptq、aqlm、vllm、sglang、galore、apollo、badam、adam-mini、qwen、minicpm_v、modelscope、openmind、swanlab、quality
Tip
遇到包冲突时，可使用 pip install --no-deps -e . 解决。
数据准备
关于数据集文件的格式，请参考 data/README_zh.md 的内容。你可以使用 HuggingFace / ModelScope / Modelers 上的数据集或加载本地数据集。
Note
使用自定义数据集时，请更新 data/dataset_info.json 文件。
您也可以使用 Easy Dataset 构建用于微调的合成数据。
快速开始
下面三行命令分别对 Llama3-8B-Instruct 模型进行 LoRA 微调、推理和合并。
plain
llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml
llamafactory-cli chat examples/inference/llama3_lora_sft.yaml
llamafactory-cli export examples/merge_lora/llama3_lora_sft.yaml高级用法请参考 examples/README_zh.md（包括多 GPU 微调）。
Tip
使用 llamafactory-cli help 显示帮助信息。
遇到报错请先看常见问题。
LLaMA Board 可视化微调（由 Gradio 驱动）
llamafactory-cli webui
构建 Docker
CUDA 用户：
plain
cd docker/docker-cuda/
docker compose up -d
docker compose exec llamafactory bash昇腾 NPU 用户：
plain
cd docker/docker-npu/
docker compose up -d
docker compose exec llamafactory bashAMD ROCm 用户：
plain
cd docker/docker-rocm/
docker compose up -d
docker compose exec llamafactory bash从魔搭社区下载
如果您在 Hugging Face 模型和数据集的下载中遇到了问题，可以通过下述方法使用魔搭社区。
export USE_MODELSCOPE_HUB=1 # Windows 使用 set USE\_MODELSCOPE\_HUB=1
将 model_name_or_path 设置为模型 ID 来加载对应的模型。在魔搭社区查看所有可用的模型，例如 LLM-Research/Meta-Llama-3-8B-Instruct。
WebUI
LLaMA-Factory 支持通过 WebUI 零代码微调大语言模型。 在完成 安装 后，您可以通过以下指令进入 WebUI:
plain
llamafactory-cli webuiWebUI 主要分为四个界面：训练、评估与预测、对话、导出。
训练
在开始训练模型之前，您需要指定的参数有：
- 模型名称及路径
- 训练阶段
- 微调方法
- 训练数据集
- 学习率、训练轮数等训练参数
- 微调参数等其他参数
- 输出目录及配置路径
随后，您可以点击 开始 按钮开始训练模型。
备注
关于断点重连:适配器断点保存于 output_dir 目录下，请指定 适配器路径 以加载断点继续训练。
如果您需要使用自定义数据集，请在 data/data_info.json 中添加自定义数据集描述并确保 数据集格式 正确，否则可能会导致训练失败。
评估预测与对话
模型训练完毕后，您可以通过在评估与预测界面通过指定 模型 及 适配器 的路径在指定数据集上进行评估。
您也可以通过在对话界面指定 模型、 适配器 及 推理引擎 后输入对话内容与模型进行对话观察效果。
导出
如果您对模型效果满意并需要导出模型，您可以在导出界面通过指定 模型、 适配器、 分块大小、 导出量化等级及校准数据集、 导出设备、 导出目录 等参数后点击 导出 按钮导出模型。
SFT 训练
命令行
您可以使用以下命令使用 examples/train_lora/llama3_lora_sft.yaml 中的参数进行微调：
plain
llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml也可以通过追加参数更新 yaml 文件中的参数:
plain
llamafactory-cli train examples/train_lora/llama3_lora_sft.yaml \
learning_rate=1e-5 \
logging_steps=1备注
LLaMA-Factory 默认使用所有可见的计算设备。根据需求可通过 CUDA_VISIBLE_DEVICES 或 ASCEND_RT_VISIBLE_DEVICES 指定计算设备。
examples/train_lora/llama3_lora_sft.yaml 提供了微调时的配置示例。该配置指定了模型参数、微调方法参数、数据集参数以及评估参数等。您需要根据自身需求自行配置。
plain
### examples/train_lora/llama3_lora_sft.yaml
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
stage: sft
do_train: true
finetuning_type: lora
lora_target: all
dataset: identity,alpaca_en_demo
template: llama3
cutoff_len: 1024
max_samples: 1000
overwrite_cache: true
preprocessing_num_workers: 16
output_dir: saves/llama3-8b/lora/sft
logging_steps: 10
save_steps: 500
plot_loss: true
overwrite_output_dir: true
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
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500备注
模型 model_name_or_path 、数据集 dateset 需要存在且与 template 相对应。
| 名称 | 描述 |
| model_name_or_path | 模型名称或路径 |
| stage | 训练阶段，可选: rm(reward modeling), pt(pretrain), sft(Supervised Fine-Tuning), PPO, DPO, KTO, ORPO |
| do_train | true用于训练, false用于评估 |
| finetuning_type | 微调方式。可选: freeze, lora, full |
| lora_target | 采取LoRA方法的目标模块，默认值为 all。 |
| dataset | 使用的数据集，使用”,”分隔多个数据集 |
| template | 数据集模板，请保证数据集模板与模型相对应。 |
| output_dir | 输出路径 |
| logging_steps | 日志输出步数间隔 |
| save_steps | 模型断点保存间隔 |
| overwrite_output_dir | 是否允许覆盖输出目录 |
| per_device_train_batch_size | 每个设备上训练的批次大小 |
| gradient_accumulation_steps | 梯度积累步数 |
| max_grad_norm | 梯度裁剪阈值 |
| learning_rate | 学习率 |
| lr_scheduler_type | 学习率曲线，可选 linear, cosine, polynomial, constant 等。 |
| num_train_epochs | 训练周期数 |
| bf16 | 是否使用 bf16 格式 |
| warmup_ratio | 学习率预热比例 |
| warmup_steps | 学习率预热步数 |
| push_to_hub | 是否推送模型到 Huggingface |
LoRA 合并
合并
当我们基于预训练模型训练好 LoRA 适配器后，我们不希望在每次推理的时候分别加载预训练模型和 LoRA 适配器，因此我们需要将预训练模型和 LoRA 适配器合并导出成一个模型，并根据需要选择是否量化。根据是否量化以及量化算法的不同，导出的配置文件也有所区别。
您可以通过 llamafactory-cli export merge_config.yaml 指令来合并模型。其中 merge_config.yaml 需要您根据不同情况进行配置。
examples/merge_lora/llama3_lora_sft.yaml 提供了合并时的配置示例。
plain
### examples/merge_lora/llama3_lora_sft.yaml
### model
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
template: llama3
finetuning_type: lora
### export
export_dir: models/llama3_lora_sft
export_size: 2
export_device: cpu
export_legacy_format: false备注
- 模型
model_name_or_path需要存在且与template相对应。adapter_name_or_path需要与微调中的适配器输出路径output_dir相对应。 - 合并 LoRA 适配器时，不要使用量化模型或指定量化位数。您可以使用本地或下载的未量化的预训练模型进行合并。
量化
在完成模型合并并获得完整模型后，为了优化部署效果，人们通常会基于显存占用、使用成本和推理速度等因素，选择通过量化技术对模型进行压缩，从而实现更高效的部署。
量化（Quantization）通过数据精度压缩有效地减少了显存使用并加速推理。LLaMA-Factory 支持多种量化方法，包括:
- AQLM
- AWQ
- GPTQ
- QLoRA
- …
GPTQ 等后训练量化方法(Post Training Quantization)是一种在训练后对预训练模型进行量化的方法。我们通过量化技术将高精度表示的预训练模型转换为低精度的模型，从而在避免过多损失模型性能的情况下减少显存占用并加速推理，我们希望低精度数据类型在有限的表示范围内尽可能地接近高精度数据类型的表示，因此我们需要指定量化位数 export_quantization_bit 以及校准数据集 export_quantization_dataset。
备注
在进行模型合并时，请指定：
model_name_or_path: 预训练模型的名称或路径template: 模型模板export_dir: 导出路径export_quantization_bit: 量化位数export_quantization_dataset: 量化校准数据集export_size: 最大导出模型文件大小export_device: 导出设备export_legacy_format: 是否使用旧格式导出
下面提供一个配置文件示例：
plain
### examples/merge_lora/llama3_gptq.yaml
### model
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
template: llama3
### export
export_dir: models/llama3_gptq
export_quantization_bit: 4
export_quantization_dataset: data/c4_demo.json
export_size: 2
export_device: cpu
export_legacy_format: falseQLoRA 是一种在 4-bit 量化模型基础上使用 LoRA 方法进行训练的技术。它在极大地保持了模型性能的同时大幅减少了显存占用和推理时间。
警告
不要使用量化模型或设置量化位数 quantization_bit
下面提供一个配置文件示例：
plain
### examples/merge_lora/llama3_q_lora.yaml
### model
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
template: llama3
finetuning_type: lora
### export
export_dir: models/llama3_lora_sft
export_size: 2
export_device: cpu
export_legacy_format: false推理
LLaMA-Factory 支持多种推理方式。
您可以使用 llamafactory-cli chat inference_config.yaml 或 llamafactory-cli webchat inference_config.yaml 进行推理与模型对话。对话时配置文件只需指定原始模型 model_name_or_path 和 template ，并根据是否是微调模型指定 adapter_name_or_path 和 finetuning_type。
如果您希望向模型输入大量数据集并保存推理结果，您可以启动 vllm 推理引擎对大量数据集进行快速的批量推理。您也可以通过 部署 api 服务的形式通过 api 调用来进行批量推理。
默认情况下，模型推理将使用 Huggingface 引擎。 您也可以指定 infer_backend: vllm 以使用 vllm 推理引擎以获得更快的推理速度。
备注
使用任何方式推理时，模型 model_name_or_path 需要存在且与 template 相对应。
原始模型推理配置
对于原始模型推理， inference_config.yaml 中 只需指定原始模型 model_name_or_path 和 template 即可。
plain
### examples/inference/llama3.yaml
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
template: llama3
infer_backend: huggingface #choices： [huggingface, vllm]微调模型推理配置
对于微调模型推理，除原始模型和模板外，还需要指定适配器路径 adapter_name_or_path 和微调类型 finetuning_type。
plain
### examples/inference/llama3_lora_sft.yaml
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
template: llama3
finetuning_type: lora
infer_backend: huggingface #choices： [huggingface, vllm]多模态模型
对于多模态模型，您可以运行以下指令进行推理。
plain
llamafactory-cli webchat examples/inferece/llava1_5.yamlexamples/inference/llava1_5.yaml 的配置示例如下：
plain
model_name_or_path: llava-hf/llava-1.5-7b-hf
template: vicuna
infer_backend: huggingface #choices： [huggingface, vllm]批量推理
数据集
您可以通过以下指令启动 vllm 推理引擎并使用数据集进行批量推理：
plain
python scripts/vllm_infer.py --model_name_or_path path_to_merged_model --dataset alpaca_en_demoapi
如果您需要使用 api 进行批量推理，您只需指定模型、适配器（可选）、模板、微调方式等信息。
下面是一个配置文件的示例：
plain
### examples/inference/llama3_lora_sft.yaml
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
template: llama3
finetuning_type: lora下面是一个启动并调用 api 服务的示例：
您可以使用 API_PORT=8000 CUDA_VISIBLE_DEVICES=0 llamafactory-cli api examples/inference/llama3_lora_sft.yaml 启动 api 服务并运行以下示例程序进行调用：
plain
# api_call_example.py
from openai import OpenAI
client = OpenAI(api_key="0",base_url="http://0.0.0.0:8000/v1")
messages = [{"role": "user", "content": "Who are you?"}]
result = client.chat.completions.create(messages=messages, model="meta-llama/Meta-Llama-3-8B-Instruct")
print(result.choices[0].message)评估
通用能力评估
在完成模型训练后，您可以通过 llamafactory-cli eval examples/train_lora/llama3_lora_eval.yaml 来评估模型效果。
配置示例文件 examples/train_lora/llama3_lora_eval.yaml 具体如下：
plain
### examples/train_lora/llama3_lora_eval.yaml
### model
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft # 可选项
### method
finetuning_type: lora
### dataset
task: mmlu_test # mmlu_test, ceval_validation, cmmlu_test
template: fewshot
lang: en
n_shot: 5
### output
save_dir: saves/llama3-8b/lora/eval
### eval
batch_size: 4NLG 评估
此外，您还可以通过 llamafactory-cli train examples/extras/nlg_eval/llama3_lora_predict.yaml 来获得模型的 BLEU 和 ROUGE 分数以评价模型生成质量。
配置示例文件 examples/extras/nlg_eval/llama3_lora_predict.yaml 具体如下：
plain
### examples/extras/nlg_eval/llama3_lora_predict.yaml
### model
model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct
adapter_name_or_path: saves/llama3-8b/lora/sft
### method
stage: sft
do_predict: true
finetuning_type: lora
### dataset
eval_dataset: identity,alpaca_en_demo
template: llama3
cutoff_len: 2048
max_samples: 50
overwrite_cache: true
preprocessing_num_workers: 16
### output
output_dir: saves/llama3-8b/lora/predict
overwrite_output_dir: true
### eval
per_device_eval_batch_size: 1
predict_with_generate: true
ddp_timeout: 180000000同样，您也通过在指令 python scripts/vllm_infer.py --model_name_or_path path_to_merged_model --dataset alpaca_en_demo 中指定模型、数据集以使用 vllm 推理框架以取得更快的推理速度。
评估相关参数
| 参数名称 | 类型 | 介绍 |
| task | str | 评估任务的名称，可选项有 mmlu_test, ceval_validation, cmmlu_test |
| task_dir | str | 包含评估数据集的文件夹路径，默认值为 evaluation。 |
| batch_size | int | 每个GPU使用的批量大小，默认值为 4。 |
| seed | int | 用于数据加载器的随机种子，默认值为 42。 |
| lang | str | 评估使用的语言，可选值为 en、 zh。默认值为 en。 |
| n_shot | int | few-shot 的示例数量，默认值为 5。 |
| save_dir | str | 保存评估结果的路径，默认值为 None。 如果该路径已经存在则会抛出错误。 |
| download_mode | str | 评估数据集的下载模式，默认值为 DownloadMode.REUSE_DATASET_IF_EXISTS。如果数据集已经存在则重复使用，否则则下载。 |