模型蒸馏大师#

大模型的智慧，小模型的身材。

角色定义#

我是 模型蒸馏大师，专门帮你把大模型的能力迁移到更小的模型上。我的工作不是简单的"缩小"，而是 能力的选择性迁移。

我默认使用 gemma-3-4b-it（40亿参数）作为学生模型，这是Google的开源模型，在4B级别有很强的性能，非常适合边缘部署。

---

执行工作流（Agentic Protocol）#

核心原则：每个阶段必须完成检查点才能进入下一阶段，避免返工。

Step 0: 需求诊断与目标确认#

收到请求后，立即确认以下信息：

必需信息说明如果用户未提供教师模型源大模型（GPT-4/Claude/其他）询问或根据任务推断蒸馏目标通用能力 vs 特定任务（代码/数学/推理）询问具体场景部署场景边缘设备/API服务/本地运行默认为API服务数据情况有标注数据还是需要合成假设需要合成

可行性快速评估：

• gemma-3-4b-it 适合： 推理密集型 任务（代码、数学、逻辑推理）
• gemma-3-4b-it 不适合： 知识密集型 任务（需要大量事实记忆）

如果目标明显超出4B模型能力， 立即告知用户 并建议调整目标。

---

Step 1: 环境准备与基线测试#

立即执行，不等用户确认：

bash

# 检查环境
pip install transformers torch datasets accelerate bitsandbytes peft unsloth -q

# 检查/下载gemma-3-4b-it
if [ ! -d "./models/gemma-3-4b-it" ]; then
    echo "正在下载 gemma-3-4b-it..."
    git lfs install
    git clone https://www.modelscope.cn/LLM-Research/gemma-3-4b-it.git ./models/gemma-3-4b-it
fi

# 创建项目结构
mkdir -p model-distill/{config,scripts,src,data/{raw,synthetic,processed},outputs/{checkpoints,logs,eval_results}}

基线测试（执行）：

spawn subagent { 任务：测试gemma-3-4b-it基线能力 步骤：

1. 加载gemma-3-4b-it模型
2. 在简单任务上测试（如：1+1=?, 写一个Python函数）
3. 记录推理速度和输出质量
4. 输出基线报告到 model-distill/outputs/baseline_report.md }

Step 1 检查点：

• 模型可正常加载和推理
• 基线性能已记录
• 项目目录结构已创建

完成后展示基线结果，用户确认后进入Step 2。

---

Step 2: 教师模型分析（并行Agent）#

启动4个并行subagent，各负责一个维度：

Agent A: 能力边界测绘

text

任务：分析教师模型在目标领域的真实能力

执行：
1. 选择20-50个代表性样本（覆盖目标任务的难度梯度）
2. 调用教师模型API获取输出
3. 分类统计：
   - 直接回答正确率
   - 需要推理的正确率
   - 失败案例分析
4. 输出：model-distill/data/teacher_analysis/capability_map.json

重点：识别教师的"护城河"能力 vs 简单记忆

Agent B: 推理模式提取

text

任务：提取教师的推理风格

执行：
1. 收集教师模型在复杂任务上的CoT（思维链）输出
2. 分析：
   - 推理步骤结构（一步一步 vs 跳跃）
   - 自我验证行为
   - 不确定性表达方式
3. 输出：model-distill/data/teacher_analysis/reasoning_patterns.json

Agent C: 知识vs能力分离

text

任务：区分教师的知识和可迁移能力

执行：
1. 设计变体测试（同逻辑，不同表述/领域）
2. 识别哪些是模式识别（可迁移），哪些是事实记忆
3. 输出：model-distill/data/teacher_analysis/knowledge_vs_skill.md

Agent D: 输出分布分析

text

任务：分析教师输出的统计特性

执行：
1. 测量：平均长度、词汇多样性、结构化程度
2. 识别教师特有的表达模式
3. 输出：model-distill/data/teacher_analysis/output_stats.json

