google/gemma-4-12B-it-qat-q4_0-gguf

`# google/gemma-4-12B-it-qat-q4_0-gguf · Hugging Face 来源: https://huggingface.co/google/gemma-4-12B-it-qat-q4_0-gguf Hugging Face (https://huggingface.co/collections/google/gemma-4)|GitHub (https://github.com/google-gemma)|发布博客 (https://blog.google/innovation-and-ai/technology/developers-tools/introducing-gemma-4-12B/)|文档 (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/)

本模型卡片适用于经过量化感知训练（QAT）优化的新版 Gemma 4 系列。该训练方式能够在极大降低模型加载所需内存的同时，保持与 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 缓存和静态激活，以最大化节省显存。适用于 Gemma 4 E2B 和 E4B。
• 压缩张量 (w4a16)：以压缩张量格式序列化的 QAT 检查点，用于在 vLLM 上进行原生、优化的推理。适用于 Gemma 4 E2B、E4B、12B 和 31B。

Gemma 是由 Google DeepMind 构建的开放模型系列。Gemma 4 模型是多模态的，可处理文本和图像输入（E2B、E4B 和 12B 模型支持音频）并生成文本输出。此版本包含预训练和指令微调两种变体的开放权重模型。

Gemma 4 拥有高达 256K token 的上下文窗口，并支持超过 140 种语言的多语言能力。Gemma 4 兼具 Dense 和 Mixture-of-Experts (MoE) 架构，非常适合文本生成、编码和推理等任务。该模型提供五种不同的尺寸：E2B、E4B、12B、26B A4B 和 31B。其多样化的尺寸使其能够部署在从高端手机到笔记本电脑和服务器的各种环境中，促进了尖端 AI 的普及。

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

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

模型概览

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

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

Dense 模型

E2B 和 E4B 中的 “E” 代表 “有效” 参数。较小的模型采用了逐层嵌入 (PLE) 技术，以最大化设备端部署的参数效率。PLE 不是增加更多的层或参数，而是为每个解码器层提供其自身针对每个 token 的小型嵌入。这些嵌入表很大，但仅用于快速查找，这就是有效参数计数远小于总数量的原因。

Gemma 4 12B Unified 中的 “Unified” 指的是其无编码器的架构。其他 Gemma 4 模型使用专门的编码器处理多模态数据，然后再传递给 LLM。Gemma 4 12B 完全取消了这些编码器，通过轻量级的线性层将原始图像块和音频波形直接投影到 LLM 的嵌入空间中。这种统一的方法意味着所有模态直接流入单个仅解码器 Transformer，从而减少了多模态延迟，并允许整个模型在一次训练中完成微调。

Mixture-of-Experts (MoE) 模型

26B A4B 中的 “A” 代表 “激活参数”，与模型包含的总参数数量形成对比。通过在推理过程中仅激活 40亿参数的子集，Mixture-of-Experts 模型的运行速度远快于其总计 260亿参数所暗示的速度。这使得它与 Dense 模型 31B 相比，成为快速推理的绝佳选择，因为它的运行速度几乎与 40亿参数模型一样快。

基准测试结果

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

*排除中文语言。

核心能力

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

• 思考 – 内置推理模式，让模型在回答前逐步思考。
• 长上下文 – 高达 128K token (E2B/E4B) 和 256K token (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": "You are a helpful assistant."},
    {"role": "user", "content": "Write a short joke about saving 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": "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."},
            {"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": "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)

处理视频的代码

确保安装以下包： 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': '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 角色。为了正确管理思考过程，请使用以下控制 token：

• 触发思考： 通过在系统提示的开头包含 <|think|> token 来启用思考。要禁用思考，请移除该 token。
• 标准生成： 当思考启用时，模型将使用以下结构输出其内部推理，然后是最终答案：<|channel>thought\n [内部推理内容] response <|channel>final\n` [最终答案]