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工程化落地的核心基础设施。