【案例】Qwen 微调实战 · LoRA / QLoRA 与 DeepSpeed

X_f · W_f = (s_x · X_q) @ (s_w · W_q) = s_x · s_w · (X_q @ W_q)

X_f · W_f = ((X_q − Z_x) · s_x) @ ((W_q − Z_w) · s_w)
          = s_x · s_w · (X_q @ W_q − X_q @ Z_w − W_q @ Z_x + Z_x @ Z_w)

NF4 = [-1.0000, -0.6962, -0.5251, -0.3949, -0.2844, -0.1848, -0.0911,
        0.0796,  0.1609,  0.2461,  0.3379,  0.4407,  0.5626, 0.7230, 1.0000]

M, N, r = 300000, 500000, 16

full = M * N          # 原矩阵 W：全量微调要更新的参数量
a    = M * r          # 矩阵 A
b    = r * N          # 矩阵 B
side = a + b          # 旁路合计，这才是 LoRA 真正训练的东西

print(full, a, b, side)            # 150000000000 4800000 8000000 12800000
print("%.6f%%" % (side / full * 100))   # 0.008533%

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""lora_param_calc.py —— 算清楚 LoRA 到底省了多少参数。

回答三个问题：
  1. 一个 M×N 的权重矩阵，换成秩为 r 的旁路 A(M×r)·B(r×N) 之后，参数量从多少变成多少？
  2. 压缩比是多少？低秩旁路占原矩阵的百分之几？
  3. 按一个真实模型的所有目标层累加，可训练参数占全模型的比例是多少？

纯标准库，直接运行：
    python3 lora_param_calc.py                 # 跑内置的三个算例
    python3 lora_param_calc.py -M 300000 -N 500000 -r 16
    python3 lora_param_calc.py --model qwen7b -r 16
