LitGPT 微调完全指南：finetune_full / finetune_lora / finetune_adapter / finetune_adapter_v2 四种方法实战与原理

LitGPT 微调完全指南：finetune_full / finetune_lora / finetune_adapter / finetune_adapter_v2 四种方法实战与原理

【免费下载链接】litgpt20+ high-performance LLMs with recipes to pretrain, finetune and deploy at scale.项目地址: https://gitcode.com/GitHub_Trending/li/litgpt

LitGPT 通过litgpt finetune_*系列命令，提供对 Alpaca、Dolly、LIMA 等指令数据集的预训练模型指令微调能力。本文以 tutorials/finetune.md 为骨架，系统讲解全参数微调、LoRA/QLoRA 与 Adapter/Adapter V2 四种方法的适用场景、完整命令、核心参数与底层实现原理，读者读完后可以依据自己的 GPU 显存与精度需求，直接选型并跑通一条从数据准备、微调到推理验证的完整链路。

一、概述：LitGPT 支持的四种微调方法

LitGPT 当前支持以下四种微调命令：

litgpt finetune_full litgpt finetune_lora litgpt finetune_adapter litgpt finetune_adapter_v2

这些命令在 litgpt/main.py 的PARSER_DATA中统一注册，分别对应litgpt.finetune.full、litgpt.finetune.lora、litgpt.finetune.adapter、litgpt.finetune.adapter_v2四个模块的setup入口函数。四个命令共享同一套训练管线设计：基于 Lightning Fabric 构建训练环境，默认数据集为 Alpaca（各setup函数中data = Alpaca() if data is None else data），默认优化器为 AdamW，默认学习率调度为「线性 warmup + 余弦退火」（见各文件中的get_lr_scheduler）。

[!TIP] 微调前先安装全部所需依赖：pip install "litgpt[all]"。

四种方法的本质区别在于哪些参数参与梯度更新，这直接决定了显存占用与训练成本：

二、全参数微调：litgpt finetune_full

2.1 命令与特性

litgpt finetune_full tiiuae/falcon-7b \ --data Alpaca

全参数微调会训练所有模型权重参数（在 litgpt/finetune/full.py 中直接以GPT(config)实例化完整模型并fabric.setup，不做任何参数冻结），是 LitGPT 中显存开销最大的微调方式。官方文档明确指出，finetune 7B 级模型（如 falcon-7b）需要至少 8 块约 40GB 显存的 GPU，因此该方法通常只推荐作为对比研究中的基线。

2.2 常用参数

litgpt finetune_full tiiuae/falcon-7b \ --data Alpaca \ --out_dir out/full/my-model-finetuned \ --precision 32-true

• --out_dir：指定检查点与日志输出目录，默认out/finetune/full；
• --precision：可选bf16-true、bf16-mixed、32-true。GPU 不支持 bfloat16 时（如 MPS 的现代 Mac），需传--precision 32-true，Fabric 会自动识别 MPS 加速器；
• --devices/--num_nodes：多卡/多机扩展。在 full.py 中，devices * num_nodes > 1时自动启用 FSDP 策略，并对每个Block开启激活检查点（activation checkpointing）以节省显存；
• --train.micro_batch_size：单卡 batch 大小，可根据显存灵活调小；
• --data：默认 Alpaca，可替换为 LIMA、Dolly 等内置数据集。

从源码结构看，finetune_full的训练循环（fit函数）会在每个eval.interval步验证集上计算 loss 与困惑度，并用当前模型生成一条示例回答，训练结束后把最终权重保存到out_dir/final/lit_model.pth（见 full.py）。

2.3 测试微调后的模型

litgpt generate tiiuae/falcon-7b \ --prompt "Recommend a movie to watch on the weekend." \ --finetuned_path out/full/my-model-finetuned/lit_model_finetuned.pth

GPU 支持 bfloat16 时脚本会自动使用该精度。

三、LoRA 与 QLoRA：litgpt finetune_lora

3.1 LoRA 原理

低秩适配（Low-Rank Adaptation，Hu et al. 2021）将线性层的权重更新近似为低秩矩阵分解：冻结预训练权重W (d×d)，只学习两个低秩矩阵A (d×r)与B (r×d)，最终更新量为BA叠加到冻结权重上。可训练参数量从d×d骤降为d×r + r×d，大幅降低显存并加速训练，而对最终模型性能影响很小。

从 litgpt/lora.py 的LoRALayer/LoRALinear实现可以看到具体机制：矩阵B初始化为 0、A按高斯分布初始化；更新量通过alpha/r缩放，其中alpha的作用是「在改变 rank r 时减少重新调超参的需求」（lora_alpha的 docstring 原话）。LoRA 分支还对输入施加 dropout（lora_dropout）。

3.2 运行 LoRA 微调

litgpt finetune_lora stabilityai/stablelm-base-alpha-3b \ --data Alpaca

该示例在单块 RTX 3090（24GB）GPU、CUDA 11.8 环境下即可完成 StableLM 3B 的 Alpaca 指令微调，检查点会周期性地保存到out/目录。

