#参数高效微调PEFT：LoRA与QLoRA大模型微调技术完整指南

def peft_definition():
    """
    PEFT核心定义与意义
    """
    print("PEFT = Parameter-Efficient Fine-Tuning")
    print("目标：通过微调少量参数实现高效的大模型适应")
    
    # 核心概念
    core_concepts = {
        "参数效率": "只微调模型的一小部分参数",
        "性能保持": "保持与全量微调相当的性能",
        "成本降低": "大幅减少计算和存储需求",
        "可扩展性": "支持多任务、多领域的并行适应"
    }
    
    print("\n核心概念:")
    for concept, description in core_concepts.items():
        print(f"  {concept}: {description}")

peft_definition()

def peft_importance():
    """
    PEFT的重要性分析
    """
    importance_factors = [
        {
            "factor": "资源效率",
            "description": "大幅减少GPU内存和计算需求"
        },
        {
            "factor": "存储节省", 
            "description": "每个任务只需保存少量参数"
        },
        {
            "factor": "训练速度",
            "description": "更快的训练和推理速度"
        },
        {
            "factor": "可扩展性",
            "description": "支持大规模多任务学习"
        }
    ]
    
    print("PEFT的重要性:")
    for factor in importance_factors:
        print(f"  {factor['factor']}: {factor['description']}")

peft_importance()

def full_finetuning_challenges():
    """
    全量微调的主要挑战
    """
    print("全量微调的典型问题:")
    
    challenges = [
        {
            "challenge": "计算资源需求高",
            "example": "GPT-3（175B参数）全量微调需要8×80GB A100 GPU",
            "impact": "成本高昂，普通用户无法承担"
        },
        {
            "challenge": "存储成本高",
            "example": "每个任务都需要复制完整模型",
            "impact": "存储空间需求巨大"
        },
        {
            "challenge": "训练时间长",
            "example": "完整模型训练周期长",
            "impact": "迭代效率低"
        },
        {
            "challenge": "版本管理困难",
            "example": "每个微调版本都是完整副本",
            "impact": "模型版本管理复杂"
        }
    ]
    
    for challenge in challenges:
        print(f"\n{challenge['challenge']}:")
        print(f"  示例: {challenge['example']}")
        print(f"  影响: {challenge['impact']}")

full_finetuning_challenges()

def peft_solution():
    """
    PEFT如何解决全量微调问题
    """
    solution_approach = """
    PEFT解决方案：
    
    1. 参数选择性更新
       - 只更新模型的特定子集
       - 冻结大部分原始参数
       - 保持原始模型完整性
    
    2. 增量学习
       - 通过少量参数增量实现适应
       - 不改变原始模型结构
       - 支持多任务并行适应
    
    3. 高效存储
       - 只保存增量参数
       - 大幅减少存储需求
       - 简化版本管理
    """
    
    print(solution_approach)

peft_solution()

def lora_basic_principle():
    """
    LoRA基本原理解析
    """
    principle = """
    LoRA工作原理：
    
    核心洞察：
    - 大模型权重矩阵通常是低秩的
    - 参数更新也具有低秩特性
    - 可以用低秩矩阵近似表示更新
    
    数学表示：
    全量更新：W_new = W_old + ΔW
    LoRA更新：W_new = W_old + (B × A)
    
    其中：
    - B: (r, d_out) 矩阵
    - A: (d_in, r) 矩阵
    - r: 低秩参数，通常为4-16
    - r << min(d_in, d_out)
    
    参数节省：
    原始更新：d_in × d_out
    LoRA更新：r × (d_in + d_out)
    节省比例：约 r/(min(d_in, d_out))
    """
    
    print("LoRA基本原理:")
    print(principle)

lora_basic_principle()

def lora_mathematical_formulation():
    """
    LoRA数学公式详解
    """
    formulas = """
    LoRA数学公式：
    
    1. 基础公式：
       h = W_0 x + (ΔW)x
       
    2. LoRA分解：
       ΔW = B × A
       h = W_0 x + (B × A)x
       
    3. 缩放因子：
       ΔW = (α/r) × B × A
       h = W_0 x + (α/r) × (B × A)x
       
    其中：
    - W_0: 原始冻结权重
    - B: 可训练矩阵 (r, d_out)
    - A: 可训练矩阵 (d_in, r)  
    - α: 缩放因子
    - r: 低秩参数
    """
    
    print("LoRA数学公式:")
    print(formulas)