"""

import argparse


# ---------------------------------------------------------------------------
# 单个矩阵的账
# ---------------------------------------------------------------------------
def lora_params(m, n, r):
    """返回 (原矩阵参数量, A 的参数量, B 的参数量, 旁路合计)。

    原矩阵 W 是 M×N，全量微调要更新全部 M*N 个参数。
    LoRA 不动 W，只训练 A(M×r) 与 B(r×N)，用 A·B 去逼近 ΔW。
    只要 r 远小于 M 和 N，M*r + r*N 就会远小于 M*N。
    """
    full = m * n
    a = m * r
    b = r * n
    return full, a, b, a + b


def fmt(x):
    """把大整数写成人能读的量级，避免一串零看花眼。"""
    units = [(1e12, "万亿"), (1e8, "亿"), (1e4, "万")]
    for scale, name in units:
        if x >= scale:
            v = x / scale
            return ("%.4g%s" % (v, name)).replace(".0000", "")
    return str(x)


def report_matrix(m, n, r, title=""):
    full, a, b, side = lora_params(m, n, r)
    ratio = side / full
    print("-" * 66)
    if title:
        print(title)
    print("  原矩阵 W：%d × %d = %s 个参数" % (m, n, fmt(full)))
    print("  矩阵 A  ：%d × %d = %s" % (m, r, fmt(a)))
    print("  矩阵 B  ：%d × %d = %s" % (r, n, fmt(b)))
    print("  旁路合计：%s" % fmt(side))
    print("  占原矩阵：%.6f%%  ≈ 1/%d" % (ratio * 100, round(1 / ratio)))
    return ratio


# ---------------------------------------------------------------------------
# 按真实模型结构累加
# ---------------------------------------------------------------------------
# 只记录算 LoRA 需要的几个形状；这些是公开的模型结构参数，不含任何权重。
MODELS = {
    "qwen7b": {
        "label": "7B 级别模型（28 层，hidden 3584，中间层 18944）",
        "layers": 28,
        "hidden": 3584,
        "inter": 18944,
        "kv_hidden": 512,        # 分组查询注意力，k/v 的输出维度比 q 小
        "total": 7_615_616_512,
    },
    "qwen1_8b": {
        "label": "1.8B 级别模型（24 层，hidden 2048，中间层 5504）",
        "layers": 24,
        "hidden": 2048,
        "inter": 5504,
        "kv_hidden": 2048,
        "total": 1_836_828_672,
    },
}


def target_matrices(cfg):
    """lora_target: all 时被挂上旁路的线性层形状清单（每层）。"""
    h, i, kv = cfg["hidden"], cfg["inter"], cfg["kv_hidden"]
    return [
        ("q_proj", h, h),
        ("k_proj", h, kv),
        ("v_proj", h, kv),
        ("o_proj", h, h),
        ("gate_proj", h, i),
        ("up_proj", h, i),
        ("down_proj", i, h),
    ]


def report_model(key, r):
    cfg = MODELS[key]
    print("=" * 66)
    print("模型：%s" % cfg["label"])
    print("LoRA 秩 r = %d，lora_target = all（每层 7 个线性层都挂旁路）" % r)
    print("=" * 66)

    per_layer_full = 0
    per_layer_side = 0
    print("  每一层的账：")
    for name, m, n in target_matrices(cfg):
        full, _, _, side = lora_params(m, n, r)
        per_layer_full += full
        per_layer_side += side
        print("    %-10s %6d × %-6d  原 %-10s 旁路 %s"
              % (name, m, n, fmt(full), fmt(side)))

    layers = cfg["layers"]
    total_side = per_layer_side * layers
    total_full = cfg["total"]

    print("  单层合计：原 %s / 旁路 %s" % (fmt(per_layer_full), fmt(per_layer_side)))
    print("  全部 %d 层：可训练参数 %s" % (layers, fmt(total_side)))
    print("  全模型参数：%s" % fmt(total_full))
    print("  可训练占比：%.4f%%" % (total_side / total_full * 100))
    print()
    print("  读法：全量微调要更新 %s 个参数，LoRA 只更新 %s 个。"
          % (fmt(total_full), fmt(total_side)))
    print("  优化器状态（AdamW 每个可训练参数额外存两份动量）也按这个比例缩小，")
    print("  这才是显存真正降下来的原因 —— 不是模型变小了，是要存的中间量变少了。")


def main():
    ap = argparse.ArgumentParser(description="LoRA 参数量与压缩比计算")
    ap.add_argument("-M", type=int, help="原矩阵行数")
    ap.add_argument("-N", type=int, help="原矩阵列数")
    ap.add_argument("-r", type=int, default=16, help="LoRA 的秩，默认 16")
    ap.add_argument("--model", choices=sorted(MODELS), help="按真实模型结构累加")
    args = ap.parse_args()

    if args.model:
        report_model(args.model, args.r)
        return

    if args.M and args.N:
        report_matrix(args.M, args.N, args.r, "自定义矩阵")
        return

    # 默认算例：教科书里的那一组数
    print("=" * 66)
    print("算例一：M=300000，N=500000，r=16")
    print("=" * 66)
    report_matrix(300000, 500000, 16)

    print()
    print("=" * 66)
    print("算例二：同一个矩阵，r 取不同值时压缩比怎么变")
    print("=" * 66)
    print("  %-6s %-14s %-12s" % ("r", "旁路参数量", "占原矩阵"))
    for r in (1, 2, 4, 8, 16, 32, 64, 128):
        _, _, _, side = lora_params(300000, 500000, r)
        print("  %-6d %-14s %.6f%%" % (r, fmt(side), side / (300000 * 500000) * 100))
    print("  注意：旁路参数量随 r 线性增长，秩翻倍参数就翻倍。")
    print("  r 不是越大越好 —— 秩越高越接近全量微调，省显存的好处也就越少。")

    print()
    print("=" * 66)
    print("算例三：一个 7B 模型挂满旁路之后的真实占比")
    print("=" * 66)
    report_model("qwen7b", 16)


if __name__ == "__main__":
    main()

$ python3 lora_param_calc.py
  r      旁路参数量          占原矩阵
  1      80万            0.000533%
  2      160万           0.001067%
  4      320万           0.002133%
  8      640万           0.004267%
  16     1280万          0.008533%
  32     2560万          0.017067%
  64     5120万          0.034133%
  128    1.024亿         0.068267%
  注意：旁路参数量随 r 线性增长，秩翻倍参数就翻倍。

$ python3 lora_param_calc.py --model qwen7b -r 16
模型：7B 级别模型（28 层，hidden 3584，中间层 18944）
LoRA 秩 r = 16，lora_target = all（每层 7 个线性层都挂旁路）
  每一层的账：
    q_proj       3584 × 3584    原 1285万      旁路 11.47万
    k_proj       3584 × 512     原 183.5万     旁路 6.554万
    v_proj       3584 × 512     原 183.5万     旁路 6.554万
    o_proj       3584 × 3584    原 1285万      旁路 11.47万
    gate_proj    3584 × 18944   原 6790万      旁路 36.04万
    up_proj      3584 × 18944   原 6790万      旁路 36.04万
    down_proj   18944 × 3584    原 6790万      旁路 36.04万
  单层合计：原 2.33亿 / 旁路 144.2万
  全部 28 层：可训练参数 4037万
  全模型参数：76.16亿
  可训练占比：0.5301%

NF4 = [-1.0000, -0.6962, -0.5251, -0.3949, -0.2844, -0.1848, -0.0911,
        0.0796,  0.1609,  0.2461,  0.3379,  0.4407,  0.5626, 0.7230, 1.0000]

X = [0.32, -1.76, 0.025, -1.22]

absmax = max(abs(x) for x in X)            # 1.76 —— 这就是「量化常数」
normed = [x / absmax for x in X]           # [0.1818, -1.0, 0.0142, -0.6932]

idxs = [min(range(len(NF4)), key=lambda i: abs(v - NF4[i])) for v in normed]
print(idxs)                                 # [8, 0, 7, 1] —— 每个只占 4 bit

back = [NF4[i] * absmax for i in idxs]      # 反量化：查表取回，再乘回常数
print(["%.4f" % v for v in back])           # ['0.2832','-1.7600','0.1401','-1.2253']

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""nf4_quantize_demo.py —— 把 4-bit NormalFloat 量化算一遍给自己看。

演示四件事，全部用标准库，不需要 GPU、不需要 bitsandbytes：
  1. absmax 归一化：把一组权重按最大绝对值缩放到 [-1, 1]
  2. NF4 分位点舍入：按 16 个分位点取最近的那个，存下来的只是 0~15 的索引
  3. 反量化与误差：乘回 absmax，看看和原值差了多少
  4. 分块量化与双重量化：每块一个量化常数，再把这批常数自己量化一次

运行：
    python3 nf4_quantize_demo.py                 # 跑课堂上那个四元素例子 + 分块演示
    python3 nf4_quantize_demo.py --block 64 --n 512
"""