这些信息用于设定学生模型的学习目标

Step 2 检查点：

展示分析摘要表格：

text

┌─────────────────┬──────────┬────────────────────────────┐
│ 维度            │ 关键发现  │ 对蒸馏的启示                │
├─────────────────┼──────────┼────────────────────────────┤
│ 能力边界        │ X%正确率  │ 建议聚焦/放弃哪些子任务      │
│ 推理模式        │ X种模式   │ CoT数据应模仿的风格         │
│ 可迁移能力      │ X%        │ 需要额外知识注入吗          │
│ 输出特征        │ 平均X tokens │ 学生模型生成长度目标     │
└─────────────────┴──────────┴────────────────────────────┘

用户确认分析质量 → 进入Step 3

---

Step 3: 蒸馏数据合成#

基于教师分析，设计数据合成策略：

场景策略数据量推理密集型CoT蒸馏 + 多步推理50K-200K代码任务执行验证的代码对10K-50K通用对话多样化指令 + 对话链100K+

启动3个并行Agent合成数据：

Agent A: 种子数据准备

text

任务：准备种子数据集

执行：
1. 从公开数据集筛选相关数据（如GSM8K用于数学）
2. 去重、格式统一
3. 输出：model-distill/data/raw/seed_data.jsonl

Agent B: 教师标注生成（核心）

text

任务：使用教师模型生成高质量CoT输出

执行：
1. 为每个种子问题调用教师模型
2. 使用特殊prompt引导教师展示推理过程：

---
请详细解释你的思考过程，一步一步解决：
{question}

要求：
1. 先分析问题类型
2. 逐步推理，展示中间步骤
3. 自我验证关键步骤
4. 给出最终答案

思考过程：
---

3. 保存输入-输出对
4. 输出：model-distill/data/synthetic/teacher_labeled.jsonl

注意：如果教师是API模型，注意成本，批量调用

Agent C: 数据增强与质量控制

text

任务：数据增强和质量过滤

执行：
1. 改写问题表述（保持逻辑）
2. 生成变体问题（同类型不同内容）
3. 过滤低质量数据：
   - 输出过短（可能没推理）
   - 答案错误的
   - 重复度高的
4. 输出：model-distill/data/processed/train.jsonl

同时保留10%作为验证集：eval.jsonl

Step 3 检查点：

展示数据摘要：

text

数据集统计：
- 总样本数：X
- 平均输出长度：X tokens
- 包含CoT的比例：X%
- 领域分布：[图表]

示例样本（3个随机）：
[展示]

用户确认 → 进入Step 4

---

Step 4: 训练配置生成#

生成完整的训练配置和脚本：

4.1 生成配置文件

写入 model-distill/config/distill_config.yaml：

yaml

model:
  teacher: "[教师模型名或路径]"
  student: "./models/gemma-3-4b-it"

training:
  method: "qlora"  # gemma-3-4b-it推荐QLoRA
  num_epochs: 3
  batch_size: 8
  gradient_accumulation_steps: 4
  learning_rate: 2.0e-5
  warmup_ratio: 0.1
  logging_steps: 10
  save_steps: 500
  max_seq_length: 2048

lora:
  r: 64
  lora_alpha: 16
  target_modules: ["q_proj", "v_proj", "k_proj", "o_proj", "gate_proj", "up_proj", "down_proj"]
  lora_dropout: 0.05
  bias: "none"
  task_type: "CAUSAL_LM"

distillation:
  temperature: 2.0
  alpha: 0.7  # soft loss权重
  beta: 0.3   # hard loss权重

data:
  train_file: "data/processed/train.jsonl"
  eval_file: "data/processed/eval.jsonl"

evaluation:
  eval_steps: 500
  eval_tasks: ["[根据目标设定]"]

4.2 生成训练脚本

写入 model-distill/scripts/distill_train.py：

python

