本地编码代理：Pi + Gemma 4

我一直在尝试完全在本地运行编码 Agent。我最终确定的方案是：

LM Studio + Pi Agent + Gemma 4 26B A4B (Q4_K_M)

Gemma 4 在 LM Studio 中运行，连接到 Pi 作为终端 Agent。效果出奇地好，本文将介绍如何进行设置。

以下是我们将涵盖的内容：

1. 安装 LM Studio
2. 下载 Gemma 4
3. 启动本地服务器
4. 配置上下文大小
5. 安装 Pi
6. 将 Pi 连接到本地模型
7. 添加技能和扩展

1、安装 LM Studio

你需要一些工具来在本地提供模型服务。我在这里使用的是 LM Studio——它是一个桌面应用程序，负责处理模型下载、量化，并暴露一个本地 OpenAI 兼容的 API 服务器。从 lmstudio.ai 下载（支持 macOS、Windows、Linux）。

如果你更喜欢 CLI 优先的工作流程，Ollama 和 llama-server（llama.cpp 的一部分）同样适用。这三者都暴露 OpenAI 兼容的端点，所以 Pi 不在乎你使用哪一个。

本指南的其余部分使用 LM Studio，但 Pi 的配置适用于其中任何一个——只需替换服务器配置即可。

2、下载 Gemma 4

Gemma 4 是 Google 最新的开放权重模型系列，在 Apache 2.0 许可证 下发布。与早期的 Gemma 版本相比，它在编码和 Agent 用例方面是一个真正的飞跃——它现在具有原生函数调用、系统提示支持和思考模式，这使它成为一个真正适合本地编码 Agent 的优秀模型。该系列包括四种规模：

我的推荐：选择 26B A4B。 它是一个混合专家模型，这意味着它有 26B 总参数，但每个 token 只激活 4B。实际上，你可以获得更大模型的质量，而推理速度接近小模型。它处理文本、图像理解、函数调用和思考模式——这正是编码 Agent 所需要的。

话虽如此，E4B 在其规模上出人意料地强大。如果你的显存不足，值得一试——但它确实需要更多的指导和更具体的提示才能获得好的结果。

要下载它，打开 LM Studio，搜索 gemma-4-26b-a4b，然后下载量化的 GGUF 版本（例如 Q4_K_M）。根据你可用的显存选择量化级别：

注意： 尽管该模型每个 token 只激活 4B 参数，但所有 26B 参数都必须加载到内存中以便快速路由。这就是为什么显存需求更接近密集型 26B 模型的原因。

如果你使用 Mac，还可以查看 Gemma 4 的 MLX 版本。MLX 原生针对 Apple Silicon 优化，在 M 系列芯片上可能比 GGUF 格式更快。

3、在 LM Studio 中启动服务器

模型下载完成后：

1. 进入 LM Studio 中的 Developer 标签页
2. 选择你下载的 Gemma 4 模型
3. 点击 Start Server

服务器默认运行在 http://localhost:1234，并暴露 OpenAI 兼容的 API。

你可以验证它是否正在运行：

curl http://localhost:1234/v1/models

4、配置上下文大小和 GPU 卸载

在开始工作之前，请检查 Developer 标签页 Model Settings 下的上下文大小和 GPU 卸载设置。

上下文大小直接影响显存使用量。该模型支持最多 256K tokens，但你可能不需要为编码任务使用全部容量。更多上下文 = 在基础模型权重之上需要更多显存。

如果你的显存允许，我建议使用 128K。编码 Agent 在会话过程中往往会积累大量上下文——文件内容、工具输出、对话历史——而在任务中途耗尽上下文是令人烦恼的。

Pi 具有内置的会话管理功能来帮助解决这个问题。/compact 总结旧消息以释放上下文。/new 开始新的会话。/tree 让你浏览会话历史并跳回到任何之前的点。/fork 从过去的消息创建新会话，当你想在不同的方向上分支而不丢失历史记录时非常有用。

