unsloth/gemma-4-12B-it-qat-GGUF · Hugging Face

原文链接：https://huggingface.co/unsloth/gemma-4-12B-it-qat-GGUF

请阅读我们的《如何运行 Gemma 4 QAT 指南》！

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

Hugging Face | GitHub | 发布博客 | 文档

许可证：Apache 2.0 | 作者：Google DeepMind

此模型卡片适用于 Gemma 4 系列的新版本，这些版本通过量化感知训练（QAT）进行了优化，能够在保持与 bfloat16 相似的质量的同时，大幅降低加载模型所需的内存。QAT 检查点共有四个版本可用：

• 未量化的 QAT 检查点（Q4_0）：从 QAT 流程中提取的半精度权重，适用于自定义下游编译和研究。适用于 Gemma 4 E2B、E4B、12B、26B A4B 和 31B，以及它们的草稿模型。
• GGUF（Q4_0）：即开即用格式，提供广泛的生态兼容性。适用于 Gemma 4 E2B、E4B、12B、26B A4B 和 31B。
• 移动端优化（wNa8o8）：专门为移动硬件效率设计的自定义模式。它具有针对性的 2-bit 解码层、优化的 KV 缓存和静态激活，以最大化 VRAM 节省。适用于 Gemma 4 E2B 和 E4B。
• 压缩张量（w4a16）：以压缩张量格式序列化的 QAT 检查点，用于与 vLLM 配合使用实现原生优化推理。适用于 Gemma 4 E2B、E4B、12B 和 31B。

Gemma 是 Google DeepMind 构建的一系列开放模型。Gemma 4 模型是多模态的，支持文本和图像输入（E2B、E4B 和 12B 还支持音频），并生成文本输出。此次发布包括预训练和指令调优两种变体的开放权重模型。

Gemma 4 提供了高达 256K 令牌的上下文窗口，并支持超过 140 种语言的多语言处理。Gemma 4 兼具稠密（Dense）和混合专家（MoE）架构，非常适合文本生成、编码和推理等任务。该模型提供五种不同的尺寸：E2B、E4B、12B、26B A4B 和 31B。这些不同的尺寸使其能够部署在高性能手机、笔记本电脑和服务器等环境中，实现了最先进 AI 的普及化。

Gemma 4 引入了关键的能力和架构进步：

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

模型概览

Gemma 4 模型旨在为每种尺寸提供前沿性能，覆盖从移动端和边缘设备（E2B、E4B）到消费级 GPU 和工作站（12B、26B A4B、31B）的部署场景。它们非常适合推理、智能体工作流、编码和多模态理解。

这些模型采用混合注意力机制，将局部滑动窗口注意力与全局注意力交错结合，确保最后一层始终是全局的。这种混合设计提供了轻量级模型的处理速度和低内存占用，同时不牺牲复杂长上下文任务所需的深层感知能力。为了优化长上下文的内存使用，全局层采用了统一的键和值，并应用了比例旋转位置编码（p-RoPE）。

稠密模型

E2B 和 E4B 中的“E”代表“有效”参数。较小的模型采用了逐层嵌入（PLE）技术，以最大化端侧部署的参数效率。PLE 并非简单地增加层数或参数量，而是为每个解码器层的每个令牌赋予一个独立的、小型嵌入表。这些嵌入表很大，但仅用于快速查找，因此有效参数量远小于总量。

Gemma 4 12B 统一版中的“统一”指的是其无编码器架构。其他 Gemma 4 模型使用专用编码器处理多模态数据后，再将其传递给大语言模型。Gemma 4 12B 完全消除了这些编码器，通过轻量级线性层将原始图像块和音频波形直接投射到大语言模型的嵌入空间中。这种统一的方法使所有模态直接流入一个仅解码器变换器，从而降低了多模态处理延迟，并允许在一次训练中微调整个模型。

混合专家（MoE）模型

26B A4B 中的“A”代表“激活参数”，与模型的总参数量相对应。通过在推理时仅激活 4B 的子集参数，混合专家模型的运行速度远比其 26B 总量所暗示的要快。这使得它成为比稠密 31B 模型更优秀的快速推理选择，因为它的运行速度几乎与 4B 参数模型一样快。

基准测试结果

这些模型针对大量不同的数据集和指标进行了评估，以覆盖文本生成的各个方面。表格中标注的评估结果针对的是指令调优模型。

* 不包括中文语言。

核心能力

Gemma 4 模型能够处理文本、视觉和音频领域的广泛任务。关键能力包括：

• 思考 – 内置推理模式，让模型在回答问题前逐步思考。
• 长上下文 – 支持高达 128K 个令牌（E2B/E4B）和 256K 个令牌（12B、26B A4B/31B）的上下文窗口。
• 图像理解 – 目标检测、文档/PDF 解析、屏幕和 UI 理解、图表理解、OCR（包括多语言）、手写识别和指点。图像可以以可变宽高比和分辨率进行处理。
• 视频理解 – 通过处理帧序列来分析视频。
• 交错多模态输入 – 在单个提示中以任意顺序自由混合文本和图像。
• 函数调用 – 原生支持结构化工具使用，实现智能体工作流。
• 编码 – 代码生成、补全和修正。
• 多语言 – 开箱即用支持 35+ 种语言，预训练语言覆盖 140+ 种。
• 音频（仅限 E2B、E4B 和 12B） – 跨多种语言的自动语音识别（ASR）和语音到翻译文本的翻译。

快速开始

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

pip install -U transformers torch accelerate

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

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-12B-it"

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

加载模型后，您可以开始生成输出：

# 提示信息
messages = [
    {"role": "system", "content": "你是一个乐于助人的助手。"},
    {"role": "user", "content": "讲一个关于节省 RAM 的简短笑话。"},
]

# 处理输入
inputs = processor.apply_chat_template(
    messages,
    tokenize=True,
    return_dict=True,
    return_tensors="pt",
    add_generation_prompt=True,
    enable_thinking=False
).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、12B）、图像和视频以及文本的代码片段：

处理音频的代码

请确保安装以下软件包：

pip install -U transformers torch torchvision librosa accelerate

然后，您可以使用以下代码加载模型：

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-12B-it"

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

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

# 提示 - 在文本后添加音频
messages = [
    {
        "role": "user",
        "content": [
            {"type": "text", "text": "以原始语言转录以下语音片段。请按照以下具体说明格式化答案：\n* 只输出转录内容，不要换行。\n* 转录数字时，请写出数字，例如写 1.7 而不是 one point seven，写 3 而不是 three。"},
            {"type": "audio", "audio": "https://raw.githubusercontent.com/google-gemma/cookbook/refs/heads/main/apps/sample-data/journal1.wav"},
        ]
    }
]

# 处理输入
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)

处理图像的代码

请确保安装以下软件包：

pip install -U transformers torch torchvision accelerate

然后，您可以使用以下代码加载模型：

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-12B-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/apps/sample-data/GoldenGate.png"},
            {"type": "text", "text": "这张图片显示了什么？"}
        ]
    }
]

# 处理输入
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)

处理视频的代码

请确保安装以下软件包：

pip install -U transformers torch torchvision librosa accelerate

然后，您可以使用以下代码加载模型：

from transformers import AutoProcessor, AutoModelForMultimodalLM

MODEL_ID = "google/gemma-4-12B-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': '描述这个视频。'}
        ]
    }
]

# 处理输入
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 角色。为了正确管理思考过程，请使用以下控制令牌：

• 触发思考： 通过在提示中包括 <|think|> 令牌来启用思考。