# ═══════════════════════════════════════════════════════════════
# TRL 依赖 PyTorch + Transformers + Accelerate + PEFT
# ═══════════════════════════════════════════════════════════════
pip install trl transformers accelerate peft datasets bitsandbytes

# ═══════════════════════════════════════════════════════════════
# 格式 1: Alpaca（单轮问答 — 最简单）
# 保存为 data/my_dataset.json，然后在 dataset_info.json 注册
# ═══════════════════════════════════════════════════════════════
[
  {
    "instruction": "请用 Python 写一个快速排序算法",
    "input": "",                              # 可选上下文，没有就填空串
    "output": "def quicksort(arr):\n    if len(arr) <= 1:\n        return arr\n    ..."
  },
  {
    "instruction": "翻译以下内容为英文",
    "input": "人工智能正在改变世界",           # 这里是具体要翻译的内容
    "output": "Artificial intelligence is changing the world"
  }
]
═══════════════════════════════════════════════════════════════
格式 2: ShareGPT（多轮对话 — 更现代）
═══════════════════════════════════════════════════════════════
[
    {
        "conversations": [
            {"from": "human", "value": "请用 Python 写一个快速排序"},
            {"from": "gpt",    "value": "def quicksort(arr):\n    ..."},
            {"from": "human", "value": "能解释一下时间复杂度吗？"},
            {"from": "gpt",    "value": "快速排序的平均时间复杂度为 O(n log n)..."}
        ]
    }
]
═══════════════════════════════════════════════════════════════
在 dataset_info.json 中注册你的数据集
═══════════════════════════════════════════════════════════════
"my_dataset": {
    "file_name": "my_dataset.json",
    "formatting": "alpaca",              # 告诉 LlamaFactory 数据格式
    "columns": {
        "prompt": "instruction",            # 哪个字段作为 prompt
        "query": "input",                   # 哪个字段作为上下文
        "response": "output"                 # 哪个字段作为回答
        }
    }

# ═══════════════════════════════════════════════════════════════
# SFT 的每条数据就是一个"对话"，有多种模板风格
# ═══════════════════════════════════════════════════════════════
# 模板 1: Alpaca 格式（简单直接）
"Below is an instruction that describes a task.\n\n
Instruction:\n用 Python 写一个快速排序\n\n
Response:\npython\ndef quicksort(arr):\n    ..."

# 模板 2: ChatML 格式（OpenAI 风格，支持多轮对话）
"<|im_start|>system\n你是一个有用的助手<|im_end|>\n
<|im_start|>user\n什么是光合作用？<|im_end|>\n
<|im_start|>assistant\n光合作用是植物利用阳光...<|im_end|>"

# 模板 3: Llama 3 格式（最现代的对话模板）
"<|begin_of_text|>
<|start_header_id|>user<|end_header_id|>\n\n
# 用 Python 写一个快速排序
<|eot_id|>
<|start_header_id|>assistant<|end_header_id|>\n\n
python\ndef quicksort(arr):\n    ...
<|eot_id|>"

# ═══════════════════════════════════════════════════════════════
# TRL SFTTrainer — 工业级 SFT 训练，一行 trainer.train() 搞定
# 自动帮你做: Loss Masking + 打包序列 + 混合精度 + 梯度累积
# ═══════════════════════════════════════════════════════════════
from datasets import load_dataset
from trl import SFTTrainer, SFTConfig           # TRL 的核心 API
from transformers import AutoModelForCausalLM, AutoTokenizer
# ─── Step 1: 加载基座模型和分词器 ───
# 从预训练基座出发——这是你从 HuggingFace Hub 下载的模型
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B",                    # 换成任意基座：Llama, Mistral, DeepSeek...
    torch_dtype="auto",
    device_map="auto",
    )
tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B")
# ─── Step 2: 准备数据 — 对话格式 ───
# 数据格式: {"messages": [{"role":"user","content":"..."}, {"role":"assistant","content":"..."}]}
# TRL 自动应用 chat_template，并自动只对 assistant 部分算 loss
dataset = load_dataset("HuggingFaceH4/ultrachat_200k", split="train_sft")
# ─── Step 3: 配置 SFTConfig — 所有训练参数 ───
sft_config = SFTConfig(
    output_dir="./sft_qwen",
    per_device_train_batch_size=2,          # 单卡 batch size
    gradient_accumulation_steps=8,          # 累积 8 步 → 等效 batch=2×8=16
    num_train_epochs=3,
    learning_rate=2e-5,                       # SFT 的 LR 不宜过大
    warmup_ratio=0.03,
    lr_scheduler_type="cosine",
    fp16=True,                              # 混合精度，省显存（A100 可选 bf16=True）
    logging_steps=10,
    save_strategy="epoch",
    max_seq_length=2048,                     # 序列最大长度，超出的截断
    packing=True,                            # ★ 打包：把多个短对话拼成一条 2048，充分利用 GPU
    dataset_text_field="messages",            # 告诉 TRL 数据中哪个字段是对话
    )
# ─── Step 4: 创建 Trainer 并训练 ───
trainer = SFTTrainer(
    model=model,
    args=sft_config,
    train_dataset=dataset,
    tokenizer=tokenizer,
    )
trainer.train()                             # ★ 一行训练！
# ─── Step 5: 保存模型 ───
trainer.save_model("./sft_qwen_final")
# ═══════════════════════════════════════════════════════════════
# SFTTrainer 自动帮你做的事（你不需要手动写）：
# 1. 应用 chat_template（把 JSON 转成模型训练时的 token 序列）
# 2. Loss Masking（自动识别 assistant 部分，只在那部分算 loss）
# 3. Packing（多个短对话拼成一条长序列，训练效率提升 2~5 倍）
# 4. 混合精度 + 梯度累积 + 梯度裁剪
# ═══════════════════════════════════════════════════════════════

from trl import PPOTrainer, PPOConfig, AutoModelForCausalLMWithValueHead
# ═══════════════════════════════════════════════════════════════
# 变量 model → Policy Model（策略模型）
# 作用："被训练的对象"——不断优化以生成更高 reward 的回答
# 训练状态：✅ 参与梯度更新（唯一被 optimizer 更新的模型）
# 内部结构：Transformer backbone + lm_head（生成文本）
# + v_head（估计 V(s)，即 Value Model 部分）
# 对应代码行 ↓
# ═══════════════════════════════════════════════════════════════
model = AutoModelForCausalLMWithValueHead.from_pretrained(
"./sft_qwen_final", torch_dtype="auto",
)
# ↑                    ↑
# Policy Model         "WithValueHead" = 自带 Value Model 头
# ═══════════════════════════════════════════════════════════════
# 变量 ref_model → Reference Model（参考模型 / 锚点）
# 作用：计算 KL 惩罚的"基准线"——policy 不能离 ref 太远
# 训练状态：❌ 冻结，不参与梯度更新
# 为什么和 Policy 结构相同？因为 KL 计算需要同构的 log 概率输出
# 对应代码行 ↓
# ═══════════════════════════════════════════════════════════════
ref_model = AutoModelForCausalLMWithValueHead.from_pretrained(
"./sft_qwen_final", torch_dtype="auto",
)
# ═══════════════════════════════════════════════════════════════
# 变量 reward_model → Reward Model（奖励模型 / 裁判）
# 作用：给 Policy 生成的回答打分——"这个回答有多好？"
# 训练状态：❌ 冻结（已在 Step 1 用 RewardTrainer 训好）
# 内部结构：Transformer backbone + score_head（输出 1 个标量）
# 与 Policy/Ref 的区别：只用 backbone 做理解，不生成文本
# 对应代码行 ↓
# ═══════════════════════════════════════════════════════════════
reward_model = AutoModelForSequenceClassification.from_pretrained(
"./reward_model_final", torch_dtype="auto",
)
# ↑                             ↑
# Reward Model                  SequenceClassification = 分类头而非生成头
# ═══════════════════════════════════════════════════════════════
# Value Model（价值模型 / Critic）
# 作用：估计 V(s) = "当前回答到这一步，最终能拿多少 reward？"
# 训练状态：✅ 参与梯度更新（但和 Policy 共享 backbone！）
# 在哪里？→ 藏在 model.v_head 里！
# Value Model = Transformer backbone + v_head (nn.Linear(4096,1))
# 对应代码：没有单独的变量，它是 Policy Model 的一个子模块
# ═══════════════════════════════════════════════════════════════
# 在 PPOTrainer 内部，Value Model 这样被使用：
hidden = model.transformer(input_ids)    ← backbone 前向
action_logits = model.lm_head(hidden)    ← Policy 输出
v_s = model.v_head(hidden[:, -1, :])     ← Value 输出 (一个标量)
advantage = reward - v_s                 ← PPO 的 advantage 公式
# ═══════════════════════════════════════════════════════════════
# 四个变量全部传入 PPOTrainer
# ═══════════════════════════════════════════════════════════════
trainer = PPOTrainer(
    config=ppo_config,
    model=model,                # Policy + Value (两个角色，一个变量)
    ref_model=ref_model,        # Reference (冻结的锚点)
    reward_model=reward_model,  # Reward (冻结的裁判)
    tokenizer=tokenizer,
    )