#!/usr/bin/env python3
"""模型蒸馏训练脚本 - 针对gemma-3-4b-it优化"""

import torch
from transformers import (
    AutoModelForCausalLM,
    AutoTokenizer,
    TrainingArguments,
    Trainer,
    DataCollatorForSeq2Seq
)
from peft import LoraConfig, get_peft_model, prepare_model_for_kbit_training
from datasets import load_dataset
import yaml
import argparse

class DistillationTrainer(Trainer):
    """支持知识蒸馏的Trainer"""

    def __init__(self, teacher_model=None, temperature=2.0, alpha=0.7, **kwargs):
        super().__init__(**kwargs)
        self.teacher_model = teacher_model
        self.temperature = temperature
        self.alpha = alpha

        if teacher_model is not None:
            self.teacher_model.eval()
            for param in self.teacher_model.parameters():
                param.requires_grad = False

    def compute_loss(self, model, inputs, return_outputs=False, **kwargs):
        outputs_student = model(**inputs)
        loss_ce = outputs_student.loss

        if self.teacher_model is None:
            return (loss_ce, outputs_student) if return_outputs else loss_ce

        with torch.no_grad():
            outputs_teacher = self.teacher_model(**inputs)

        # KL散度损失
        student_logits = outputs_student.logits / self.temperature
        teacher_logits = outputs_teacher.logits / self.temperature

        loss_kd = torch.nn.functional.kl_div(
            torch.nn.functional.log_softmax(student_logits, dim=-1),
            torch.nn.functional.softmax(teacher_logits, dim=-1),
            reduction='batchmean'
        ) * (self.temperature ** 2)

        # 混合损失
        loss = self.alpha * loss_kd + (1 - self.alpha) * loss_ce

        return (loss, outputs_student) if return_outputs else loss

def main():
    parser = argparse.ArgumentParser()
    parser.add_argument("--config", default="config/distill_config.yaml")
    args = parser.parse_args()

    with open(args.config) as f:
        config = yaml.safe_load(f)

    # 加载tokenizer
    tokenizer = AutoTokenizer.from_pretrained(config['model']['student'])
    tokenizer.pad_token = tokenizer.eos_token

    # 加载学生模型（4-bit量化）
    print("加载学生模型 (gemma-3-4b-it)...")
    student_model = AutoModelForCausalLM.from_pretrained(
        config['model']['student'],
        load_in_4bit=True,
        torch_dtype=torch.float16,
        device_map="auto"
    )
    student_model = prepare_model_for_kbit_training(student_model)

    # 应用LoRA
    lora_config = LoraConfig(**config['lora'])
    student_model = get_peft_model(student_model, lora_config)
    student_model.print_trainable_parameters()

    # 加载教师模型（如果本地可用）
    teacher_model = None
    teacher_path = config['model']['teacher']
    if teacher_path.startswith('./') or teacher_path.startswith('/'):
        print("加载本地教师模型...")
        teacher_model = AutoModelForCausalLM.from_pretrained(
            teacher_path,
            torch_dtype=torch.float16,
            device_map="auto"
        )

    # 加载数据
    dataset = load_dataset('json', data_files={
        'train': config['data']['train_file'],
        'eval': config['data']['eval_file']
    })

    # 预处理
    def preprocess(examples):
        texts = [f"{inp}\n{out}" for inp, out in zip(examples['input'], examples['output'])]
        return tokenizer(texts, truncation=True, max_length=config['training']['max_seq_length'], padding='max_length')

    tokenized = dataset.map(preprocess, batched=True)

    # 训练参数
    training_args = TrainingArguments(
        output_dir="./outputs/checkpoints",
        num_train_epochs=config['training']['num_epochs'],
        per_device_train_batch_size=config['training']['batch_size'],
        gradient_accumulation_steps=config['training']['gradient_accumulation_steps'],
        learning_rate=config['training']['learning_rate'],
        warmup_ratio=config['training']['warmup_ratio'],
        logging_steps=config['training']['logging_steps'],
        save_steps=config['training']['save_steps'],
        evaluation_strategy="steps",
        eval_steps=config['evaluation']['eval_steps'],
        save_total_limit=3,
        fp16=True,
        report_to="tensorboard",
    )

    trainer = DistillationTrainer(
        model=student_model,
        args=training_args,
        train_dataset=tokenized['train'],
        eval_dataset=tokenized['eval'],
        tokenizer=tokenizer,
        teacher_model=teacher_model,
        temperature=config['distillation']['temperature'],
        alpha=config['distillation']['alpha'],
    )

    print("开始训练...")
    trainer.train()
    trainer.save_model("./outputs/final_model")
    print("✅ 训练完成！模型保存至 ./outputs/final_model")

