什么是 Gemma 4?
Gemma 4 是 Google DeepMind 的开放权重模型家族,面向本地部署与研究而设计。它延续了 Gemma 系列,并在指令遵循、更长上下文窗口、原生多模态输入处理等方面得到提升,且与 Gemini 3 共享同一研究基础设施。

图:模型性能与规模对比(来源: Gemma 4 博客)
诸如 Gemma-4-26B(MOE)和 Gemma-4-31B 等模型取得了与更大模型相当的 Elo 分数,显示出很强的参数效率表现。31B 模型目前在 Arena AI 文本排行榜上位列全球开源模型第 3,26B 模型位列第 6。 这使得 Gemma 4 特别适合在本地和资源受限环境中部署,同时不牺牲能力。
Gemma 4 模型家族
Gemma 4 发布了四种灵活的大小:Effective 2B(E2B)、Effective 4B(E4B)、26B 专家混合(MoE)以及 31B 稠密模型。 该家族基于部署目标分为两个层级:
|
模型 |
架构 |
总参数量 |
激活/有效参数 |
上下文长度 |
模态 |
|
Gemma-4-31B |
稠密 Transformer |
31B |
31B |
256K tokens |
文本、视觉、视频 |
|
Gemma-4-26B-A4B |
MoE(128 专家) |
26B |
3.8B 激活 |
256K tokens |
文本、视觉、视频 |
|
Gemma-4-E4B |
稠密 Transformer |
7.9B(含嵌入) |
4.5B 有效 |
128K tokens |
文本、音频、视觉、视频 |
|
Gemma-4-E2B |
稠密 Transformer |
5.1B(含嵌入) |
2.3B 有效 |
128K tokens |
文本、音频、视觉、视频 |
下面我们深入了解各个变体:

图:Gemma 4 可视化指南(来源)
- 31B 稠密 是旗舰模型,针对数据中心部署和复杂推理工作负载优化。支持 256K token 上下文窗口,并配有 1024-token 滑动窗口以高效处理长上下文。
- 26B-A4B(MoE) 是 Gemma 的首个 MoE 模型,将 token 路由至 128 位专家,同时每次前向仅保持 3.8B 参数激活。它以更低的每 token 计算成本接近 31B 的质量,非常适合高吞吐量服务。
- E4B 与 E2B 属于端侧与移动端层级。不同于更大变体,它们原生支持语音识别的音频输入,并兼具视觉与视频能力,使其成为该家族中在边缘部署上多模态能力最强的模型。
四个模型均采用 Apache 2.0 许可,并可通过 Ollama、vLLM、llama.cpp 或 Unsloth 在本地部署。
在编码任务上,Gemma 4 擅长:
- 编写完整、结构化代码并配以说明
- 在提供上下文的前提下对现有代码库进行推理
- 与编排层配合使用工具与工具型工作流
- 与代码一起处理图像(例如读取 UI 截图并生成匹配的 HTML)
在本教程中,我们通过 Ollama 使用 gemma4:e4b(9.6GB)变体,这是一个适合在消费级硬件上进行本地推理的量化版本。
通过 Ollama 运行 Gemma 4
Ollama 负责模型下载、量化与服务,并提供兼容 OpenAI 的 HTTP API。在本教程中,Ollama 充当推理后端,我们的应用通过 localhost:11434 与其通信。
拉取并运行模型:
curl -fsSL https://ollama.com/install.sh | sh
ollama pull gemma4:e4b
ollama serve
上述命令通过官方安装脚本在本地安装 Ollama。随后我们在本地下载 gemma 4:e4b 模型变体以进行端侧推理。最后,ollama serve 启动 Ollama 服务,使我们的应用能够向模型发送请求。
服务启动后,Gradio 应用会自动连接。
Gemma 4 演示:用 Ollama 构建编码助手
本节我们将逐步构建该编码助手。整体而言,应用将完成以下工作:
-
在聊天面板接收自然语言消息,可选附带图像或文件
-
将当前编辑器中的代码注入为模型上下文
-
通过 Ollama 的
/api/chat端点向 Gemma 4 发送流式请求 -
在工具型循环中可选调用工具(代码执行、数学求值)
-
将响应中提取的代码块推送到实时编辑器
我们一步步来搭建。

