LLaMA-Factory微调实战：从环境到API部署

Ne0inhk

24 Mar 2026 — 9 min read

LLaMA-Factory微调实战：从环境到API部署

在大模型应用落地的今天，如何快速将一个通用语言模型适配到特定领域，已成为开发者最关心的问题之一。全参数微调成本高、门槛高，而像LoRA这样的高效微调技术又常因配置复杂让人望而却步。有没有一种方式，能让我们像搭积木一样完成模型定制？

LLaMA-Factory正是为此而生——它不只是一套工具，更像是一个“大模型工厂”，把数据准备、训练、评估、合并、部署等环节全部打通。无论你是想给模型换个身份人设，还是让它学会写广告文案、医疗问答或法律咨询，都可以通过这个框架快速实现。

本文将以Meta-Llama-3-8B-Instruct为例，带你走完一次完整的LoRA微调旅程：从环境搭建开始，到自定义数据集构建、模型训练与评估，再到最终以OpenAI兼容接口对外提供服务。整个过程无需深入源码，命令行+YAML即可掌控全局。

环境准备：让一切跑起来的基础

任何微调任务都建立在稳定可靠的运行环境之上。我们本次实验基于以下配置：

操作系统：Ubuntu 22.04 LTS
GPU：NVIDIA RTX 4090（24GB显存）
CUDA 版本：12.1
Python：3.10.13
PyTorch：2.4.0+cu121
Transformers：4.45.2
LLaMA-Factory：0.9.1.dev0（主干最新版）

单卡RTX 4090足以支持Llama-3-8B级别的QLoRA微调。若使用纯LoRA，16GB以上显存即可流畅运行。多卡用户需确保NCCL通信正常，避免分布式训练时报错。

⚠️ 提示：QLoRA对显存要求更低，但首次加载时仍可能触发OOM，建议设置--export_device cpu进行模型合并。

安装与验证：第一步不能出错

首先克隆项目并安装依赖：

git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory pip install -e ".[torch,metrics]" -i https://mirrors.aliyun.com/pypi/simple/

这里的-e表示开发模式安装，便于后续调试；[torch,metrics]会自动安装PyTorch及相关评估库（如jieba、rouge-chinese）。如果遇到依赖冲突，可先跳过依赖检查：

pip install --no-deps -e .

安装完成后，用两条命令确认环境就绪：

llamafactory-cli version

输出应显示当前版本信息和项目主页链接。接着检查CUDA是否可用：

import torch print(torch.cuda.is_available()) # 应返回 True print(torch.cuda.get_device_name(0)) # 显示 GPU 型号

同时验证Transformers版本：

import transformers print(transformers.__version__) # 推荐 ≥ 4.37

一切正常后，就可以进入下一步了。

模型下载：获取基础骨架

我们选用Meta官方发布的Meta-Llama-3-8B-Instruct作为基座模型。由于该模型受访问限制，请提前在Hugging Face或ModelScope申请权限。

推荐使用Git方式克隆：

# ModelScope 方式 git clone https://www.modelscope.cn/LLM-Research/Meta-Llama-3-8B-Instruct.git # 或 Hugging Face（需登录） git clone https://huggingface.co/meta-llama/Meta-Llama-3-8B-Instruct

将模型路径记为/path/to/Meta-Llama-3-8B-Instruct，后续所有操作都将引用此路径作为--model_name_or_path。

初步测试：看看原模型有多强

在动手微调前，先了解原始模型的能力边界非常重要。这不仅能验证环境正确性，也能为后续效果对比提供基准。

LLaMA-Factory提供了两种交互方式：命令行聊天和WebUI界面。

启动命令行对话：

llamafactory-cli chat \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --template llama3

其中--template llama3是关键参数。不同模型有不同的Prompt模板，例如ChatGLM用chatglm3，Qwen用qwen。模板错误会导致指令无法识别甚至无限生成。

你也可以创建YAML配置文件复用参数：

# examples/inference/llama3.yaml model_name_or_path: /path/to/Meta-Llama-3-8B-Instruct template: llama3

之后只需运行：

llamafactory-cli webchat examples/inference/llama3.yaml

即可启动Gradio网页界面，默认地址为http://localhost:7860。

数据集构建：教会模型新技能