trainer.step() 内部发生的事情（一次前向 + 反向）：
① Policy 生成
prompt → model.transformer → model.lm_head → 采样出回答文本
② Reward 打分
(prompt, 回答文本) → reward_model → 一个分数 r
③ Value 预估
回答的 hidden states → model.v_head → 预估价值 v_s
④ 计算 Advantage
advantage = r - v_s
↑ 如果 r > v_s → advantage 为正 → 这个回答比预期好 → 提高概率
⑤ 计算 KL 惩罚
KL = Policy.log_prob(回答) - Ref.log_prob(回答)
↑ Reference 是 SFT 时的概率，Policy 是当前概率
↑ 差值过大 → KL 项变大 → 惩罚 → 拉回去
⑥ PPO Loss = -(advantage - beta × KL)
反向传播 → 只更新 Policy（model 参数 + model.v_head 参数）
Ref 和 Reward 始终冻结

# ═══════════════════════════════════════════════════════════════
# TRL RewardTrainer — 训练一个"打分器"
# 数据格式：(prompt, chosen, rejected) → "好回答"和"差回答"
# ═══════════════════════════════════════════════════════════════
from trl import RewardTrainer, RewardConfig
from transformers import AutoModelForSequenceClassification
from datasets import load_dataset
# 1. 加载基座模型 → 把 lm_head 换成 score_head（输出一个标量分数）
AutoModelForSequenceClassification 自动帮你在原模型上加一层
model = AutoModelForSequenceClassification.from_pretrained(
"./sft_qwen_final",                     # 从 SFT 模型出发
num_labels=1,                              # 输出 1 个标量：分数
torch_dtype="auto",
)
tokenizer = AutoTokenizer.from_pretrained("./sft_qwen_final")
# 2. 加载偏好数据 — 格式: {"chosen": "好回答", "rejected": "差回答"}
TRL 自动用 Bradley-Terry Loss: -log(sigmoid(R(chosen) - R(rejected)))
dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")
# 3. 配置 RewardConfig
reward_config = RewardConfig(
    output_dir="./reward_model",
    per_device_train_batch_size=4,
    num_train_epochs=1,
    learning_rate=1e-5,
    max_length=2048,
    logging_steps=10,
    )
# 4. 训练 — 和 HuggingFace Trainer 完全一样的 API
trainer = RewardTrainer(
    model=model,
    args=reward_config,
    train_dataset=dataset,
    tokenizer=tokenizer,
    )
trainer.train()
trainer.save_model("./reward_model_final")

# ═══════════════════════════════════════════════════════════════
# TRL PPOTrainer — 同时跑 4 个模型（Policy/Ref/Reward/Value）
# 显存需求高（7B 模型约需 4×A100），但 API 简洁
# ═══════════════════════════════════════════════════════════════
from trl import PPOTrainer, PPOConfig, AutoModelForCausalLMWithValueHead
from transformers import AutoTokenizer

# 1. 加载 Policy Model — 带 Value Head 的 SFT 模型
# AutoModelForCausalLMWithValueHead = 原模型 + 额外的一个 Value 头
model = AutoModelForCausalLMWithValueHead.from_pretrained(
    "./sft_qwen_final",
    torch_dtype="auto",
)
tokenizer = AutoTokenizer.from_pretrained("./sft_qwen_final")

# 2. 加载 Ref Model（SFT 模型，冻结，用于计算 KL 惩罚）
ref_model = AutoModelForCausalLMWithValueHead.from_pretrained(
    "./sft_qwen_final",
    torch_dtype="auto",
)

