Llama-Factory LoRA微调实战指南

Llama-Factory LoRA微调实战指南

在大模型时代，我们不再只是使用通用语言模型来回答问题或写文章。越来越多的场景要求模型具备特定领域的知识表达能力——比如医疗问答、法律文书生成、金融摘要提取等。全参数微调虽然效果好，但动辄上百GB显存的需求让大多数开发者望而却步。

于是，轻量级微调方法如LoRA（Low-Rank Adaptation）成为了主流选择：它通过仅训练低秩矩阵的方式，在几乎不损失性能的前提下，将可训练参数减少90%以上。然而，从环境配置到数据处理、再到训练与部署，整个流程依然繁琐且容易踩坑。

这时候，一个真正开箱即用的工具就显得尤为重要。Llama-Factory正是为此而生——它不仅支持 LLaMA、Qwen、Baichuan、ChatGLM 等数十种主流架构，还统一了训练、评估和推理接口，并提供了命令行与 WebUI 双模式操作。本文将带你完整走通一次基于 Llama-Factory 的 LoRA 微调实战，涵盖环境搭建、数据准备、训练启动到推理部署全流程。

项目初始化与环境配置

首先克隆仓库：

git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory

--depth 1能显著加快下载速度。如果你不需要后续同步上游更新，可以删除.git目录节省空间：

rm -rf .git

建议使用 Conda 创建独立环境以避免依赖冲突。以下是经过验证的稳定组合：

创建并激活环境：

conda create -n lora-factory python=3.10 conda activate lora-factory

由于网络限制，直接pip install torch常常失败。推荐前往 PyTorch 官方下载页 下载对应.whl文件进行本地安装。例如，在 Linux + CUDA 12.1 环境下：

pip install torch-2.3.0+cu121-cp310-cp310-linux_x86_64.whl pip install torchaudio-2.3.0+cu121-cp310-cp310-linux_x86_64.whl pip install torchvision-0.18.0+cu121-cp310-cp310-linux_x86_64.whl

接着安装其他必要依赖：

pip install transformers==4.43.4 pip install vllm==0.4.3 pip install datasets accelerate peft gradio einops

最后执行可编辑安装，便于调试修改源码：

pip install -e ".[torch,metrics]"

安装完成后可通过以下命令验证是否成功：

llamafactory-cli -h

如果看到帮助信息输出，则说明安装无误。

HuggingFace 登录与加速访问

多数大模型托管于 HuggingFace 平台，需登录账户获取访问权限。

先升级huggingface_hub工具至最新版：

pip install --upgrade huggingface_hub

然后前往 HuggingFace Settings → Access Tokens，生成一个具有read权限的 Token。执行登录命令：

huggingface-cli login

输入你的 Token 完成认证。

若无法科学上网，建议切换为国内镜像站以避免超时：

export HF_ENDPOINT=https://hf-mirror.com

将其写入 shell 配置文件中以便持久生效：

echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc source ~/.bashrc

此后所有模型拉取都会自动走镜像通道，下载速度提升明显。

自定义数据集构建与注册

Llama-Factory 支持标准 SFT（监督式微调）任务格式，核心是"instruction", "input", "output"三元组结构。

典型的项目目录如下：

LLaMA-Factory/ ├── data/ │ ├── dataset_info.json │ └── news_summary.json ├── examples/ │ ├── train_lora/ │ │ └── news_summary_lora.yaml │ ├── inference/ │ │ └── news_summary_api.yaml └── saves/ └── llama3-8b-lora-news-summary/

假设我们要微调一个“新闻摘要生成”任务，示例数据如下：

[ { "instruction": "请根据以下新闻内容生成一段简洁的摘要。", "input": "近日，我国自主研发的新一代高速列车‘复兴号’智能动车组在京沪高铁实现常态化运营……", "output": "我国‘复兴号’智能动车组在京沪高铁实现常态化运营，具备全自动驾驶能力……" }, { "instruction": "请根据以下新闻内容生成一段简洁的摘要。", "input": "国家统计局发布数据显示，2024年上半年全国GDP同比增长5.3%……", "output": "2024年上半年我国GDP同比增长5.3%，经济持续回升向好……" } ]

保存为./data/news_summary.json。

接下来在data/dataset_info.json中注册该数据集：

"news_summary": { "file_name": "news_summary.json" }

注意：这里的 key 名称（如news_summary）将在后续 YAML 配置中作为dataset参数引用，务必保持一致。

LoRA 微调配置与训练启动

进入examples/train_lora/目录，新建news_summary_lora.yaml：

### model model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct adapter_name_or_path: cache_dir: use_fast_tokenizer: true ### method finetuning_type: lora lora_target: all lora_rank: 64 lora_alpha: 128 lora_dropout: 0.05 trainable: "all" modules_to_save: [] additional_target: [] ### training stage: sft do_train: true dataset: news_summary template: llama3 cutoff_len: 1024 buffer_size: 10000 max_samples: 10000 overwrite_cache: true preprocessing_num_workers: 16 ### output output_dir: saves/llama3-8b-lora-news-summary/ logging_steps: 10 save_steps: 500 eval_steps: 500 evaluation_strategy: steps per_device_train_batch_size: 1 gradient_accumulation_steps: 8 max_grad_norm: 1.0 num_train_epochs: 3 optim: adamw_torch learning_rate: 2e-4 warmup_steps: 100 lr_scheduler_type: cosine fp16: true bf16: false ddp_timeout: 180000000 save_total_limit: 2 load_best_model_at_end: true compute_dtype: fp16 ### logging & distributed dataloader_num_workers: 0 ddp_find_unused_parameters: false