要让模型具备特定能力，必须提供相应的训练数据。LLaMA-Factory支持JSON/JSONL格式，并通过data/dataset_info.json注册数据集。

示例一：修改助手身份（identity）

系统内置了一个简单的身份替换数据集data/identity.json，内容如下：

[ { "instruction": "你的名字是什么？", "input": "", "output": "我叫 {{name}}，由 {{author}} 开发。" } ]

我们可以用sed命令批量替换变量：

sed -i 's/{{name}}/PonyBot/g' data/identity.json sed -i 's/{{author}}/LLaMA Factory/g' data/identity.json

更新后的输出变为：“我叫 PonyBot，由 LLaMA Factory 开发。”

示例二：广告文案生成（AdGen）

我们再引入一个更实用的任务——根据商品描述生成广告语。使用清华大学开源的AdvertiseGen数据集：

wget https://cloud.tsinghua.edu.cn/seafhttp/files/1746ec39-a653-4c81-9197-55383e942282/AdvertiseGen.tar.gz tar -zxvf AdvertiseGen.tar.gz mv AdvertiseGen LLaMA-Factory/data/

然后在data/dataset_info.json中注册：

"adgen_local": { "file_name": "AdvertiseGen/train.json", "columns": { "prompt": "content", "response": "summary" } }

现在就可以在训练脚本中通过adgen_local引用该数据集。

LoRA微调：低成本定制专属模型

相比全参数微调动辄上百GB显存消耗，LoRA仅训练低秩矩阵，显存占用可降至原来的1/10，且训练速度更快。

执行以下命令启动SFT训练：

export NCCL_P2P_DISABLE="1" export NCCL_IB_DISABLE="1" llamafactory-cli train \ --stage sft \ --do_train \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --dataset alpaca_gpt4_zh,identity,adgen_local \ --dataset_dir ./data \ --template llama3 \ --finetuning_type lora \ --output_dir ./saves/LLaMA3-8B/lora/sft \ --overwrite_cache \ --overwrite_output_dir \ --cutoff_len 1024 \ --preprocessing_num_workers 16 \ --per_device_train_batch_size 2 \ --per_device_eval_batch_size 1 \ --gradient_accumulation_steps 8 \ --lr_scheduler_type cosine \ --logging_steps 50 \ --warmup_steps 20 \ --save_steps 100 \ --eval_steps 50 \ --evaluation_strategy steps \ --load_best_model_at_end \ --learning_rate 5e-5 \ --num_train_epochs 5.0 \ --max_samples 1000 \ --val_size 0.1 \ --plot_loss \ --fp16

几个关键点值得注意：

--finetuning_type lora启用LoRA；
--dataset支持多个数据集联合训练；
--fp16开启半精度，提升效率；
--plot_loss会自动生成loss.png，直观查看收敛情况。

在RTX 4090上，整个训练过程约8–15分钟。结束后可在输出目录看到：

./saves/LLaMA3-8B/lora/sft/ ├── adapter_config.json ├── adapter_model.bin ← LoRA权重核心文件 ├── training_args.bin └── trainer_state.json

动态推理：即时验证微调效果

训练完成后，无需合并模型即可直接测试效果。LLaMA-Factory支持动态加载LoRA权重。

启动命令行对话：

llamafactory-cli chat \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \ --template llama3 \ --finetuning_type lora

你会发现模型已经能正确回答“你是谁？”并生成更专业的广告文案。

也可以用YAML简化调用：

# examples/inference/llama3_lora_sft.yaml model_name_or_path: /path/to/Meta-Llama-3-8B-Instruct adapter_name_or_path: ./saves/LLaMA3-8B/lora/sft template: llama3 finetuning_type: lora

然后运行：

llamafactory-cli webchat examples/inference/llama3_lora_sft.yaml

即可打开带图形界面的聊天窗口。

效果评估：用数据说话

主观体验之外，我们也需要量化指标来衡量性能变化。

先安装评估依赖：

pip install jieba rouge-chinese nltk

然后运行预测任务：

llamafactory-cli train \ --stage sft \ --do_predict \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \ --eval_dataset adgen_local \ --dataset_dir ./data \ --template llama3 \ --finetuning_type lora \ --output_dir ./saves/LLaMA3-8B/lora/predict \ --cutoff_len 1024 \ --per_device_eval_batch_size 1 \ --max_samples 20 \ --predict_with_generate

