本地大模型已经从「勉强能跑」进化到「能干活」的阶段了。本文作者 Vicki Boykis（一家创业公司的创始 ML 工程师）在 HackerNews 上的爆款文章证明：用 Pi 智能体框架配合 LM Studio，在一台 2022 款 M2 Mac（64GB 内存）上就能跑 Gemma 4 完成 Agent 编码任务——重构 Python 脚本、写单元测试、搭建推荐系统仓库，循环准确率达到前沿模型的 75% 左右。本教程拆解完整配置流程，适合想在本地搭建私有 Agent 编码环境的开发者。

开始前的准备

运行本地 Agent 流程，你需要三样东西：一个本地模型推理引擎、一个智能体框架，以及本地模型工件。本教程的配置如下：

• 推理服务器：LM Studio（图形界面，配置简单，适合入门）
• 智能体框架：Pi（轻量级 Agent 框架）
• 模型：Gemma 4 系列（推荐 gemma-4-12b-qat，更新、更小、更快，准确性损失不大）
• 硬件：建议 Mac with Apple Silicon，至少 16GB 统一内存（作者用的是 M2 + 64GB）
• 隔离：Docker（强烈建议，限制 Agent 的执行权限）
• 预计时间：30 分钟配置 + 模型下载时间
• 成本：完全免费（开源工具 + 本地运行）

💡 提示：作者实测过多种本地推理方案（Open WebUI + llama.cpp、llama-cpp-python、Ollama、llamafiles、LM Studio），最终选择 LM Studio 是因为它把配置门槛降到了最低。如果你追求极致速度，直接用 llama.cpp 会更快。

具体步骤

第一步：安装 LM Studio 并下载模型

前往 LM Studio 官网 下载安装。打开后在搜索栏找到 Gemma 4 系列模型，推荐下载：

• google/gemma-4-12b-qat（推荐，体积小速度快）
• gemma-4-26b-a4b（性能更强，但需要更多内存）

下载完成后在 LM Studio 的 Local Server 标签页启动推理服务，默认监听 http://localhost:1234/v1（兼容 OpenAI API 格式）。

第二步：配置 Pi 的 models.json

由于作者把所有 Pi 会话都运行在 Docker 容器中，需要编辑 Pi 的 models.json，让容器内的 Pi 能访问宿主机上 LM Studio 提供的推理端点。

关键配置是 baseUrl 指向 host.docker.internal:1234（这是 Docker 访问宿主机服务的标准方式）：

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

把这个文件保存到 ${HOME}/.pi/agent/models.json。

💡 提示：gemma-4-12b-qat 支持多模态输入（text + image），所以 input 字段同时列出了两种类型。如果你的模型只支持文本，去掉 "image" 即可。

第三步：配置 Docker Compose

这是最关键的一步——把 Pi 跑在受限的容器里，只授予 bash 权限（不直接运行 Python 代码，不联网浏览），避免 Agent 误操作擦除宿主机文件。

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: ${ANTHROPIC_API_KEY:-}
      OPENAI_API_KEY: ${OPENAI_API_KEY:-not-needed}
      GEMINI_API_KEY: ${GEMINI_API_KEY:-}
      OPENAI_API_BASE: ${OPENAI_API_BASE:-http://host.docker.internal:1234/v1}
      WHATEVER_API_KEY: ${WHATEVER_API_KEY:-}
    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:

关键点说明：

• extra_hosts 把 host.docker.internal 映射到宿主机网关，容器才能访问 LM Studio。
• OPENAI_API_BASE 默认指向本地 LM Studio。注意如果你同时用 OpenAI 官方 API，需要单独指定 base。
• volumes 把工作目录挂载进容器，Agent 只能操作这个目录内的文件。

第四步：编写启动脚本

下面这个 bash 脚本会自动构建容器、设置工作区、启动 Pi：

#!/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 -- "$WORKSPACE_DIR" && pwd)" ;;
esac

export WORKSPACE="$WORKSPACE_DIR"
sandbox="${PI_SANDBOX:-0}"
pi_args=()

while (($#)); do
  case "$1" in
    --sandbox)    sandbox=1 ;;
    --no-sandbox) sandbox=0 ;;
    *)            pi_args+=("$1") ;;
  esac
  shift
done

compose_files=( -f "$SCRIPT_DIR/docker-compose.yml" )
if [[ "$sandbox" == "1" ]]; then
  compose_files+=( -f "$SCRIPT_DIR/docker-compose.sandbox.yml" )
fi

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

api_key_args=(
  -e OPENAI_API_KEY
  -e DEEPSEEK_API_KEY
  -e ANTHROPIC_API_KEY
  -e GEMINI_API_KEY
)

cmd=(
  docker compose
  --project-directory "$SCRIPT_DIR"
  "${compose_files[@]}"
  run --rm
  --name "$container_name"
  "${api_key_args[@]}"
  pi
)

if ((${#pi_args[@]})); then
  cmd+=("${pi_args[@]}")
fi

exec "${cmd[@]}"

保存为 pi，赋予执行权限（chmod +x pi），然后在你想让 Agent 工作的项目目录里运行即可。

验证结果

配置完成后，在工作目录中运行启动脚本。Pi 会启动 Docker 容器并加载你挂载的 models.json，连接到 LM Studio 的推理端点。

作者用这套配置完成的具体任务包括：

• 把一个 Python 脚本（原本是 notebook）重构为一个包含 5-6 个模块的仓库，并对模块进行代码检查，确保泛型使用正确的类型提示。
• 校对博客文章、编写单元测试。
• 搭建一个基于双塔模型的推荐系统仓库。

这些任务都远超去年本地模型能达到的水平。运行时 KV 缓存会增长到接近 64GB RAM 的上限，说明模型确实在充分利用硬件。

本地化模式最吸引人的地方之一是透明度：你可以实时观察 token 的流入流出、更改上下文窗口大小、调整系统提示和量化设置，深入理解 GPU 如何处理 token。

常见问题

• 推理速度太慢：优先尝试更小的模型（如 gemma-4-12b-qat 而非 26b）；如果追求极致速度，改用直接调用 llama.cpp 而非 LM Studio。
• 上下文窗口受限：本地上下文窗口大小完全取决于你的硬件。64GB 内存的 Mac 可以撑到接近满载；内存更小的设备需要选择更小量化的模型。
• 提示模板不匹配：早期版本常见问题，LM Studio 和 HuggingFace 的「使用此模型」按钮已经大幅简化了相关工作。遇到这类问题通常很快会被社区修复。
• Agent 误删文件：这就是为什么要用 Docker 隔离。即使 Agent 在容器内出问题，也不会波及宿主机的其他文件。如果你需要联网能力（比如 curl），建议在另一个独立的镜像中放开权限。
• 生产环境能用吗：作者明确表示「不确定它是否已经完全准备好用于生产软件开发」。把它当作开发辅助和实验环境，而不是生产流水线的核心环节。