3.3 核心 LoRA 参数

litgpt/finetune/lora.py 的setup函数定义了以下参数：

[!NOTE] LoRA 不仅可以作用于query、key、value矩阵，还可以作用于projection、mlp与分类head。根据 QLoRA 论文第 4 节，「在所有线性 Transformer 块层上应用 LoRA 才能匹配全参数微调的性能」。默认只作用于query和value；如需扩展，修改lora_*参数即可。仓库自带的 config_hub/finetune/tiny-llama/lora.yaml 示例将lora_r: 32并同时开启lora_key、lora_projection、lora_mlp、lora_head，可作为追求更高性能的配置参考。

3.4 QLoRA：4-bit 量化微调

通过--quantize参数即可启用 QLoRA 风格的量化微调。可用取值包括bnb.nf4、bnb.nf4-dq、bnb.fp4、bnb.fp4-dq、bnb.int8-training，分别对应 bitsandbytes 的 4-bit NormalFloat / FP4（可叠加双量化-dq）与 8-bit 训练模式：

# 4-bit NormalFloat litgpt finetune_lora stabilityai/stablelm-base-alpha-3b \ --quantize "bnb.nf4" # 带双量化 litgpt finetune_lora stabilityai/stablelm-base-alpha-3b \ --quantize "bnb.nf4-dq"

在 lora.py 中，bnb.*量化通过BitsandbytesPrecision插件实现，且与混合精度不兼容（--precision中含mixed会直接报错）。量化模式下会使用 bitsandbytes 的StableEmbedding替换原始词嵌入层（见 lora.py），并使用instantiate_bnb_optimizer创建适配的优化器。需要注意：量化目前不支持多 GPU 训练（源码中明确raise NotImplementedError，需devices=1且num_nodes=1）。

3.5 不同设置下的显存与耗时对比

以下为官方教程 tutorials/finetune_lora.md 记录的实测数据（StableLM 3B / Llama 2 7B，Alpaca 数据集，1,000 步迭代，microbatch=1），供选型参考：

StableLM 3B：

Llama 2 7B：

可见 QLoRA 式量化的优势在 7B 等更大模型上更加显著——它让 Llama 2 7B 的训练显存从直接 OOM 降到约 14GB，推理显存更是降到 4.3GB 左右。更多资源需求对比可参考 tutorials/resource-tables.md。

3.6 测试 LoRA 模型与合并权重

litgpt generate "out/lora/final" \ --prompt "Recommend a movie to watch on the weekend."

LoRA 微调产出的是lit_model.pth.lora文件，仅包含远小于原始模型的 LoRA 权重以节省存储空间。若在litgpt generate/litgpt chat等推理命令中使用，LitGPT 会自动合并；仅当需要在 LitGPT 之外使用检查点时才需要手动合并：

litgpt merge_lora "out/lora/step-002000"

该命令会生成完整的lit_model.pth检查点，消除推理时动态叠加 LoRA 权重的开销（实现见 litgpt/scripts/merge_lora.py）。事实上，lora.py 在微调结束保存final检查点时，也会自动调用merge_lora生成合并后的完整权重。

四、Adapter 与 Adapter V2：litgpt finetune_adapter/litgpt finetune_adapter_v2

4.1 原理：从 Prefix Tuning 到 LLaMA-Adapter

Adapter 方法源自 LLaMA-Adapter 论文（Gao et al. 2023，论文页标注 v1 为 2303.16199、v2 为 2304.15010），其本质是一种前缀微调（prefix-tuning）形式：在 LLM 的每个注意力块输入前拼接一组可学习的适应提示（adaption prompt）。在 StableLM 3B 上，整个微调只需要更新约500k个参数，显著降低显存占用并加速训练，官方教程演示在单块 RTX 3060 上即可完成，8 卡并行时可在 1 小时内完成微调。

从 litgpt/adapter.py 的实现可以看到关键结构：

• Config新增两个超参：adapter_prompt_length: int = 10（适应提示长度）与adapter_start_layer: int = 2（从第几层开始插入适配提示）；
• CausalSelfAttention在block_idx >= adapter_start_layer时添加可学习的adapter_wte嵌入层和初始化为全零的gating_factor（零初始化门控），微调仅更新这些新增参数（对应论文的 zero-init attention 思想）。

LLaMA-Adapter v2（Zhang et al. 2023）在 v1 基础上扩展：

• 为 Transformer 中每个线性层新增可训练的bias 与 scale 参数（StableLM 3B 约 +1.5M 参数）；
• 使归一化层（normalization layers）可训练（约 +300k 参数）；
• 合计约2.3M可训练参数。

4.2 运行 Adapter 微调

litgpt finetune_adapter stabilityai/stablelm-base-alpha-3b \ --data Alpaca

或使用 Adapter V2：

litgpt finetune_adapter_v2 stabilityai/stablelm-base-alpha-3b \ --data Alpaca

