框架选型与环境搭建

一句话定义

训练框架决定了你是「写训练循环」还是「填配置」：HF 生态（transformers + PEFT + TRL）代码可控，LLaMA-Factory 配置化开箱即用，unsloth 主打单卡加速省显存。

为什么重要

环境与框架问题是初学者耗时最多的地方——CUDA 版本、依赖冲突、数据格式不识别，随便一项就能耗掉一整天。选对框架并一次把环境装对，后面所有知识点才有落点；同时框架的抽象差异会影响你对训练过程的理解深度。

前置知识

kp-006 的 LoRA 配置项含义；Python 虚拟环境（conda/venv）的基本用法。

核心概念

• HF 生态：transformers（模型）+ PEFT（适配器）+ TRL（SFT/DPO Trainer）+ datasets（数据），代码级控制，适合需要定制的研究与工程。
• LLaMA-Factory：YAML/WebUI 驱动，把数据模板、LoRA、量化、训练、导出串成一条龙，适合快速迭代与团队协作。
• unsloth：重写注意力与反量化内核，单卡场景提效明显（宣称 2 倍速、省显存），适合消费级显卡。
• 版本矩阵：torch、CUDA、transformers、peft、trl、bitsandbytes 之间的兼容关系，是环境问题的主要来源。

原理与机制

选型依据三条：团队是否需要读改训练循环（要 → HF 栈）、迭代速度优先还是可控性优先（速度 → LLaMA-Factory）、是否单卡小显存（是 → unsloth 叠加 QLoRA）。框架之下都是同一套底层语义：数据 → 模板 → tokenize + label masking → Trainer 循环（前向/反向/优化器步进）→ checkpoint。理解了这条链，换框架只是换语法。

图示

数据(jsonl) → 模板渲染 → tokenize+mask → Trainer(前向/反向/优化)
   ▲                                    │
   └── LLaMA-Factory: 填yaml   HF栈: 写python   unsloth: 换快内核

直观类比

LLaMA-Factory 是自动挡（配置到位就开走），HF 栈是手动挡（每个动作自己控制），unsloth 是给同一台车换了台更强的发动机。目的地相同，驾驶体验与可调空间不同。

实例或案例

最小 LoRA SFT（HF 栈核心骨架，约 20 行）：

from trl import SFTTrainer, SFTConfig
from peft import LoraConfig

peft_cfg = LoraConfig(r=16, lora_alpha=32, target_modules="all-linear")
trainer = SFTTrainer(
    model="Qwen/Qwen2.5-7B-Instruct",
    train_dataset=ds,                    # {"messages": [...]} 格式
    peft_config=peft_cfg,
    args=SFTConfig(output_dir="out", per_device_train_batch_size=2,
                   gradient_accumulation_steps=8, num_train_epochs=2,
                   learning_rate=1e-4, bf16=True, logging_steps=10),
)
trainer.train()

同一件事在 LLaMA-Factory 里是一份 yaml：model_name、finetuning_type: lora、lora_rank: 16、dataset: mydata。

操作步骤

1. 建 conda 环境，conda create -n ft python=3.11。
2. 按框架官方文档安装匹配版本的 torch（先确认 nvidia-smi 的 CUDA 版本）。
3. 装齐依赖并验证导入：python -c "import torch; print(torch.cuda.is_available())"。
4. 跑通官方最小示例（不接自己的数据），确认 GPU、精度、显存链路正常。
5. 再接入自己的数据，跑 100 step 冒烟测试。

排错清单

• torch.cuda.is_available() 为 False：驱动/CUDA/torch 版本不匹配，按 torch 官网命令重装。
• 加载模型就报 OOM：忘了量化配置或默认 fp32 加载，显式传 torch_dtype。
• 数据集格式不识别：核对框架要求的数据字段（如 TRL 的 messages 列表格式）。
• bitsandbytes 报错：Linux 上需匹配 CUDA 版本；macOS 不可用（QLoRA 需 Linux/WSL）。
• 依赖冲突地狱：新建干净环境重装，不要在旧环境上打补丁。

常见误区

• 框架决定效果：效果取决于数据与超参，框架只影响效率与可控性；不要为了「听说某框架强」反复迁移。
• 版本随便装：PEFT/TRL 迭代快、API 变动多，严格按框架文档的版本矩阵装。
• 跳过冒烟测试直跑全量：先 100 step 验证链路，再投长时间训练。

与其他知识点的关系

QLoRA 的量化配置属于环境的一部分，见 kp-007；训练循环中的超参见 kp-016；跑起来之后看什么日志见 kp-019。

延伸阅读

Zheng et al. 2024《LlamaFactory: A Unified No-code Fine-tuning Platform》。

自测题

1. 什么时候必须选 HF 栈而不是 LLaMA-Factory？

答：需要定制训练循环（自定义损失、特殊数据流、非标准训练技巧）或要在论文/实验中精确控制每个组件时。

1. 新环境第一步验证什么？

答：torch.cuda.is_available() 为 True 且显存可见——GPU 链路通了才有资格谈训练。

1. 为什么要先跑官方最小示例再接自己的数据？

答：把「环境/框架问题」与「数据问题」解耦——官方示例跑不通是环境问题，通了再出问题就是自己数据或配置的问题。