lora_mathematical_formulation()

def lora_implementation_example():
    """
    LoRA实现示例
    """
    implementation_code = """
    import torch
    import torch.nn as nn

    class LoRALayer(nn.Module):
        def __init__(self, in_features, out_features, rank=8, alpha=16):
            super(LoRALayer, self).__init__()
            self.rank = rank
            self.alpha = alpha
            self.scaling = alpha / rank
            
            # 初始化LoRA参数
            self.lora_A = nn.Parameter(
                torch.randn(rank, in_features) * 0.01
            )
            self.lora_B = nn.Parameter(
                torch.zeros(out_features, rank)
            )
            
            # 冻结原始权重
            self.weight.requires_grad = False

        def forward(self, x):
            # 原始输出
            original_output = torch.matmul(x, self.weight.t()) + self.bias
            
            # LoRA增量
            lora_intermediate = torch.matmul(x, self.lora_A.t())
            lora_output = torch.matmul(lora_intermediate, self.lora_B.t())
            
            # 缩放并添加
            lora_output = lora_output * self.scaling
            
            return original_output + lora_output

    # 实际应用中的LoRA线性层
    class LinearWithLoRA(nn.Linear):
        def __init__(self, in_features, out_features, rank=8, alpha=16, **kwargs):
            super().__init__(in_features, out_features, **kwargs)
            self.lora_layer = LoRALayer(in_features, out_features, rank, alpha)
        
        def forward(self, x):
            # 原始线性变换
            original_output = super().forward(x)
            # 加上LoRA增量
            lora_output = self.lora_layer(x)
            return lora_output
    """
    
    print("LoRA实现示例:")
    print(implementation_code)

lora_implementation_example()

def lora_configuration_params():
    """
    LoRA配置参数详解
    """
    config_params = [
        {
            "parameter": "rank (r)",
            "range": "4-32",
            "default": "8-16",
            "description": "低秩参数，影响模型容量和性能"
        },
        {
            "parameter": "alpha",
            "range": "8-64", 
            "default": "16-32",
            "description": "缩放因子，控制LoRA影响强度"
        },
        {
            "parameter": "dropout",
            "range": "0.0-0.1",
            "default": "0.05",
            "description": "防止过拟合的dropout率"
        },
        {
            "parameter": "target_modules",
            "range": "特定层名称",
            "default": "attention层",
            "description": "应用LoRA的具体模块"
        }
    ]
    
    print("LoRA配置参数:")
    for param in config_params:
        print(f"\n{param['parameter']}:")
        print(f"  范围: {param['range']}")
        print(f"  默认: {param['default']}")
        print(f"  说明: {param['description']}")

lora_configuration_params()

def qlora_basic_principle():
    """
    QLoRA基本原理解析
    """
    principle = """
    QLoRA工作原理：
    
    核心技术：
    1. 4位量化（NF4）
       - 将权重从FP16量化到4位
       - 大幅减少内存需求
       - 保持模型精度
    
    2. LoRA适配
       - 在量化模型上应用LoRA
       - 进一步减少参数量
       - 保持高效训练
    
    3. 双重量化
       - 4位权重 + 4位激活
       - 最大化内存节省
       - 优化推理效率
    
    效果：
    - 65B参数模型可在48GB GPU上微调
    - 与全量BF16微调性能相当
    - 成本降低90%以上
    """
    
    print("QLoRA基本原理:")
    print(principle)

qlora_basic_principle()

def quantization_techniques():
    """
    量化技术详解
    """
    quantization_methods = [
        {
            "method": "NF4 (Normal Float 4)",
            "precision": "4位",
            "use_case": "权重量化，保持统计特性",
            "advantage": "针对正态分布权重优化"
        },
        {
            "method": "Int4",
            "precision": "4位",
            "use_case": "通用整数量化",
            "advantage": "硬件支持广泛"
        },
        {
            "method": "Float8",
            "precision": "8位",
            "use_case": "平衡精度和效率",
            "advantage": "保持较高精度"
        }
    ]
    
    print("量化技术对比:")
    for method in quantization_methods:
        print(f"\n{method['method']}:")
        print(f"  精度: {method['precision']}")
        print(f"  应用: {method['use_case']}")
        print(f"  优势: {method['advantage']}")