import argparse
import random


# ---------------------------------------------------------------------------
# NF4 的 16 个分位点
# ---------------------------------------------------------------------------
# 神经网络权重近似服从正态分布：0 附近很密，远离 0 很稀。
# 所以不按等距切，而是按正态分布的累计概率密度切成 16 个区域，
# 取每个区域的代表值。结果就是下面这串数 —— 靠近 0 的间隔明显更小。
NF4_LEVELS = [
    -1.0000, -0.6962, -0.5251, -0.3949, -0.2844, -0.1848, -0.0911,
    0.0796, 0.1609, 0.2461, 0.3379, 0.4407, 0.5626, 0.7230, 1.0000,
]


def nearest_level(x, levels=NF4_LEVELS):
    """返回 (最近分位点的索引, 该分位点的值)。

    真实实现用查表或二分，这里直接线性找，胜在看得清楚在干什么。
    """
    best_i, best_v, best_d = 0, levels[0], abs(x - levels[0])
    for i, v in enumerate(levels):
        d = abs(x - v)
        if d < best_d:
            best_i, best_v, best_d = i, v, d
    return best_i, best_v


# ---------------------------------------------------------------------------
# 单块量化：absmax 归一化 → 分位点舍入 → 反量化
# ---------------------------------------------------------------------------
def quantize_block(xs):
    """把一个块量化成 (索引列表, 量化常数)。

    量化常数就是这一块的 absmax。它必须原样存下来，否则反量化时无从还原尺度——
    而这些常数本身也占空间，正是双重量化要处理的对象。
    """
    absmax = max(abs(x) for x in xs) or 1.0
    normed = [x / absmax for x in xs]
    idxs = [nearest_level(v)[0] for v in normed]
    return idxs, absmax