步骤 1:安装依赖
该应用仅需少量用于 UI、图像处理与 HTTP 通信的库。由于模型通过 Ollama 在本地运行,无需任何云端 SDK 依赖。
pip install gradio requests pillow
本项目将使用:
-
gradio构建分栏编辑器与聊天 UI -
requests与 Ollama 的 HTTP API 通信 -
pillow为 UI 提供图像处理支持
这使环境保持轻量,并可在任何运行 Ollama 的机器上工作,包括搭载 Apple Silicon 的 macOS、Linux 以及通过 WSL 的 Windows。
步骤 2:配置与常量
在编写逻辑之前,我们先定义导入、模型名称、Ollama 基础 URL、支持的语言以及默认系统提示。这些常量决定整个应用的行为。
import base64
import json
import math
import os
import re
import subprocess
import tempfile
from pathlib import Path
import gradio as gr
import requests
OLLAMA_BASE = "http://localhost:11434"
MODEL = "gemma4:e4b"
LANGUAGES = [
"python", "javascript", "typescript", "bash", "sql",
"rust", "go", "java", "c", "cpp", "html", "css",
"json", "yaml", "markdown", "plaintext",
]
TEXT_EXTS = {
".py", ".js", ".ts", ".jsx", ".tsx", ".html", ".css",
".json", ".yaml", ".yml", ".toml", ".md", ".txt",
".csv", ".sql", ".sh", ".bash", ".rs", ".go",
".java", ".c", ".cpp", ".h", ".hpp", ".rb", ".php",
}
IMAGE_EXTS = {".jpg", ".jpeg", ".png", ".webp", ".gif", ".bmp"}
DEFAULT_SYSTEM = """\
You are an expert coding assistant. When you write code:
- Always wrap it in a markdown code block with the language tag
- Write complete, working code — not fragments
- Briefly explain what the code does
You have a code-runner tool. Use it to validate logic when helpful.\
"""
TEXT_EXTS 与 IMAGE_EXTS 集合驱动两种不同的附件行为。文本/代码文件会被读取并以上下文形式注入到提示中,而图像文件会被 base64 编码并放入 images 字段,供 Gemma 4 的视觉能力使用。
DEFAULT_SYSTEM 提示用于塑造模型的代码生成风格,明确要求使用带语言标签的完整代码块,因为应用会解析这些代码块以将代码推送到编辑器。
步骤 3:定义工具型能力
助手可在工具型模式下工作,即在推理过程中调用工具。我们按照 Ollama 支持的标准函数调用模式定义两个工具:
TOOLS = [
{
"type": "function",
"function": {
"name": "run_code",
"description": (
"Execute Python code in a sandboxed subprocess and return "
"stdout + stderr. Use this to validate, test, or demonstrate code."
),
"parameters": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "Python code to run (max ~50 lines, 5 s timeout).",
}
},
"required": ["code"],
},
},
},
{
"type": "function",
"function": {
"name": "calculate",
"description": "Evaluate a mathematical expression precisely.",
"parameters": {
"type": "object",
"properties": {
"expression": {
"type": "string",
"description": "Python-compatible math expression, e.g. 'math.sqrt(2) * 100'",
}
},
"required": ["expression"],
},
},
},
]
上述代码段定义了 run_code 工具,它通过子进程在临时文件中执行 Python(5 秒超时),并捕获 stdout 与 stderr。这使模型不仅能生成静态文本,还能验证逻辑、运行示例并给出实时输出。
同时,calculate 工具会在受限命名空间下只使用 math 模块与安全内建函数求值数学表达式。当需要精确数值结果且不想启动完整 Python 进程时,它就派上用场。
步骤 4:工具执行
执行层将工具名称映射到其实现。每当模型返回 tool_calls 块时,代理循环会调用这里的实现。
def _run_python(code: str) -> str:
with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
f.write(code)
tmp = f.name
try:
r = subprocess.run(
["python3", tmp],
capture_output=True, text=True, timeout=5,
)
out = (r.stdout + r.stderr).strip()
return out[:3000] if out else "(no output)"
except subprocess.TimeoutExpired:
return "⏱ Timed out (>5 s)"
except Exception as e:
return f"Error: {e}"
finally:
os.unlink(tmp)
def _calculate(expr: str) -> str:
ns = {k: getattr(math, k) for k in dir(math) if not k.startswith("_")}
ns.update({"abs": abs, "round": round})
try:
return str(eval(expr, {"__builtins__": {}}, ns)) # noqa: S307
except Exception as e:
return f"Error: {e}"
def execute_tool(name: str, args: dict) -> str:
if name == "run_code":
return _run_python(args.get("code", ""))
if name == "calculate":
return _calculate(args.get("expression", ""))
return f"Unknown tool: {name}"
在工具执行栈中,有几项值得注意的安全设计:
-
_run_python()将代码写入临时文件并在结束时清理,避免即便出错也遗留文件 -
输出限制为 3000 字符,防止大量打印内容淹没上下文
-
_calculate()使用将__builtins__设为空字典的eval(),阻止访问除白名单math函数外的 Python 内建 -
硬性 5 秒超时,足以满足多数验证任务,又能避免失控进程
步骤 5:辅助工具函数
在构建核心聊天逻辑前,我们需要一些处理路径、图像编码与代码提取的实用函数。这些辅助函数会贯穿整个流式处理管线。
def encode_image(path: str) -> str | None:
if not path:
return None
try:
with open(path, "rb") as f:
return base64.b64encode(f.read()).decode()
except Exception:
return None
def file_as_context(path: str) -> str | None:
if not path:
return None
p = Path(path)
if p.suffix.lower() not in TEXT_EXTS:
return None
try:
content = p.read_text(encoding="utf-8", errors="replace")[:8000]
lang = p.suffix.lstrip(".")
return f"\n\n**Attached file — {p.name}:**\n```{lang}\n{content}\n```"
except Exception:
return None
def resolve_gradio_path(val) -> str | None:
if val is None:
return None
if isinstance(val, Path):
s = str(val)
return s if s.strip() else None
if isinstance(val, str):
s = val.strip()
return s if s else None
if isinstance(val, dict):
p = val.get("path")
if isinstance(p, str) and p.strip():
return p.strip()
nested = val.get("file")
if isinstance(nested, dict):
np = nested.get("path")
if isinstance(np, str) and np.strip():
return np.strip()
return None
name = getattr(val, "name", None)
if isinstance(name, str) and name.strip():
return name.strip()
return None
def is_image_path(path: str | None) -> bool:
return bool(path) and Path(path).suffix.lower() in IMAGE_EXTS
def extract_last_code_block(text: str) -> tuple[str | None, str]:
blocks = re.findall(r"```(\w*)\n(.*?)```", text, re.DOTALL)
if blocks:
lang, code = blocks[-1]
return code.strip(), lang.strip() or "python"
return None, "python"
def ollama_ok() -> bool:
try:
requests.get(f"{OLLAMA_BASE}/", timeout=2)
return True
except Exception:
return False
def _gradio_content_to_text(content) -> str:
if content is None:
return ""
if isinstance(content, str):
return content
if isinstance(content, list):
parts: list[str] = []
for block in content:
if isinstance(block, dict):
if block.get("type") == "text":
parts.append(str(block.get("text", "")))
elif "text" in block:
parts.append(str(block["text"]))
elif isinstance(block, str):
parts.append(block)
return "".join(parts)
return str(content)
def _append_chat_turn(
history: list | None, user_text: str, assistant_text: str
) -> list:
base = list(history) if history else []
return base + [
{"role": "user", "content": user_text},
{"role": "assistant", "content": assistant_text},
]
def run_code_btn(code: str) -> str:
if not code.strip():
return "Nothing to run."
result = _run_python(code)
return result
这些工具函数让多模态输入与结构化输出处理更顺畅:
-
encode_image()函数:将图像文件转换为base64字符串,以便传入 Ollama 的images字段。这样 Gemma 就能与文本一同处理图像,实现多模态推理。 -
file_as_context()函数:读取文本/代码文件,并将其直接作为格式化的 Markdown 块注入提示。这避免了单独的检索系统,一切以内联上下文传递。 -
resolve_gradio_path()函数:将 Gradio 返回的多种文件格式统一解析为可用的文件路径,避免文件处理中的边界问题。 -
is_image_path()函数:快速判断给定文件是否为图像,便于正确路由图像输入。 -
extract_last_code_block()函数:从模型响应中提取最后一个代码块。 -
ollama_ok()函数:在发起请求前验证本地 Ollama 服务是否已运行。 -
_gradio_content_to_text()与_append_chat_turn()函数:将 Gradio 的结构化消息扁平化为纯文本,便于一致处理,并维护对话历史。 -
run_code_btn()函数:当用户在 UI 中点击运行代码按钮时,用于执行生成的代码。
有了这些辅助工具,我们就可以实现核心的 chat() 函数了。
步骤 6:核心聊天流式生成器
该函数驱动整个交互循环:从准备输入到流式接收响应,再到处理工具执行。
概览来看,chat() 函数会:
- 构建对话历史
- 为当前用户输入补充上下文(代码、文件、图像)
- 向 Ollama 发送流式请求
- 可选执行工具(工具型模式)
- 逐步产出片段以实时更新 UI
def chat(
message, history, image_path, file_path,
editor_code, language, system_prompt,
agentic, thinking, temperature,
):
该函数遵循如下逐步序列:
步骤 1:构建消息历史
我们先将之前的机器人轮次转换为 Ollama 的消息格式。系统提示会置于最前,以引导模型行为,确保模型在生成响应前拥有完整的对话上下文。
for h in history or []:
if not isinstance(h, dict):
continue
role = h.get("role")
if role not in ("user", "assistant"):
continue
messages.append(
{"role": role, "content": _gradio_content_to_text(h.get("content"))}
)
content = message
步骤 2:组合用户轮次
接着通过注入额外上下文来构造当前用户消息。如果用户正在处理代码,我们会附加编辑器内容:
if editor_code.strip() and editor_code.strip() != STARTER_CODE.strip():
content += (
f"\n\n**Current code in editor ({language}):**\n"
f"```{language}\n{editor_code}\n```"
)
同理,上传的文件会以内联上下文的形式添加,图像会进行 base64 编码并通过 images 字段传递。这使模型能够同时对文本、代码和图像进行推理。
步骤 3:发送 Ollama 请求
请求负载包含模型名称、消息历史、流式标志与选项,如下所示:
payload = {
"model": MODEL,
"messages": messages,
"stream": True,
"options": options,
}
if agentic:
payload["tools"] = TOOLS
若启用思考模式,会设置 options["think"] = True,在支持的模型中激活扩展的链式思考推理。
步骤 4:处理工具调用(工具型模式)
若启用工具型模式,模型可能返回工具调用而非文本。此时会执行各工具,将结果追加至对话,然后发送后续请求继续生成。
if agentic and msg.get("tool_calls"):
for tc in msg["tool_calls"]:
fn_name = tc["function"]["name"]
fn_args = tc["function"]["arguments"]
result = execute_tool(fn_name, fn_args)
if fn_name == "run_code" and fn_args.get("code"):
new_code = fn_args["code"]
messages.append(msg)
messages.append({"role": "tool", "content": result})
resp2 = requests.post(f"{OLLAMA_BASE}/api/chat", ...)
这会创建一个单轮的工具型循环:模型调用工具、查看结果,然后继续生成最终响应。工具调用日志会预先展示给用户。
步骤 5:提取代码并更新编辑器
最后,在流结束后,我们从响应中提取最后一个代码块:
extracted, _ = extract_last_code_block(full_response)
if extracted:
new_code = extracted
总体而言,模型生成代码,编辑器自动更新,无需手动复制粘贴。
步骤 7:Gradio 界面布局
在核心逻辑就位后,我们使用 Gradio 设计用户界面。目标是创建一套布局,使编码工作流与 AI 辅助交互并行呈现。
我们使用 gr.Blocks 定义两列布局:
- 左侧面板专注代码编辑与执行
- 右侧面板负责聊天、附件与模型控制
with gr.Blocks(title="Gemma 4 · Code Assistant") as demo:
with gr.Row(equal_height=False):
# LEFT: Code Editor
with gr.Column(scale=11):
with gr.Row():
lang_sel = gr.Dropdown(choices=LANGUAGES, value="python", label="Language")
run_btn = gr.Button("Run Code", elem_classes=["run-btn"])
clear_ed = gr.Button("Clear")
code_editor = gr.Code(
value=STARTER_CODE,
language="python",
label="Editor",
lines=24,
interactive=True,
)
run_output = gr.Textbox(
label="Output",
lines=6,
interactive=False,
elem_id="run-output",
)
# RIGHT: Chat
with gr.Column(scale=9):
chatbot = gr.Chatbot(value=[], elem_id="chatbot", height=430)
with gr.Row():
image_upload = gr.Image(label="Image (vision)", type="filepath")
file_upload = gr.File(label="Code / text file")
with gr.Row():
msg_input = gr.Textbox(placeholder="Ask the agent...", scale=6)
send_btn = gr.Button("Send", variant="primary")
with gr.Row():
agentic_cb = gr.Checkbox(label="Enable Agentic", value=True)
thinking_cb = gr.Checkbox(label="Enable Thinking", value=False)
clear_chat = gr.Button("Clear chat")
with gr.Accordion("Settings", open=False):
sys_prompt = gr.Textbox(value=DEFAULT_SYSTEM, label="System prompt")
temperature = gr.Slider(minimum=0.0, maximum=2.0, value=0.7)
让我们看看 UI 如何与上述组件协同工作:
- 代码工作区:左侧面板包含语言选择器、代码编辑器以及运行/清空控件。执行输出会显示在高亮文本框中。
- 聊天与交互:右侧面板包含用于对话的聊天组件、查询输入框,并支持上传用于多模态推理的图像和用于上下文注入的文件。额外的开关可启用工具型调用和可选推理模式。
- 布局与易用性:界面采用双栏布局,约 55/45 分配,优先保证代码编辑器,同时让聊天触手可及。这样的平衡确保在编码、AI 协助与执行之间获得顺畅工作流。
步骤 8:事件绑定
发送与提交事件共用相同的输入输出,因此点击按钮与在文本框中按 Enter 会触发相同行为:
_inputs = [
msg_input, chatbot, image_upload, file_upload,
code_editor, lang_sel,
sys_prompt, agentic_cb, thinking_cb, temperature,
]
_outputs = [chatbot, code_editor, msg_input]
send_btn.click(fn=respond, inputs=_inputs, outputs=_outputs)
msg_input.submit(fn=respond, inputs=_inputs, outputs=_outputs)
respond() 封装函数会先将 Gradio 的文件路径对象解析为普通字符串路径,再传入流式生成器。随后它会在每个分片上产出 (history, code, ""),其中空字符串会在首次产出时清空消息输入框。
步骤 9:主题与 CSS
为提升可用性与视觉一致性,我们在 Gradio 默认样式之上添加自定义主题与 CSS,使应用更精致,具有 GitHub 风格,并同时支持亮/暗模式。本步骤完全可选。
首先使用 gr.themes.Base 定义基础主题:
THEME = gr.themes.Base(
primary_hue = "blue",
secondary_hue = "slate",
neutral_hue = "slate",
font = [gr.themes.GoogleFont("Inter"), "system-ui", "sans-serif"],
font_mono = [gr.themes.GoogleFont("JetBrains Mono"), "monospace"],
)
这为应用设定了协调的配色与干净的 UI 正文字体(Inter),并采用对开发者友好的等宽字体(JetBrains Mono)。接着,我们通过覆盖关键 CSS 变量来控制应用外观:
gradio-app {
--body-background-fill: #f0f3f7;
--block-background-fill: #ffffff;
--body-text-color: #1f2328;
--button-primary-background-fill: #1a7f37;
}
body.dark gradio-app {
--body-background-fill: #0d1117;
--block-background-fill: #1c2128;
--body-text-color: #e6edf3;
--button-primary-background-fill: #238636;
}
其中第一段定义亮色主题,第二段为暗色模式覆盖变量。尽管是可选项,但自定义主题与 CSS 能显著提升整体体验。
至此,UI 已完整搭建并完成样式设置,我们即可进行最后一步:启动应用。
步骤 10:启动
最后,通过以下方式启动应用:
if __name__ == "__main__":
print(f"Model : {MODEL}")
print(f"Ollama : {OLLAMA_BASE}")
if not ollama_ok():
print("Ollama not detected — run ollama serve before chatting")
demo.launch(
server_name="0.0.0.0",
server_port=7860,
share=False,
theme=THEME,
css=CSS,
)
此处 server_name="0.0.0.0" 让应用可在本地网络中访问,share=False 使一切保持本地。ollama_ok() 会向 localhost:11434 发起快速 GET 请求,并在启动时就提示 Ollama 未运行,而不是等到用户首次发送消息才报错。
应用运行后,请访问 http://localhost:7860。
以下是用户视角下的完整执行流程:

