03 模型与供应商

1. 概念

• model（模型）：生成回复的具体模型，如 claude-sonnet-4-5。
• provider（供应商）：Pi 访问该模型的服务或账号，如 anthropic、openrouter、ollama。

同一模型可能经由不同供应商提供；模型 ID 可用 provider/id 形式限定。

2. 接入路径速查

你手上有什么	推荐做法
受支持的订阅	/login 走 OAuth
供应商 API key	/login 存储，或设环境变量
本地 GGUF 模型	接 llama.cpp router
OpenAI / Anthropic / Google 兼容端点	写入 models.json
自定义协议或认证流程	写 provider extension

Pi 内置模型目录（catalog），也可从 pi.dev 覆盖更新目录数据；缓存数据离线可用，pi update --models 强制刷新。

3. 凭据解析优先级

配置了多个来源时，Pi 按以下顺序选用：

1. 运行时 --api-key（不持久化）；
2. auth.json 中已存储的凭据；
3. models.json 里的 apiKey；
4. 供应商的环境变量或云端环境凭据（ambient credentials）。

Provider extension 可以自定义认证行为。

4. 交互式认证

/login          # 选择供应商，走 OAuth 或 API key 流程
/login radius   # 直接指定供应商
/logout         # 删除已存储凭据（不会 unset 环境变量，也不会在供应商侧吊销）

远程/无头机器上 OAuth 回调可能到不了本地：提示时把最终重定向 URL 或授权码粘回 Pi。

auth.json 可能包含 API key 与 OAuth token，不要提交、不要外泄。

5. 用环境变量提供 key（CI 友好）

export ANTHROPIC_API_KEY=sk-ant-...
pi

单一主变量的常用供应商：

Provider	环境变量
Anthropic	ANTHROPIC_API_KEY（另有 ANTHROPIC_OAUTH_TOKEN、ANTHROPIC_AUTH_TOKEN）
OpenAI	OPENAI_API_KEY
Google Gemini	GEMINI_API_KEY
GitHub Copilot	COPILOT_GITHUB_TOKEN
DeepSeek	DEEPSEEK_API_KEY
xAI	XAI_API_KEY
OpenRouter	OPENROUTER_API_KEY
Mistral / Groq / Cerebras	MISTRAL_API_KEY / GROQ_API_KEY / CEREBRAS_API_KEY
Vercel AI Gateway	AI_GATEWAY_API_KEY
Hugging Face	HF_TOKEN
Fireworks / Together / Baseten	FIREWORKS_API_KEY / TOGETHER_API_KEY / BASETEN_API_KEY
Kimi / Moonshot / MiniMax / Qwen / Xiaomi MiMo	KIMI_API_KEY / MOONSHOT_API_KEY / MINIMAX_API_KEY / QWEN_TOKEN_PLAN_API_KEY / XIAOMI_API_KEY
Radius	RADIUS_API_KEY
TypeSafe（分类器模型）	TYPESAFE_API_KEY

需要额外配置的供应商：

• Azure OpenAI：AZURE_OPENAI_API_KEY + AZURE_OPENAI_BASE_URL 或 AZURE_OPENAI_RESOURCE_NAME。
• Amazon Bedrock：AWS_PROFILE 或 IAM 三元组（AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN），或 AWS_BEARER_TOKEN_BEDROCK；区域用 AWS_REGION；支持 ECS 任务凭据与 IRSA。
• Cloudflare AI Gateway：CLOUDFLARE_API_KEY + CLOUDFLARE_ACCOUNT_ID + CLOUDFLARE_GATEWAY_ID。
• Cloudflare Workers AI：CLOUDFLARE_API_KEY + CLOUDFLARE_ACCOUNT_ID。
• Google Vertex AI：GOOGLE_CLOUD_API_KEY，或 ADC（GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION + gcloud auth application-default login），或用 GOOGLE_APPLICATION_CREDENTIALS 指定服务账号文件。
• Anthropic 无密钥场景：同时设置 ANTHROPIC_FEDERATION_RULE_ID、ANTHROPIC_ORGANIZATION_ID、ANTHROPIC_IDENTITY_TOKEN_FILE 时走 workload identity federation（SDK 自行换取短期 token 并刷新。注意它会在长会话中重读该文件）。

6. 用命令取 key（不落盘）

auth.json 中把 key 写成以 ! 开头的命令，Pi 在首次需要时执行并缓存其 stdout（进程生命周期内）：

{
  "anthropic": {
    "type": "api_key",
    "key": "!security find-generic-password -ws 'anthropic'"
  }
}