quantization_techniques()

def qlora_implementation_example():
    """
    QLoRA实现示例
    """
    implementation_code = """
    import torch
    from transformers import AutoModelForCausalLM, AutoTokenizer
    from transformers import BitsAndBytesConfig
    from peft import LoraConfig, get_peft_model, TaskType

    # 4位量化配置
    bnb_config = BitsAndBytesConfig(
        load_in_4bit=True,                           # 4位量化
        bnb_4bit_use_double_quant=True,              # 双重量化
        bnb_4bit_quant_type="nf4",                   # NF4量化类型
        bnb_4bit_compute_dtype=torch.bfloat16        # 计算精度
    )

    # 加载量化模型
    model = AutoModelForCausalLM.from_pretrained(
        "microsoft/DialoGPT-medium",
        quantization_config=bnb_config,
        device_map="auto"                            # 自动设备映射
    )

    # LoRA配置
    lora_config = LoraConfig(
        task_type=TaskType.CAUSAL_LM,
        inference_mode=False,
        r=16,                                        # LoRA秩
        lora_alpha=32,                               # 缩放因子
        lora_dropout=0.1,                            # dropout
        target_modules=[                             # 目标模块
            "q_proj",
            "k_proj", 
            "v_proj",
            "o_proj",
            "gate_proj",
            "up_proj",
            "down_proj"
        ]
    )

    # 应用PEFT
    model = get_peft_model(model, lora_config)

    # 训练配置
    from transformers import TrainingArguments, Trainer

    training_args = TrainingArguments(
        output_dir="./qlora_model",
        num_train_epochs=3,
        per_device_train_batch_size=1,               # 小批次适应量化模型
        gradient_accumulation_steps=16,              # 梯度累积补偿
        optim="paged_adamw_32bit",                   # 优化器
        logging_steps=10,
        save_strategy="epoch",
        learning_rate=2e-4,
        bf16=True,
        fp16=False,
        group_by_length=True,
        report_to="none"
    )

    # 创建训练器
    trainer = Trainer(
        model=model,
        args=training_args,
        train_dataset=train_dataset,
        eval_dataset=test_dataset,
        tokenizer=tokenizer,
    )

    # 开始训练
    trainer.train()
    """
    
    print("QLoRA实现示例:")
    print(implementation_code)

qlora_implementation_example()

def qlora_performance_optimization():
    """
    QLoRA性能优化策略
    """
    optimization_strategies = [
        {
            "strategy": "梯度累积",
            "method": "增大accumulation_steps",
            "benefit": "补偿小批次大小"
        },
        {
            "strategy": "混合精度",
            "method": "使用bfloat16",
            "benefit": "平衡精度和效率"
        },
        {
            "strategy": "设备映射",
            "method": "device_map='auto'",
            "benefit": "优化显存使用"
        },
        {
            "strategy": "梯度检查点",
            "method": "gradient_checkpointing",
            "benefit": "减少显存峰值"
        }
    ]
    
    print("QLoRA性能优化策略:")
    for strategy in optimization_strategies:
        print(f"\n{strategy['strategy']}:")
        print(f"  方法: {strategy['method']}")
        print(f"  益处: {strategy['benefit']}")

qlora_performance_optimization()

def adapter_method():
    """
    Adapter方法详解
    """
    adapter_info = """
    Adapter方法：
    
    原理：
    - 在预训练模型层之间插入小型适配器层
    - 保持原始模型参数不变
    - 只训练适配器参数
    
    优点：
    - 架构简单，易于实现
    - 可插拔，支持多任务
    - 训练稳定
    
    缺点：
    - 增加推理延迟
    - 参数量相对较大
    
    典型配置：
    - 降维比例：通常为64:1
    - 激活函数：GELU
    - 归一化：LayerNorm
    """
    
    print("Adapter方法:")
    print(adapter_info)

adapter_method()

