本地运行的 AI 模型在最近半年迎来了真正的分水岭——智力、智能体能力、工具链成熟度都跨越了一道坎。本文作者 Vicki Boykis（创业公司创始机器学习工程师，曾就职 Mozilla.ai、Tumblr、Automattic）在一台 2022 款 M2 Mac（64GB 内存）上，用 Pi 智能体框架 + LM Studio 把 Gemma 4 系列跑成了日常编码搭档，准确率达到前沿模型的约 75%。

这篇教程把她的工作流拆成可复现的步骤：装推理服务器、配智能体框架、用 Docker 沙箱跑起来。

开始前的准备

所需硬件

• 一台内存充裕的机器（作者用的是 M2 Mac + 64GB 内存 + 1TB 存储）。本地智能体会把 KV 缓存吃到接近物理内存上限。
• 建议至少 16GB 统一内存，跑 12B 级别模型更舒服需要 32GB 以上。

所需软件

• LM Studio：本地模型推理服务器（提供 OpenAI 兼容的 /v1 端点）
• Pi：智能体框架（https://github.com/patloeber/gemma-4-pi-agent 有参考设置）
• Docker：把智能体会话关进沙箱，避免直接操作物理硬盘

推荐模型

作者实测过 Mistral 7B、Gemma 3、OpenAI GPT-OSS-20B、Qwen 3 MOE 等。当前默认推荐：

• gemma-4-26b-a4b（LM Studio 实现）：作者的主力默认模型
• gemma-4-12b-qat：更新、更小、更快，准确性损失不大，是本文教程的示例模型

💡 提示：作者判断一个本地模型是否够用的标准是「我是否还需要把它和 API 模型比对」。GPT-OSS 是第一个让她大幅减少比对次数的模型，而 Gemma 4 系列让她第一次能在本地稳定跑智能体编码循环。

具体步骤

第一步：在 LM Studio 下载并启动模型

1. 打开 LM Studio，搜索 google/gemma-4-12b-qat 并下载。
2. 在 LM Studio 的 Server 标签页启动本地推理服务器，默认监听 http://localhost:1234/v1（OpenAI 兼容端点）。

LM Studio 的好处是能实时观察 token 流入流出、调整上下文窗口、对比不同量化设置。

第二步：配置 Pi 的 models.json 指向本地端点

由于所有 Pi 会话都跑在 Docker 容器里，需要编辑 Pi 的 models.json，让容器内的 Pi 能通过 host.docker.internal 访问宿主机上的 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"
      ]
    }
  ]
}

第三步：写 docker-compose.yml

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:
      OPENAI_API_KEY: ${OPENAI_API_KEY:-not-needed}
      OPENAI_API_BASE: ${OPENAI_API_BASE:-http://host.docker.internal:1234/v1}
    volumes:
      - ${HOME}/.pi/agent/models.json:/config/models.json
      - ${WORKSPACE:-.}:/workspace
      - pi-config:/config
      - pi-sessions:/sessions
    working_dir: /workspace
volumes:
  pi-config:
  pi-sessions:

💡 提示：把工作目录挂载到容器的 /workspace，Pi 就能在容器内修改你正在编辑的仓库文件，而不会直接操作物理硬盘——这是避免误删文件的关键安全垫。

第四步：用启动脚本运行 Pi

#!/usr/bin/env bash
# Pi — Start the containerized Pi agent.
SCRIPT_DIR="$(cd -- "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
WORKSPACE_DIR="${WORKSPACE:-$(pwd)}"
export WORKSPACE="$WORKSPACE_DIR"

repo_slug="$(basename -- "$WORKSPACE_DIR" | tr -c 'a-zA-Z0-9_.-' '-' | sed 's/^-//')"
[[ -z "$repo_slug" ]] && repo_slug="workspace"
container_name="pi-${repo_slug}-$$"

cmd=(
  docker compose
  --project-directory "$SCRIPT_DIR"
  -f "$SCRIPT_DIR/docker-compose.yml"
  run --rm
  --name "$container_name"
  -e OPENAI_API_KEY
  -e ANTHROPIC_API_KEY
  -e GEMINI_API_KEY
  pi
)
exec "${cmd[@]}"

保存为 pi 并赋予执行权限后，在工作目录下运行 ./pi 即可启动一个带隔离沙箱的本地智能体会话。

验证结果

作者用这套配置完成了这些任务（都是 6 个月前本地模型做不到的）：

• 把一个 Python 脚本（原本是 notebook）重构成包含 5-6 个模块的仓库，并做类型提示的代码检查
• 校对博客文章、编写单元测试
• 在空白环境下搭建一个基于双塔模型的推荐系统仓库

智能体工作流的循环准确率 / 速度达到了前沿模型的约 75%。

安全建议

作者做了三层收紧，值得照搬：

1. 模型选择：教程示例用 gemma-4-12b-qat，比参考文章推荐的 26B 更小更快、准确性损失不大。
2. 沙箱隔离：所有 Pi 会话跑在 Docker 容器里，只授予 bash 权限，不允许直接跑 Python 或浏览网页（如需联网研究，另起一个允许 curl 的镜像）。
3. 目录挂载：Pi 在容器内修改自身仓库文件，再在目标工作仓库里启动，避免直接擦除物理硬盘文件。

常见问题

• 推理速度慢：本地模型受限于你的硬件。直接用 llama.cpp 会比 LM Studio 更快，是后续优化方向。
• 上下文窗口小：受物理内存限制。作者跑智能体时 KV 缓存增长到接近 64GB。
• 提示模板不匹配：早期版本常见问题，但通常修复得很快。
• 能否用于生产开发：作者明确表示尚不确定。当前更适合个人智能体工作流、学习模型行为、研究 token 推断过程。

参考

• 原文（Vicki Boykis 博客）：https://vickiboykis.com/2026/06/15/running-local-models-is-good-now/
• Pi 参考设置：https://patloeber.com/gemma-4-pi-agent/