1. 项目缘起：为什么要在服务器上折腾LLaMA-Factory和LoRA？

最近几个月，大模型微调的热度居高不下，无论是开源社区还是企业应用，都在探索如何让通用大模型更好地适配自己的特定任务。我手头恰好有一台闲置的、配备了多张消费级显卡的服务器，放着吃灰实在可惜。正好团队有个需求，想基于某个垂直领域的知识问答，定制一个更“懂行”的助手。直接调用GPT-4 API成本太高，且数据隐私是个问题；用ChatGLM、Qwen等开源基座模型，虽然免费，但回答不够精准，经常“一本正经地胡说八道”。

这时候， 参数高效微调（PEFT） 技术就成了救命稻草，而 LoRA（Low-Rank Adaptation） 又是其中公认的“性价比之王”。它不像全参数微调那样需要动辄几百GB的显存，而是通过注入少量的、可训练的低秩矩阵来调整模型行为，通常只需要原模型百分之一甚至千分之一的参数量，就能达到接近全参数微调的效果。这对于我们这种资源有限的团队来说，简直是量身定做。

那么，工具选型上，为什么是 LLaMA-Factory ？市面上微调框架不少，比如Hugging Face的 peft + transformers 原生组合，或者 axolotl 等。LLaMA-Factory吸引我的地方在于它的“一站式”和“小白友好”。它封装了从数据准备、模型加载、LoRA配置、训练到推理部署的完整流水线，提供了清晰的Web UI和命令行两种操作方式。特别是它的数据集格式化、模型仓库支持以及丰富的训练参数模板，大大降低了从零开始搭建微调环境的认知负担和操作成本。对于想快速验证想法、不想在环境配置上耗费太多时间的实践者来说，它是一个非常高效的起点。

这次记录，就是我在这台Ubuntu服务器上，从零开始，使用LLaMA-Factory对Qwen1.5-7B-Chat模型进行LoRA微调的全过程。我会详细拆解每一个步骤背后的逻辑、遇到的坑以及最终的解决方案，目标是产出一份可复现、有深度的实操指南。

2. 服务器环境准备：不只是安装驱动那么简单

工欲善其事，必先利其器。在服务器上跑大模型训练，环境配置是第一个，也是坑最多的环节。我的服务器配置是：双路E5-2696v4 CPU，256GB内存，搭载了4张RTX 3090 24GB显卡。系统是Ubuntu 22.04 LTS。

2.1 显卡驱动与CUDA：版本对齐是生命线

很多教程会告诉你“安装最新版驱动和CUDA”，但这恰恰是最大的陷阱。大模型生态对CUDA版本非常敏感，PyTorch、FlashAttention-2等关键组件都有明确的CUDA版本要求。

我的策略是 反向推导 ：先确定我要用的核心软件版本，再安装匹配的CUDA和驱动。

  1. 确定PyTorch版本 ：访问PyTorch官网，查看稳定版。当前（记录时）PyTorch 2.2+ 对CUDA 12.1支持良好，且很多优化（如 torch.compile ）在新版中更完善。我选择PyTorch 2.3.0。
  2. 确定CUDA版本 ：PyTorch 2.3.0 官方预编译版本支持CUDA 12.1。因此，我决定安装CUDA 12.1。
  3. 安装显卡驱动 ：CUDA 12.1要求驱动版本>=530.30.02。我使用 ubuntu-drivers 工具自动安装推荐版本： 
    sudo ubuntu-drivers autoinstall
sudo reboot
    重启后，使用 nvidia-smi 验证驱动安装成功，并确认驱动版本满足要求。
  4. 安装CUDA Toolkit 12.1 ：从NVIDIA官网下载runfile安装包， 切记不要安装捆绑的驱动 ！ 
    wget https://developer.download.nvidia.com/compute/cuda/12.1.0/local_installers/cuda_12.1.0_530.30.02_linux.run
sudo sh cuda_12.1.0_530.30.02_linux.run
    在安装选项中，反选 Driver ，只安装 CUDA Toolkit 。
  5. 环境变量配置 ：将CUDA路径加入 .bashrc 。 
    echo 'export PATH=/usr/local/cuda-12.1/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda-12.1/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
    验证： nvcc --version 应显示12.1。

踩坑记录1 ：我曾尝试安装CUDA 12.4，结果在编译FlashAttention-2时遭遇各种不兼容错误，回溯发现是PyTorch的CUDA Extension与CUDA Runtime版本不匹配。浪费了大半天时间后，老老实实回退到与PyTorch预编译版本对齐的CUDA 12.1，一切顺利。 教训：在深度学习领域，追求最新版本往往意味着踩最多的坑，稳定和兼容性优先。