def prefix_tuning_method():
    """
    Prefix Tuning方法详解
    """
    prefix_info = """
    Prefix Tuning方法：
    
    原理：
    - 在输入序列前添加可学习的虚拟token
    - 通过这些prefix tokens影响模型行为
    - 不修改原始模型参数
    
    优点：
    - 参数量极小
    - 保持模型架构不变
    - 适合生成任务
    
    缺点：
    - 对序列长度敏感
    - 需要调整prefix长度
    
    应用场景：
    - 文本生成任务
    - 对话系统
    - 语言模型适配
    """
    
    print("Prefix Tuning方法:")
    print(prefix_info)

prefix_tuning_method()

def prompt_tuning_method():
    """
    Prompt Tuning方法详解
    """
    prompt_info = """
    Prompt Tuning方法：
    
    原理：
    - 学习连续的"软提示"向量
    - 代替传统的离散提示词
    - 优化提示词的连续表示
    
    优点：
    - 参数量最小
    - 简单高效
    - 适合少样本学习
    
    缺点：
    - 表达能力有限
    - 需要大量调优
    
    与传统提示的区别：
    - 硬提示：离散token序列
    - 软提示：连续向量表示
    - 可学习优化
    """
    
    print("Prompt Tuning方法:")
    print(prompt_info)

prompt_tuning_method()

def peft_methods_comparison():
    """
    PEFT方法全面对比
    """
    comparison_table = [
        {
            "方法": "LoRA",
            "参数量": "~0.1%",
            "性能": "优秀",
            "易用性": "高",
            "适用场景": "通用微调"
        },
        {
            "方法": "QLoRA", 
            "参数量": "~0.1%",
            "性能": "优秀",
            "易用性": "中",
            "适用场景": "大模型微调"
        },
        {
            "方法": "Adapter",
            "参数量": "1-5%",
            "性能": "良好",
            "易用性": "中",
            "适用场景": "多任务学习"
        },
        {
            "方法": "Prefix Tuning",
            "参数量": "~0.1%",
            "性能": "良好",
            "易用性": "中",
            "适用场景": "生成任务"
        },
        {
            "方法": "Prompt Tuning",
            "参数量": "~0.01%",
            "性能": "一般",
            "易用性": "高",
            "适用场景": "少样本学习"
        }
    ]
    
    print("PEFT方法对比:")
    print(f"{'方法':<12} {'参数量':<10} {'性能':<8} {'易用性':<8} {'适用场景':<12}")
    print("-" * 60)
    for item in comparison_table:
        print(f"{item['方法']:<12} {item['参数量']:<10} {item['性能']:<8} {item['易用性']:<8} {item['适用场景']:<12}")

peft_methods_comparison()

def huggingface_peft_integration():
    """
    Hugging Face PEFT集成示例
    """
    integration_example = """
    from transformers import AutoModelForCausalLM, AutoTokenizer
    from peft import LoraConfig, TaskType, get_peft_model
    import torch

    # 1. 加载基础模型
    model_name = "microsoft/DialoGPT-medium"
    model = AutoModelForCausalLM.from_pretrained(
        model_name,
        torch_dtype=torch.float16,
        device_map="auto"
    )
    tokenizer = AutoTokenizer.from_pretrained(model_name)

    # 2. 配置LoRA
    peft_config = LoraConfig(
        task_type=TaskType.CAUSAL_LM,
        inference_mode=False,
        r=8,
        lora_alpha=32,
        lora_dropout=0.1,
        target_modules=["c_attn"]  # GPT模型的注意力层
    )

    # 3. 应用PEFT
    model = get_peft_model(model, peft_config)

    # 4. 训练
    model.train()
    # ... 训练代码 ...

    # 5. 保存
    model.save_pretrained("./peft_model")
    tokenizer.save_pretrained("./peft_model")
    """
    
    print("Hugging Face PEFT集成示例:")
    print(integration_example)

huggingface_peft_integration()