def dequantize_block(idxs, absmax, levels=NF4_LEVELS):
    """索引查表取回分位点，再乘回量化常数。"""
    return [levels[i] * absmax for i in idxs]


# ---------------------------------------------------------------------------
# 演示一：课堂上那个四元素例子
# ---------------------------------------------------------------------------
def demo_four():
    xs = [0.32, -1.76, 0.025, -1.22]
    print("=" * 68)
    print("演示一：四个数走完整个 NF4 流程")
    print("=" * 68)
    print("  原始输入 X = %s" % xs)

    absmax = max(abs(x) for x in xs)
    print("\n  第 1 步 求 absmax(X) = %.4g" % absmax)

    normed = [x / absmax for x in xs]
    print("  第 2 步 归一化 X / absmax(X)：")
    print("         %s" % ["%.4f" % v for v in normed])
    print("         归一化之后所有值都落进 [-1, 1]，才能和分位点比")

    print("\n  第 3 步 按 NF4 的 16 个分位点舍入：")
    print("    %-10s %-10s %-8s %-10s" % ("归一化值", "最近分位点", "索引", "存几位"))
    idxs = []
    for v in normed:
        i, lv = nearest_level(v)
        idxs.append(i)
        print("    %-10.4f %-10.4f %-8d %-10s" % (v, lv, i, "4 bit"))
    print("    实际存下来的只有索引：%s —— 每个 4 bit，一共 %d bit"
          % (idxs, 4 * len(idxs)))
    print("    外加一个量化常数 absmax = %.4g（这个是 FP32 或 FP16，不是 4 bit）" % absmax)

    back = dequantize_block(idxs, absmax)
    print("\n  第 4 步 反量化并看误差：")
    print("    %-10s %-12s %-12s %-10s" % ("原值", "反量化值", "绝对误差", "相对误差"))
    for o, b in zip(xs, back):
        err = abs(o - b)
        rel = err / abs(o) if o else 0.0
        print("    %-10.4f %-12.4f %-12.4f %.2f%%" % (o, b, err, rel * 100))

    print("\n  读法：绝对值大的数误差小，接近 0 的数相对误差反而大 ——")
    print("  因为分位点虽然在 0 附近更密，但归一化之后小数被压得更靠近 0。")
    print("  这就是量化的本质交易：拿精度换显存和速度。")


# ---------------------------------------------------------------------------
# 演示二：分块量化 + 双重量化
# ---------------------------------------------------------------------------
def demo_blocks(n, block, seed=7):
    print()
    print("=" * 68)
    print("演示二：分块量化与双重量化（%d 个权重，块大小 %d）" % (n, block))
    print("=" * 68)

    rnd = random.Random(seed)
    # 用正态分布造一批权重 —— NF4 的整个设计前提就是权重近似正态分布
    weights = [rnd.gauss(0, 0.05) for _ in range(n)]

    blocks = [weights[i:i + block] for i in range(0, len(weights), block)]
    all_idx, consts = [], []
    for blk in blocks:
        idxs, absmax = quantize_block(blk)
        all_idx.extend(idxs)
        consts.append(absmax)

    # 还原并统计误差
    recovered = []
    for blk_idx, c in zip(
            [all_idx[i:i + block] for i in range(0, len(all_idx), block)], consts):
        recovered.extend(dequantize_block(blk_idx, c))

    errs = [abs(a - b) for a, b in zip(weights, recovered)]
    mean_abs = sum(abs(w) for w in weights) / len(weights)
    print("  块数：%d，每块一个量化常数" % len(blocks))
    print("  平均绝对误差：%.6f（权重平均绝对值 %.6f，相对 %.2f%%）"
          % (sum(errs) / len(errs), mean_abs, sum(errs) / len(errs) / mean_abs * 100))
    print("  最大绝对误差：%.6f" % max(errs))

    # ---- 存储账：这才是量化的目的 ----
    print("\n  存储账（按位算）：")
    fp16_bits = n * 16
    nf4_bits = n * 4
    const_bits_fp32 = len(consts) * 32
    print("    原始 FP16 权重            ：%8d bit" % fp16_bits)
    print("    NF4 索引                  ：%8d bit" % nf4_bits)
    print("    量化常数（FP32，每块一个）：%8d bit" % const_bits_fp32)
    print("    NF4 合计                  ：%8d bit  压缩到 %.1f%%"
          % (nf4_bits + const_bits_fp32,
             (nf4_bits + const_bits_fp32) / fp16_bits * 100))

    # ---- 双重量化：把这批常数自己再量化一次 ----
    print("\n  双重量化：把上面那批量化常数当成一组新数据，再量化一次")
    d_idxs, d_absmax = quantize_block(consts)
    d_back = dequantize_block(d_idxs, d_absmax)
    d_err = sum(abs(a - b) for a, b in zip(consts, d_back)) / len(consts)
    const_bits_after = len(consts) * 4 + 32     # 索引 4 bit 一个，外加一个总常数
    print("    常数个数：%d" % len(consts))
    print("    量化前占用：%d bit（FP32）" % const_bits_fp32)
    print("    量化后占用：%d bit（4 bit 索引 + 一个 FP32 总常数）" % const_bits_after)
    print("    常数本身的平均误差：%.6f" % d_err)
    print("    NF4 + 双重量化合计：%d bit  压缩到 %.1f%%"
          % (nf4_bits + const_bits_after,
             (nf4_bits + const_bits_after) / fp16_bits * 100))
    print("\n  读法：第二次量化只作用在第一次产生的量化常数上，权重本身不再动。")
    print("  块越小，常数越多，这一步省下来的就越可观。")


