基于 Llama-Factory 部署微调大模型 API 服务实战

CUDA_VISIBLE_DEVICES=0 python src/train_bash.py \
 --stage sft \
 --do_train \
 --model_name_or_path meta-llama/Llama-3-8B \
 --dataset ./data/essays.json \
 --template llama3 \
 --finetuning_type qlora \
 --lora_rank 64 \
 --lora_dropout 0.1 \
 --output_dir ./output/llama3-8b-essay \
 --per_device_train_batch_size 1 \
 --gradient_accumulation_steps 8 \
 --learning_rate 2e-4 \
 --num_train_epochs 3.0 \
 --fp16

这里有几个值得深挖的技术点。--finetuning_type qlora 不只是启用低秩适配那么简单——它背后整合了 bitsandbytes 的 4-bit 量化、NF4 数据类型以及双重量化（Double Quantization），使得原本需要上百 GB 显存才能加载的模型，现在一张 24GB 的 A10G 就能跑起来。

而 gradient_accumulation_steps=8 则是一种巧妙的资源换精度策略。由于 batch size 被迫设为 1，通过累积 8 步梯度再更新参数，等效于全局 batch size=8。不过要注意，过大的累积步数可能导致梯度方向漂移，实践中建议不超过总训练步数的 10%。

训练完成后，你会得到一组 LoRA 适配器权重。它们本质上是附加在原始模型上的小型矩阵，体积通常只有原模型的 1%~3%。但这带来了一个新问题：推理时需要同时加载基础模型和适配器，增加了部署复杂度。因此，在正式上线前最好执行合并操作：

python src/export_model.py \
 --model_name_or_path meta-llama/Llama-3-8B \
 --adapter_name_or_path ./output/llama3-8b-essay \
 --export_dir ./exported/essay-grader \
 --finetuning_type lora

这个导出过程会将 LoRA 权重'烧录'回主干网络，生成一个独立的 HuggingFace 格式模型。从此不再依赖额外组件，大大简化了后续的服务封装。

如何让模型真正'跑'起来？

很多团队走到这一步就停住了——他们有了模型，却不知道怎么变成可用的服务。常见的做法是写个 Flask 接口包装 transformers.pipeline，就像这样：

from transformers import AutoModelForCausalLM, AutoTokenizer
from flask import Flask, request, jsonify

app = Flask(__name__)
model = AutoModelForCausalLM.from_pretrained("./exported/essay-grader").to("cuda")
tokenizer = AutoTokenizer.from_pretrained("./exported/essay-grader")

@app.route("/grade", methods=["POST"])
def grade_essay():
    data = request.json
    inputs = tokenizer(data["text"], return_tensors="pt").to("cuda")
    outputs = model.generate(**inputs, max_new_tokens=512)
    result = tokenizer.decode(outputs[0], skip_special_tokens=True)
    return jsonify({"feedback": result})

这确实能工作，但在真实场景中很快会暴露瓶颈。Flask 默认的同步模型无法处理并发请求，当多个老师同时上传作文时，响应延迟会急剧上升。这时候就需要引入专业的推理引擎。

vLLM 是目前最优的选择之一。它采用 PagedAttention 技术，显著提升了 KV Cache 的利用率，吞吐量可达 HuggingFace 原生方案的 24 倍以上。集成方式极其简单：

pip install vllm
python -m vllm.entrypoints.api_server \
 --host 0.0.0.0 \
 --port 8000 \
 --model ./exported/essay-grader \
 --tensor-parallel-size 1

启动后就能通过标准接口调用：

curl http://localhost:8000/generate \
 -d '{ "prompt": "请批改这篇作文...", "max_new_tokens": 512, "temperature": 0.7 }'

你会发现，同样的硬件条件下，QPS（每秒查询数）提升了近十倍。更重要的是，vLLM 原生支持连续 batching，能把多个小请求自动聚合成大批次处理，这对成本敏感的应用至关重要。

当然，生产环境还需要考虑更多细节。比如 WebUI 默认监听 0.0.0.0，这意味着任何人都能访问你的训练界面——这在演示时很便利，但在服务器上等于敞开了大门。正确的做法是在前端加一层 Nginx 做反向代理，并配置 Basic Auth 或 JWT 认证。

另一个常被忽视的问题是版本管理。很多人训练完就把 output 目录打包归档，但半年后想复现实验时却发现无法还原结果。最佳实践是配合 Git + DVC 使用：将 train_bash.py 的完整命令记录在 .yaml 配置文件中，连同 adapter_config.json 和 training_args.bin 一起纳入版本控制。这样哪怕换了硬件或框架版本，也能确保实验可复现。

工程背后的权衡艺术

Llama-Factory 强大之处不仅在于功能全面，更体现在它对各种约束条件的平衡能力。举个例子，当你面对不同规模的项目时，微调策略的选择就充满取舍。

如果有充足的算力资源（比如多张 A100），全参数微调当然是首选——它能最大化模型性能。但现实中更多情况是，你只能拿到一块二手 3090。这时 QLoRA 成为救命稻草，但它也不是万能的。我们曾遇到一个案例：某医疗问答系统使用 QLoRA 微调后，在专业术语准确性上始终达不到要求。排查发现，LoRA 的低秩假设限制了某些关键层的表达能力。最终解决方案是采用 Adapter Tuning，虽然显存开销略高，但在特定领域表现更稳健。

数据质量的影响也远超预期。有团队用爬取的公开问答数据训练客服机器人，结果模型经常输出'请联系人工客服'这类敷衍回复。根本原因在于原始数据中存在大量此类样本。这提醒我们：模型学到的不仅是知识，更是数据分布本身。所以在数据清洗阶段，除了去重和过滤噪声，更要分析标签分布是否合理。

还有一个隐藏陷阱是 prompt 泄露。当你的训练数据里混入了测试集中的相似指令时，模型可能会记住而不是泛化。解决方法是在评估阶段设计对抗性测试集，或者使用 Jaccard 相似度提前筛查数据重叠。

这些经验告诉我们，工具再强大，也无法替代对问题本质的理解。Llama-Factory 把技术门槛从'必须懂分布式训练'降低到了'需要理解超参含义'，但这个中间地带恰恰是最容易出错的地方。比如学习率设置——对于 QLoRA，通常推荐 1e-4 ~ 3e-4，但如果用了较高的 dropout（如 0.3），可能需要适当提高学习率来补偿信息损失。

为什么这不仅仅是个工具？

回顾整个流程，Llama-Factory 实际上重新定义了大模型落地的工作模式。过去，微调是一项由算法工程师主导的'手工艺'，而现在它正在变成一项标准化的工程实践。这种转变的意义堪比当年 DevOps 对软件开发的重塑。

它让产品经理可以直接参与模型迭代：提出需求 → 准备样例数据 → 观察训练效果 → 反馈调整。这种闭环速度是传统流程难以想象的。我们也看到越来越多的企业开始建立