2.2 Python环境与关键依赖：虚拟环境是保命符

绝对不要在系统Python环境下直接操作！使用Conda或venv创建独立环境。 

conda create -n llama_factory python=3.10 -y
conda activate llama_factory

接下来安装PyTorch。根据之前的规划，使用CUDA 12.1的版本： 

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

安装LLaMA-Factory。直接从GitHub拉取最新代码，便于后续自定义和问题追踪： 

git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e .[torch,metrics]

这里的 [torch,metrics] 是可选依赖，安装了包含PyTorch和评估指标（如ROUGE）的完整环境。 -e 参数代表“可编辑模式”，这样你修改源码后无需重新安装。

关键依赖补全 ：

  • FlashAttention-2 ：对于长序列训练，能极大提升速度并降低显存。必须安装。 
    pip install flash-attn --no-build-isolation
    如果安装失败，通常是CUDA环境或编译器问题。确保gcc/g++版本合适（Ubuntu 22.04默认的11即可）。
  • bitsandbytes ：用于QLoRA（4位量化微调），如果想尝试更低显存消耗，需要安装。 
    pip install bitsandbytes
  • 其他 ： accelerate （分布式训练）、 peft （LoRA实现）、 transformers 、 datasets 等会在安装LLaMA-Factory时作为依赖被安装。

2.3 模型与数据准备：路径规划的艺术

在服务器上，合理的文件路径规划能避免后续的权限和路径混乱问题。我建立了如下目录结构： 

/home/workspace/llm_finetune/
├── LLaMA-Factory/          # 框架源码
├── models/                 # 存放基座模型
│   └── Qwen1.5-7B-Chat/
├── data/                   # 存放训练数据
│   └── my_domain_qa.json
├── output/                 # 训练输出（适配器权重、日志）
└── scripts/                # 存放训练脚本
  1. 下载基座模型 ：使用Hugging Face的 snapshot_download ，或者直接 git lfs clone 。我更喜欢前者，因为它能更好地处理网络中断续传。 
    python -c "from huggingface_hub import snapshot_download; snapshot_download(repo_id='Qwen/Qwen1.5-7B-Chat', local_dir='/home/workspace/llm_finetune/models/Qwen1.5-7B-Chat')"
  2. 准备数据集 ：LLaMA-Factory支持多种格式，最常用的是JSON。每个样本通常包含 instruction （指令）、 input （可选输入）、 output （输出）。对于问答对，可以把问题放在 instruction ，答案放在 output 。 
    [
  {
    "instruction": "什么是量子计算的叠加原理？",
    "input": "",
    "output": "叠加原理是量子力学的基本原理之一...（详细解释）"
  },
  {
    "instruction": "请比较Transformer和RNN在长序列建模上的优劣。",
    "input": "",
    "output": "Transformer依靠自注意力机制...（详细解释）"
  }
]

    实操心得 ：数据质量决定模型上限。在构造数据时，我遵循了以下原则：① 指令清晰、无歧义；② 输出内容准确、详尽，模拟专家口吻；③ 适当加入思维链（Chain-of-Thought），例如“首先...其次...因此...”，这能显著提升模型复杂推理能力；④ 对数据进行清洗，去除乱码、重复和低质量样本。一个只有几百条但高质量的数据集，远胜于一个数万条但噪声巨大的数据集。

3. LoRA微调核心配置详解：参数不是玄学

环境就绪，数据备好，接下来就是最核心的微调配置。LLaMA-Factory提供了丰富的参数，理解每个参数背后的含义，是调出好模型的关键。

3.1 模型与数据加载配置

首先创建一个训练脚本 scripts/train_lora.sh ，使用命令行方式，便于复现和调度。 

#!/bin/bash
export CUDA_VISIBLE_DEVICES=0,1,2,3  # 指定使用的GPU，我这里有4张卡