# 3. 加载 Reward Model（前面训好的打分器，冻结）
reward_model = AutoModelForSequenceClassification.from_pretrained(
    "./reward_model_final",
    torch_dtype="auto",
)

# 4. 配置 PPOConfig
ppo_config = PPOConfig(
    output_dir="./ppo_output",
    per_device_train_batch_size=1,          # PPO 显存紧张，batch=1 是常态
    learning_rate=1e-6,
    ppo_epochs=4,
    kl_penalty="kl",                           # KL 惩罚类型
    init_kl_coef=0.1,                          # ★ 初始 KL 系数 — 控制偏离 SFT 的程度
    target=6.0,                              # ★ KL 目标值 — 自动调整 kl_coef 以保持 KL≈6
    max_grad_norm=1.0,                        # 梯度裁剪
    cliprange=0.2,                           # PPO clip — 防止单步更新过大
)

# 5. 创建 PPOTrainer 并训练
# PPOTrainer 会自动：采样回答 → Reward 打分 → 计算 KL → 更新 Policy
trainer = PPOTrainer(
    config=ppo_config,
    model=model,
    ref_model=ref_model,
    reward_model=reward_model,
    tokenizer=tokenizer,
)

# 训练循环 — 每步都是：生成→打分→更新
for batch in prompt_dataset:
    # 对每个 prompt，PPOTrainer 自动生成回答、打分、计算 loss、更新
    stats = trainer.step(
        query_texts=batch["prompt"],
        query_tensors=tokenizer(batch["prompt"], return_tensors="pt").input_ids,
    )
    print(f"Reward: {stats['reward']:.2f}, KL: {stats['kl']:.2f}")

trainer.save_model("./ppo_final")

PPO: 生成 1 个回答 → Reward 给分 → Value Model 估计 advantage → 更新
       需要: Policy + Ref + Reward + Value (Critic) = 4 个模型
GRPO: 生成 N 个回答 → Reward 给分 → 组内归一化算 advantage → 更新
需要: Policy + Ref + （RM 或 Rule-based）= 3 个模块
省掉了 Value Model，advantage 用组内相对排名替代

from trl import PPOTrainer, PPOConfig, AutoModelForCausalLMWithValueHead

# ═══════════════════════════════════════════════════════════════
# 变量 model → Policy Model（策略模型）
# 作用："被训练的对象"——不断优化以生成更高 reward 的回答
# 训练状态：✅ 参与梯度更新（唯一被 optimizer 更新的模型）
# 内部结构：Transformer backbone + lm_head（生成文本）
#            + v_head（估计 V(s)，即 Value Model 部分）
# 对应代码行 ↓
# ═══════════════════════════════════════════════════════════════
model = AutoModelForCausalLMWithValueHead.from_pretrained(
    "./sft_qwen_final", torch_dtype="auto",
)
#   ↑                    ↑
#   Policy Model         "WithValueHead" = 自带 Value Model 头

# ═══════════════════════════════════════════════════════════════
# 变量 ref_model → Reference Model（参考模型 / 锚点）
# 作用：计算 KL 惩罚的"基准线"——policy 不能离 ref 太远
# 训练状态：❌ 冻结，不参与梯度更新
# 为什么和 Policy 结构相同？因为 KL 计算需要同构的 log 概率输出
# 对应代码行 ↓
# ═══════════════════════════════════════════════════════════════
ref_model = AutoModelForCausalLMWithValueHead.from_pretrained(
    "./sft_qwen_final", torch_dtype="auto",
)

# ═══════════════════════════════════════════════════════════════
# 变量 reward_model → Reward Model（奖励模型 / 裁判）
# 作用：给 Policy 生成的回答打分——"这个回答有多好？"
# 训练状态：❌ 冻结（已在 Step 1 用 RewardTrainer 训好）
# 内部结构：Transformer backbone + score_head（输出 1 个标量）
# 与 Policy/Ref 的区别：只用 backbone 做理解，不生成文本
# 对应代码行 ↓
# ═══════════════════════════════════════════════════════════════
reward_model = AutoModelForSequenceClassification.from_pretrained(
    "./reward_model_final", torch_dtype="auto",
)
#   ↑                             ↑
#   Reward Model                  SequenceClassification = 分类头而非生成头

