PI模型与供应商: 一个工具接所有大模型

AI 模型三个月换一代, 编程工具却常常和某一家深度绑定------想试个新模型, 先祈祷它支持; 想用本地模型省钱, 直接没门。

pi 在这件事上的答案很干脆: 模型是插件, 不是内置件。 今天把它的模型接入机制一次讲透。

三种接入方式, 覆盖从订阅到本地

pi 拿模型的路径分三类, 你可以同时混用。

第一类: 订阅账号 (OAuth)。 已经买了 ChatGPT Plus/Pro、Claude Pro/Max、GitHub Copilot、xAI 订阅的, 直接复用, 不用另外买 API key:

text 复制代码

/login    # 选供应商, 走一遍 OAuth 授权

授权后 token 存在 ~/.pi/agent/auth.json, 过期自动刷新。

第二类: API key。 最省事的用法是设环境变量, pi 认识几十家供应商的约定名字:

bash 复制代码

export ANTHROPIC_API_KEY=sk-ant-...
export DEEPSEEK_API_KEY=sk-...
pi

或者干脆 /login 里选供应商填 key, 让它存进 auth.json。凭证的优先级是: 命令行 --api-key > auth.json > 环境变量 > models.json。

第三类: 任意兼容服务。 这是 pi 最不像"产品"、最像"接口"的地方------只要你的服务说 OpenAI Completions、OpenAI Responses、Anthropic Messages 或 Google Generative AI 中任意一种协议, 就能接进来。Ollama、LM Studio、vLLM、公司自建的代理网关, 全在这类。

日常怎么切模型

配置好之后, 切换成本低到可以忽略:

/model(或 Ctrl+L) 打开模型选择器, 挑完按 Ctrl+S 存为启动默认
命令行一次性指定: pi --model openai/gpt-4o, 连 --provider 都省了
简写带思考等级: pi --model sonnet:high "解这道题"
批量循环: pi --models "claude-*,gpt-4o,deepseek-*", 之后 Ctrl+P 在它们之间切
看清单: pi --list-models claude

思考等级也值得单独说一句。pi 把它抽象成统一的一档: off / minimal / low / medium / high / xhigh / max, 按 Shift+Tab 循环切换。不同厂商对"深度思考"的实现天差地别, 但你在 pi 里只需要记住这一个旋钮。我自己的默认值是 medium。

自定义供应商: 一个 JSON 文件

重点来了。上面第三类"任意兼容服务", 靠的就是 ~/.pi/agent/models.json。这也是 pi 和"支持 N 家供应商"的工具的本质区别: 别人是硬编码一张支持列表, pi 是给你一套配置语言。

最小可用例子, 接本机的 Ollama:

json 复制代码

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}

对本地模型来说, 每个 model 只有 id 是必填------其余全走默认值。apiKey 写个占位符是因为 Ollama 根本不校验, 但 pi 把"模型需要认证"当成前置条件, 不填它就不出现在 /model 列表里。

这个文件每次打开 /model 都会重新读取, 改完不用重启。

如果服务只填 id 还不够, 可以覆盖任何一项:

json 复制代码

{
  "id": "llama3.1:8b",
  "name": "Llama 3.1 8B (本地)",
  "reasoning": false,
  "input": ["text"],
  "contextWindow": 128000,
  "maxTokens": 32000,
  "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
}

cost 填 0 之后, 底部状态栏的费用计价器就是真实的"免费"。contextWindow 写错会直接影响压缩行为, 别乱填。

那些"兼容但不完全兼容"的坑

自建服务最容易翻车的地方, 是各家对 OpenAI 协议的实现程度参差不齐。pi 把这类差异收进一个 compat 字段, 而不是逼你去 patch 源码:

json 复制代码

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [{ "id": "gpt-oss:20b", "reasoning": true }]
    }
  }
}