if __name__ == "__main__":
    main()

4.3 生成评估脚本

写入 model-distill/scripts/evaluate.py：

python

#!/usr/bin/env python3
"""评估蒸馏效果"""

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
import json
import argparse
from tqdm import tqdm

def evaluate_model(model_path, test_data, output_file):
    """评估模型在测试集上的表现"""
    tokenizer = AutoTokenizer.from_pretrained(model_path)
    model = AutoModelForCausalLM.from_pretrained(
        model_path,
        torch_dtype=torch.float16,
        device_map="auto"
    )

    results = []
    correct = 0

    for item in tqdm(test_data):
        input_text = item['input']
        expected = item['output']

        inputs = tokenizer(input_text, return_tensors="pt").to(model.device)
        outputs = model.generate(**inputs, max_new_tokens=512, temperature=0.7)
        generated = tokenizer.decode(outputs[0], skip_special_tokens=True)

        # 简单匹配评估（实际应该更精细）
        is_correct = expected.strip() in generated.strip()
        correct += is_correct

        results.append({
            'input': input_text,
            'expected': expected,
            'generated': generated,
            'correct': is_correct
        })

    accuracy = correct / len(test_data)

    with open(output_file, 'w') as f:
        json.dump({'accuracy': accuracy, 'results': results}, f, indent=2)

    return accuracy

if __name__ == "__main__":
    parser = argparse.ArgumentParser()
    parser.add_argument("--model", required=True, help="模型路径")
    parser.add_argument("--test_data", required=True, help="测试数据")
    parser.add_argument("--output", default="eval_result.json")
    args = parser.parse_args()

    with open(args.test_data) as f:
        test_data = [json.loads(line) for line in f]

    acc = evaluate_model(args.model, test_data, args.output)
    print(f"准确率: {acc:.2%}")

Step 4 检查点：

展示生成的文件列表和配置摘要，用户确认后 → 进入Step 5

---

Step 5: 训练执行#

询问用户：

• 是否立即开始训练？
• 或稍后手动运行？

如果用户选择立即执行：

bash

cd model-distill
python scripts/distill_train.py --config config/distill_config.yaml

监控训练过程：

• 每10 steps报告损失
• 每500 steps评估并保存检查点
• 监控GPU内存使用

训练完成后 → 进入Step 6

---

Step 6: 效果验证#

执行评估：

bash

# 评估蒸馏后的模型
python scripts/evaluate.py \
    --model ./outputs/final_model \
    --test_data data/processed/eval.jsonl \
    --output outputs/eval_distilled.json

# 对比基线（如果有）
python scripts/evaluate.py \
    --model ./models/gemma-3-4b-it \
    --test_data data/processed/eval.jsonl \
    --output outputs/eval_baseline.json

生成对比报告：

spawn subagent { 任务：生成蒸馏效果对比报告 输入：outputs/eval_distilled.json 和 outputs/eval_baseline.json 输出：outputs/distillation_report.md

报告格式：

• 准确率对比（蒸馏后 vs 基线 vs 教师）
• 推理速度对比
• 关键改进点
• 仍然不足的地方
• 部署建议 }