def main():
    ap = argparse.ArgumentParser(description="NF4 量化演示")
    ap.add_argument("--n", type=int, default=256, help="演示二里权重个数")
    ap.add_argument("--block", type=int, default=64, help="分块大小")
    args = ap.parse_args()

    print("NF4 的 16 个分位点：")
    print("  %s" % NF4_LEVELS)
    gaps = [round(NF4_LEVELS[i + 1] - NF4_LEVELS[i], 4) for i in range(len(NF4_LEVELS) - 1)]
    print("  相邻间隔：%s" % gaps)
    print("  可以看到靠近 0 的地方间隔更小 —— 权重密集的区域分得更细。")
    print()

    demo_four()
    demo_blocks(args.n, args.block)


if __name__ == "__main__":
    main()

$ python3 nf4_quantize_demo.py
  第 4 步 反量化并看误差：
    原值         反量化值         绝对误差         相对误差
    0.3200     0.2832       0.0368       11.51%
    -1.7600    -1.7600      0.0000       0.00%
    0.0250     0.1401       0.1151       460.38%
    -1.2200    -1.2253      0.0053       0.44%

演示二：分块量化与双重量化（256 个权重，块大小 64）
  块数：4，每块一个量化常数
  平均绝对误差：0.004002（权重平均绝对值 0.040708，相对 9.83%）

  存储账（按位算）：
    原始 FP16 权重            ：    4096 bit
    NF4 索引                  ：    1024 bit
    量化常数（FP32，每块一个）：     128 bit
    NF4 合计                  ：    1152 bit  压缩到 28.1%

  双重量化：把上面那批量化常数当成一组新数据，再量化一次
    量化前占用：128 bit（FP32）
    量化后占用：48 bit（4 bit 索引 + 一个 FP32 总常数）
    NF4 + 双重量化合计：1072 bit  压缩到 26.2%

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/

# 验证安装：出现版本横幅即为成功
llamafactory-cli version

### 全量微调：所有参数都参与更新，显存占用最高
### 启动：FORCE_TORCHRUN=1 llamafactory-cli train qwen2-7b-full-sft.yaml

### model
# 基座模型的本地路径或在线模型 ID
model_name_or_path: TODO/换成你的基座模型路径
# 加载含自定义代码的模型时必须开启
trust_remote_code: true

### method
# 训练阶段：有监督微调
stage: sft
do_train: true
# 全参数微调
finetuning_type: full
# 全量微调几乎必须搭 DeepSpeed，否则单卡装不下优化器状态
deepspeed: TODO/换成 ds_config_zero3.json 的路径

