> ## Content Index
> Fetch the complete content index at: https://www.hubwiz.com/blog/llms.txt
> Use this file to discover other available public pages before exploring further.

# 本地编码代理：Pi + Gemma 4
- URL: https://www.hubwiz.com/blog/local-coding-agent-pi-gemma-4/
- Published: 2026-05-01T18:45:20.000Z
- Updated: 2026-10-13T14:49:30.000Z
- Description: 我一直在尝试完全在本地运行编码 Agent。我最终确定的方案是：LM Studio + Pi Agent + Gemma 4 26B A4B (Q4_K_M)
- Author: admin
- Tags: AGENT, PI, #Import 2026-10-14 14:41

我一直在尝试完全在本地运行编码 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](https://lmstudio.ai/?ref=hubwiz.com)——它是一个桌面应用程序，负责处理模型下载、量化，并暴露一个本地 OpenAI 兼容的 API 服务器。从 [lmstudio.ai](https://lmstudio.ai/?ref=hubwiz.com) 下载（支持 macOS、Windows、Linux）。

如果你更喜欢 CLI 优先的工作流程，[Ollama](https://ollama.com/?ref=hubwiz.com) 和 [llama-server](https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md?ref=hubwiz.com)（llama.cpp 的一部分）同样适用。这三者都暴露 OpenAI 兼容的端点，所以 Pi 不在乎你使用哪一个。

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

## 2、下载 Gemma 4

[Gemma 4](https://ai.google.dev/gemma/docs/core?ref=hubwiz.com) 是 Google 最新的开放权重模型系列，在 [Apache 2.0 许可证](https://ai.google.dev/gemma/apache%5F2?ref=hubwiz.com) 下发布。与早期的 Gemma 版本相比，它在编码和 Agent 用例方面是一个真正的飞跃——它现在具有原生函数调用、系统提示支持和思考模式，这使它成为一个真正适合本地编码 Agent 的优秀模型。该系列包括四种规模：

| 模型规模            | 架构类型       | 上下文长度       |
| --------------- | ---------- | ----------- |
| Gemma 4 E2B     | Dense      | 128K tokens |
| Gemma 4 E4B     | Dense      | 128K tokens |
| Gemma 4 26B A4B | 混合专家 (MoE) | 256K tokens |
| Gemma 4 31B     | Dense      | 256K tokens |

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

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

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

| 量化级别     | 下载大小  | 质量      |
| -------- | ----- | ------- |
| Q4\_K\_M | 18 GB | 质量与大小平衡 |
| Q6\_K    | 24 GB | 更高质量    |
| Q8\_0    | 28 GB | 接近原始质量  |

![gemma4](https://www.hubwiz.com/blog/content/images/2026/05/image-2.png)

> **注意：**

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

## 3、在 LM Studio 中启动服务器

模型下载完成后：

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

![server1](https://www.hubwiz.com/blog/content/images/2026/05/image-3.png)

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

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

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

```

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

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

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

| 使用场景     | 上下文大小 | 额外显存（约） |
| -------- | ----- | ------- |
| 小型编辑、单文件 | 16K   | \~1 GB  |
| 标准编码会话   | 64K   | \~4 GB  |
| 多文件重构    | 128K  | \~8 GB  |
| 完整仓库上下文  | 256K  | \~16 GB |

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

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

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

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

![server2](https://www.hubwiz.com/blog/content/images/2026/05/image-4.png)

## 5、安装 Pi

[Pi](https://pi.dev/?ref=hubwiz.com) 是由 [Mario Zechner](https://github.com/badlogic?ref=hubwiz.com) 开发的极简终端编码工具。核心故意保持小巧——模型获得四个工具（`read`、`write`、`edit`、`bash`），仅此而已。

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

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

```

## 6、在 Pi 中配置本地模型

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

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

```

> **注意：**`id`

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

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

```

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

![pi-start](https://www.hubwiz.com/blog/content/images/2026/05/image-5.png)

## 7、技能

技能是按需提供的能力包，可以扩展 Pi 的功能。它们遵循 [Agent Skills 标准](https://agentskills.io/?ref=hubwiz.com)，实际上就是带有说明的 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](https://github.com/run-llama/llamaparse-agent-skills/blob/main/skills/liteparse/SKILL.md?ref=hubwiz.com)：快速的本地文档解析（PDF、DOCX、PPTX 等）。对于 Gemma 特别方便，因为它只能理解图像——liteparse 将文档转换为模型实际可以处理的格式。
- [frontend-slides](https://github.com/zarazhangrui/frontend-slides?ref=hubwiz.com)：用 HTML 创建演示幻灯片。
- [pi-skills](https://github.com/badlogic/pi-skills?ref=hubwiz.com)：pi-coding-agent 的技能合集。
- [grill-me](https://github.com/mattpocock/skills/blob/main/grill-me/SKILL.md?ref=hubwiz.com)：通过质询来梳理和迭代想法。
- [gemini-skills](https://github.com/google-gemini/gemini-skills?ref=hubwiz.com)：用于 Gemini API、SDK 和模型交互的技能。

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

## 8、扩展

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

有一点需要了解：**Pi 默认以 YOLO 模式运行。** 它会在不询问的情况下执行 bash 命令。这很快但可能有风险，特别是对于本地模型可能会产生破坏性命令的幻觉。[permission-gate](https://github.com/badlogic/pi-mono/blob/HEAD/packages/coding-agent/examples/extensions/permission-gate.ts?ref=hubwiz.com) 扩展可以帮助——它在运行潜在危险的命令之前提示你确认。但这不是一个完整的安全沙箱。如果你想要更强大的功能，请查看 [cco](https://github.com/nikvdp/cco?ref=hubwiz.com)（在容器中运行命令）或 [sandbox 扩展](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent/examples/extensions/sandbox?ref=hubwiz.com)。

```
# 使用 --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](https://patloeber.com/gemma-4-pi-agent/?ref=hubwiz.com)

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

> **这是「本地 & 自托管 LLM」专题的一部分。**完整地图见：[本地 & 自托管 LLM 完全指南](https://www.hubwiz.com/blog/local-llm-stack/)