---
title: 如何在本地用 Ollama 和 OpenCode 运行 Gemma 4 12B
description: >-
  Google 最新发布的 Gemma 4 12B 是一款多模态开放模型，可在 16GB 内存的笔记本上运行。本文将介绍如何用 Ollama 拉取模型，并接入
  OpenCode 作为本地编程助手。
date: 2026-06-04T00:00:00.000Z
location: 美国加州旧金山 – 2026 年 6 月 4 日
image: /images/gemma-4-12b-ollama-opencode-setup-hero.jpg
keywords: >-
  gemma 4 12b, gemma 4 12b ollama, gemma 4 12b opencode, 本地运行 gemma 4 12b, gemma
  4 12b 部署, gemma 4 12b 多模态
faq:
  - question: Gemma 4 12B 是什么？
    answer: >-
      Gemma 4 12B 是 Google 于 2026 年 6 月 3 日发布的 120 亿参数开放模型，采用 Apache 2.0
      许可证。它原生支持多模态（文本、视觉和音频），采用无编码器架构，Google 表示其基准测试性能接近 26B 模型，而内存占用不到后者的一半。
  - question: 本地运行 Gemma 4 12B 需要多少内存？
    answer: >-
      Google 列出的最低要求是 16GB 显存或统一内存，即可在消费级笔记本上运行 Gemma 4 12B。默认 4-bit 量化下，模型权重约为
      8GB，因此 16GB 还能为上下文和其他应用留出空间。24GB 或更多内存则能让长时间编程会话更从容。
  - question: Gemma 4 12B 可以配合 OpenCode 使用吗？
    answer: >-
      可以。通过 Ollama 运行 Gemma 4 12B，然后在 ~/.config/opencode/opencode.jsonc 中将
      Ollama 添加为自定义 provider，指向 http://localhost:11434/v1.。重启 重启 OpenCode 后使用
      /models 选择该模型即可。模型拉取完成后无需 API 密钥或网络连接。
locale: zh-cn
translationKey: gemma-4-12b-ollama-opencode-setup
---
Google 于 2026 年 6 月 3 日发布了 **Gemma 4 12B**，它恰好满足了大多数本地开发者最实际的需求：推理能力够强，体量又够小，手头的笔记本就能跑起来。

最大的亮点是新增的中间尺寸模型。此前的 Gemma 4 系列只有一个小型边缘模型和一个 26B 旗舰模型，中间存在明显空档。12B 正好补上了这个缺口。Google 表示其基准测试性能接近 26B 模型，而内存占用不到后者的一半，整个模型在 16GB 内存下即可运行——大多数新款 Mac 和中端 GPU 早已满足。

本指南先介绍 12B 变体的变化，然后演示如何通过 Ollama 运行它，并接入 OpenCode 作为本地私有编程助手。

## Gemma 4 12B 有哪些新特性

- **120 亿参数**，定位于 E4B 边缘模型和 26B 混合专家（MoE）旗舰模型之间。
- **原生多模态输入。** 文本、视觉和音频由同一个模型处理。架构采用无编码器设计：图像通过轻量级嵌入模块处理，原始音频直接投影到文本 token 空间。相比外挂式视觉编码器，整体组件更少。
- **推理能力接近 26B 模型。** Google 表示 12B 的基准测试性能接近其 26B 变体，而内存占用不到一半。
- **多 Token 预测（MTP）草稿模型**，可降低延迟，对需要等待每个 token 输出的交互式场景很有帮助。
- **为 Agent 工作流而构建**，工具调用和多步编程循环是核心功能，而非事后补充。
- **Apache 2.0 许可证。** 支持商业使用、微调和再分发。Gemma 4 系列下载量已突破 1.5 亿次。

模型权重已发布在 Hugging Face 和 Kaggle，首日即支持 Transformers、llama.cpp、MLX、SGLang 和 vLLM。Ollama 基于 llama.cpp 和 GGUF 构建，因此 12B 的运行方式与之前的 Gemma 4 模型完全一致。

## Gemma 4 12B 与系列其他型号对比

| 变体 | 适用场景 | 内存需求 |
|---|---|---|
| E4B（边缘） | 手机、嵌入式和端侧应用 | 极低 |
| **12B（新增）** | 笔记本上的本地编程 + 视觉/音频 | 16GB+ |
| 26B MoE（旗舰） | 更重的推理任务、大型多文件工作 | 24GB+ |