python src/train_bash.py \
    --stage sft \                    # 训练阶段：监督微调
    --do_train \                     # 执行训练
    --model_name_or_path /home/workspace/llm_finetune/models/Qwen1.5-7B-Chat \  # 基座模型路径
    --dataset_dir data \             # 数据集目录
    --dataset my_domain_qa \         # 数据集名称（对应json文件名）
    --template qwen \                # 模板：必须与基座模型匹配！Qwen就用qwen
    --finetuning_type lora \         # 微调类型：lora
    --lora_target all \              # LoRA注入的目标模块：all表示所有Linear层
    --output_dir output/qwen_lora \  # 输出目录
    --overwrite_cache \              # 覆盖缓存
    --overwrite_output_dir \         # 覆盖输出目录
    --per_device_train_batch_size 2 \ # 每张GPU的批次大小
    --gradient_accumulation_steps 8 \ # 梯度累积步数
    --lr_scheduler_type cosine \     # 学习率调度器：余弦退火
    --logging_steps 10 \             # 每10步记录一次日志
    --save_steps 500 \               # 每500步保存一次检查点
    --eval_steps 500 \               # 每500步评估一次（需提供eval_dataset）
    --learning_rate 1e-4 \           # 学习率
    --num_train_epochs 3.0 \         # 训练轮数
    --max_samples 100000 \           # 最大训练样本数
    --max_grad_norm 1.0 \            # 梯度裁剪范数
    --quantization_bit 4 \           # 量化位数：4（即QLoRA），极大节省显存
    --lora_rank 64 \                 # LoRA秩（rank）
    --lora_alpha 128 \               # LoRA缩放系数（alpha）
    --lora_dropout 0.1 \             # LoRA层dropout
    --plot_loss \                    # 绘制损失曲线
    --fp16 \                         # 使用混合精度训练（FP16）
    --ddp_timeout 18000000 \         # DDP超时设置（多卡时需要）
    --report_to none                 # 不报告给wandb/tensorboard

关键参数解读与选型理由 ：

  • per_device_train_batch_size 和 gradient_accumulation_steps ：这是控制 有效批次大小（Effective Batch Size） 的两个杠杆。有效批次大小 = per_device_train_batch_size * gradient_accumulation_steps * GPU数量 。对于7B模型，常见的有效批次大小在32-128之间。我单卡batch_size设为2，累积8步，4卡，有效批次大小=2 8 4=64，处于合理区间。 调参技巧 ：先根据显存确定单卡能承受的最大 per_device_train_batch_size （通常为1或2），再通过 gradient_accumulation_steps 调整有效批次大小。
  • quantization_bit: 4 (QLoRA) ：这是显存节省的 关键 。将基座模型以4位精度加载，而LoRA参数以16位或32位训练。实测中，7B模型全参数FP16训练需要约14GB 4显存，而QLoRA仅需约6GB 4显存，让消费级显卡训练7B模型成为可能。
  • lora_rank 和 lora_alpha ：这是LoRA的核心超参。
    • rank （秩） ：决定了低秩矩阵的大小，即LoRA引入的可训练参数量。rank越大，能力越强，但过拟合风险也越大，且训练更慢。对于7B模型，rank=8, 16, 32, 64都是常见选择。我从64开始，这是一个兼顾能力和效率的起点。
    • alpha ：缩放因子。训练时，LoRA的输出会乘以 alpha/rank 。 通常将 alpha 设置为 rank 的两倍 ，这是一个经验法则，能保持输出尺度稳定。所以我设 alpha=128 。
  • lora_target ：指定将LoRA适配器加到模型的哪些层。 all 是最常用的，即所有线性层（Q, K, V, O, 以及FFN层中的两个线性层）。对于某些任务，只加到注意力层（ q_proj,v_proj ）可能也有效，但 all 通常是更稳妥的选择。
  • template ： 必须与基座模型对齐！ 不同模型（如Qwen, Llama, ChatGLM）有不同的对话模板（即如何将instruction, input组装成模型输入）。用错模板会导致模型无法理解你的指令格式，训练完全无效。LLaMA-Factory内置了主流模型的模板，直接指定即可。

3.2 启动训练与监控

给脚本加上执行权限并运行： 

chmod +x scripts/train_lora.sh
./scripts/train_lora.sh

训练开始后，监控是关键：

  1. 显存监控 ：使用 nvidia-smi -l 1 实时观察每张卡的显存占用和利用率。QLoRA下，4张3090的显存占用应稳定在20-25GB/卡（包含了模型、优化器状态、梯度、激活值等），利用率应接近100%。
  2. 日志监控 ：训练日志会输出到控制台和 output_dir 下的 trainer_log.jsonl 。重点关注 loss 下降曲线是否平滑，以及 learning_rate 的变化。
  3. 损失曲线 ：如果设置了 --plot_loss ，训练结束后会在 output_dir 生成 loss.png 。一个健康的曲线应该是训练损失稳步下降，验证损失（如果有）先降后升（过拟合信号）或趋于平稳。