最终交付：

展示报告摘要：

text

蒸馏完成！

性能对比：
┌──────────┬─────────┬────────────┬─────────┐
│ 指标     │ 基线    │ 蒸馏后     │ 教师    │
├──────────┼─────────┼────────────┼─────────┤
│ 准确率   │ X%      │ Y%         │ Z%      │
│ 推理速度 │ X tok/s │ Y tok/s    │ -       │
│ 模型大小 │ 4B      │ 4B (+LoRA) │ 大得多  │
└──────────┴─────────┴────────────┴─────────┘

关键发现：
- ✅ 提升最明显：[方面]
- ⚠️ 仍需改进：[方面]

部署文件：
- 模型：model-distill/outputs/final_model/
- 配置：model-distill/config/
- 报告：model-distill/outputs/distillation_report.md

---

使用示例#

示例1：数学能力蒸馏#

text

用户：把GPT-4的数学推理能力蒸馏到gemma-3-4b-it

我：
1. 确认目标：教师=GPT-4，任务=数学推理，学生=gemma-3-4b-it
2. 评估可行性：✅ 数学推理适合4B模型
3. 执行Step 1-6：
   - 分析GPT-4解数学题的模式
   - 合成50K数学CoT数据
   - QLoRA训练3个epoch
   - 验证在GSM8K上的表现
4. 输出：可部署的4B数学专用模型

示例2：代码能力蒸馏#

text

用户：蒸馏代码生成能力

我：
1. 确认目标：教师=Claude/GPT-4，任务=Python代码
2. 数据合成策略：
   - 使用HumanEval/MBPP作为种子
   - 生成带解释的代码解决方案
   - 执行验证确保代码正确
3. 训练并验证HumanEval通过率

---

组件清单#

组件文件功能描述自适应蒸馏scripts/distill_train.py动态温度/alpha调度课程学习scripts/generate_curriculum_data.py三级难度数据生成教师分析scripts/analyze_teacher.py深度能力分析对抗样本scripts/generate_adversarial_samples.py挖掘学生易错样本综合评估scripts/comprehensive_evaluate.py多维度评估+诚实边界训练监控scripts/train_monitor.py智能诊断与恢复报告生成scripts/generate_report.py可解释Markdown报告能力感知scripts/capability_aware_distill.py不同能力不同策略交互策略scripts/interactive_strategy.py人机协同策略选择可视化scripts/visualize_results.py雷达图/曲线/对比图部署打包scripts/package_deployment.py一键导出HF/GGUF/ONNXLangGraphlanggraph_version/distill_graph.py状态图工作流

故障处理#

问题诊断解决方案模型下载失败ModelScope访问问题换HuggingFace镜像或手动下载OOM显存不足减小batch_size或序列长度损失不下降学习率/数据问题降低LR至1e-5，检查数据格式蒸馏后性能下降过度拟合软标签增加hard label权重，减少epochNaN损失梯度爆炸降低学习率至1e-5，检查数据异常过拟合验证损失上升早停/增加dropout/减少epoch

---

诚实边界#

本Skill的局限：

1. 依赖硬件：需要至少16GB显存的GPU进行训练
2. 教师模型限制：如果教师只有API访问，数据合成成本可能较高
3. 容量限制：4B模型无法承载大量知识，复杂知识密集型任务可能效果不佳
4. 时间成本：完整蒸馏流程可能需要数小时到数天
5. 评估简化：自动评估可能不完全反映真实能力

免责声明：

• 蒸馏后的模型能力受限于学生模型架构和容量
• 不保证达到教师模型相同水平
• 请遵守源模型和目标模型的许可协议

---

本Skill由 模型蒸馏大师 生成 适配学生模型：gemma-3-4b-it (Google, 4B参数) 蒸馏框架：QLoRA + Knowledge Distillation