结果保存在generated_predictions.jsonl和predict_results.json中，包含以下指标：

指标	含义
`BLEU-4`	四元语法匹配度（越高越好）
`rouge-1`, `rouge-2`	单词/双词召回率
`rouge-l`	最长公共子序列相似度
`predict_samples_per_second`	推理吞吐量

这些数值可以帮助判断是否出现过拟合或欠拟合。

模型合并：打造独立可部署模型

虽然可以动态加载LoRA，但在生产环境中通常希望得到一个完整模型文件。

使用export命令完成合并：

llamafactory-cli export \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \ --template llama3 \ --finetuning_type lora \ --export_dir ./merged-model-path \ --export_size 2 \ --export_device cpu \ --export_legacy_format false

注意事项：

不要在量化模型上执行合并；
使用--export_device cpu防止GPU显存溢出；
--export_size 2表示将模型切分为两个bin文件，适合跨设备部署。

导出后的模型完全符合Hugging Face标准，可用于vLLM、TGI等高性能推理框架。

WebUI可视化面板：零代码操作利器

对于不想敲命令的用户，LLaMA-Factory还提供了一站式WebUI：

CUDA_VISIBLE_DEVICES=0 GRADIO_SHARE=1 GRADIO_SERVER_PORT=7860 llamafactory-cli webui

访问http://localhost:7860即可进入图形界面，功能涵盖：

Training：拖拽式配置训练参数，实时查看loss曲线；
Evaluation：选择MMLU、C-Eval等基准一键评测；
Inference：多轮对话测试，支持流式输出；
Export：点击按钮完成模型合并导出。

非常适合教学演示或团队协作场景。

API服务部署：接入下游应用

最终目标往往是将模型集成进业务系统。LLaMA-Factory支持OpenAI协议API服务，轻松对接LangChain、AutoGPT等Agent框架。

方式一：原生后端API

CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \ --model_name_or_path /path/to/Meta-Llama-3-8B-Instruct \ --adapter_name_or_path ./saves/LLaMA3-8B/lora/sft \ --template llama3 \ --finetuning_type lora

启动后可用标准OpenAI客户端调用：

from openai import OpenAI client = OpenAI( api_key="0", # 占位符 base_url="http://localhost:8000/v1" ) messages = [{"role": "user", "content": "写一段智能手表的广告语"}] response = client.chat.completions.create(model="default", messages=messages) print(response.choices[0].message.content)

方式二：vLLM加速（推荐生产使用）

若已合并模型，可切换至vLLM后端获得更高并发：

CUDA_VISIBLE_DEVICES=0 API_PORT=8000 llamafactory-cli api \ --model_name_or_path ./merged-model-path \ --template llama3 \ --infer_backend vllm \ --vllm_enforce_eager

vLLM在批处理和连续提示生成方面表现优异，适合高负载场景。

进阶评测：检验知识保留能力

微调后模型是否“遗忘”了原有知识？这是常见问题。LLaMA-Factory内建支持主流评测基准：

llamafactory-cli eval \ --model_name_or_path ./merged-model-path \ --template llama3 \ --task mmlu_test \ --lang en \ --n_shot 5 \ --batch_size 1

输出示例：

Average: 63.64 STEM: 50.83 Social Sciences: 76.31 Humanities: 56.63 Other: 73.31

若分数显著下降，说明存在“灾难性遗忘”，建议降低学习率或增加通用数据比例。

对于Base模型（非Instruct版），需改用fewshot模板：

llamafactory-cli eval \ --model_name_or_path meta-llama/Meta-Llama-3-8B \ --template fewshot \ --task mmlu \ --split validation \ --lang en \ --n_shot 5 \ --batch_size 1

这种高度集成的设计思路，正推动大模型定制从“专家专属”走向“人人可用”。LLaMA-Factory不仅降低了技术门槛，更重要的是建立了标准化的工作流范式——从数据到部署，每一步都有迹可循。未来随着QLoRA、RAG、Agent等技术的深度融合，这类一体化框架将成为AI工程化落地的核心基础设施。

LLaMA-Factory微调实战：从环境到API部署

Ne0inhk