第 4 章：提供商与模型——一个接口，百家模型

Markdown

模型是易耗品，工作流才是资产；切换成本越低，你越自由。

设计思想

Pi 为各家语言模型提供商提供统一抽象：用简单命令在多厂商模型间切换，并对思考级别（thinking）做细粒度控制；同时通过 models.json 支持自定义提供商（Ollama、vLLM、LM Studio、内部网关等），完全自定义协议则走 Extension。

原理

提供商体系（两类认证方式）

  • 订阅登录（/login 后选择）：Anthropic Claude Pro/Max、OpenAI ChatGPT Plus/Pro (Codex)、GitHub Copilot。
  • API Key（环境变量或 --api-key）：Anthropic、Ant Ling、OpenAI、Azure OpenAI、DeepSeek、NVIDIA NIM、Google Gemini、Google Vertex、Amazon Bedrock、Mistral、Groq、Cerebras、Cloudflare AI Gateway、Cloudflare Workers AI、xAI、OpenRouter、Vercel AI Gateway、ZAI Coding Plan、OpenCode Zen/Go、Hugging Face、Fireworks、Together AI、Baseten、Kimi For Coding、MiniMax、小米 MiMo 等。
  • 本地模型：支持 llama.cpp router server——/login llama.cpp 配置，/llama 管理模型下载与加载，/model 选择已加载模型（详见 docs/llama-cpp.md）。
  • 每个内置提供商维护一份工具可用模型目录，自动刷新；pi update --models 可强制立即刷新。

认证与凭据

  • /login 交互式登录；/logout 登出；凭据存储在 ~/.pi/agent/ 下。
  • 环境变量（ANTHROPIC_API_KEY、OPENAI_API_KEY 等）或 --api-key <key>（优先于环境变量）。

模型选择方式

  1. 交互式选择器 /model（或 Ctrl+L）：过滤、选择；Ctrl+S 把高亮模型存为启动默认。
  2. 启动参数：--provider <name> + --model <pattern>；或直接 --model openai/gpt-4o（provider 前缀，无需 --provider）。
  3. 思考级别：--thinking <level>，取值 off / minimal / low / medium / high / xhigh / max；也可用模型简写后缀 --model sonnet:high。Shift+Tab 循环切换。
  4. 模型循环：--models "claude-*,gpt-4o" 限定 Ctrl+P 循环范围；/scoped-models 交互管理。

自定义提供商（models.json）

编辑 ~/.pi/agent/models.json，providers 是对象（键为自定义提供商名）：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    }
  }
}
  • api 取支持的 API 类型（如 openai-completions、google-generative-ai 等）。
  • apiKey 支持占位（本地服务可填假值）或 "$GEMINI_API_KEY" 环境变量引用语法。
  • 模型项可覆写 name、reasoning、contextWindow、maxTokens、cost、input 等。
  • compat 开关处理兼容性（如 supportsDeveloperRole: false、supportsReasoningEffort: false，常见于 Ollama/vLLM/SGLang）。
  • 该文件在每次打开 /model 时自动重载——改完即生效，无需重启。
  • 完全自定义 API/OAuth 需写 Extension 注册 provider，见 docs/custom-provider.md。

用法

查看与登录

pi --list-models          # 列出所有可用模型
pi --list-models claude   # 按关键词过滤

pi        # 启动后输入 /login → 选择提供商 → 完成认证
/session  # 查看当前 provider、model、tokens、cost 等会话信息

切换模型

pi --provider anthropic --model claude-sonnet-4-5 "用两句话解释相对论。"
pi --model openai/gpt-4o "写一首关于春天的五言绝句。"     # provider 前缀
pi --thinking high "请逐步推导费马小定理的证明。"           # 思考级别
pi --models "claude-*,gpt-4o"                              # 限定 Ctrl+P 循环

交互内：/model 选择（Ctrl+S 存默认）、/scoped-models 管理循环列表、Shift+Tab 切思考级别。

自定义提供商示例（内部网关）

# 1. 编辑 ~/.pi/agent/models.json（格式见上）
# 2. 打开 /model 即可看到新模型（自动重载）
# 3. 使用
pi --provider myinternal --model internal-gpt4 "分析这段财务数据的趋势。"

刷新模型目录

pi update --models

常见问题与技巧

  • 找不到模型：确认已登录对应提供商，或运行 pi update --models 刷新目录。
  • 思考级别无效：部分提供商不支持该参数，Pi 会安全忽略。
  • 安全：API key 优先用环境变量或 /login 存储，不要明文写进脚本或仓库。
  • 离线：PI_OFFLINE=1（或 --offline）禁用启动期网络操作（版本检查、目录刷新、遥测）；本地模型走 llama.cpp。