本地大模型已经跨过了"勉强能用"的分水岭。借助谷歌最新发布的 Gemma 4 系列，你可以在一台 2022 款 M2 Mac（64GB 内存）上完成智能体编码、脚本重构、单元测试编写等工作，循环准确率和速度大约能达到前沿模型的 75%。这篇教程会把整个本地 Agent 工作流拆解成可复现的步骤，适合想在隐私环境或离线场景下跑 AI 编码助手的开发者。

开始前的准备

• 硬件：建议 Apple Silicon Mac（M2 及以上），16GB 以上统一内存，64GB 更佳（KV 缓存会占满内存）
• 软件：Docker Desktop、LM Studio（本地推理服务）、Pi 智能体框架
• 模型：Gemma 4 系列，推荐 gemma-4-12b-qat（更新、更小、更快，准确性损失不大）或 gemma-4-26b-a4b
• 预计时间：首次配置约 30 分钟

本地模型现在什么水平

在 OpenAI 2025 年 8 月发布 GPT-OSS 之前，本地模型对大多数编程任务都不够准。Gemma 4 系列发布后，作者实际用它完成了这些任务：

• 把一个 Python notebook 重构成包含 5-6 个模块的仓库
• 对模块做代码检查，修正泛型类型提示
• 校对博客文章、编写单元测试
• 从零搭建一个基于双塔模型的推荐系统仓库骨架

这些都是 6 个月前本地模型完全无法胜任的任务。

第一步：用 LM Studio 启动本地推理服务

1. 安装并打开 LM Studio。
2. 在模型市场下载 gemma-4-12b-qat。
3. 启动 Local Server，默认监听 http://localhost:1234/v1（OpenAI 兼容接口）。

启动后，LM Studio 会提供一个 OpenAI 格式的推理端点，Pi 会通过这个端点调用本地模型。

提示：你也可以用 Ollama、llama.cpp 或 Open WebUI 替代 LM Studio。直接用 llama.cpp 会更快，是后续可以尝试的优化方向。

第二步：配置 Pi 指向 LM Studio

Pi 通过 models.json 配置模型。将下面的配置写入 ~/.pi/agent/models.json，把端点指向 Docker 宿主机上的 LM Studio：

{
  "lmstudio": {
    "baseUrl": "http://host.docker.internal:1234/v1",
    "api": "openai-completions",
    "apiKey": "not-needed",
    "models": [
      {
        "id": "google/gemma-4-12b-qat",
        "input": ["text", "image"]
      }
    ]
  }

注意 host.docker.internal 是 Docker 容器访问宿主机的别名。如果你同时在用真实 OpenAI API，需要为 OPENAI_API_BASE 单独指定 base，避免冲突。

第三步：用 Docker Compose 运行 Pi（安全沙箱）

强烈建议把 Pi 跑在受限的 Docker 容器里，只授予 bash 权限，避免它直接读写你的物理硬盘。

services:
  pi:
    build:
      context: .
      dockerfile: Dockerfile
    image: pi-agent:0.74.0
    init: true
    stdin_open: true
    tty: true
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      ANTHROPIC_API_KEY

关键点：把当前工作目录挂载为 /workspace，Pi 就能在你的代码仓库里操作文件，而不会动到容器外的系统目录。

第四步：编写启动脚本

下面是一个推荐的 pi 启动脚本，会根据工作目录自动生成容器名，并支持 --sandbox 选项启用更严格的沙箱：

#!/usr/bin/env bash
# Pi — Start the containerized Pi agent.

SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORKSPACE_DIR="${WORKSPACE:-$(pwd)}"
case "$WORKSPACE_DIR" in
  /) ;;
  *) WORKSPACE_DIR="$(cd --

验证结果

在你正在编辑的代码仓库目录下执行 ./pi，Pi 会启动 Docker 并进入 /workspace。你可以让它做这些事来验证：

• 让 Pi 重构当前仓库的一个模块，观察它能否正确拆分文件
• 让它检查类型提示是否正确
• 在 LM Studio 界面实时观察 token 推理过程、KV 缓存占用和上下文窗口变化

成功运行后，你会看到 Pi 在 Docker 内修改文件、调用 bash，而本地模型在后台逐 token 推理。

常见问题

• 推理速度慢：本地模型受限于硬件，上下文窗口小。可换用更小的量化模型（如 12B QAT），或减少上下文长度。
• 提示模板不匹配：早期版本常见问题，LM Studio 和 HuggingFace 的"使用此模型"按钮通常会快速修复，保持工具更新即可。
• KV 缓存爆满：64GB 内存可能被长上下文填满，监控内存使用，必要时重启会话。
• 能否用于生产软件开发？ 目前还不完全成熟，但作为快速、个性化的本地文档查询和辅助编码已经足够实用，尤其在隐私敏感场景下值得投入。