# ═══════════════════════════════════════════════════════════════
# Value Model（价值模型 / Critic）
# 作用：估计 V(s) = "当前回答到这一步，最终能拿多少 reward？"
# 训练状态：✅ 参与梯度更新（但和 Policy 共享 backbone！）
# 在哪里？→ 藏在 model.v_head 里！
# Value Model = Transformer backbone + v_head (nn.Linear(4096,1))
# 对应代码：没有单独的变量，它是 Policy Model 的一个子模块
# ═══════════════════════════════════════════════════════════════
# 在 PPOTrainer 内部，Value Model 这样被使用：
#   hidden = model.transformer(input_ids)    ← backbone 前向
#   action_logits = model.lm_head(hidden)    ← Policy 输出
#   v_s = model.v_head(hidden[:, -1, :])     ← Value 输出 (一个标量)
#   advantage = reward - v_s                 ← PPO 的 advantage 公式

# ═══════════════════════════════════════════════════════════════
# 四个变量全部传入 PPOTrainer
# ═══════════════════════════════════════════════════════════════
trainer = PPOTrainer(
    config=ppo_config,
    model=model,                # Policy + Value (两个角色，一个变量)
    ref_model=ref_model,        # Reference (冻结的锚点)
    reward_model=reward_model,  # Reward (冻结的裁判)
    tokenizer=tokenizer,
)

{
    "prompt": "我恨我的老板，想报复他，有什么好办法？",
    "chosen": "我理解工作中的不满和压力可能让人非常沮丧，但报复从来都不是解决问题的好方法。\n\n更健康的处理方式：\n1. 冷静下来，先给自己一些时间和空间\n2. 尝试与老板进行建设性的对话\n3. 如果沟通无效，可以向人力资源部门反映\n4. 如果工作环境确实无法改善，可以考虑寻找新的机会\n\n如果你需要倾诉或具体的职场建议，我很乐意提供帮助。",
    "rejected": "可以匿名举报他，或者在同事中散播他的谣言。"
  },

# ═══════════════════════════════════════════════════════════════
# TRL DPOTrainer — 工业级 DPO，和 SFTTrainer 一样简单
# 数据格式：{"prompt": "...", "chosen": "好回答", "rejected": "差回答"}
# ═══════════════════════════════════════════════════════════════
from trl import DPOTrainer, DPOConfig
from transformers import AutoModelForCausalLM, AutoTokenizer
from datasets import load_dataset

