图解 LoRA 低秩适配：矩阵分解如何减少 99% 训练参数

使用 Hugging Face 的 tech-qa-pairs 数据集，或自定义 JSONL 格式：

import json
from datasets import Dataset

# 自定义数据格式
data = [
    {
        "instruction": "解释 Python 装饰器的工作原理",
        "response": """**装饰器本质**：接收函数并返回新函数的可调用对象

**执行流程**：
1. Python 在模块加载时立即执行装饰器
2. 装饰器接收原函数，返回包装后的新函数
3. 原函数名被重新绑定到包装函数

**示例代码**：
```python
def timing_decorator(func):
    def wrapper(*args, **kwargs):
        import time
        start = time.time()
        result = func(*args, **kwargs)
        end = time.time()
        print(f"{func.__name__} 耗时：{end-start:.4f}s")
        return result
    return wrapper

@timing_decorator
def slow_function():
    time.sleep(1)
```"""
    }
    # ... 更多样本
]

dataset = Dataset.from_list(data)
dataset = dataset.train_test_split(test_size=0.1)
print(f"训练集：{len(dataset['train'])} 条")
print(f"测试集：{len(dataset['test'])} 条")

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig

model_name = "meta-llama/Llama-3.2-3B-Instruct"

# 配置 4-bit NF4 量化
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,  # 双重量化
)

tokenizer = AutoTokenizer.from_pretrained(model_name)
tokenizer.pad_token = tokenizer.eos_token
tokenizer.padding_side = "right"

# 加载量化模型
model = AutoModelForCausalLM.from_pretrained(
    model_name,
    quantization_config=bnb_config,
    device_map="auto",  # 自动分配到 GPU
    trust_remote_code=True,
)

print(f"模型已加载到：{model.device}")
print(f"显存占用：{torch.cuda.memory_allocated() / 1024**2:.2f} MB")

from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training

# LoRA 配置
lora_config = LoraConfig(
    r=16,  # 秩：捕获 95%+ 微调信息
    lora_alpha=32,  # 缩放因子：α=2r 是经验法则
    lora_dropout=0.05,  # 防止过拟合
    bias="none",
    task_type="CAUSAL_LM",
    # 指定要注入 LoRA 的模块
    target_modules=[
        "q_proj", "k_proj", "v_proj", "o_proj",  # Attention
        "gate_proj", "up_proj", "down_proj",     # MLP
    ],
)

# 准备模型用于 K-bit 训练
model = prepare_model_for_kbit_training(model)

# 应用 LoRA
model = get_peft_model(model, lora_config)
model.print_trainable_parameters()

# 输出示例：
# trainable params: 4,194,304 || all params: 3,212,748,800 || trainable%: 0.1305

def format_prompt(example):
    """将 instruction-response 转换为 Llama-3 对话格式"""
    prompt = f"""<|begin_of_text|><|start_header_id|>system<|end_header_id|>
你是一个技术问答专家，以结构化、简洁的方式回答问题。<|eot_id|>
<|start_header_id|>user<|end_header_id|>
{example['instruction']}<|eot_id|>
<|start_header_id|>assistant<|end_header_id|>
{example['response']}<|eot_id|>"""
    return prompt

def tokenize_function(examples):
    texts = [format_prompt({"instruction": i, "response": r})
             for i, r in zip(examples['instruction'], examples['response'])]
    tokenized = tokenizer(texts, truncation=True, max_length=512, padding="max_length")
    tokenized["labels"] = tokenized["input_ids"].copy()
    return tokenized

tokenized_dataset = dataset.map(tokenize_function, batched=True, remove_columns=dataset["train"].column_names)
print(f"输入形状：{tokenized_dataset['train']['input_ids'][0][:10]}")

from transformers import TrainingArguments
from trl import SFTTrainer

training_args = TrainingArguments(
    output_dir="./lora-tech-qa",
    per_device_train_batch_size=2,
    per_device_eval_batch_size=2,
    gradient_accumulation_steps=4,  # 有效 batch size = 2×4 = 8
    learning_rate=2e-4,
    num_train_epochs=3,
    fp16=True,  # 混合精度训练
    logging_steps=10,
    eval_strategy="steps",
    eval_steps=50,
    save_steps=50,
    max_steps=500,  # 小数据集用 step 而非 epoch
    warmup_steps=50,
    lr_scheduler_type="cosine",
    gradient_checkpointing=True,  # 减少显存占用
    optim="paged_adamw_32bit",  # QLoRA 推荐优化器
    logging_dir="./logs",
    report_to="wandb",  # 可选：使用 wandb 监控
)

trainer = SFTTrainer(
    model=model,
    args=training_args,
    train_dataset=tokenized_dataset["train"],
    eval_dataset=tokenized_dataset["test"],
    tokenizer=tokenizer,
    dataset_text_field="instruction",  # SFTTrainer 需要
    max_seq_length=512,
)

print("训练配置就绪！")

# 启动训练
train_result = trainer.train()

# 保存 LoRA 适配器
trainer.save_model("./lora-tech-qa-final")
tokenizer.save_pretrained("./lora-tech-qa-final")

# 打印训练指标
print(f"训练损失：{train_result.metrics['train_loss']:.4f}")
print(f"训练耗时：{train_result.metrics['train_runtime']:.2f} 秒")

# 可选：上传到 Hugging Face Hub
# model.push_to_hub("your-username/lora-tech-qa")
# tokenizer.push_to_hub("your-username/lora-tech-qa")

from peft import PeftModel
from transformers import AutoModelForCausalLM, AutoTokenizer

# 加载基础模型 + LoRA 适配器
base_model = AutoModelForCausalLM.from_pretrained(
    model_name,
    device_map="auto",
    torch_dtype=torch.float16,
)
model = PeftModel.from_pretrained(base_model, "./lora-tech-qa-final")

# 推理示例
def answer_question(question):
    prompt = f"""<|begin_of_text|><|start_header_id|>system<|end_header_id|>
你是一个技术问答专家。<|eot_id|>
<|start_header_id|>user<|end_header_id|>
{question}<|eot_id|>
<|start_header_id|>assistant<|end_header_id|>"""

    inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
    outputs = model.generate(
        **inputs,
        max_new_tokens=256,
        do_sample=True,
        temperature=0.7,
        top_p=0.9,
    )
    return tokenizer.decode(outputs[0], skip_special_tokens=True)

# 测试
question = "Python 中如何实现单例模式？"
print(answer_question(question))