用 Pi + LM Studio 在本地跑大模型 Agent：完整配置指南

本地大模型已经跨过了"勉强能用"的分水岭。借助谷歌最新发布的 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 启动本地推理服务

安装并打开 LM Studio。
在模型市场下载 gemma-4-12b-qat。
启动 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: ${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}
    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 启动脚本，会根据工作目录自动生成容器名，并支持 --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 -- "$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，Pi 会启动 Docker 并进入 /workspace。你可以让它做这些事来验证：

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

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

常见问题

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

开始前的准备

硬件：建议 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 启动本地推理服务

安装并打开 LM Studio。
在模型市场下载 gemma-4-12b-qat。
启动 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: ${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}
    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 启动脚本，会根据工作目录自动生成容器名，并支持 --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 -- "$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，Pi 会启动 Docker 并进入 /workspace。你可以让它做这些事来验证：

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

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

常见问题

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

全部

AI教程

AI产品

AI资源

用 Pi + LM Studio 在本地跑大模型 Agent：完整配置指南

用 Pi + LM Studio 在本地跑大模型 Agent：完整配置指南

开始前的准备

本地模型现在什么水平

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

第二步：配置 Pi 指向 LM Studio

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

第四步：编写启动脚本

验证结果

常见问题

作者

分类

相关文章

Codex 开源模式：一行配置接入本地模型

Codex Security Plugin：用 OpenAI 一键扫描代码安全隐患

Claude Science：科研界的 Claude Code，附免费开源平替

用 Pi + LM Studio 在本地跑大模型 Agent：完整配置指南

用 Pi + LM Studio 在本地跑大模型 Agent：完整配置指南

开始前的准备

本地模型现在什么水平

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

第二步：配置 Pi 指向 LM Studio

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

第四步：编写启动脚本

验证结果

常见问题

作者

分类

相关文章

Codex 开源模式：一行配置接入本地模型

Codex Security Plugin：用 OpenAI 一键扫描代码安全隐患

Claude Science：科研界的 Claude Code，附免费开源平替