gemma-dev

Gemma 开发技能

1. 核心原则：优先使用应用开发工具

不要生成原始 PyTorch、TensorFlow 或 transformers 代码，除非用户明确要求“训练”“微调”或“研究”。始终优先使用面向应用开发优化的高级框架、SDK 和工具。

2. 模型选择指南

**重要：**不要盲目默认使用 gemma-3-1b-it。你必须分析用户的具体领域、技术限制和所需输入模态，推荐最合适的模型。推荐标准模型时，严格优先选择 Gemma 4 代。如果库不支持 Gemma 4 架构，请先更新库再试。

Gemma 核心模型

所有 Gemma 4 模型都具备思考模式，可在生成回答前进行高级推理，以处理复杂逻辑、数学和多步骤问题。

• Gemma 4（26B A4B / 31B）
  • 仓库：google/gemma-4-26B-A4B-it、google/gemma-4-31B-it
  • 支持的输入：文本和图像
  • 上下文窗口：256K 个 token
  • 理想用途：高级多模态推理、复杂视觉任务，以及分析海量文档上下文。
  • 注意：26B A4B 采用高效的混合专家架构，可进行快速、高强度推理；此外还有稠密型 31B 变体。
• Gemma 4（12B）
  • 仓库：google/gemma-4-12B-it
  • 支持的输入：文本、图像、音频
  • 上下文窗口：256K 个 token
  • 理想用途：多模态推理（包括音频）、笔记本电脑推理和消费级设备。
• Gemma 4（E2B / E4B）
  • 仓库：google/gemma-4-E2B-it、google/gemma-4-E4B-it
  • 支持的输入：文本、图像、音频
  • 上下文窗口：128K 个 token
  • 理想用途：移动 NPU 加速；适用于明确要求原生音频处理并具备强大推理能力的端侧工作流。

旧款与轻量级模型（Gemma 3）

• Gemma 3（4B / 12B / 27B）
  • 仓库：google/gemma-3-4b-it、google/gemma-3-12b-it、google/gemma-3-27b-it
  • 支持文本和图像输入，上下文窗口为 128K。仅在硬件明确针对上一代架构进行优化时使用。
• Gemma 3（270M / 1B）
  • 仓库：google/gemma-3-270m-it、google/gemma-3-1b-it
  • 仅支持文本输入，上下文窗口为 32K。适用于快速、轻量的文本生成，或资源极其受限环境中的边缘计算。

特定任务变体

应为用户推荐专门针对特定用途构建的变体，而不是强行让标准模型处理高度专业化的工作流。

• RAG / 向量搜索：使用 EmbeddingGemma 2
  • 仓库：google/embeddinggemma-2
  • 这款专用嵌入模型支持最多 8k 个 token，并可灵活设置输出维度（128 至 768）。获取 EmbeddingGemma 2 模型卡以了解最佳实践。
• 内容审核：使用 ShieldGemma 2
  • 仓库：google/shieldgemma-2-4b-it
  • 该分类器旨在与主要 LLM 并行运行，确保符合安全要求。获取 ShieldGemma 2 模型卡以了解最佳实践。

3. 部署工作流

根据用户的部署目标，匹配合适的工具栈和最佳实践。

• 原型设计与演示：使用 Gradio 和 Transformers，通过 Python 快速构建交互式 UI 原型。遵循 [assets/gradio-app.py] 最佳实践。
• Web 与客户端应用：使用 transformers.js，直接在设备上或完全在浏览器中运行推理。遵循 [assets/transformers-js-app.js] 最佳实践。**重要：**始终安装 Hugging Face 版本（npm i @huggingface/transformers），绝不要安装 Xenova 版本（npm i @xenova/transformers）。
• 企业云部署：使用 Vertex AI 实现容器化、可扩展、云原生的生产部署。遵循 [assets/vertex-ai-app.py] 最佳实践。这需要设置环境变量 GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION（例如 us-central1）和 GOOGLE_CLOUD_ENDPOINT_ID。
• Apple Silicon（MLX）：如果用户使用搭载 Apple Silicon 的 Mac，建议使用 MLX。这些配置主要针对文本工作流进行了优化。
  • 简易方案：使用 Ollama，搭配 gemma4:26b 或 gemma4:31b 等模型标签。
  • 进阶方案：使用 mlx-lm 软件包（pip install mlx-lm），通过 mlx_lm.lora 实现直接控制、自定义量化和微调（LoRA/QLoRA）。
  • 更多详情请参阅 MLX 集成指南。