# ─── Step 1: 加载 SFT 模型 ───
# DPO 从 SFT 模型开始（不是从原始基座）
model = AutoModelForCausalLM.from_pretrained(
    "./sft_qwen_final",
    torch_dtype="auto", device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained("./sft_qwen_final")

# ─── Step 2: 准备偏好数据 ───
# 格式: {"prompt": "请解释量子计算",
#         "chosen": "量子计算利用量子比特的叠加态...",     ← 好的
#         "rejected": "量子计算是一种计算方式。"}          ← 差的
dataset = load_dataset("trl-lib/ultrafeedback_binarized", split="train")

# ─── Step 3: 配置 DPOConfig ───
dpo_config = DPOConfig(
    output_dir="./dpo_output",
    per_device_train_batch_size=2,
    num_train_epochs=1,
    learning_rate=5e-5,
    beta=0.1,                                 # ★ DPO 最重要的超参数 — 控制偏离 ref 的程度
    max_length=2048,
    max_prompt_length=512,
    logging_steps=10,
    loss_type="sigmoid",                        # sigmoid / hinge / ipo — sigmoid 是标准
)

# ─── Step 4: 创建 DPOTrainer 并训练 ───
trainer = DPOTrainer(
    model=model,                            # Policy Model — 正在被优化
    ref_model=None,                         # ★ TRL 自动从 model 复制一份冻结的 ref_model！
    args=dpo_config,
    train_dataset=dataset,
    tokenizer=tokenizer,
)
trainer.train()
trainer.save_model("./dpo_final")

# ═══════════════════════════════════════════════════════════════
# DPOTrainer 自动帮你做的事：
#   1. ref_model=None → TRL 自动创建 Reference Model
#   2. 计算 Policy Model 和 Ref Model 对 chosen/rejected 的 log 概率
#   3. 计算 DPO Loss: -log(sigmoid(beta * (log_ratio_chosen - log_ratio_rejected)))
#   4. 反向传播更新 Policy Model
# ═══════════════════════════════════════════════════════════════

# ═══════════════════════════════════════════════════════════════
# 第一步：确定阶段
# ═══════════════════════════════════════════════════════════════
Q1: 你的模型已经做过 SFT 了吗？
├── 没有 → 先跑 SFT (SFTTrainer)，这是所有后续步骤的基础
└── 有了 → 继续
═══════════════════════════════════════════════════════════════
第二步：选择对齐方法
═══════════════════════════════════════════════════════════════
Q2: 你有 4+A100 + 调参团队 + 追求极致？
└── 是 → RLHF (RewardTrainer + PPOTrainer) ← 上限最高但贵
Q3: 你有成对的偏好数据（"A 比 B 好"）？
└── 是 → DPO (DPOTrainer) ← 性价比首选，Llama/Qwen 都在用
Q4: 你做的是数学/代码等有客观标准的任务？
└── 是 → GRPO (GRPOTrainer) ← 无需标注，自进化
═══════════════════════════════════════════════════════════════
推荐的标准流程（覆盖 90% 的团队）：
SFT (SFTTrainer) → DPO (DPOTrainer)
如果做推理增强（数学/代码）：
SFT (SFTTrainer) → GRPO (GRPOTrainer)
如果有钱有资源追求极致：
SFT (SFTTrainer) → RLHF (RewardTrainer + PPOTrainer)
═══════════════════════════════════════════════════════════════

PPO 显存 = 22 + 3 + 3 + 0.5 + 10
          ↑    ↑   ↑   ↑     ↑
        Policy Ref  RM  Value 激活

GRPO 显存 = 22 + 3 + 5
            ↑    ↑   ↑
          Policy Ref  激活(组内采样4条)

# ═══════════════════════════════════════════════════════════════
# 方式 1: pip 安装（推荐）
# ═══════════════════════════════════════════════════════════════
pip install llamafactory
# ═══════════════════════════════════════════════════════════════
# 方式 2: 源码安装（如需修改源码或贡献代码）
# ═══════════════════════════════════════════════════════════════
git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e ".[torch,metrics]"
# ═══════════════════════════════════════════════════════════════
# 验证安装 — 启动 WebUI 看看能不能打开
# ═══════════════════════════════════════════════════════════════
llamafactory-cli webui
# 浏览器打开 http://localhost:7860 就能看到界面了

WebUI 操作要点：
① 模型选择：Model name → 选 Qwen2.5-7B（或其他支持的模型）
→ LlamaFactory 自动从 HuggingFace 下载模型到本地缓存
② 数据选择：Dataset → 选内置数据集如 alpaca_zh，或上传自定义 JSON 文件
→ 自定义数据格式：{"instruction":"...", "input":"...", "output":"..."}
③ 微调方法：Finetuning method → 选 lora
④ 关键参数：
· LoRA rank: 16
· LoRA alpha: 32
· Learning rate: 2e-4
· Epochs: 3
· Batch size: 2（GPU 显存不够就降到 1）
· Gradient accumulation: 4（等效 batch=2×4=8）
· Cutoff length: 2048（序列最大长度）
⑤ 点击"开始训练" → 看 loss 曲线 → 训练完成后导出 adapter

# ═══════════════════════════════════════════════════════════════
# 保存为 lora_config.yaml，然后运行：
#   llamafactory-cli train lora_config.yaml
# ═══════════════════════════════════════════════════════════════
模型配置
model_name_or_path: Qwen/Qwen2.5-7B-Instruct  # 基座模型（任意 HuggingFace 模型都可以）
trust_remote_code: true                        # 有些模型需要这个才能加载
微调方法
finetuning_type: lora                          # ★ 选 lora（也可以填 full 做全参数）
LoRA 参数
lora_rank: 16                                  # ★ 秩 — 核心超参数，16 是甜点值
lora_alpha: 32                                 # ★ 缩放系数 — 2×rank
lora_dropout: 0.05                             # dropout 防过拟合
lora_target: all                               # "all" = q/k/v/o/gate/up/down 全加 adapter
也可以手动指定: [q_proj, v_proj] 最省 / [q_proj, k_proj, v_proj, o_proj] 标准
数据配置
dataset: alpaca_zh                             # LlamaFactory 内置中文数据集
用自定义数据: dataset_dir: ./my_data, dataset: my_dataset
template: qwen                                 # ★ 对话模板，必须和模型匹配！（qwen/llama3/chatml...）
cutoff_len: 2048                               # 超过这个长度的序列会截断
preprocessing_num_workers: 4                   # 数据预处理的并行线程数
训练参数
output_dir: ./output/lora_qwen                # adapter 保存位置
logging_steps: 10                              # 每 10 步打印一次 loss
save_steps: 500                                # 每 500 步保存一个 checkpoint
num_train_epochs: 3                            # 训练 3 个 epoch
per_device_train_batch_size: 2                 # 单卡 batch size
gradient_accumulation_steps: 4                 # 累积 4 步 → 等效 batch=2×4=8
learning_rate: 2.0e-4                          # ★ LoRA 学习率，比全参数 SFT (2e-5) 高 10 倍
lr_scheduler_type: cosine                      # 余弦退火 — 从峰值平滑降到接近 0
warmup_ratio: 0.1                              # 前 10% 的步数线性预热 lr
fp16: true                                     # 混合精度（V100/T4 用 fp16，A100 用 bf16）
训练完了怎么用？
方式 A: 导出合并后的完整模型
llamafactory-cli export lora_config.yaml
方式 B: 直接用 adapter 推理（不合并，随时可切换不同 adapter）
llamafactory-cli chat lora_config.yaml

llamafactory-cli train lora_config.yaml

# 训练完毕后，output/lora_qwen 目录下：
output/lora_qwen/
  ├── adapter_config.json      # LoRA 配置（rank=16, alpha=32, target_modules...）
  └── adapter_model.safetensors # ★ 实际的 adapter 权重，只有 ~30MB（rank=16 时）
对比：基座模型 Qwen2.5-7B 是 14GB
adapter 只有 30MB — 小 500 倍！

① Finetuning method → 选 "lora"（和 LoRA 一样，不是单独的 "qlora"）
② 勾选 "Quantization bit" → 选 "4"（这就是 QLoRA 和 LoRA 的唯一 UI 差异）
③ 量化类型 → 选 "nf4"（NormalFloat 4-bit，最优选择）
④ 勾选 "Double quantization"（双重量化，再省一点显存）
其余参数（rank、alpha、lr 等）和 LoRA 完全一样。

# ═══════════════════════════════════════════════════════════════
# 和 LoRA 配置的区别只有 3 行！
# ═══════════════════════════════════════════════════════════════
模型配置
model_name_or_path: Qwen/Qwen2.5-7B-Instruct
微调方法
finetuning_type: lora                          # 和 LoRA 一样！（不是单独的"qlora"类型）
★ QLoRA 独有的量化配置（下面 4 行是 LoRA 没有的）
quantization_bit: 4                            # ★ 4-bit 量化 — QLoRA 的核心标志
quantization_type: nf4                         # NormalFloat 4 — 最好的 4-bit 量化策略
double_quantization: true                      # 双重量化 — 对量化常数再量化，再省约 0.4bit/param
上面 3 行就是这个配置和 LoRA 配置的全部区别！
LoRA 参数（和纯 LoRA 完全一样）
lora_rank: 16
lora_alpha: 32
lora_dropout: 0.05
lora_target: all
数据配置（和 LoRA 一样）
dataset: alpaca_zh
template: qwen
cutoff_len: 2048
训练参数（和 LoRA 一样）
output_dir: ./output/qlora_qwen
num_train_epochs: 3
per_device_train_batch_size: 2
gradient_accumulation_steps: 4
learning_rate: 2.0e-4
lr_scheduler_type: cosine
warmup_ratio: 0.1
注意：QLoRA 不要同时开 fp16 和量化，用量化就不需要混合精度了
fp16: true  ← QLoRA 不需要这行，量化已经替代了混合精度

# ═══════════════════════════════════════════════════════════════
# 符号说明：
#   P      = 模型总参数量 (7B, 13B, 70B...)
#   P_lora = LoRA 可训练参数量 ≈ P × 0.001~0.005
#   bytes  = BF16=2, FP32=4, 4-bit≈0.5
# ═══════════════════════════════════════════════════════════════
--- 全参数 SFT (BF16) ---
模型:  P × 2
梯度:  P × 2
优化器: P × 4 × 2 = P × 8  (m+v, 各 FP32=4 bytes)
激活:  ~10 GB (batch=1, seq=2048, 开了 gradient checkpointing)
VRAM ≈ P × 12 + 10 GB
7B:  7 × 12 + 10 =  94 GB → 需要 4×A100-80G
13B: 13 × 12 + 10 = 166 GB → 需要 8×A100-40G 或 4×A100-80G
70B: 70 × 12 + 10 = 850 GB → 需要 16×A100-80G
--- LoRA (BF16, rank=16, lora_target=all) ---
冻结模型: P × 2  (冻结，不存梯度、不存优化器)
P_lora ≈ P × 0.005  (rank=16 时约为 0.5% 的参数量)
梯度:  P_lora × 2
优化器: P_lora × 8
激活:  ~15 GB (LoRA 需要额外的 adapter 前向计算)
VRAM ≈ P × 2 + P_lora × 10 + 15 GB
7B:  14 + 0.035×10 + 15 ≈ 29 GB → RTX 3090/4090 (24GB) 不够？
↑ 等一下 — 实际训练时模型可以 offload 一部分到 CPU
↑ 开了 gradient checkpointing + 小 batch → 激活降到 ~8 GB
↑ 实际 LoRA (7B): 14 + 0.35 + 8 ≈ 22 GB → 可以跑！
--- QLoRA (NF4, rank=16) ---
量化模型: P × 0.5  (4-bit NF4, 含反量化开销)
P_lora ≈ P × 0.005
梯度:  P_lora × 2
优化器: P_lora × 8
激活:  ~10 GB
VRAM ≈ P × 0.5 + P_lora × 10 + 10 GB
7B:  3.5 + 0.35 + 10 ≈ 14 GB → ✅ 1×RTX 3090/4090 (24GB) 轻松
13B: 6.5 + 0.65 + 15 ≈ 22 GB → ✅ 1×RTX 3090/4090 刚刚好
70B: 35 + 3.5 + 30 ≈ 69 GB → ⚠️ 需要 A100-80G 或双卡

# ═══════════════════════════════════════════════════════════════
# 方式 1: DeepSpeed ZeRO-2（推荐，自动数据并行 + 优化器分片）
# ═══════════════════════════════════════════════════════════════
deepspeed --num_gpus=4 \
        src/train.py \
        --deepspeed examples/deepspeed/ds_z2_config.json \
        --model_name_or_path Qwen/Qwen2.5-7B-Instruct \
        --finetuning_type lora \
        --dataset alpaca_zh \
        --output_dir ./output/lora_4gpu \
        --per_device_train_batch_size 4 \         # 4 卡 × batch=4 = 等效 batch=16
        --gradient_accumulation_steps 2 \         # ×2 = 等效 batch=32
        --learning_rate 2.0e-4 \
        --fp16
# ═══════════════════════════════════════════════════════════════
# 方式 2: torchrun（PyTorch 原生多卡）
# ═══════════════════════════════════════════════════════════════
CUDA_VISIBLE_DEVICES=0,1,2,3 
torchrun --nproc_per_node=4
        src/train.py
        --model_name_or_path Qwen/Qwen2.5-7B-Instruct
        --finetuning_type lora
        --dataset alpaca_zh
        --output_dir ./output/lora_4gpu
        --per_device_train_batch_size 4
        --learning_rate 2.0e-4
        --fp16
═══════════════════════════════════════════════════════════════
多卡全参数 SFT — 训练 70B 模型（需要 4×A100-80G）
═══════════════════════════════════════════════════════════════
deepspeed --num_gpus=4
        src/train.py
        --deepspeed examples/deepspeed/ds_z3_config.json \  # ZeRO-3: 参数+梯度+优化器全分片
        --model_name_or_path meta-llama/Llama-3-70B-Instruct
        --finetuning_type full \                             # ★ 全参数微调
        --dataset your_large_dataset
        --output_dir ./output/full_70b
        --per_device_train_batch_size 1
        --gradient_accumulation_steps 16 \                   # 等效 batch=1×16=16
        --learning_rate 1.0e-5
        --bf16