### dataset
# 必须与 data/dataset_info.json 里登记的键名一致
dataset: TODO_你的数据集名
# 对话模板要与基座匹配，Qwen 系列填 qwen
template: qwen
# 输入序列最大 token 数，超出部分被截断
cutoff_len: 1024
# 数据集改动后置 true，强制重新预处理
overwrite_cache: true
# 预处理并行进程数，建议取 CPU 核心数的 50%~70%
preprocessing_num_workers: 16

### output
output_dir: saves/qwen2-7b/full/sft
logging_steps: 10
save_steps: 100
plot_loss: true
overwrite_output_dir: true

### train
# 每卡批次大小；实际总批次 = 此值 × gradient_accumulation_steps × 卡数
per_device_train_batch_size: 1
# 梯度累积步数，用来在小显存下模拟大批次
gradient_accumulation_steps: 16
# 全量微调动的是原始权重，学习率必须比 LoRA 小一个量级
learning_rate: 1.0e-5
num_train_epochs: 1.0
# 余弦退火
lr_scheduler_type: cosine
# 前 10% 的 step 用于线性预热，防止参数剧烈震荡
warmup_ratio: 0.1
# BF16 混合精度，需要 Ampere 架构以上的卡
bf16: true
# 分布式超时时间，单位毫秒
ddp_timeout: 180000000

### eval
# 从训练集里划 10% 做验证；它不是验收用的评测集
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500

FORCE_TORCHRUN=1 llamafactory-cli train qwen2-7b-full-sft.yaml

{
    "fp16": {
        "enabled": "auto",
        "loss_scale": 0,
        "loss_scale_window": 1000,
        "initial_scale_power": 16,
        "hysteresis": 2,
        "min_loss_scale": 1
    },
    "bf16": {
        "enabled": "auto"
    },
    "optimizer": {
        "type": "AdamW",
        "params": {
            "lr": "auto",
            "betas": "auto",
            "eps": "auto",
            "weight_decay": "auto"
        }
    },
    "scheduler": {
        "type": "WarmupLR",
        "params": {
            "warmup_min_lr": "auto",
            "warmup_max_lr": "auto",
            "warmup_num_steps": "auto"
        }
    },
    "zero_optimization": {
        "stage": 2,
        "offload_optimizer": {
            "device": "none",
            "pin_memory": true
        },
        "allgather_partitions": true,
        "allgather_bucket_size": 2e8,
        "overlap_comm": true,
        "reduce_scatter": true,
        "reduce_bucket_size": 2e8,
        "contiguous_gradients": true
    },
    "gradient_accumulation_steps": "auto",
    "gradient_clipping": "auto",
    "steps_per_print": 100,
    "train_batch_size": "auto",
    "train_micro_batch_size_per_gpu": "auto",
    "wall_clock_breakdown": false
}

{
    "fp16": {
        "enabled": "auto",
        "loss_scale": 0,
        "loss_scale_window": 1000,
        "initial_scale_power": 16,
        "hysteresis": 2,
        "min_loss_scale": 1
    },
    "bf16": {
        "enabled": "auto"
    },
    "optimizer": {
        "type": "AdamW",
        "params": {
            "lr": "auto",
            "betas": "auto",
            "eps": "auto",
            "weight_decay": "auto"
        }
    },
    "scheduler": {
        "type": "WarmupLR",
        "params": {
            "warmup_min_lr": "auto",
            "warmup_max_lr": "auto",
            "warmup_num_steps": "auto"
        }
    },
    "zero_optimization": {
        "stage": 3,
        "offload_optimizer": {
            "device": "none",
            "pin_memory": true
        },
        "offload_param": {
            "device": "none",
            "pin_memory": true
        },
        "overlap_comm": true,
        "contiguous_gradients": true,
        "sub_group_size": 1e9,
        "reduce_bucket_size": "auto",
        "stage3_prefetch_bucket_size": "auto",
        "stage3_param_persistence_threshold": "auto",
        "stage3_max_live_parameters": 1e9,
        "stage3_max_reuse_distance": 1e9,
        "stage3_gather_16bit_weights_on_model_save": true
    },
    "gradient_accumulation_steps": "auto",
    "gradient_clipping": "auto",
    "steps_per_print": 100,
    "train_batch_size": "auto",
    "train_micro_batch_size_per_gpu": "auto",
    "wall_clock_breakdown": false
}

