Gemma 4 + Ollama 本地 Agent 工具调用实战指南

当 Gemma 4 在你的电脑上学会了打电话，一个纯粹本地运行的 AI Agent 是如何炼成的

故事：从只会聊天到能干活

2024 年，AI 大模型风起云涌，但大多数应用还停留在聊天机器人的范畴。你问它天气，它只能假设今天阳光明媚；你让它查文件，它只能说对不起我无法访问你的电脑。这种只会说话，不会干活的局限，根源在于缺乏工具调用（Tool Calling）能力，模型能理解查天气这个意图，却无法真正调用天气 API。

Gemma 4 工具调用项目，就是来解决这个问题的。作者 mmmayo13 用三个 Python 脚本，演示了如何让 Gemma 4 通过 Ollama 本地推理引擎，真正调用外部工具：查天气、执行文件操作、处理 API 故障时的优雅降级……全部在本地完成，数据不离开你的电脑。

背景：为什么选择 Ollama + Gemma 4？

Ollama 是近年来最受开发者欢迎的本地大模型推理框架之一。它最大的特点是对用户极度友好：ollama run llama2 一条命令就能在本地跑起一个 LLM，门槛远低于 llama.cpp 或 vLLM 等方案。对新手来说，它绕开了复杂的 GPU 配置和模型量化步骤；对老手来说，它支持几乎所有主流开源模型，并提供标准化的 API 接口。

Gemma 4 则是 Google DeepMind 在 2024 年底发布的轻量级开源模型系列。虽然参数量只有 2B 到 27B，却在多项基准测试中超越了同规模竞品。Gemma 4 在工具调用（Function Calling）任务上表现尤为突出，支持结构化输出和多轮推理，是构建 Agent 的理想基座。

两者结合的优势：Ollama 负责推理引擎，Gemma 4 负责智能决策，本地运行，成本为零，隐私无忧。

核心功能：三个场景，层层递进

场景一：API 工具调用（api_calling.py）

这是项目最基础的演示。get_current_weather 函数模拟了一个天气查询工具，模型通过 function calling 机制生成结构化参数，由程序执行真实 API 请求后返回结果。天气数据来自免费的 Open-Meteo API，无需申请 API Key，项目开箱即用。

当用户问伦敦现在多少度，Gemma 4 会识别出需要调用 get_current_weather 工具，自动生成参数，程序执行后返回真实天气数据。整个过程对用户透明。

场景二：命令执行工具（cmd_calling.py）

这是最接近真 Agent 的场景。list_directory_contents 和 execute_python 两个工具让模型能直接操作文件系统。

这个设计有明确的安全考量：

• 路径限制（SAFE_BASE_DIR）：所有文件操作被约束在启动时指定的目录内，防止目录遍历攻击
• Python 执行超时（PYTHON_EXEC_TIMEOUT = 5s）：防止恶意代码无限循环占用资源
• 无网络访问：Python interpreter 在沙箱内运行，无法发起外部请求

用户可以让 Agent 列出当前目录下的所有 Python 文件或统计某文件夹的行数，模型理解意图后生成对应工具调用，程序执行后返回结果。

场景三：错误恢复与容错（error_recovery.py）

这是项目最有深度的部分，展示了生产级 Agent 必备的韧性设计。

项目设计了 SIMULATE_GEOCODING_OUTAGE 开关，激活后会随机让地理编码服务不可用。当外部 API 不可用时，Agent 检测到错误后，模型会自动改用本地内置的静态城市数据回答问题。这种优雅降级（Graceful Degradation）策略，是真实生产环境中 AI 系统必须考虑的设计模式。

此外，项目还设计了 MAX_ITERATIONS = 6 的迭代上限，防止模型在复杂场景下陷入无限循环。

上手指南

环境准备

1. 安装 Ollama（macOS/Linux 一条命令）：

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

2. 拉取 Gemma 4 模型（需 8GB+ 显存或内存）：

   ollama pull gemma4:e2b
   

3. 运行（仅 Python 标准库，无需 pip install）：

   python3 api_calling.py
   

运行脚本

三个脚本均支持命令行参数：

# 基础 API 调用
python3 api_calling.py "What is the weather in Tokyo?"

# 命令执行
python3 cmd_calling.py "List all Python files in the current directory"

# 错误恢复演示
python3 error_recovery.py "What time is it in London right now?"

所有脚本都支持交互模式（不带参数启动）和单次查询模式（命令行传参）。

局限与争议

1. 工具数量受限

当前项目每个脚本只内置了 1-3 个工具。真实的 Agent 系统需要数十个工具，涉及到工具注册、编排、冲突解决等复杂问题。项目更像是最小可运行示例。

2. 安全性权衡

cmd_calling.py 的沙箱设计虽然考虑到了路径限制和超时，但沙箱本身由 Python exec() 实现。生产环境建议使用更严格的容器级隔离（如 Docker）。

3. 缺乏持久化记忆

三个脚本都是无状态的，每次运行都是从零开始，没有对话历史、用户偏好或上下文积累。真实的 AI 助手需要长期记忆系统。

4. 模型能力依赖

Gemma 4 的工具调用质量高度依赖模型本身的指令遵循能力。2B 规模的 Gemma 模型在简单场景下表现尚可，但在复杂多步推理任务中可能出现工具调用错误或循环。

行业意义

本地 Agent 的崛起

Gemma 4 工具调用项目代表了一个重要趋势：AI 能力正在从云端向边缘下沉。随着开源模型的推理能力不断逼近 GPT-4 水平，加上 Ollama 等本地推理工具的成熟，数据不出本地的 AI 应用正在从概念走向现实。

工具调用标准化

随着 MCP（Model Context Protocol）、OpenAI Function Calling 等标准的普及，工具调用正在成为 LLM 应用开发的基础范式。这个项目虽然用的是 Ollama 原生 API，但其设计思路与行业标准完全兼容。理解了这个项目，就理解了大多数 Agent 系统的核心原理。

增长潜力

截至分析时项目已有 44 颗星，作为 2024 年底才发布的项目，这个增速说明开发者对本地 Agent 实战的的需求非常旺盛。随着更多开源模型支持 function calling，这类教程型项目的热度预计会持续上升。

---

总结：如果你想了解 Gemma 4 的工具调用能力，或想用 Ollama 构建本地 AI Agent，这个项目是极佳的起点。它不是最强大的 Agent 框架，但可能是最容易理解的入门示例。三个脚本，三个场景，帮你从零到一理解 Agent 的核心机制。