Adapter 微调只需约 12GB 显存的 GPU。若要将 Adapter V2 控制在 12GB 内，可设--train.micro_batch_size 2；若希望 1 小时内完成，官方建议--devices 4 --train.micro_batch_size 4。多卡场景下，adapter.py 与 adapter_v2.py 同样启用 FSDP 策略并对 Block 开启激活检查点。

两个命令同样支持--out_dir自定义输出目录、--precision 32-true适配不支持 bfloat16 的环境，以及--quantize量化微调：

litgpt finetune_adapter stabilityai/stablelm-base-alpha-3b \ --quantize "bnb.nf4" litgpt finetune_adapter_v2 stabilityai/stablelm-base-alpha-3b \ --quantize "bnb.nf4-dq"

4.3 测试 Adapter 模型

litgpt generate_adapter stabilityai/stablelm-base-alpha-3b \ --prompt "Recommend a movie to watch on the weekend."

或 Adapter V2：

litgpt generate_adapter_v2 stabilityai/stablelm-base-alpha-3b \ --prompt "Recommend a movie to watch on the weekend."

输出示例：

A good movie to watch on the weekend would be The Lion King, since it's a classic family film that everyone can enjoy...

4.4 Adapter 检查点与恢复训练

Adapter 微调保存的是仅含适配器权重的lit_model.pth.adapter/lit_model.pth.adapter_v2文件，保存时通过adapter_filter只筛选适配器相关权重（见 adapter.py）。与 LoRA 类似，加载预训练权重时使用strict=False，因为适配器权重不在预训练 state dict 中。此外，finetune_adapter_v2还额外支持--resume断点续训：启动时会自动查找out_dir下最新的step-*/*.pth.adapter_v2检查点并从中恢复（见 adapter_v2.py）。

五、使用自定义数据集微调

四种方法都支持用 JSON 格式的指令数据微调。

第一步：创建 JSON 数据文件。每一行（元素）对应一条「指令-回复」对，字段包含instruction、output，可选input。注意：input字段目前只在 Alpaca 聊天模板中使用，若指令无需上下文可置为空字符串：

[ { "instruction": "Arrange the given numbers in ascending order.", "input": "2, 4, 0, 8, 3", "output": "0, 2, 3, 4, 8" }, { "instruction": "What is the capital of France?", "input": "", "output": "Paris" } ]

第二步：通过--data JSON指定数据路径：

litgpt finetune_lora stabilityai/stablelm-base-alpha-3b \ --data JSON \ --data.json_path data/mydata.json \ --out_dir out/mydata-finetuned

tiiuae/falcon-7b等模型名可替换为任意已下载的 checkpoint 路径，如checkpoints/stabilityai/stablelm-base-alpha-3b。

第三步：验证与使用微调结果：

litgpt chat out/mydata-finetuned/final

或部署为服务：

litgpt serve out/mydata-finetuned/final

六、准备工作与进阶资源

四种微调方法共用的准备工作（只需执行一次）：

1. 按 README.md 安装依赖，并执行pip install "litgpt[all]"；
2. 按 tutorials/download_model_weights.md 下载并转换权重到checkpoints/目录。

LitGPT 内置了 Alpaca、LIMA、Dolly 等常用微调数据集，关于支持的指令数据集清单以及如何准备更多自定义数据，可参见 tutorials/prepare_dataset.md。

各方法的独立教程与原始论文资源：

• 全参数微调：tutorials/finetune_full.md
• LoRA/QLoRA：tutorials/finetune_lora.md（概念入门可参考参数高效 LLM 微调教程 Parameter-Efficient LLM Finetuning With Low-Rank Adaptation (LoRA)）
• Adapter/Adapter V2：tutorials/finetune_adapter.md（概念入门可参考 Understanding Parameter-Efficient Finetuning of Large Language Models: From Prefix Tuning to LLaMA-Adapters）
• 显存与资源参考：tutorials/resource-tables.md

七、选型总结

• 显存充裕（多卡 40GB+）且需要最强效果：选择finetune_full作为基线；
• 单卡微调 7B 级模型、追求性价比：选择finetune_lora，显存紧张时叠加--quantize bnb.nf4-dq降为 QLoRA；
• 显存极度受限（约 12GB）：选择finetune_adapter；需要更强表达能力时选择finetune_adapter_v2（约 2.3M 可训练参数）。

从源码结构看，四种方法的训练循环、验证逻辑、学习率调度与检查点保存机制高度一致（均由各自模块的fit/validate/get_lr_scheduler/save_*_checkpoint组成），差异集中于「哪些参数被标记为可训练」与「模型结构如何插入可学习模块」。因此，无论选择哪种方法，其余的经验（如--train.micro_batch_size的显存调节、--out_dir的组织方式、--data JSON的自定义数据流程）都可以直接迁移复用。

【免费下载链接】litgpt20+ high-performance LLMs with recipes to pretrain, finetune and deploy at scale.项目地址: https://gitcode.com/GitHub_Trending/li/litgpt