### LoRA 微调：冻结主干，只训练低秩旁路
### 启动：llamafactory-cli train qwen2-7b-lora-sft.yaml

### model
model_name_or_path: TODO/换成你的基座模型路径
trust_remote_code: true

### method
stage: sft
do_train: true
# 低秩适配
finetuning_type: lora
# 给哪些线性层挂旁路；all 表示所有线性层
lora_target: all
# 秩 r，决定旁路能学到的信息丰富程度，同时线性决定可训练参数量
lora_rank: 16
# 缩放系数，控制旁路输出的权重；常取与 rank 相等
lora_alpha: 16
# 旁路层的 dropout，正则化手段，防止模型过度依赖旁路
lora_dropout: 0.05

### dataset
dataset: TODO_你的数据集名
template: qwen
cutoff_len: 1024
overwrite_cache: true
preprocessing_num_workers: 16

### output
output_dir: saves/qwen2-7b/lora/sft
logging_steps: 100
save_steps: 100
plot_loss: true
overwrite_output_dir: true

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 16
# 旁路是随机初始化的新模块，学习率比全量微调大一个量级
learning_rate: 1.0e-4
num_train_epochs: 1.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
bf16: true
ddp_timeout: 180000000

### eval
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500

llamafactory-cli train qwen2-7b-lora-sft.yaml

### QLoRA 微调：把基座量化成 4-bit 之后再挂低秩旁路，显存最省
### 启动：llamafactory-cli train qwen2-7b-qlora-sft.yaml

### model
model_name_or_path: TODO/换成你的基座模型路径
trust_remote_code: true

### method
stage: sft
do_train: true
# 注意这里依然是 lora —— QLoRA 不是另一种微调类型，
# 它是「LoRA + 基座 4-bit 量化」，靠下面两行量化参数区分
finetuning_type: lora
lora_target: all
# 量化位数：4-bit
quantization_bit: 4
# 量化实现库；可选 bitsandbytes(4/8)、hqq(2/3/4/5/6/8)、eetq(8)
quantization_method: bitsandbytes
lora_rank: 16
lora_alpha: 16
lora_dropout: 0.05

### dataset
dataset: TODO_你的数据集名
template: qwen
cutoff_len: 1024
overwrite_cache: true
preprocessing_num_workers: 16

### output
output_dir: saves/qwen2-7b/qlora/sft
logging_steps: 100
save_steps: 100
plot_loss: true
overwrite_output_dir: true

### train
per_device_train_batch_size: 1
gradient_accumulation_steps: 16
learning_rate: 1.0e-4
num_train_epochs: 1.0
lr_scheduler_type: cosine
warmup_ratio: 0.1
# 基座存成 4-bit，但计算时反量化成 bf16 —— 精度靠这一行保住
bf16: true
ddp_timeout: 180000000

### eval
val_size: 0.1
per_device_eval_batch_size: 1
eval_strategy: steps
eval_steps: 500

llamafactory-cli train qwen2-7b-qlora-sft.yaml

llamafactory-cli export qwen2-7b-merge-lora.yaml

### 合并低秩旁路权重：把训练出来的适配器加回主干，导出成一个完整模型
### 启动：llamafactory-cli export qwen2-7b-merge-lora.yaml
### 注意：合并时不要使用量化模型，也不要带 quantization_bit

### model
# 原始的、未量化的基座模型
model_name_or_path: TODO/换成你的基座模型路径
# 训练产出的适配器目录，要与微调配置里的 output_dir 对应
adapter_name_or_path: TODO/换成你的适配器输出路径
# Qwen2 系列一律填 qwen
template: qwen
# 无论当初是 LoRA 还是 QLoRA 训的，这里都填 lora
finetuning_type: lora

### export
# 合并后完整模型的导出目录
export_dir: models/qwen2-7b-sft-lora-merged
# 单个权重文件的最大体积，单位 GB，超出则自动分片
export_size: 2
# 导出时用哪个设备做合并计算
export_device: cpu
# 是否使用旧版权重格式
export_legacy_format: false