踩坑记录2 ：第一次训练时，loss居高不下，且波动剧烈。排查后发现是 学习率（ learning_rate ）过高 。对于LoRA微调，由于大部分参数被冻结，可训练参数很少，通常需要使用比全参数微调 更小的学习率 （例如1e-4到5e-5）。我将学习率从3e-4调整为1e-4后，loss开始平稳下降。 教训：LoRA微调对学习率更敏感，建议从一个较小的值开始尝试。

4. 训练过程问题排查与性能优化

在实际训练中，不可能一帆风顺。以下是几个我遇到并解决的典型问题。

4.1 报错： RuntimeError: CUDA out of memory

这是最常见的问题。除了使用QLoRA，还有以下优化手段：

  • 梯度检查点（Gradient Checkpointing） ：用时间换空间。它会重新计算某些层的激活值，而不是存储它们，可以显著减少显存占用，但会拖慢训练速度约20%。在LLaMA-Factory中，可以通过 --gradient_checkpointing 参数开启。
  • 使用 --fp16 而非 --bf16 ：虽然BF16精度更高、范围更广，但某些旧显卡（如30系）对FP16支持更好，且FP16有时能节省一点点显存。如果你的卡支持BF16（如A100, H100），优先用BF16。
  • 减少 max_length ：模型处理的最大序列长度。默认可能是2048或4096。如果你的数据普遍很短（比如平均只有200个token），可以将其设置为512或1024，能大幅减少显存。通过 --cutoff_len 参数设置。
  • 卸载优化器状态至CPU（CPU Offload） ：这是 accelerate 库的进阶功能。可以将优化器状态和梯度保存在CPU内存，仅在更新时传输到GPU。这能极大节省GPU显存，但会显著增加CPU-GPU通信开销，训练速度变慢。仅当显存极度紧张时考虑。

4.2 报错： ValueError: You can't train a model that has been loaded in 8-bit or 4-bit precision...

这个错误通常是因为你想在已经量化（4bit或8bit）的模型上继续应用LoRA，但配置有冲突。确保你的配置是自洽的：

  • 如果使用了 --quantization_bit 4 ，那么 --finetuning_type 必须是 lora （即QLoRA）。
  • 如果你加载了一个本地已经用bitsandbytes量化过的模型，在LLaMA-Factory中可能需要通过 --model_name_or_path 指定路径，并确保框架能正确识别其量化状态。最稳妥的方式是让框架自己从原始模型开始量化。

4.3 训练速度慢，GPU利用率低

  1. 数据加载瓶颈 ：使用 htop 或 iotop 观察CPU和磁盘IO。如果数据预处理慢，可以尝试：
    • 使用 --preprocessing_num_workers 参数增加数据预处理进程数。
    • 将数据集转换为Arrow格式（ datasets 库的缓存格式），加速后续读取。
  2. 通信瓶颈（多卡时） ：使用NCCL调试。设置环境变量 NCCL_DEBUG=INFO 可以输出通信日志，观察是否有异常。确保服务器内GPU之间是通过NVLink或PCIe高速互联，而不是通过网卡。
  3. 使用FlashAttention-2 ： 这可能是提升训练速度最有效的一步 ，尤其是序列长度较长时。确保已正确安装，并且模型支持（Qwen, Llama等主流架构都支持）。LLaMA-Factory通常会自动启用。

4.4 模型“学废了”：过拟合与欠拟合

  • 过拟合迹象 ：训练损失持续下降，但验证损失（或人工评估效果）在某个点后开始变差。模型记住了训练数据的噪声，而非泛化规律。
    • 对策 ：增加 lora_dropout （如从0.1调到0.2或0.3）；使用更小的 rank （如从64降到32）；增加正则化（如果框架支持权重衰减 weight_decay ）；最重要的是， 扩充或提升训练数据质量 。
  • 欠拟合迹象 ：训练损失和验证损失都下降得很慢，或者早早进入平台期，模型能力没有明显提升。
    • 对策 ：适当增加 rank （如从32升到64）；提高学习率（谨慎）；增加训练轮数 num_train_epochs ；检查数据质量和任务定义是否清晰。

5. 模型评估、推理与部署

训练完成后， output_dir 下会保存适配器权重（ adapter_model.bin ）和配置文件（ adapter_config.json ）。基座模型本身没有被修改。

5.1 加载与推理

LLaMA-Factory提供了便捷的推理脚本： 

python src/cli_demo.py \
    --model_name_or_path /home/workspace/llm_finetune/models/Qwen1.5-7B-Chat \  # 基座模型
    --adapter_name_or_path output/qwen_lora \  # LoRA适配器路径
    --template qwen \
    --finetuning_type lora