还要检查 GPU Offload 设置。这控制着有多少层加载到 GPU 上，而不是保留在系统 RAM 中。GPU 上的层越多 = 推理越快，但需要更多显存。如果你的 GPU 无法容纳整个模型，LM Studio 会在 GPU 和 CPU 之间分割——它仍然可以工作，只是 CPU 部分较慢。我将此设置为最大值（26B A4B 为 30）。

如果遇到内存不足的问题，首先降低上下文大小。

5、安装 Pi

Pi 是由 Mario Zechner 开发的极简终端编码工具。核心故意保持小巧——模型获得四个工具（read、write、edit、bash），仅此而已。

你可以通过扩展、技能、提示模板和主题来定制它。它也是 token 高效的，系统提示很小，因此你可以进行真正的上下文工程。当你运行本地模型时，这非常重要。

npm install -g @mariozechner/pi-coding-agent

6、在 Pi 中配置本地模型

创建（或编辑）文件 ~/.pi/agent/models.json，将 Pi 指向你的本地 LM Studio 服务器：

{  
  "providers": {  
    "lmstudio": {  
      "baseUrl": "http://localhost:1234/v1",  
      "api": "openai-completions",  
      "apiKey": "lm-studio",  
      "models": [  
        {  
          "id": "google/gemma-4-26b-a4b",  
          "input": [  
            "text",  
            "image"  
          ]  
        }  
      ]  
    }  
  }  
}

注意： 将模型 id 设置为与 LM Studio 服务器标签页中显示的确切模型名称匹配。

然后启动 Pi 并选择你的本地模型：

pi  
# 使用 /model 切换到你的本地 LM Studio 模型

就是这样。你现在拥有了一个完全在自己的机器上运行的本地编码 Agent。

7、技能

技能是按需提供的能力包，可以扩展 Pi 的功能。它们遵循 Agent Skills 标准，实际上就是带有说明的 Markdown 文件。

通过 git 安装社区技能：

# 用户级别（在所有项目中可用）  
git clone https://github.com/badlogic/pi-skills ~/.pi/agent/skills/pi-skills  
  
# 或项目级别  
git clone https://github.com/badlogic/pi-skills .pi/skills/pi-skills

一些我觉得有用的技能：

• liteparse：快速的本地文档解析（PDF、DOCX、PPTX 等）。对于 Gemma 特别方便，因为它只能理解图像——liteparse 将文档转换为模型实际可以处理的格式。
• frontend-slides：用 HTML 创建演示幻灯片。
• pi-skills：pi-coding-agent 的技能合集。
• grill-me：通过质询来梳理和迭代想法。
• gemini-skills：用于 Gemini API、SDK 和模型交互的技能。

在会话中使用 /skill:name 调用技能，或让 Agent 自动发现并使用它们。

8、扩展

扩展是更深入的 TypeScript 模块——自定义工具、命令、UI 组件、权限门，甚至子 Agent。

有一点需要了解：Pi 默认以 YOLO 模式运行。 它会在不询问的情况下执行 bash 命令。这很快但可能有风险，特别是对于本地模型可能会产生破坏性命令的幻觉。permission-gate 扩展可以帮助——它在运行潜在危险的命令之前提示你确认。但这不是一个完整的安全沙箱。如果你想要更强大的功能，请查看 cco（在容器中运行命令）或 sandbox 扩展。

# 使用 --extension 标志加载扩展  
pi --extension examples/extensions/permission-gate.ts  
  
# 或复制到扩展目录以自动发现  
cp permission-gate.ts ~/.pi/agent/extensions/

以上就是完整的设置。一旦一切就绪，这是一个出人意料地强大的工作流程——而且知道一切都运行在你自己的硬件上感觉很棒。祝本地构建愉快！

原文链接: How to run a local coding agent with Gemma 4 and Pi

汇智网翻译整理，转载请标明出处