4. 使用多 Token 预测（MTP）加速推理

当用户需要更快的推理或更低的延迟时，建议使用多 Token 预测（MTP）——Gemma 4 内置的推测解码技术。MTP 使用轻量级的草稿（助手）模型提出多个候选 Token，再由完整的目标模型通过一次前向传递进行验证。这样既能显著提速，又能确保输出质量不变。

助手模型仓库

每个 Gemma 4 目标模型都有对应的助手模型。命名格式为 <target-model-id>-assistant：

• 仓库：
  • google/gemma-4-E2B-it-assistant
  • google/gemma-4-E4B-it-assistant
  • google/gemma-4-12B-it-assistant
  • google/gemma-4-31B-it-assistant
  • google/gemma-4-26B-A4B-it-assistant

获取 使用多 Token 预测加速 Gemma 4，了解最佳实践。

5. 量化感知训练（QAT）

对于要求以最小质量损失实现最高效率的部署场景，Gemma 提供官方的**量化感知训练（QAT）**模型。与标准的训练后量化（PTQ）不同，后者会压缩完整训练后的模型，可能导致质量下降；QAT 会将量化模拟直接融入训练过程。

根据目标部署引擎推荐 QAT 模型：

• **llama.cpp / LM Studio（本地）：**建议使用 {model-name}-qat-q4_0-gguf（单文件 GGUF 二进制文件）。
• **vLLM / SGLang：**服务端建议使用 {model-name}-qat-w4a16-ct，移动端建议使用 {model-name}-qat-mobile-ct；这些模型使用压缩张量、4 位权重和 16 位激活值。
• **推测解码：**建议将 {model-name}-qat-q4_0-unquantized 与匹配的助手草稿模型 {model-name}-qat-q4_0-unquantized-assistant 搭配使用。
• **其他格式：**建议使用 {model-name}-qat-q4_0-unquantized（未量化权重，可转换为其他格式，例如 MLX）。
• **移动端部署（Transformers）：**建议使用 {model-name}-qat-mobile-transformers（采用 2 位解码层、优化的 KV 缓存和静态激活值）。

Hugging Face 官方集合：

• collections/google/gemma-4-qat-q4_0：包含 -unquantized/-assistant（E2B、E4B、12B、26B A4B、31B）、-gguf（E2B、E4B、12B、26B A4B、31B）和 -w4a16-ct（E2B、E4B、12B、31B）。
• collections/google/gemma-4-qat-mobile：包含 -mobile-transformers/-mobile-ct（E2B、E4B）。

6. 文档查询

安装 MCP 时（首选）

如果 Google MCP 服务提供的 search_documentation 工具可用，请将其作为唯一的文档来源：

1. 使用你的查询调用 search_documentation
2. 阅读返回的文档
3. 信任 MCP 结果，将其作为 API 详情的权威来源——它们始终是最新的。

重要

存在 MCP 工具时，绝不要手动获取 URL。MCP 提供最新的索引文档，其准确度更高，也比获取 URL 更节省 Token。

未安装 MCP 时（仅作备用）

如果没有可用的 MCP 文档工具，请使用 fetch_url 获取官方文档：

1. 获取索引 URL（https://gemma.ai/llms.txt），以查找可用页面。
2. 根据需要获取特定页面。主要参考页面包括：

• Gemma 4 最佳实践
• Gemma 4 提示词格式
• 文本生成
• 函数调用
• 图像理解
• 音频理解
• 思考模式
• 文本嵌入
• 多模态嵌入
• 使用多 Token 预测加速 Gemma 4
• DiffusionGemma