这会启动一个基于命令行的交互式对话界面。你可以输入问题，测试微调后的模型在目标领域上的表现。

评估策略 ：

  • 定性评估 ：人工构造一批测试问题，对比微调前后模型的回答。关注：准确性、专业性、是否会产生幻觉（胡编乱造）、是否遵循指令格式。
  • 定量评估 ：如果任务有标准答案（如封闭式问答、文本摘要），可以使用BLEU、ROUGE等自动评估指标。LLaMA-Factory在训练时可以通过 --eval_dataset 指定验证集，并计算损失，但这只是粗糙的指标。更可靠的定量评估需要额外的评估脚本。

5.2 模型合并与导出

为了部署方便，有时需要将LoRA权重合并回基座模型，得到一个完整的、独立的模型文件。 

python src/export_model.py \
    --model_name_or_path /home/workspace/llm_finetune/models/Qwen1.5-7B-Chat \
    --adapter_name_or_path output/qwen_lora \
    --template qwen \
    --finetuning_type lora \
    --export_dir merged_qwen_model \  # 合并后模型输出目录
    --export_size 2 \                   # 保存为FP16精度
    --export_device cpu                # 在CPU上执行合并操作

合并后的模型可以直接用 transformers 库加载，像使用任何普通模型一样进行推理，无需再加载适配器。

5.3 部署考量

  • API服务 ：可以使用FastAPI、Gradio等框架，将合并后的模型或“基座模型+适配器”封装成HTTP API服务。
  • 显存考量 ：合并后的FP16模型大约占14GB显存（7B * 2 bytes）。如果服务并发量不高，可以常驻GPU内存。否则，需要结合vLLM、TGI（Text Generation Inference）等高性能推理框架，它们支持动态批处理、PagedAttention等优化，能显著提升吞吐量。
  • 成本权衡 ：对于长期稳定服务，合并模型更方便。如果经常需要切换不同任务的适配器，则保持“基座+多适配器”的模式更灵活。

6. 总结与进阶思考

经过这一轮从环境搭建到训练部署的完整流程，有几点深刻的体会：

第一， 数据是天花板，工程是地板 。无论模型和算法多精妙，低质量的数据都无法训练出可靠的模型。在数据清洗和构造上花的时间，远比调参更有价值。特别是对于专业领域，构建包含领域术语、逻辑链条和多种问法的优质数据集，是成功的一半。

第二， LoRA的超参调优有迹可循 。 rank 和 alpha 的比例关系、较小的学习率、合适的有效批次大小，这些是相对稳定的经验。不必一开始就陷入网格搜索，从一个社区验证过的配置（如rank=64, alpha=128, lr=1e-4）开始，根据训练损失和验证效果进行微调，效率更高。

第三， 显存优化是一套组合拳 。QLoRA是基础，梯度检查点、序列长度裁剪、甚至CPU Offload是延伸。在实际操作中，需要根据硬件条件和时间成本进行权衡。我的建议是优先使用QLoRA，如果显存还不够，再考虑梯度检查点，最后才是牺牲速度的Offload方案。

第四， 监控与日志至关重要 。不要启动训练就放任不管。密切监控GPU利用率、损失曲线和显存占用，能在问题早期（如梯度爆炸、数据异常）就及时干预，避免浪费几天时间后才发现训练失败。

最后，大模型微调正在从“黑科技”变为“工程实践”。随着LLaMA-Factory这类工具的出现，门槛已大大降低。未来的方向可能在于：更高效的PEFT方法（如DoRA）、更自动化的超参优化、以及对多模态模型和更长上下文的微调支持。对于个人开发者和小团队而言，聚焦于自己独特的领域数据，利用好这些开源工具，完全有能力打造出专属的、高性能的AI助手。这个过程，本身就是一次充满挑战和成就感的深度学习之旅。

# LLaMA-Factory # LoRA
Logo
码道开发者社区

码道开发者社区，聚焦华为云码道 CodeArts 代码智能体，沉淀 Agent、Skill、鸿蒙开发实战内容，供开发者查阅资料、交流技术、分享工程实践

更多推荐

cover

AI 已经能直接改设计稿了:Windows部署Penpot，接入Codex MCP实测

avatar 码道开发者社区
cover

【AI大模型】-DeepSeek Harness 深度解析

avatar 码道开发者社区
cover

实测推荐 3 个 Skill，轻松上手 Codex 网页设计与交付流程

avatar 码道开发者社区