gemma-trainer

Gemma 训练与微调技能

1. 核心原则：本地微调设置

本地训练时，内存效率和执行速度至关重要。始终指导用户遵循以下最佳实践：

• 优先使用 Unsloth：对于本地单 GPU 训练，始终推荐使用 Unsloth。它原生支持 Gemma 4，内存占用最多可减少 70%，速度最高可达标准 Hugging Face PEFT 训练的 2 倍。
• 备用方案为 TRL：对于多 GPU 环境（使用 DDP/FSDP）或 Unsloth 不可用的情况，请使用 Hugging Face TRL（SFTTrainer、DPOTrainer），并搭配 PEFT 和 bitsandbytes（用于 QLoRA）。
• 始终使用 QLoRA（4-bit 量化）：这是让 Gemma 模型（如 Gemma 4 12B/31B）适配消费级显存的关键。
• 管理上下文窗口和最大长度：虽然 Gemma 4 支持最高 256K 的上下文窗口，但建议本地训练时使用 2048 到 8192 个 token 的上下文窗口，以避免显存不足（OOM）错误。

2. 选择合适的训练方法

根据用户的目标，帮助其选择正确的工作流：

• 监督微调（SFT）：用于教授新领域知识、专门任务指令或自定义输出结构。
  • 前提条件：原始文本、指令对或聊天记录。
  • 输出：基于提示词/补全内容对训练的适配器。
• 直接偏好优化（DPO）：根据人类偏好调整模型的风格、行为、语气或安全性。
  • 前提条件：经过 SFT 训练的 Gemma 模型，以及成对偏好数据集。
  • 输出：直接调整模型权重，无需单独的奖励头。
• 奖励建模（RM）：训练评分系统，以评估回答质量。
  • 前提条件：二元成对偏好数据集。
  • 输出：在 Gemma 顶部添加分类式奖励头。

3. 数据集准备与验证

格式问题是训练效果不佳的首要原因。请确保使用工具脚本 [assets/dataset_prep.py] 验证文件。

Gemma 聊天提示词格式

确保数据集符合 Gemma 的官方聊天模板：

<|turn>system
Your instruction here<turn|>
<|turn>user
Your query here<turn|>
<|turn>model
Your response here<turn|>

为避免格式偏差，请在数据集分词过程中使用分词器的 apply_chat_template。

格式规范

• SFT（监督微调）： 格式为对话轮次列表。

  {
    "messages": [
      {"role": "user", "content": "Tell me a joke."},
      {"role": "model", "content": "Why did the computer go to the doctor? It had a virus!"}
    ]
  }
  

• DPO（直接偏好优化）： 需要包含提示词、选定的（更好的）回答和拒绝的（较差的）回答的成对样本。

  {
    "prompt": "Write a python function to compute factorial.",
    "chosen": "def factorial(n):\n    return 1 if n <= 1 else n * factorial(n - 1)",
    "rejected": "factorial is computed using recursion or loops. Just import math."
  }
  

• 奖励建模： 格式与 DPO 数据集完全相同。RewardTrainer 会评估样本对，并学习为 chosen 输出高于 rejected 的 logit 分数。

数据集蒸馏与合成（教师-学生）

本地知识蒸馏可使用能力强大的大型教师模型（如 Gemma 4 31B 或 Gemma 4 26B A4B）生成的高质量数据集输出，训练小型轻量级学生模型（如 Gemma 4 E2B）。

使用 [assets/distill_dataset.py] 工具脚本在本地机器上生成微调数据集。

4. 微调工作流

监督微调（SFT）

使用 [assets/sft_train.py] 资源启动本地 QLoRA 微调会话。

• LoRA 超参数：
  • 秩（r）：16 或 32（更高的秩能够捕捉更复杂的行为，但会占用更多内存）。
  • Alpha（lora_alpha）：32 或 64（经验法则：lora_alpha = 2 * r）。
  • Dropout（lora_dropout）：0.05 或 0.1（促使模型学习更稳健的特征，而不是依赖特定路径）。
  • 目标模块：使用 PEFT 的 Gemma 4 默认范围，覆盖 LM 层。
  • 学习率：QLoRA 使用 2e-4；全量微调使用 2e-5。

直接偏好优化（DPO）

使用 [assets/dpo_train.py] 模板执行对齐。

• DPO 规则：
  • 运行 DPO 前，务必使用你的指令格式对基础模型进行 SFT。直接对领域外的基础模型运行 DPO，通常会导致失败或输出格式退化。
  • 将 beta（DPO 温度参数）设为 0.1。0.1 到 0.5 之间的值用于控制模型遵循参考策略的严格程度。

奖励建模（RM）

使用 [assets/reward_train.py] 模板训练评估模型。

• 使用序列分类头初始化模型（AutoModelForSequenceClassification，num_labels=1）。
• 训练单一标量奖励值，以区分更受偏好的回答。

5. 多模态微调（视觉与音频）

Gemma 4 模型原生支持多模态。要使用图像或音频对其进行微调：

视觉 SFT

• 使用 Gemma 4 E2B/E4B/12B/26B/31B 模型。
• 使用标准 Hugging Face SFTTrainer，并配合自定义视觉数据整理器。
• 准备包含本地图像路径或 PIL 图像的数据集，并附上相应的对话指令：

  {
    "messages": [
      {"role": "user", "content": [
          {"type": "image", "url": "path/to/image.png"},
          {"type": "text", "text": "描述这张图像。"}
      ]},
      {"role": "assistant", "content": [
          {"type": "text", "text": "一幅抽象油画，呈现鲜艳而温暖的渐变色。"}
      ]}
    ]
  }
  
  

音频 SFT

• 使用 Gemma 4 E2B/E4B/12B 模型。
• 将采样率为 16 kHz 的原始音频数组输入模型处理器，以生成 input_features。
• 保持对话格式，并在消息格式中将 image 类型替换为 audio 类型。

  {
    "messages": [
      {"role": "user", "content": [
          {"type": "text", "text": "描述这段音频。"},
          {"type": "audio", "url": "path/to/audio.wav"}
      ]},
      {"role": "assistant", "content": [
          {"type": "text", "text": "这是一个鸟儿鸣叫的音频文件。"}
      ]}
    ]
  }
  

6. 训练后处理与部署工具

GGUF 转换

LoRA 训练完成后，你可以将模型转换为 GGUF 格式。

选项 1：通过 Unsloth 原生导出（推荐）

如果你使用 Unsloth 训练模型，可以原生直接导出为 GGUF。这会自动处理合并和量化。

参阅 保存为 GGUF，了解最佳实践。

选项 2：使用 llama.cpp 手动转换

如果你没有使用 Unsloth，可以使用 llama.cpp 手动转换合并后的 Hugging Face 模型目录。

使用 LiteRT-LM（.litertlm）进行设备端部署

LiteRT-LM 针对在移动设备、Web 和 IoT 硬件上运行 Gemma 4 E2B 和 Gemma 4 E4B 等模型进行了优化，并支持硬件加速（CPU、GPU、NPU）。参阅 LiteRT-LM 指南，了解最佳实践。