如果你的机器配置较低，或者只是想用更小的默认模型，之前的 [Gemma 4 + Ollama + OpenCode 部署指南](/zh-cn/blog/使用ollama为opencode配置gemma-4/) 仍然适用。当你有充足的内存余量，想要明显更强的推理能力、又不想直接上 26B 时，12B 就是你的升级之选。

## 前置要求

- 搭载 Apple Silicon（M1–M5）且至少 16GB 统一内存的 Mac，或配备 16GB+ 显存 GPU 的 PC
- macOS 上已安装 Homebrew
- 已安装 OpenCode（参见 [opencode.ai](https://opencode.ai)）

Google 给出的最低要求是 16GB。这个配置足以满足日常使用。如果有 24GB 或更多内存，长时间会话和更大的上下文窗口就不再是问题。

## 第 1 步：安装 Ollama

macOS 上：

```bash
brew install --cask ollama-app
open -a Ollama
```

Linux 上：

```bash
curl -fsSL https://ollama.com/install.sh | sh
```

等待菜单栏图标出现（macOS）或服务启动，然后确认服务器已运行：

```bash
ollama list
```

本地 API 地址为 `http://localhost:11434`。

## 第 2 步：拉取 Gemma 4 12B

```bash
ollama pull gemma4:12b
```

默认 4-bit 量化下，下载大小约为 8GB。确认模型已就位：

```bash
ollama list
# NAME             ID              SIZE      MODIFIED
# gemma4:12b       ...             ~8 GB     ...
```

做一次快速验证：

```bash
ollama run gemma4:12b "Write a small TypeScript function that debounces a callback"
```

确认 GPU 正在进行计算：

```bash
ollama ps
# Should show a CPU/GPU split, e.g. 12%/88% CPU/GPU
```

在 Apple Silicon 上，较新版本的 Ollama 会自动使用 Apple 的 MLX 后端，因此你无需做任何加速配置。

> **找不到 tag？** Gemma 4 12B 刚刚发布，如果 `gemma4:12b` 尚未收录到 Ollama 模型库，可以从 Hugging Face 拉取官方 GGUF 文件并导入，或者更新 Ollama（`brew upgrade ollama-app`）后重试。

## 第 3 步：将 Gemma 4 12B 连接到 OpenCode

OpenCode 从 `~/.config/opencode/opencode.jsonc` 读取配置。将 Ollama 添加为自定义 provider：

```jsonc
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gemma4:12b": {}
      }
    }
  }
}
```

Ollama 不验证密钥，但 OpenCode 仍需要一个认证条目。在 `~/.local/share/opencode/auth.json` 中添加一个占位符：

```json
{
  "ollama": {
    "type": "api",
    "key": "ollama"
  }
}
```

重启 OpenCode，运行 `/models`，然后切换到 `ollama/gemma4:12b`。这样你就拥有了一个绝不会将代码发送到外部的编程助手。

## 第 4 步：保持模型常驻内存

默认情况下，Ollama 在空闲约五分钟后会卸载模型，这意味着每次回到终端都要经历冷启动。让模型保持加载：

```bash
launchctl setenv OLLAMA_KEEP_ALIVE "-1"
```

重启 Ollama 使配置生效。要让设置在重启后依然有效，将以下内容添加到 `~/.zshrc`：

```bash
export OLLAMA_KEEP_ALIVE="-1"
```

在 Ollama 菜单栏图标中，你还可以启用**登录时启动**，这样在你打开终端前服务器就已就绪。

## Gemma 4 12B 在 OpenCode 中的优势场景

额外参数和 MTP 草稿模型，在之前小模型表现吃力的场景中提升最明显：

- **多步编辑。** 相比 8B，它能在跨文件修改时更好地保持整体方案，因此小型重构一次通过的概率更高。
- **代码解释和审查。** 询问某个模块的功能，或 bug 可能藏在哪里，回答会更精准。
- **样板代码和脚手架。** 配置文件、测试桩、路由处理器和 CRUD 层都能生成得很整洁。
- **视觉输入。** 由于 12B 是多模态的，你可以直接给它一张错误对话框截图或 UI 原型图，让它给出修复方案或生成组件，无需单独部署视觉模型。

## 目前的不足之处

- **大型跨模块重构。** 跨十几个文件的协调修改仍然容易跑偏。12B 比 8B 做得更好，但仍未彻底解决这个问题。
- **最困难的调试。** 跨越多个抽象层，或需要深厚领域知识的 bug，仍是前沿云端模型的优势所在。
- **16GB 上的超长上下文。** 模型支持较大的上下文窗口，但在 16GB 机器上，内存压力会导致质量下降。保持输入量合理，或升级到 24GB+。

## 混合方案：本地 Gemma 4 12B + 云端模型

大多数人最终采用的方案是：日常 70% 的工作用本地模型，剩下 30% 的难题交给云端。以下是各自的获取方式：

- **[haimaker.ai](https://haimaker.ai)** — 一个 API 密钥即可访问 Claude Opus、GPT-5、Gemini Pro 及数百个其他模型，统一计费并提供基准测试，方便你在选择之前先做对比。
- **Ollama** — 本地 Gemma 4 12B，免费且私密，适合日常编辑和查看。
- **直接使用 Provider API** — 如果你只需要一家云端供应商，并且想自行管理每个 provider 的密钥。

在 OpenCode 中将 Haimaker 与 Ollama 并列添加：

```jsonc
{
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "gemma4:12b": {}
      }
    },
    "haimaker": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "https://api.haimaker.ai/v1"
      },
      "models": {
        "anthropic/claude-sonnet-4-6": {},
        "openai/gpt-5": {},
        "google/gemini-2.5-pro": {}
      }
    }
  }
}
```

将你的 Haimaker 密钥添加到 `auth.json`：

```json
{
  "ollama": {
    "type": "api",
    "key": "ollama"
  },
  "haimaker": {
    "type": "api",
    "key": "YOUR_HAIMAKER_API_KEY"
  }
}
```

日常简单任务用 Gemma 4 12B，遇到难题时用 `/models` 切换到 Sonnet 或 GPT-5。云端开销只是全用前沿模型的一小部分。如果想跳过手动切换，[Haimaker 的自动路由](/blog/openclaw-auto-router-setup/) 可以检测任务复杂度并自动为你选择模型。

在 [haimaker.ai](https://haimaker.ai) 注册，浏览完整的[模型目录](https://haimaker.ai/models)。

<a href="https://app.haimaker.ai/sign-up?utm_source=blog&utm_medium=cta&utm_campaign=gemma4-12b-opencode" class="cta-button">获取你的 HAIMAKER API 密钥</a>

## 故障排除

**/models 中看不到 provider。** 编辑配置后重启 OpenCode。它不会在运行时重新加载 `opencode.jsonc`。

**"Model not found"（找不到模型）。** 运行 `ollama list` 并确保模型 ID 完全一致，通常是 `gemma4:12b`。如果该 tag 尚未收录到模型库，请参阅第 2 步中关于导入 Hugging Face GGUF 的说明。

**Ollama 认证错误。** `"key": "ollama"` 中的占位符 `auth.json` 就足够了。OpenCode 只需要该条目存在即可。

**生成速度慢。** 确保你使用的是较新版本的 Ollama，以便在 Apple Silicon 上获得 MLX 加速（`ollama --version`）。关闭占用内存大的应用。在 16GB 机器上，几个正在播放视频的浏览器标签页就可能触发内存交换。

**长提示词质量下降。** 这是 16GB 机器上的内存压力所致。保持上下文输入适度，或升级到 24GB+ 以获得余量。

## 常用 Ollama 命令

| 命令 | 说明 |
|---|---|
| `ollama list` | 列出已下载的模型 |
| `ollama ps` | 显示运行中的模型及内存使用情况 |
| `ollama run gemma4:12b` | 交互式对话 |
| `ollama stop gemma4:12b` | 从内存中卸载 |
| `ollama pull gemma4:12b` | 更新到最新版本 |
| `ollama rm gemma4:12b` | 删除模型 |

## 总结

Gemma 4 12B 正是许多人期待已久的本地模型：多模态、Apache 许可证、足够强大，能在 16GB 笔记本上处理日常编程的大部分工作。通过 Ollama 运行它，把 OpenCode 指向它，你就拥有了一个处理日常工作的私有助手。遇到难题时，随时用 `/models` 切到云端模型——既能享受本地运行的速度和隐私，也不会受限于本地模型的推理上限。

---

*刚接触本地部署？从 [Gemma 4 + OpenCode 指南](/zh-cn/blog/使用ollama为opencode配置gemma-4/) 开始，使用更小的默认模型；如果你使用 OpenClaw 作为 Agent，可以参考 [Gemma 4 + OpenClaw 部署指南](/blog/gemma-4-ollama-openclaw-setup/)。如需了解云端定价，请查看[模型目录](https://haimaker.ai/models)。*