-
用户在聊天面板输入消息,可选上传图像或代码文件,并切换工具型/思考模式
-
提交后,
respond()构建完整的 Ollama 请求,其中包括编辑器当前代码与所有附件作为上下文 -
请求以 token 流式返回,部分响应会实时推送到 Gradio 聊天组件进行渲染
-
若开启工具型模式且模型决定调用工具,则工具会在本地运行,结果追加至对话,随后以流式方式返回最终答案
-
流结束后,将自动提取响应中最后一个围栏代码块并推送至编辑器
总结
在本教程中,我们使用 Gemma 4、Ollama 与 Gradio 构建了一个完全本地的 AI 编码助手。该应用支持多模态输入、真实工具使用、流式响应与实时代码编辑器,且无需任何外部 API,全部在您的机器上运行。
将编辑器中的代码直接注入每次提示的“全上下文”方法,对于单文件工作流而言比 RAG 更简单,尤其适合解释、重构或扩展您正在编辑的代码。
接下来,您可以从多个方向扩展该项目:
- 新增文件树面板以支持多文件项目,并将选中文件注入为上下文
- 通过下拉菜单支持更多 Ollama 模型,便于在 Gemma 4、Llama 3 等之间切换
- 将会话历史持久化到磁盘,从而在重启应用后继续会话
我是一名 Google Developers 机器学习(生成式 AI)领域的专家、Kaggle 三项专家,以及 Women Techmakers 大使,拥有 3 年以上的技术从业经验。2020 年我共同创办了一家健康科技初创公司,目前在佐治亚理工学院攻读计算机科学硕士,专攻机器学习。
Gemma 4 常见问题
是否必须使用 GPU?
不一定需要。Gemma 4 e4b 是可在 CPU 上运行的量化模型,不过使用 GPU 会显著提升推理速度。
工具型模式与常规聊天有什么区别?
常规模式下,模型仅流式输出文本。在工具型模式中,模型可以调用 run_code 或 calculate,检查结果,并在完成响应前将其纳入。
当 Agent 写代码时编辑器如何自动更新?
extract_last_code_block() 辅助函数会在助手响应中扫描最后一个围栏代码块,并在流结束后将其推送到编辑器。这也是系统提示要求模型始终用带语言标签的围栏代码块包裹代码的原因。
如果 Ollama 未运行会发生什么?
ollama_ok() 会在启动时和每次提交聊天时检查。如果无法连接 Ollama,聊天会返回格式化的错误信息,而不是崩溃。

本地 LLM 正在迎来转折点。借助 Gemma 4 的长上下文窗口、原生多模态支持,以及 Ollama 的易用性,您现在可以在自己的机器上完全本地运行一位强大的“工具型”编码助手。
在本教程中,我将演示如何通过 Ollama 使用 Gemma 4,并配合 Gradio 界面构建一个编码助手。该应用采用分栏布局:左侧是实时代码编辑器,右侧是具备工具能力的对话面板。您可以上传图像或代码文件作为上下文,启用工具使用以便模型运行并验证代码,还能在遇到更难的问题时切换“思考模式”。
完成本教程后,您将得到一个可用的本地应用,它可以:
本教程的完整代码可在 此处获取。