unsloth/gemma-4-26B-A4B-it-GGUF · Hugging Face 原文地址：https://huggingface.co/unsloth/gemma-4-26B-A4B-it-GGUF

阅读我们的 如何运行 Gemma 4 指南！

查看 Unsloth Dynamic 2.0 GGUFs 以获取我们的量化基准测试结果。

• 4月11日更新： 重新下载以获取 Google 最新的聊天模板及 llama.cpp 修复补丁。
• 现在可以在 Unsloth Studio 中运行和微调 Gemma 4。阅读我们的指南（https://unsloth.ai/docs/models/gemma-4）。
• 在我们的收藏集中查看 Gemma 4 的所有版本（GGUF、16-bit 等）(https://huggingface.co/collections/unsloth/gemma-4)。
• Gemma 4 E4B（4位 GGUF）在 Unsloth Studio 中使用工具调用的示例：gemma 4 in unsloth studio

Hugging Face (https://huggingface.co/collections/google/gemma-4) | GitHub (https://github.com/google-gemma) | 发布博客 (https://blog.google/innovation-and-ai/technology/developers-tools/gemma-4/) | 文档 (https://ai.google.dev/gemma/docs/core) 许可证：Apache 2.0 (https://ai.google.dev/gemma/docs/gemma_4_license) | 作者：Google DeepMind (https://deepmind.google/models/gemma/) Gemma 是由 Google DeepMind 构建的开源模型系列。Gemma 4 模型为多模态，可处理文本和图像输入（小模型支持音频），并生成文本输出。此版本包含预训练和指令微调两种变体的开放权重模型。Gemma 4 拥有高达 256K token 的上下文窗口，并支持超过 140 种语言的多元语言功能。凭借密集型（Dense）和混合专家（MoE）架构，Gemma 4 非常适合文本生成、编程和推理等任务。该系列模型提供四种不同的尺寸：E2B、E4B、26B A4B 和 31B。其多样化的尺寸使其能够部署从高端手机到笔记本电脑和服务器的各种环境中，让尖端人工智能普及化。 Gemma 4 引入了关键的能力与架构改进：

• 推理能力 – 该系列所有模型均设计为强大的推理器，支持可配置的思考模式。
• 扩展的多模态支持 – 处理文本、图像（支持可变宽高比和分辨率，所有模型均支持）、视频，以及音频（E2B 和 E4B 模型原生支持）。
• 多样且高效的架构 – 提供不同尺寸的密集型和混合专家（MoE）变体，以实现可扩展的部署。
• 针对端侧优化 – 小模型专为在笔记本电脑和移动设备上高效本地运行而设计。
• 更大的上下文窗口 – 小模型具备 128K 上下文窗口，中模型支持 256K。
• 增强的编程与智能体能力 – 在编程基准测试中取得显著进步，并提供原生函数调用支持，赋能高度自主的智能体。
• 原生系统提示词支持 – Gemma 4 原生支持 system 角色，使对话更加结构化且可控。

模型概览

Gemma 4 模型旨在每种尺寸下均能提供前沿性能，目标部署场景涵盖移动端和边缘设备（E2B、E4B）以及消费级 GPU 和工作站（26B A4B、31B）。它们非常适合推理、智能体工作流、编程和多模态理解。 这些模型采用了一种混合注意力机制，将局部滑动窗口注意力与完整的全局注意力交替结合，并确保最后一层始终为全局注意力。这种混合设计在无需牺牲复杂长上下文任务所需深度感知能力的同时，提供了轻量级模型的处理速度与低内存占用特性。 为优化长上下文的内存使用，全局层采用了统一的键（Keys）和值（Values），并应用了比例旋转位置编码（Proportional RoPE, p-RoPE）。

密集型模型 (Dense Models)

E2B 和 E4B 中的“E”代表“effective”（有效参数量）。较小的模型采用了逐层嵌入（Per-Layer Embeddings, PLE）技术，以最大化端侧部署时的参数效率。PLE 没有通过增加层数或参数来扩大模型，而是为每个解码器层的每个 token 分配独立的专属小型嵌入表。这些嵌入表虽然体积较大，但仅用于快速查找，因此有效参数量远小于总参数量。

混合专家（MoE）模型

26B A4B 中的“A”代表“active parameters”（激活参数），以区别于模型包含的总参数量。通过在推理期间仅激活约 4B 的子集参数，混合专家模型的实际运行速度远超其 26B 总量所暗示的水平。这使得它在推理速度上成为优于密集型 31B 模型的绝佳选择，因为它的运行速度几乎与一个 4B 参数的模型相当。

基准测试结果

我们对这组模型进行了大量不同数据集和指标的综合评估，以全面覆盖文本生成的各个方面。表格中标记的评测结果均针对指令微调模型。

核心能力

Gemma 4 模型可处理广泛的任务，涵盖文本、视觉和音频领域。核心能力包括：

• 思考模式 – 内置推理模式，支持模型在回答前进行逐步思考。
• 长上下文 – 上下文窗口最大支持 128K token（E2B/E4B）和 256K token（26B A4B/31B）。
• 图像理解 – 支持物体检测、文档/PDF 解析、屏幕与 UI 理解、图表解读、OCR（含多语言）、手写识别及指点定位。图像可按任意宽高比和分辨率进行处理。
• 视频理解 – 通过按序处理帧序列来分析视频内容。
• 交错多模态输入 – 允许在单个提示词中以任何顺序自由混合文本与图像。
• 函数调用 – 原生支持结构化工具使用，赋能智能体工作流。
• 编程 – 代码生成、补全与纠错。
• 多语言 – 开箱支持 35+ 种语言，基于 140+ 种语言进行预训练。
• 音频（仅限 E2B 和 E4B） – 自动语音识别（ASR）及跨多语言的语音转翻译文本。

快速开始

您可以搭配最新版的 Transformers 使用所有 Gemma 4 模型。首先，请在您的环境中安装必要的依赖项：

pip install -U transformers torch accelerate

完成安装后，可使用以下代码加载模型：

from transformers import AutoProcessor, AutoModelForCausalLM

MODEL_ID = "google/gemma-4-26B-A4B-it"

# 加载模型
processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForCausalLM.from_pretrained(
    MODEL_ID, 
    dtype="auto", 
    device_map="auto"
)

模型加载完成后，即可开始生成输出：

# 提示词
messages = [
    {"role": "system", "content": "You are a helpful assistant."},
    {"role": "user", "content": "Write a short joke about saving RAM."},
]

# 处理输入文本
text = processor.apply_chat_template(
    messages, 
    tokenize=False, 
    add_generation_prompt=True, 
    enable_thinking=False
)
inputs = processor(text=text, return_tensors="pt").to(model.device)
input_len = inputs["input_ids"].shape[-1]

# 生成输出
outputs = model.generate(**inputs, max_new_tokens=1024)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)

# 解析输出
processor.parse_response(response)

如需启用推理思考，请设置 enable_thinking=True，随后 parse_response 函数将自动解析思考输出。此外，下文还提供了配合文本处理音频（仅限 E2B 和 E4B）、图像和视频的代码示例：

处理音频的代码 与其使用 AutoModelForCausalLM，不如使用 AutoModelForMultimodalLM 来处理音频。使用前请确保安装以下包：

pip install -U transformers torch librosa accelerate

随后可使用以下代码加载模型：

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-E2B-it"

# 加载模型
processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForMultimodalLM.from_pretrained(
    MODEL_ID, 
    dtype="auto", 
    device_map="auto"
)

模型加载完成后，可直接在提示词中引用音频 URL 来开始生成输出：

# 提示词 - 在文本前添加音频
messages = [
    {
        "role": "user",
        "content": [
            {"type": "audio", "audio": "https://raw.githubusercontent.com/google-gemma/cookbook/refs/heads/main/Demos/sample-data/journal1.wav"},
            {"type": "text", "text": "Transcribe the following speech segment in its original language. Follow these specific instructions for formatting the answer:\n* Only output the transcription, with no newlines.\n* When transcribing numbers, write the digits, i.e. write 1.7 and not one point seven, and write 3 instead of three."},
        ]
    }
]

# 处理输入
inputs = processor.apply_chat_template(
    messages, 
    tokenize=True, 
    return_dict=True, 
    return_tensors="pt", 
    add_generation_prompt=True,
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

# 生成输出
outputs = model.generate(**inputs, max_new_tokens=512)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)

# 解析输出
processor.parse_response(response)

处理图像的代码 与其使用 AutoModelForCausalLM，不如使用 AutoModelForMultimodalLM 来处理图像。使用前请确保安装以下包：

pip install -U transformers torch torchvision accelerate

随后可使用以下代码加载模型：

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-26B-A4B-it"

# 加载模型
processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForMultimodalLM.from_pretrained(
    MODEL_ID, 
    dtype="auto", 
    device_map="auto"
)

模型加载完成后，可直接在提示词中引用图像 URL 来开始生成输出：

# 提示词 - 在文本前添加图像
messages = [
    {
        "role": "user",
        "content": [
            {"type": "image", "url": "https://raw.githubusercontent.com/google-gemma/cookbook/refs/heads/main/Demos/sample-data/GoldenGate.png"},
            {"type": "text", "text": "What is shown in this image?"}
        ]
    }
]

# 处理输入
inputs = processor.apply_chat_template(
    messages, 
    tokenize=True, 
    return_dict=True, 
    return_tensors="pt", 
    add_generation_prompt=True,
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

# 生成输出
outputs = model.generate(**inputs, max_new_tokens=512)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)

# 解析输出
processor.parse_response(response)

处理视频的代码 与其使用 AutoModelForCausalLM，不如使用 AutoModelForMultimodalLM 来处理视频。使用前请确保安装以下包：

pip install -U transformers torch torchvision torchcodec librosa accelerate

随后可使用以下代码加载模型：

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-26B-A4B-it"

# 加载模型
processor = AutoProcessor.from_pretrained(MODEL_ID)
model = AutoModelForMultimodalLM.from_pretrained(
    MODEL_ID, 
    dtype="auto", 
    device_map="auto"
)

模型加载完成后，可直接在提示词中引用视频 URL 来开始生成输出：

# 提示词 - 在文本前添加视频
messages = [
    {
        'role': 'user',
        'content': [
            {"type": "video", "video": "https://github.com/bebechien/gemma/raw/refs/heads/main/videos/ForBiggerBlazes.mp4"},
            {'type': 'text', 'text': 'Describe this video.'}
        ]
    }
]

# 处理输入
inputs = processor.apply_chat_template(
    messages, 
    tokenize=True, 
    return_dict=True, 
    return_tensors="pt", 
    add_generation_prompt=True,
).to(model.device)
input_len = inputs["input_ids"].shape[-1]

# 生成输出
outputs = model.generate(**inputs, max_new_tokens=512)
response = processor.decode(outputs[0][input_len:], skip_special_tokens=False)

# 解析输出
processor.parse_response(response)

最佳实践

为获得最佳性能，建议采用以下配置与最佳实践：

1. 采样参数

在所有应用场景中，请使用以下标准化的采样配置：

• temperature=1.0
• top_p=0.95
• top_k=64

2. 思考模式配置

相较于 Gemma 3，本模型系列采用标准的 system、assistant 和 user 角色划分。为正确管理思考过程，请使用以下控制标记（tokens）：

• 触发思考： 在系统提示词开头包含 <|think|> 标记即可启用思考模式。若要禁用思考，移除此标记即可。
• 标准生成： 启用思考时，模型将先输出内部推理过程，随后给出最终答案，结构如下： <|channel|>thought\n[内部推理过程]`
• 禁用思考行为： 除 E2B 和 E4B 变体外，其余模型在禁用思考时仍会生成对应标记，但思考块为空： <|channel|>thought\n[最终答案]`

注意：Transformers 和 llama.cpp 等许多库已为您自动处理了聊天模板的底层复杂性。

3. 多轮对话

• 历史消息中不包含思考内容：在多轮对话中，历史记录应仅包含模型的最终回复。切勿在下一轮用户提问前添加先前轮次的思考过程。