几个关键参数值得特别说明：

• lora_target: all表示对所有线性层注入 LoRA 模块；你也可以精细控制为q_proj,v_proj等。
• lora_rank: 64是低秩矩阵的维度，越大拟合能力越强，但也更耗显存。实践中 8~64 是常见范围。
• lora_alpha: 128是缩放因子，通常设为 rank 的两倍，用于维持原始激活幅度。
• cutoff_len: 1024控制最大上下文长度，影响显存占用和训练效率。
• gradient_accumulation_steps: 8配合per_device_train_batch_size: 1实现全局 batch size = 8，适合多卡小批量场景。
• fp16: true启用混合精度训练，既能节省显存又能加速计算。

开始训练：

CUDA_VISIBLE_DEVICES=0,1 llamafactory-cli train examples/train_lora/news_summary_lora.yaml

如果是单卡，改为CUDA_VISIBLE_DEVICES=0即可。训练过程中会实时输出 loss 曲线、学习率变化等信息，最终模型权重保存在saves/llama3-8b-lora-news-summary/。

多样化推理方式：API服务与批量预测

启动 OpenAI 兼容 API 服务

适用于在线服务部署。在examples/inference/下创建news_summary_api.yaml：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct adapter_name_or_path: saves/llama3-8b-lora-news-summary/ template: llama3 infer_backend: vllm vllm_enforce_eager: true dtype: half gpu_memory_utilization: 0.9 max_model_len: 2048 tensor_parallel_size: 2

其中tensor_parallel_size: 2表示使用两张 GPU 进行张量并行推理。

启动服务：

CUDA_VISIBLE_DEVICES=0,1 API_PORT=8000 llamafactory-cli api examples/inference/news_summary_api.yaml

服务默认监听http://localhost:8000/v1。

Python 调用示例：

from openai import OpenAI client = OpenAI( base_url="http://localhost:8000/v1", api_key="EMPTY" ) response = client.chat.completions.create( model="meta-llama/Meta-Llama-3-8B-Instruct", messages=[ {"role": "user", "content": "请根据以下新闻内容生成一段简洁的摘要。\n\n近日，我国自主研发的新一代高速列车……"} ], temperature=0.7, max_tokens=150 ) print(response.choices[0].message.content)

这种设计极大降低了接入成本——任何兼容 OpenAI 接口的客户端都能无缝对接。

批量推理：高效评估测试集

对于离线评估或批量生成任务，推荐使用内置的do_predict模式。

准备测试数据data/inference_news.json，格式同上，但output字段可省略：

{ "instruction": "请根据以下新闻内容生成一段简洁的摘要。", "input": "国家统计局发布数据显示，2024年上半年全国GDP同比增长5.3%……" }

在dataset_info.json中注册：

"inference_news": { "file_name": "inference_news.json" }

新建examples/train_lora/news_summary_predict.yaml：

model_name_or_path: meta-llama/Meta-Llama-3-8B-Instruct adapter_name_or_path: saves/llama3-8b-lora-news-summary/ template: llama3 stage: sft do_predict: true predict_with_generate: true dataset: inference_news cutoff_len: 1024 max_samples: 500 preprocessing_num_workers: 8 output_dir: saves/llama3-8b-lora-news-summary/predict/ overwrite_output_dir: true per_device_eval_batch_size: 4 generation_max_length: 150 generation_num_beams: 1 predict_pad_token_id: 128001

执行批量推理：

CUDA_VISIBLE_DEVICES=0,1 llamafactory-cli train examples/train_lora/news_summary_predict.yaml

结果将以 JSONL 格式保存在generated_predictions.jsonl中，每行为一条生成文本，方便后续分析与评测。

进阶技巧与常见问题应对

显存不足怎么办？

这是最常见的痛点之一。几种有效缓解策略包括：

• 启用 QLoRA：在配置中添加quantization_bit: 4，结合fp16或bf16，可在消费级显卡上运行 7B 级模型。
• 降低 batch size：将per_device_train_batch_size设为 1，并增加gradient_accumulation_steps来补偿总批量。
• 启用 bf16：若硬件支持（Ampere 架构及以上），设置bf16: true比fp16更稳定，尤其在多节点训练时。

如何更换模型？支持哪些？

Llama-Factory 兼容性强，只需更改model_name_or_path即可切换模型。常见支持列表如下：

只要模型能在 HuggingFace Hub 上公开访问或你有权限拉取，基本都可以无缝接入。

是否支持图形界面操作？

当然！Llama-Factory 内置基于 Gradio 的 WebUI，启动命令：

CUDA_VISIBLE_DEVICES=0 llamafactory-cli webui

浏览器访问http://localhost:7860，即可通过拖拽上传数据、可视化设置参数、一键启动训练与交互式测试模型，真正做到“零代码微调”。

这对于非技术人员快速验证想法、产品经理做原型演示都非常友好。

结语

Llama-Factory 不只是一个微调框架，更是一套面向生产落地的完整解决方案。它把原本复杂的大模型定制流程封装成清晰的配置驱动模式，同时兼顾灵活性与易用性。

无论是科研实验中的快速迭代，还是企业级应用中的稳定部署，这套工具链都展现出极高的实用价值。更重要的是，它的活跃社区和持续更新保证了长期可用性。

现在就开始动手吧，用几百行 YAML 和一份业务数据，打造属于你自己的领域专家模型。