def peft_inference_example():
    """
    PEFT模型加载与推理示例
    """
    inference_example = """
    from transformers import AutoModelForCausalLM, AutoTokenizer
    from peft import PeftModel
    import torch

    # 1. 加载基础模型
    base_model = AutoModelForCausalLM.from_pretrained(
        "microsoft/DialoGPT-medium",
        torch_dtype=torch.float16
    )
    tokenizer = AutoTokenizer.from_pretrained("microsoft/DialoGPT-medium")

    # 2. 加载PEFT适配器
    model = PeftModel.from_pretrained(base_model, "./peft_model")

    # 3. 推理
    inputs = tokenizer("Hello, how are you?", return_tensors="pt")
    
    with torch.no_grad():
        outputs = model.generate(
            **inputs,
            max_length=100,
            num_return_sequences=1,
            temperature=0.7,
            pad_token_id=tokenizer.eos_token_id
        )
    
    response = tokenizer.decode(outputs[0], skip_special_tokens=True)
    print(response)
    """
    
    print("PEFT模型加载与推理示例:")
    print(inference_example)

peft_inference_example()

def memory_optimization_strategies():
    """
    PEFT显存优化策略
    """
    optimization_strategies = [
        {
            "strategy": "梯度检查点",
            "implementation": "model.gradient_checkpointing_enable()",
            "memory_reduction": "~30-50%"
        },
        {
            "strategy": "混合精度训练",
            "implementation": "bf16=True, fp16=True",
            "memory_reduction": "~50%"
        },
        {
            "strategy": "梯度累积",
            "implementation": "gradient_accumulation_steps=N",
            "memory_reduction": "通过小批次实现"
        },
        {
            "strategy": "优化器状态分片",
            "implementation": "DeepSpeed ZeRO, FSDP",
            "memory_reduction": "~75%"
        }
    ]
    
    print("PEFT显存优化策略:")
    for strategy in optimization_strategies:
        print(f"\n{strategy['strategy']}:")
        print(f"  实现: {strategy['implementation']}")
        print(f"  内存减少: {strategy['memory_reduction']}")

memory_optimization_strategies()

def training_efficiency_optimization():
    """
    PEFT训练效率优化
    """
    efficiency_tips = [
        "选择合适的rank参数：r=8-16通常效果良好",
        "调整学习率：PEFT通常需要更高的学习率(1e-3 - 1e-4)",
        "使用更大的批次大小：充分利用GPU资源",
        "合理设置训练轮数：PEFT收敛通常更快",
        "监控梯度范数：确保训练稳定性"
    ]
    
    print("PEFT训练效率优化建议:")
    for i, tip in enumerate(efficiency_tips, 1):
        print(f"  {i}. {tip}")

training_efficiency_optimization()

def large_model_finetuning_case():
    """
    大模型微调案例分析
    """
    print("大模型微调案例:")
    
    case_study = [
        {
            "case": "LLaMA系列模型",
            "size": "7B-65B参数",
            "method": "QLoRA",
            "requirements": "24-48GB GPU",
            "results": "性能接近全量微调"
        },
        {
            "case": "ChatGLM系列",
            "size": "6B-130B参数", 
            "method": "LoRA",
            "requirements": "8-24GB GPU",
            "results": "高效指令跟随能力"
        },
        {
            "case": "Qwen系列",
            "size": "1.8B-72B参数",
            "method": "LoRA/QLoRA",
            "requirements": "8-48GB GPU",
            "results": "多语言能力增强"
        }
    ]
    
    for case in case_study:
        print(f"\n{case['case']}:")
        print(f"  规模: {case['size']}")
        print(f"  方法: {case['method']}")
        print(f"  要求: {case['requirements']}")
        print(f"  结果: {case['results']}")

large_model_finetuning_case()

def enterprise_application_case():
    """
    企业应用案例分析
    """
    enterprise_cases = [
        {
            "application": "客服机器人",
            "requirement": "领域知识适配",
            "method": "LoRA",
            "benefit": "低成本定制化"
        },
        {
            "application": "代码助手",
            "requirement": "编程语言适配", 
            "method": "QLoRA",
            "benefit": "高效代码理解"
        },
        {
            "application": "内容生成",
            "requirement": "风格适配",
            "method": "Adapter",
            "benefit": "快速风格切换"
        }
    ]
    
    print("企业应用案例:")
    for case in enterprise_cases:
        print(f"\n{case['application']}:")
        print(f"  需求: {case['requirement']}")
        print(f"  方法: {case['method']}")
        print(f"  优势: {case['benefit']}")

enterprise_application_case()