📚 编程进阶教程站

第 3 章 · Providers 与 Models 配置 ​

本章目标：掌握 pi 的认证体系（订阅/API Key/auth.json）与密钥解析顺序，学会用 models.json 接入 OpenAI 兼容的自定义模型，并能在多模型之间高效切换。

3.1 两类接入方式 ​

pi 把模型来源分为两类：

  • 订阅（Subscription）：复用你已有的官方订阅账号，通过 /login 完成 OAuth 登录。内置支持：ChatGPT Plus/Pro (Codex)、Claude Pro/Max、GitHub Copilot、xAI (Grok 订阅)、OpenRouter、Radius。OAuth 令牌存于 ~/.pi/agent/auth.json 并自动续期；
  • API Key：按量付费，通过环境变量或 auth.json 提供密钥。
bash
# API Key 最简用法
export OPENAI_API_KEY=sk-...
export DEEPSEEK_API_KEY=sk-...
pi

常用 provider 与环境变量对照（节选自官方表格）：

Provider环境变量
AnthropicANTHROPIC_API_KEY
OpenAIOPENAI_API_KEY
DeepSeekDEEPSEEK_API_KEY
Google GeminiGEMINI_API_KEY
GroqGROQ_API_KEY
OpenRouterOPENROUTER_API_KEY
火山方舟类/Qwen Token PlanQWEN_TOKEN_PLAN_API_KEY

3.2 auth.json 与密钥解析顺序 ​

/login 选择 API-key 类 provider 时，密钥写入 ~/.pi/agent/auth.json（0600 权限），auth.json 的优先级高于环境变量：

json
{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "deepseek": { "type": "api_key", "key": "sk-..." }
}

key 字段支持四种写法（值解析规则）：

json
{
  "a": { "type": "api_key", "key": "!security find-generic-password -ws 'anthropic'" },
  "b": { "type": "api_key", "key": "$MY_ANTHROPIC_KEY" },
  "c": { "type": "api_key", "key": "${KEY_PREFIX}_${KEY_SUFFIX}" },
  "d": { "type": "api_key", "key": "$$literal-dollar-prefix" }
}
  • "!命令"：执行 shell 命令取 stdout（适合接 macOS Keychain、1Password CLI）；
  • "$VAR" / "${VAR}"：环境变量插值；$$ 与 $! 是字面转义。

完整解析优先级（高→低）：CLI --api-key → auth.json → 环境变量 → models.json 中自定义 provider 的 key。

3.3 用 models.json 接入 OpenAI 兼容模型 ​

凡是说 OpenAI / Anthropic / Google 协议的服务都能接入 ~/.pi/agent/models.json。本地 Ollama 只需 id：

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

要点：

  • apiKey 写占位符即可（Ollama 不校验），但必须存在否则模型不出现在 /model 列表；
  • 很多 OpenAI 兼容服务器不认识 reasoning 模型的 developer 角色，用 compat.supportsDeveloperRole: false 让系统提示降级为 system 消息；不支持 reasoning_effort 时同理关闭；
  • compat 可放在 provider 级（对全部模型生效）或模型级覆盖。

需要精确声明能力时使用完整字段：

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

热加载

models.json 在每次打开 /model 时重新读取——会话中改文件无需重启 pi。

3.4 多模型切换实战 ​

bash
pi update --models   # 强制刷新配置型 provider 的模型目录缓存
pi --list-models     # 命令行列出全部可用模型

交互内的切换手段：

操作效果
/model 或 Ctrl+L打开模型选择器
Ctrl+P / Shift+Ctrl+P在 scoped models 间正反循环
/scoped-models配置哪些模型参与 Ctrl+P 循环

典型工作流：把"便宜快模型 + 强推理模型"都加入 scoped models，日常问答用前者，遇到硬骨头一键切到后者；Shift+Tab 调整思考等级控制推理深度与成本。

3.5 模型能力差异对编码任务的影响 ​

  • contextWindow 决定一次能塞多少代码上下文，小窗口模型要靠 /compact（第 6 章）勤压缩；
  • reasoning/thinkingLevelMap 影响架构设计与疑难调试质量，但显著增加延迟与 token 成本；
  • input 支持 image 才能粘贴截图 UI 还原任务；
  • samplingParams 仅对 OpenAI 兼容 API 生效，可透传 vLLM 的 top_k、llama.cpp 的 min_p 等服务端特有参数。

本章小结 ​

  • 认证两条路：/login 订阅 OAuth 或 API Key；auth.json > 环境变量 > models.json key；
  • 密钥值支持 !命令、$ENV、${VAR} 插值与 $$/$! 转义四种解析方式；
  • ~/.pi/agent/models.json 可接入任意 OpenAI/Anthropic/Google 协议服务，compat 解决兼容性；
  • Ctrl+L 选模型、Ctrl+P 循环 scoped models、Shift+Tab 调思考等级是日常三板斧；
  • 模型的上下文窗口/推理能力/多模态支持直接决定它适合的编码任务类型。

🧪 随堂测验

点击你认为正确的选项。答错时会展示正确答案与原因解析。

1. pi 解析 provider 凭据的正确优先级是？

2. 本地 Ollama 接入后模型不出现在 /model 列表，最可能的原因是？

3. 某 OpenAI 兼容服务器不认识 developer 角色消息，应如何处理？

4. 修改了 ~/.pi/agent/models.json 之后，正确的说法是？

🛠️ 动手实践 ​

  1. 用 models.json 把一个本地或第三方 OpenAI 兼容端点接入 pi，并用 --list-models 验证。
  2. 为你的 DeepSeek/OpenAI 密钥改造成 auth.json 中 "!命令" 形式（如从密码管理器读取），验证优先级高于环境变量。
  3. 配置两个价格/能力差异明显的模型加入 scoped models，用同一个重构任务分别执行，对比成本与质量。

进入下一章：交互模式，把终端效率拉满。