#### :interrobang:Gemma-4 31B 和 26B-A4B 推理中的 IndexError
在对 31B 和 26B 进行推理时，你可能会看到此错误：
```python
文件 "/.../cache_utils.py"，第 937 行，在 update 中
keys, values = self.layers[layer_idx].update(...)
IndexError: 列表索引超出范围
```
元凶如下：
```python
if hasattr(decoder_config, "num_kv_shared_layers"):
layer_types = layer_types[: -decoder_config.num_kv_shared_layers]
```
Gemma-4 31B 和 26B-A4B 随附 `num_kv_shared_layers = 0`。在 Python 中， `-0 == 0`，因此 `layer_types[:-0]` 会退化为 `layer_types[:0] == []`。缓存被构建为零个层槽位，而第一步 attention 前向就在 `Cache.update`.
#### :no\_entry: `use_cache = True` 对 E2B、E4B 来说，生成结果是一堆乱码
[参见 issue](https://github.com/huggingface/transformers/issues/45242) "\[Gemma 4] `use_cache=False` 会破坏注意力计算，生成垃圾 logits #45242"
Gemma-4 E2B 和 E4B 在层之间共享 KV 状态（`num_kv_shared_layers = 20` 和 `18`）。缓存是唯一一个早期层为后续层复用而存放 KV 的地方。当 `use_cache=False` （正如每个 QLoRA 教程都会设置的那样，并且 `gradient_checkpointing=True` 强制如此）， `Gemma4TextModel.forward` 会跳过缓存构建，因此 KV 共享层会退回到基于当前隐藏状态在本地重新计算 K 和 V。logits 会变成乱码，训练损失会发散。
**修复前（`unsloth/gemma-4-E2B-it`，提示 “1+1 是多少？”）：**
```
use_cache=True -> '1 + 1 = **2**'
use_cache=False -> 'BROAD\\肯. Specificallyboard K supposed\\_n통 \\'
max_abs_logit_diff: 48.937500
```
**修复后：**
```
use_cache=True -> '1 + 1 = **2**'
use_cache=False -> '1 + 1 = **2**'
max_abs_logit_diff: 0.000000 （位级完全一致，全部 9 个 token 都相同）
```
#### :radio:音频 float16 溢出
`Gemma4AudioAttention` 使用 `config.attention_invalid_logits_value = -1e9` 在一次 `masked_fill` 调用中。在 fp16（Tesla T4）上，-1e9 会溢出 fp16 的最大值 65504，导致：
```python
RuntimeError: 值无法在不发生溢出的情况下转换为类型 c10::Half
```
这是由于 `self.config.attention_invalid_logits_value` :
```python
attn_weights = attn_weights.masked_fill(
attention_mask.logical_not(), self.config.attention_invalid_logits_value
)
```
#### 💡Gemma-4 提示
1. 如果你想要 **保留推理** 能力，你可以将推理风格示例与直接回答混合使用（至少保留 75% 的推理）。否则你可以完整输出它。\n\n使用 `gemma-4` 用于非思考型聊天模板，以及 `gemma-4-thinking` 用于思考型变体。\n对更大的 26B 和 31B 模型使用思考型，对较小的模型使用非思考型。
```python
from unsloth.chat_templates import get_chat_template
tokenizer = get_chat_template(
tokenizer,
chat_template = "gemma-4-thinking", # 或 "gemma-4"
)
```
2. 要启用思考模式，请使用 `enable_thinking = True / False` 在 `tokenizer.apply_chat_template`
已启用思考：
processor.tokenizer.apply_chat_template([
{\"role\" : \"user\", \"content\" : \"2+2 等于多少？\"},
], tokenize = False, enable_thinking = True, add_generation_prompt = True)
将打印 `<|turn>system\n<|think|>\n<|turn>user\n2+2 等于多少？\n<|turn>model\n`
思考已禁用：
```python
processor.tokenizer.apply_chat_template([
{\"role\" : \"user\", \"content\" : \"2+2 等于多少？\"},
], tokenize = False, enable_thinking = False, add_generation_prompt = True)
```
将打印 `<|turn>user\n2+2 等于多少？\n<|turn>model\n<|channel>thought\n`
3. Gemma 4 支持 140 种语言，因此非常适合多语言微调。
4. 建议训练 **E4B QLoRA** 而不是 **E2B LoRA** ，因为 E4B 更大，而量化精度差异微乎其微。Gemma 4 E4B LoRA 甚至更好。
5. 微调后，你可以导出为 [GGUF](#saving-export-your-fine-tuned-model) （用于 llama.cpp/Unsloth/Ollama 等）
### ⚡快速入门
#### 🦥 Unsloth Studio 指南
{% columns %}
{% column %}
Gemma 4 可以在 [Unsloth Studio](/docs/zh/xin-de/studio.md)中运行和微调，这是我们面向本地 AI 的新开源 Web UI。
使用 Unsloth Studio，你可以在以下平台本地运行模型： **MacOS、Windows**、Linux，并训练 NVIDIA GPU。本月还将支持 Intel、MLX 和 AMD 训练。
{% endcolumn %}
{% column %}
"""
sloth_link = "https://files.worldwildlife.org/wwfcmsprod/images/Sloth_Sitting_iStock_3_12_2014/story_full_width/8l7pbjmj29_iStock_000011145477Large_mini__1_.jpg"
messages = [{
"role" : "user",
"content": [
{ "type": "image", "image" : sloth_link },
{ "type": "text", "text" : "这个动物出演过哪些电影？" }
]
}]
# 你可能需要等待 1 分钟让 Unsloth 的自动编译器完成
do_gemma_4_inference(messages, max_new_tokens = 256)
"""让我们给树懒写一首诗！"""
messages = [{
"role": "user",
"content": [{ "type" : "text",
"text" : "写一首关于树懒的诗。" }]
}]
do_gemma_4_inference(messages)
"""# 让我们微调 Gemma 4！
现在可以通过选择来微调视觉和文本部分——音频部分也可以微调——我们正在努力让它也能被选择！
我们现在添加 LoRA 适配器，这样只需要更新少量参数！
"""
model = FastModel.get_peft_model(
model,
finetune_vision_layers = False, # 仅文本时关闭！
finetune_language_layers = True, # 应保持开启！
finetune_attention_modules = True, # 注意力对 GRPO 有帮助
finetune_mlp_modules = True, # 应始终保持开启！
r = 8, # 越大 = 精度越高，但可能过拟合
lora_alpha = 8, # 建议 alpha 至少等于 r
lora_dropout = 0,
bias = "none",
random_state = 3407,
)
"""
### 数据准备
我们现在使用 `Gemma-4` 格式来进行对话风格微调。我们使用 [Maxime Labonne 的 FineTome-100k](https://huggingface.co/datasets/mlabonne/FineTome-100k) 数据集，采用 ShareGPT 风格。Gemma-4 会像下面这样渲染多轮对话：
```
<|turn>user
你好
<|turn>model
嗨！
```
我们使用 `get_chat_template` 函数来获取正确的聊天模板。我们支持 `zephyr, chatml, mistral, llama, alpaca, vicuna, vicuna_old, phi3, llama3, phi4, qwen2.5, gemma3, gemma-4` 等更多模板。
"""
from unsloth.chat_templates import get_chat_template
tokenizer = get_chat_template(
tokenizer,
chat_template = "gemma-4-thinking",
)
"""我们获取数据集的前 3000 行"""
from datasets import load_dataset
dataset = load_dataset("mlabonne/FineTome-100k", split = "train[:3000]")
"""我们现在使用 `standardize_data_formats` 尝试将数据集转换为适合微调的正确格式！"""
from unsloth.chat_templates import standardize_data_formats
dataset = standardize_data_formats(dataset)
"""让我们看看第 100 行长什么样！"""
dataset[100]
"""我们现在必须将 `Gemma-3` 的聊天模板应用到这些对话上，并将其保存到 `text`。由于我们在做微调，所以使用 removeprefix(`''`) 去掉 `` token。Processor 会在训练前添加这个 token，而模型只期望有一个。"""
def formatting_prompts_func(examples):
convos = examples["conversations"]
texts = [tokenizer.apply_chat_template(convo, tokenize = False, add_generation_prompt = False).removeprefix('') for convo in convos]
return { "text" : texts, }
dataset = dataset.map(formatting_prompts_func, batched = True)
"""让我们看看聊天模板的效果！注意这里没有 `` token，因为 processor tokenizer 会添加一个。"""
dataset[100]["text"]
"""
### 训练模型
现在让我们训练模型。我们做 60 步以加快速度，但你可以设置 `num_train_epochs=1` 进行完整运行，并关闭 `max_steps=None`。
"""
from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
model = model,
tokenizer = tokenizer,
train_dataset = dataset,
eval_dataset = None, # 可以设置评估！
args = SFTConfig(
dataset_text_field = "text",
per_device_train_batch_size = 1,
gradient_accumulation_steps = 4, # 使用梯度累积来模拟批大小！
warmup_steps = 5,
# num_train_epochs = 1, # 若要完整训练一轮就设置这个。
max_steps = 60,
learning_rate = 2e-4, # 长训练建议降到 2e-5
logging_steps = 1,
optim = "adamw_8bit",
weight_decay = 0.001,
lr_scheduler_type = "linear",
seed = 3407,
report_to = "none", # 使用 TrackIO/WandB 等
),
)
"""我们还使用 Unsloth 的 `train_on_completions` 方法，只训练助手输出，并忽略用户输入上的损失。这有助于提高微调精度！"""
from unsloth.chat_templates import train_on_responses_only
trainer = train_on_responses_only(
trainer,
instruction_part = "<|turn>user\n",
response_part = "<|turn>model\n",
)
"""让我们验证一下是否已完成对指令部分的掩码！再打印一次第 100 行。注意样本如预期那样只包含一个 ``！"""
tokenizer.decode(trainer.train_dataset[100]["input_ids"])
"""现在让我们打印被掩码的示例——你应该会看到只有答案被保留："""
tokenizer.decode([tokenizer.pad_token_id if x == -100 else x for x in trainer.train_dataset[100]["labels"]]).replace(tokenizer.pad_token, " ")
"""# 让我们训练模型！
若要恢复训练，设置 `trainer.train(resume_from_checkpoint = True)`
"""
trainer_stats = trainer.train()
````
{% endcode %}
{% hint style="info" %}
如果你遇到 OOM：
* 降低 `per_device_train_batch_size` 改为 **1** 和/或减少 `max_seq_length`.
* 保持 `use_`[`gradient_checkpointing`](/docs/zh/bo-ke/500k-context-length-fine-tuning.md#unsloth-gradient-checkpointing-enhancements)`="unsloth"` 开启（它旨在减少 VRAM 使用并延长上下文长度）。
{% endhint %}
**MoE（bf16 LoRA）加载器示例：**
```python
导入 os
import torch
from unsloth import FastModel
model, tokenizer = FastModel.from_pretrained(
model_name = "unsloth/Gemma-4-26B-A4B-it",
max_seq_length = 2048,
load_in_4bit = False, # 不建议对 MoE 使用 QLoRA，稠密 31B 没问题
load_in_16bit = True, # bf16/16 位 LoRA
full_finetuning = False,
)
```
加载完成后，您将添加 LoRA 适配器，并以与上面的 SFT 示例类似的方式进行训练。
### 强化学习（RL）
现在，您可以使用以下内容通过 RL、GSPO、GRPO 等训练 Gemma 4： [我们的免费笔记本](https://colab.research.google.com/github/unslothai/notebooks/blob/main/nb/Qwen3_5_\(4B\)_Vision_GRPO.ipynb).
{% columns %}
{% column %}
Gemma 4 E2B RL 可在 9GB 显存上运行。
{% embed url="" %}
该笔记本的目标是让 Gemma 4 学会使用以下内容解决数独谜题： [GRPO](/docs/zh/kai-shi-shi-yong/reinforcement-learning-rl-guide.md#from-rlhf-ppo-to-grpo-and-rlvr).
模型将设计一种填充空白单元格的策略，我们会根据正确填入数字和完成有效谜题来给予奖励。
即使 vLLM 不支持它，您仍可通过设置以下选项，使用 Unsloth 运行 Gemma 4 RL： `fast_inference=False` 加载模型时：
{% endcolumn %}
{% column %}
{% endcolumn %}
{% endcolumns %}
```python
从 unsloth 导入 FastLanguageModel
model, tokenizer = FastLanguageModel.from_pretrained(
model_name="unsloth/gemma-4-E2B-it",
fast_inference=False,
)
```
### MoE 微调（26B-A4B）
该 **26B-A4B** 模型在 Gemma 4 系列中兼顾速度与质量。由于它是一个 **MoE** 模型，每个 token 仅激活部分参数，因此建议采用保守的微调方法：
* 使用 **LoRA** 而非全量微调
* 优先选择 **16 位 / bf16 LoRA** 如果内存允许
* 先从较短的上下文和较小的秩开始
* 仅在流水线稳定后再进行扩展
如果您的目标是获得最高质量，并且拥有更多内存，请使用 **31B** 来替代。
### 多模态微调（E2B / E4B）
由于 **E2B** 和 **E4B** 支持 **图像** 和 **音频**，它们是用于多模态微调的主要 Gemma 4 变体。
* 使用以下内容加载多模态模型： `FastVisionModel`
* 保持 `finetune_vision_layers = False` 优先
* 仅微调语言、注意力和 MLP 层
* 如果任务需要，稍后再启用视觉或音频层
#### Gemma 4 多模态 LoRA 示例：
{% code expandable="true" %}
````python
从 unsloth 导入 FastVisionModel # 用于 LLM 的 FastLanguageModel
import torch
model, processor = FastVisionModel.from_pretrained(
"unsloth/gemma-4-26B-A4B-it",
load_in_4bit = True, # 使用 4 位以减少内存占用。16 位 LoRA 则设为 False。
use_gradient_checkpointing = "unsloth", # 对于长上下文，使用 True 或 "unsloth"
)
"""现在我们为参数高效微调添加 LoRA 适配器，从而能够高效地仅训练全部模型参数中的 1%。
**[新增]** 我们还支持仅微调视觉组件、仅微调语言组件，或同时微调两者。此外，您可以选择微调注意力模块、MLP 层，或两者兼顾！
"""
model = FastVisionModel.get_peft_model(
model,
finetune_vision_layers = True, # 如果不微调视觉层则设为 False
finetune_language_layers = True, # 如果不微调语言层则设为 False
finetune_attention_modules = True, # 如果不微调注意力层则设为 False
finetune_mlp_modules = True, # 如果不微调 MLP 层则设为 False
r = 32, # 越大准确率越高，但可能会过拟合
lora_alpha = 32, # 建议 alpha 至少等于 r
lora_dropout = 0,
bias = "none",
random_state = 3407,
use_rslora = False, # 我们支持秩稳定化 LoRA
loftq_config = None, # 以及 LoftQ
target_modules = "all-linear", # 现为可选！如有需要可指定列表
)
"""
### 数据准备
我们将使用一个手写数学公式的采样数据集。目标是将这些图像转换为计算机可读的格式——具体而言是 LaTeX——以便进行渲染。这对于复杂表达式尤其有用。
您可在[此处](https://huggingface.co/datasets/unsloth/LaTeX_OCR)访问该数据集。完整数据集在[此处](https://huggingface.co/datasets/linxy/LaTeX_OCR)。
"""
from datasets import load_dataset
dataset = load_dataset("unsloth/LaTeX_OCR", split = "train")
"""让我们概览一下数据集。我们将查看第二张图像及其对应的说明文字。"""
数据集
dataset[2]["image"]
dataset[2]["text"]
"""我们还可以直接在浏览器中渲染 LaTeX！"""
从 IPython.display 导入 display、Math、Latex
latex = dataset[3]["text"]
display(Math(latex))
"""为格式化数据集，所有视觉微调任务都应遵循以下格式：
```python
[
{
"role": "user",
"content": [
{"type": "text", "text": instruction},
{"type": "image", "image": sample["image"]},
],
},
{
"role": "user",
"content": [
{"type": "text", "text": instruction},
{"type": "image", "image": sample["image"]},
],
},
]
```
"""
instruction = "为此图像编写 LaTeX 表示。"
def convert_to_conversation(sample):
conversation = [
{
"role": "user",
"content": [
{"type": "text", "text": instruction},
{"type": "image", "image": sample["image"]},
],
},
{"role": "assistant", "content": [{"type": "text", "text": sample["text"]}]},
]
return {"messages": conversation}
pass
"""让我们将数据集转换为适用于微调的“正确”格式："""
converted_dataset = [convert_to_conversation(sample) for sample in dataset]
"""现在，第一个示例如下所示："""
converted_dataset[0]
"""让我们获取 Gemma 4 指令聊天模板，并将其用于基础模型"""
从 unsloth 导入 get_chat_template
processor = get_chat_template(
processor,
"gemma-4-thinking"
)
"""微调前，让我们评估基础模型的性能。由于它此前未接触过此聊天模板，我们不期待很好的结果。"""
image = dataset[2]["image"]
instruction = "为此图像编写 LaTeX 表示。"
messages = [
{
"role": "user",
"content": [{"type": "image"}, {"type": "text", "text": instruction}],
}
]
input_text = processor.apply_chat_template(messages, add_generation_prompt = True)
inputs = processor(
image,
input_text,
add_special_tokens = False,
return_tensors = "pt",
).to("cuda")
from transformers import TextStreamer
text_streamer = TextStreamer(processor, skip_prompt = True)
result = model.generate(**inputs, streamer = text_streamer, max_new_tokens = 128,
use_cache = True, temperature = 1.0, top_p = 0.95, top_k = 64)
"""可以看到，它糟糕透顶！它完全不遵循指令
### 训练模型
现在让我们训练模型。为加快速度，我们执行 60 步；但您可以将 `num_train_epochs=1` 用于完整运行，并关闭 `max_steps=None`。我们也支持用于强化学习的 `DPOTrainer` 和 `GRPOTrainer`！！
我们使用新的 `UnslothVisionDataCollator`，它将帮助我们进行视觉微调设置。
"""
从 unsloth.trainer 导入 UnslothVisionDataCollator
from trl import SFTTrainer, SFTConfig
trainer = SFTTrainer(
model = model,
train_dataset = converted_dataset,
processing_class = processor.tokenizer,
data_collator = UnslothVisionDataCollator(model, processor),
args = SFTConfig(
per_device_train_batch_size = 1,
gradient_accumulation_steps = 4,
max_grad_norm = 0.3,
warmup_ratio = 0.03,
max_steps = 60,
# num_train_epochs = 2, # 完整训练运行时请设置此项，而非 max_steps
learning_rate = 2e-4,
logging_steps = 1,
save_strategy = "steps",
optim = "adamw_8bit",
weight_decay = 0.001,
lr_scheduler_type = "cosine",
seed = 3407,
output_dir = "outputs",
report_to = "none", # 用于 Weights and Biases 或其他服务
# 视觉微调时必须加入以下项目：
remove_unused_columns = False,
dataset_text_field = "",
dataset_kwargs = {"skip_prepare_dataset": True},
max_length = 2048,
)
)
trainer_stats = trainer.train()
````
{% endcode %}
#### 图像示例格式
请记住：对于 Gemma 4 多模态提示，请将图像放在 **之前** 文本指令。
{% code expandable="true" %}
```json
{
"messages": [
{
"role": "user",
"content": [
{"type": "image", "image": "/path/to/image 或对象"},
{"type": "text", "text": "提取此收据中的所有文本。以 JSON 格式返回行项目、总额、商家和日期。"}
]
},
{
"role": "assistant",
"content": [
{"type": "text", "text": "{\"merchant\": \"示例商店\", \"total\": \"19.99\"}"}
]
}
]
}
```
{% endcode %}
#### 音频示例格式
音频仅适用于 **E2B / E4B** 。请保持音频片段简短且针对具体任务。
{% code expandable="true" %}
```json
{
"messages": [
{
"role": "user",
"content": [
{"type": "audio", "audio": "/path/to/audio 或对象"},
{"type": "text", "text": "将以下英语语音片段转录为英文文本。仅输出转录内容。"}
]
},
{
"role": "assistant",
"content": [
{"type": "text", "text": "大家好，欢迎回来。"}
]
}
]
}
```
{% endcode %}
### 保存 / 导出微调后的模型
您可以查看我们针对以下内容的推理 / 部署指南： [Unsloth Studio](/docs/zh/xin-de/studio/export.md), [llama.cpp](/docs/zh/ji-chu-zhi-shi/inference-and-deployment/saving-to-gguf.md), [vLLM](/docs/zh/ji-chu-zhi-shi/inference-and-deployment/vllm-guide.md), [llama-server](/docs/zh/ji-chu-zhi-shi/inference-and-deployment/llama-server-and-openai-endpoint.md), [Ollama](/docs/zh/ji-chu-zhi-shi/inference-and-deployment/saving-to-ollama.md) 或 [SGLang](/docs/zh/ji-chu-zhi-shi/inference-and-deployment/sglang-guide.md).
#### 保存为 GGUF
Unsloth 支持直接保存为 GGUF：
```python
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "q4_k_m")
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "q8_0")
model.save_pretrained_gguf("directory", tokenizer, quantization_method = "f16")
```
或者将 GGUF 推送到 Hugging Face：
```python
model.push_to_hub_gguf("hf_username/directory", tokenizer, quantization_method = "q4_k_m")
model.push_to_hub_gguf("hf_username/directory", tokenizer, quantization_method = "q8_0")
```
如果导出的模型在其他运行时中表现较差，Unsloth 会指出最常见的原因： **推理时使用了错误的聊天模板 / EOS token** （您必须使用与训练时相同的聊天模板）。
有关更多详情，请阅读我们的推理指南：
{% columns %}
{% column width="50%" %}
{% content-ref url="/pages/9a72670992feb75def412a693565c84a88c8a266" %}
[推理与部署](/docs/zh/ji-chu-zhi-shi/inference-and-deployment.md)
{% endcontent-ref %}
{% content-ref url="/pages/b83d88f106d75c3396c46f5342fb401501910093" %}
[GGUF & llama.cpp](/docs/zh/ji-chu-zhi-shi/inference-and-deployment/saving-to-gguf.md)
{% endcontent-ref %}
{% endcolumn %}
{% column width="50%" %}
{% content-ref url="/pages/f7c3389bdba9af3050e66a941596d827cdb11e0b" %}
[Model Export](/docs/zh/xin-de/studio/export.md)
{% endcontent-ref %}
{% content-ref url="/pages/9f0e22d200c9105481e4854b8473aba99ca44835" %}
[vLLM](/docs/zh/ji-chu-zhi-shi/inference-and-deployment/vllm-guide.md)
{% endcontent-ref %}
{% endcolumn %}
{% endcolumns %}
### Gemma 4 数据最佳实践
Gemma 4 有一些格式细节需要牢记。
#### 1. 使用标准聊天角色
Gemma 4 使用标准的：
* `系统`
* `用户`
* `assistant`
这意味着您的 SFT 数据集应使用常规聊天格式编写，而不是旧版 Gemma 专用角色格式。
#### 2. 思考模式是显式的
如果您想在 SFT 期间保留思考风格的行为：
* 保持格式一致
* 决定是否要针对以下内容进行训练： **可见的思考块** 或 **仅最终答案**
* 务必 **不要** 在同一数据集中混合多种不兼容的思考格式
对于大多数生产环境助手，最简单的设置是在以下内容上进行微调： **仅最终可见答案**.
#### 3. 多轮规则
对于多轮对话，仅保留 **最终可见答案** 在对话历史中。不要 **不要** 将先前的思考块反馈到后续轮次中。
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://unsloth.ai/docs/zh/mo-xing/gemma-4/train.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.