┌──────────────────────────────────────────────────────┐
│              你需要微调模型吗？                          │
│   Prompt Engineering 能解决？ → 不需要微调              │
│   RAG 能解决？ → 不需要微调                            │
│   需要改变模型行为/风格/格式？ → 需要微调               │
└─────────────────────┬────────────────────────────────┘
                      ▼
┌──────────────────────────────────────────────────────┐
│              你的 GPU 显存是多少？                       │
│   ≤ 24GB → QLoRA（4-bit 量化 + LoRA）                 │
│   24-80GB → LoRA（16-bit 全精度 + 低秩适配）           │
│   ≥ 80GB（多卡）→ 全参数微调 / LoRA（更高 rank）       │
└─────────────────────┬────────────────────────────────┘
                      ▼
┌──────────────────────────────────────────────────────┐
│              你的任务需要什么级别？                       │
│   快速验证 / 原型 → LoRA r=16                          │
│   生产级质量 → LoRA r=64-128 或 DoRA                  │
│   最高质量 / 安全关键 → 全参数微调                      │
└──────────────────────────────────────────────────────┘

W_updated = W - η · ∇L(W)

Y = (W + B·A) · X

其中：
  W ∈ R^(d×d)        — 冻结的预训练权重
  A ∈ R^(r×d)        — 降维矩阵（可训练）
  B ∈ R^(d×r)        — 升维矩阵（可训练）
  r << d              — 秩（rank），通常 8-64

# 合并前
W_effective = W + B @ A

# 合并后：推理时与原始模型完全相同的计算图
W_merged = W + B @ A  # 一次性合并
output = W_merged @ x  # 与原始模型完全相同的推理路径

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, TrainingArguments
from peft import LoraConfig, get_peft_model
from trl import SFTTrainer

model_name = "meta-llama/Llama-3.1-8B-Instruct"

model = AutoModelForCausalLM.from_pretrained(
    model_name,
    torch_dtype=torch.bfloat16,
    device_map="auto",
)
tokenizer = AutoTokenizer.from_pretrained(model_name)

lora_config = LoraConfig(
    r=64,
    lora_alpha=128,
    lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                     "gate_proj", "up_proj", "down_proj"],
    bias="none",
    task_type="CAUSAL_LM",
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()

training_args = TrainingArguments(
    output_dir="./lora_output",
    num_train_epochs=3,
    per_device_train_batch_size=4,
    gradient_accumulation_steps=8,
    learning_rate=2e-4,
    weight_decay=0.01,
    warmup_ratio=0.03,
    lr_scheduler_type="cosine",
    bf16=True,
    gradient_checkpointing=True,
    logging_steps=10,
    save_strategy="steps",
    save_steps=500,
    max_grad_norm=1.0,
    report_to="wandb",
)

trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=dataset,
    tokenizer=tokenizer,
    max_seq_length=2048,
)

trainer.train()

model.merge_and_unload()
model.save_pretrained("./merged_model")

┌─────────────────────────────────────────────────────────┐
│                   QLoRA 训练架构                          │
│                                                          │
│   预训练模型（4-bit NF4 量化）                             │
│   ┌──────────────────────────────────┐                  │
│   │  W_4bit（冻结，每个参数仅 0.5 字节）│                  │
│   └──────────────────────────────────┘                  │
│                    ↓ 前向传播时反量化                       │
│   ┌──────────────────────────────────┐                  │
│   │  W_dequant（bf16，临时反量化）     │                  │
│   └──────────────────────────────────┘                  │
│                    +                                     │
│   ┌──────────────────────────────────┐                  │
│   │  LoRA 适配器（bf16，可训练）       │                  │
│   │  A ∈ R^(r×d), B ∈ R^(d×r)       │                  │
│   └──────────────────────────────────┘                  │
│                    =                                     │
│            Y = W_dequant·X + B·A·X                       │
│                                                          │
│   优化器状态（仅针对 LoRA 参数，bf16）                      │
└─────────────────────────────────────────────────────────┘

import torch
from transformers import AutoModelForCausalLM, BitsAndBytesConfig
from peft import LoraConfig, get_peft_model

bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-70B-Instruct",
    quantization_config=bnb_config,
    device_map="auto",
)

lora_config = LoraConfig(
    r=64,
    lora_alpha=128,
    lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                     "gate_proj", "up_proj", "down_proj"],
    bias="none",
    task_type="CAUSAL_LM",
)

model = get_peft_model(model, lora_config)
model.print_trainable_parameters()
# 输出类似：trainable params: 83,886,080 || all params: 70,181,836,800 || trainable%: 0.12%

W_DoRA = m · (W₀ + B·A) / ‖W₀ + B·A‖_c

其中：
  m ∈ R^d         — 可学习的幅度向量（每列一个标量）
  (W₀ + B·A)      — 方向分量（标准 LoRA）
  ‖·‖_c            — 列归一化

from peft import LoraConfig

dora_config = LoraConfig(
    r=64,
    lora_alpha=128,
    lora_dropout=0.05,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                     "gate_proj", "up_proj", "down_proj"],
    use_dora=True,  # 启用 DoRA
)

重要性评分：I_l = ‖∇A_l‖_F + ‖∇B_l‖_F

rank 分配：r_l ∝ I_l（重要性越高，分配越多 rank）

from unsloth import FastLanguageModel

model, tokenizer = FastLanguageModel.from_pretrained(
    model_name="unsloth/Meta-Llama-3.1-8B-Instruct",
    max_seq_length=2048,
    load_in_4bit=True,
)

model = FastLanguageModel.get_peft_model(
    model,
    r=16,
    target_modules=["q_proj", "k_proj", "v_proj", "o_proj",
                     "gate_proj", "up_proj", "down_proj"],
    lora_alpha=32,
    lora_dropout=0.05,
    use_gradient_checkpointing="unsloth",
    random_state=3407,
)

{
  "instruction": "将以下英文翻译为中文",
  "input": "The quick brown fox jumps over the lazy dog.",
  "output": "敏捷的棕色狐狸跳过了懒狗。"
}

from transformers import TrainingArguments, TrainerCallback

class OverfitDetector(TrainerCallback):
    def __init__(self, patience=3):
        self.patience = patience
        self.best_val_loss = float("inf")
        self.wait = 0

    def on_evaluate(self, args, state, control, metrics, **kwargs):
        val_loss = metrics.get("eval_loss", float("inf"))
        if val_loss < self.best_val_loss:
            self.best_val_loss = val_loss
            self.wait = 0
        else:
            self.wait += 1
            if self.wait >= self.patience:
                control.should_training_stop = True
                print(f"Early stopping: val_loss hasn't improved for {self.patience} evaluations")

from peft import PeftModel
from transformers import AutoModelForCausalLM

base_model = AutoModelForCausalLM.from_pretrained(
    "meta-llama/Llama-3.1-8B-Instruct",
    torch_dtype=torch.bfloat16,
)

merged_model = PeftModel.from_pretrained(base_model, "./lora_output/checkpoint-500")
merged_model = merged_model.merge_and_unload()

merged_model.save_pretrained("./merged_model")
tokenizer.save_pretrained("./merged_model")