supportsDeveloperRole: false 是给不认 developer 角色、只认 system 的老服务。类似的开关还有一堆: 流式响应里带不带用量、用 max_tokens 还是 max_completion_tokens、思考参数用哪种格式......每个 switch 都对应一个真实的坑, 官方文档里列了全表。

这个设计很 pi: 不隐藏兼容性差异, 而是把它变成你可以自己拨的开关。 工具厂商替你猜的每一次, 猜错时你都得等它发版。

密钥不该裸奔在配置文件里

models.json 里写密钥还有个我特别喜欢的细节: 值支持命令执行和环境变量插值。

json 复制代码

{
  "providers": {
    "my-proxy": {
      "baseUrl": "https://proxy.example.com/v1",
      "api": "anthropic-messages",
      "apiKey": "!op read 'op://vault/anthropic/credential'",
      "headers": {
        "x-portkey-api-key": "$PORTKEY_API_KEY"
      },
      "models": [{ "id": "claude-sonnet-4" }]
    }
  }
}

! 开头会执行整个值作为 shell 命令取 stdout, 所以 1Password CLI、keychain、公司内部命令都能接。$VAR 做环境变量插值。配置文件可以放心提交到仓库, 密钥留在保险箱里。

而且 pi 明确不做 TTL 缓存------因为不同命令的缓存策略不同, 它不替你做决定, 你可以自己包一层脚本。又是同一条哲学。

本地模型: 让 pi 跑在你自己的显卡上

最后专门说说本地模型, 因为它对隐私敏感和想省钱的场景是刚需。pi 走的是 llama.cpp 的 router 模式------一个服务发现多个 GGUF, 按需加载。

启动 router(注意不要传 --model, 否则会退化成单模型模式):

bash 复制代码

llama-server \
  --models-dir ~/models \
  --no-models-autoload \
  --jinja \
  --host 127.0.0.1 \
  --port 8080 \
  -ngl 999 \
  -c 32768

--jinja 开启工具调用支持的对话模板, 这个必须有, 否则 pi 的工具协议会失效
-ngl 999 尽量把层丢给 GPU
-c 32768 给每个加载的模型设上下文; 省略就用模型原生上下文, 显存可能直接爆

然后在 pi 里登录一次:

text 复制代码

/login llama.cpp   # 填 http://127.0.0.1:8080 即可

之后 /llama 是你的模型管家: 选未加载的模型就加载它, 选已加载的就卸载它, 还有 Download model... 能直接搜 Hugging Face 下载。下载和加载全程在 /llama 面板里看进度, 按 Esc 取消。有意思的是它还支持"边下边聊"式的提示, 并且从不静默卸载、从不删你的模型文件------毕竟 router 可能还被别的客户端共用。

注意只有已加载 的模型会出现在 /model 里。加载完再 /model 选中当前会话用。

不想走交互式登录也行:

bash 复制代码

export LLAMA_BASE_URL=http://127.0.0.1:8080
export LLAMA_API_KEY=optional-secret
pi

我自己的配置长这样

说点真实的。我的 ~/.pi/agent/settings.json 里默认模型是:

json 复制代码

{
  "defaultProvider": "deepseek",
  "defaultModel": "deepseek-v4-flash",
  "defaultThinkingLevel": "medium"
}

日常写代码用便宜快的 flash 档, 遇到硬骨头 Shift+Tab 抬到 high 换强模型。因为 pi 允许我把"哪种活配哪个模型"的自由度留在自己手里, 所以我算得清每个月的账------状态栏的计价器一直跳着, 想装看不见都难。

这就是这个系列反复出现的那句话在模型层面的样子: 模型是耗材, 不是婚姻。工具应该适应你的预算和口味, 而不是反过来。

下一篇我们讲会话管理: pi 的会话怎么存、怎么分支出多条路线做方案对比、长任务怎么压缩不丢上下文------那才是把 agent 当"同事"而非"搜索框"用的关键。

换模型不应该像搬家, 应该像换副眼镜。