输出为空、超时或非零退出时，key 在本进程内保持未解析。存储型 API key 凭据还可带 env 对象，其值在该供应商范围内优先于进程环境：

{
  "cloudflare-workers-ai": {
    "type": "api_key",
    "key": "...",
    "env": { "CLOUDFLARE_ACCOUNT_ID": "account-id" }
  }
}

7. 选择与切换模型

• /model 搜索并选择（只展示能解析出可用凭据的模型）；在该界面按 Ctrl+S 存为新会话的默认模型。
• /thinking 选择推理强度；按 Ctrl+S 保存启动档位。Pi 会把选项限制在该模型支持的范围内。
• Ctrl+P 循环已启用模型；/scoped-models 控制循环范围并保存。
• --model sonnet:high 支持模糊匹配、provider/id 与 :<thinking> 后缀；--models <patterns> 设定启动与循环范围；--list-models [search] 列出后退出。
• 设置项：defaultProvider、defaultModel、defaultThinkingLevel（默认 medium）、modelThinkingLevels、enabledModels。

会话会记录模型与 thinking level 的变更（model_change / thinking_level_change 条目），恢复会话时还原它们，但不改变新会话的默认值。

8. 本地模型与兼容端点

llama.cpp

Pi 直接集成 llama.cpp router：router 发现 GGUF 文件并按需加载模型；/llama 管理 router，/model 选择其中已加载的模型。详见官方 docs/llama-cpp.md。

兼容端点（models.json）

适用于 Ollama、LM Studio、vLLM、SGLang 以及大多数代理部署：

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

要点：

• dummy key 只是为了“模型可用”，Ollama 会忽略它。
• apiKey 与 header 值支持 $NAME / ${NAME} 环境插值、字面值、或以 !command 开头的命令（在请求时执行，Pi 不缓存）。
• 打开 /model 会重载该文件；models 条目按同 ID 新增或替换；modelOverrides 只改元数据而不替换供应商的模型列表（未知 ID 忽略）。
• 兼容性开关应描述已验证的端点行为差异，不要仅因对方声称 OpenAI/Anthropic 兼容就打开。

图片输入与缓存声明

{
  "id": "vision-model",
  "input": ["text", "image"],
  "inputLimits": {
    "images": {
      "resize": { "maxWidth": 1568, "maxHeight": 1568, "maxBytes": 524288, "jpegQuality": 75 }
    }
  },
  "promptCache": { "short": 300, "long": 3600 }
}

• resize 控制新图片附件、read 结果与工具结果图片的编码；省略时默认 2000x2000、编码后 4.5 MiB、JPEG 质量 80。图片只编码一次，换模型不会重写历史图片。
• maxBytes 限制的是 base64 编码后的载荷。
• promptCache 声明供应商尽力而为的缓存寿命（秒），分 short / long 两档；未声明对应档位的模型不会被预热。cacheWarming 默认为 streaming。

9. 分类器模型与图片模型（只能经 codemode 触达）

• 分类器模型不聊天，只对 JSON 状态做类型化问答（多选/是非/打分，带概率）。Pi 内置 TypeSafe 的 Jev，可用供应商包括 typesafe、openrouter、cloudflare-workers-ai、vercel-ai-gateway、opencode。
• 图片模型根据 prompt（及可选输入图）生图，Pi 内置 OpenRouter 的图片模型，如 google/gemini-2.5-flash-image。
• 这两类模型不出现在 /model，只能通过 codemode 工具的 models.classify() / models.generateImages() 调用；codemode 默认关闭，需在 defaultTools 里加 +codemode（或由 MCP 自行打开）。
• 脚本内用 models.getAvailableOfType("classifier") / models.getModelOfType("image", provider, id) 获取。脚本中分类/生图的用量会计入 codemode 工具结果，从而计入会话费用。
• Extension 里不经 codemode，直接调 ctx.modelRegistry.classify() / generateImages()；virtual model 可用分类器做路由（如官方 examples/extensions/jev-router.ts）。

10. 故障排查

现象	排查
模型不出现	确认该供应商已有可用凭据；models.json 里的自定义模型没凭据前不会在 /model 出现；llama.cpp 只显示 router 当前已加载的模型
只在一个 shell 能用	key 来自环境变量而非 auth.json，必须在启动 Pi 的那个进程里存在
远程机器弹浏览器登录	用供应商的 headless 流程，把最终重定向 URL/授权码粘回 Pi
兼容端点拒绝请求	核对 models.json 的 api 类型与兼容性开关；上游必须真的支持对应请求字段与行为

溯源

• 官方 docs/models.md、docs/providers.md、docs/custom-provider.md、docs/virtual-models.md、docs/llama-cpp.md、docs/settings.md