Providers：接入更多模型

pi 是一个 BYOK（Bring Your Own Key，自带密钥）工具。它不卖模型调用额度，也不捆绑某个特定厂商——你用谁的模型、花多少钱，完全由你自己决定。

本章基于 pi v0.84.1。

---

两类接入方式

pi 支持两种接入方式：

1. 订阅登录：你有 ChatGPT Plus、Claude Pro、GitHub Copilot 等订阅，pi 通过 OAuth 登录直接复用你的订阅额度
2. API Key：你有厂商的 API Key，通过环境变量或 auth.json 配置，pi 按量调用

两种方式对应不同的使用场景。订阅登录适合已经有会员、不想额外付费的人；API Key 适合用量大、需要精确控制成本的人。

---

订阅登录

在 pi 的交互模式下，敲 /login 然后选择一个 provider：

提供商	需要的订阅	说明
Claude Pro/Max	Anthropic 订阅	按 token 额外计费，不走套餐额度
ChatGPT Plus/Pro	OpenAI 订阅	官方支持的 Codex 通道
GitHub Copilot	GitHub Copilot 订阅	支持企业服务器
xAI (Grok/X)	X Premium 订阅	使用 Grok 模型
OpenRouter	OpenRouter 账户	OAuth 创建 API Key，从 OpenRouter 余额扣费
Radius	Radius 账户	动态 pi-messages 网关

登录后，凭证存储在 ~/.pi/agent/auth.json，Token 过期后自动刷新。用 /logout 可以清除。

---

API Key 配置

API Key 有三种配置优先级（从高到低）：

1. CLI 参数 --api-key
2. ~/.pi/agent/auth.json
3. 环境变量

常用 Provider 环境变量一览

下表列出主流 provider 的环境变量名。完整列表见官方源码。

提供商	环境变量	auth.json 键
OpenAI	OPENAI_API_KEY	openai
Anthropic	ANTHROPIC_API_KEY	anthropic
Google Gemini	GEMINI_API_KEY	google
DeepSeek	DEEPSEEK_API_KEY	deepseek
OpenRouter	OPENROUTER_API_KEY	openrouter
Groq	GROQ_API_KEY	groq
Mistral	MISTRAL_API_KEY	mistral
xAI	XAI_API_KEY	xai
NVIDIA NIM	NVIDIA_API_KEY	nvidia
Cerebras	CEREBRAS_API_KEY	cerebras
Hugging Face	HF_TOKEN	huggingface
Fireworks	FIREWORKS_API_KEY	fireworks
Together AI	TOGETHER_API_KEY	together
Kimi For Coding	KIMI_API_KEY	kimi-coding
MiniMax	MINIMAX_API_KEY	minimax
通义千问 Token Plan	QWEN_TOKEN_PLAN_API_KEY	qwen-token-plan
ZAI Coding Plan	ZAI_API_KEY	zai

设置方式很简单：

# 设置环境变量后启动 pi
export ANTHROPIC_API_KEY=sk-ant-xxxxx
pi

也可以在 auth.json 中集中管理：

{
  "anthropic": { "type": "api_key", "key": "sk-ant-xxxxx" },
  "openai": { "type": "api_key", "key": "sk-xxxxx" },
  "deepseek": { "type": "api_key", "key": "sk-xxxxx" }
}

auth.json 文件的权限是 0600（仅当前用户可读写），相对环境变量更安全。

Key 的高级解析

auth.json 中的 key 字段不只是纯文本，它支持三种写法：

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

"!command" 开头时，pi 会执行该命令并用 stdout 作为 key，进程生命周期内缓存结果。适合搭配 macOS Keychain、1Password CLI 等密码管理工具。

"$ENV_VAR" 从环境变量读取，"$$" 输出字面量 $。

---

云厂商接入

Azure OpenAI

需要额外设置终结点地址：

export AZURE_OPENAI_API_KEY=xxxxx
export AZURE_OPENAI_BASE_URL=https://your-resource.ai.azure.com
# 或者用资源名
export AZURE_OPENAI_RESOURCE_NAME=your-resource

可选配置 API 版本和部署名映射：

export AZURE_OPENAI_API_VERSION=2024-02-01
export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o

Amazon Bedrock

支持 AWS Profile、IAM Key、Bearer Token 三种认证方式：

# 方式一：AWS Profile
export AWS_PROFILE=your-profile

# 方式二：IAM Keys
export AWS_ACCESS_KEY_ID=AKIAxxxxx
export AWS_SECRET_ACCESS_KEY=xxxxx

# 方式三：Bearer Token
export AWS_BEARER_TOKEN_BEDROCK=xxxxx

# 指定区域（默认 us-east-1）
export AWS_REGION=us-west-2

调用时直接指定 provider 和模型 ID：

pi --provider amazon-bedrock --model us.anthropic.claude-sonnet-4-20250514-v1:0

Claude 模型的 prompt caching（提示缓存）自动开启，能显著降低重复上下文的成本。

Google Vertex AI

用 Google Cloud 的应用默认凭证：

gcloud auth application-default login
export GOOGLE_CLOUD_PROJECT=your-project
export GOOGLE_CLOUD_LOCATION=us-central1

---

Provider 配置：settings.json

在 settings.json 中，你可以指定 pi 启动时用哪个 provider 和模型：

{
  "defaultProvider": "anthropic",
  "defaultModel": "claude-sonnet-4-20250514"
}

也可以在命令行直接覆盖：

pi --provider openai --model gpt-5.1
pi --provider deepseek --model deepseek-chat
pi --provider google --model gemini-2.5-pro

provider 和 model 的值对应 pi 内置的 provider 名称和模型 ID。想查看当前支持哪些模型？在交互模式下敲 /model。

---

自定义 Provider：models.json

除了内置 provider 之外，pi 允许你通过 ~/.pi/agent/models.json 添加自定义 provider。这个机制非常实用——你可以接入任何兼容 OpenAI API 或 Anthropic API 的服务。

最简配置：接入 Ollama

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

Ollama 不校验 API Key，所以 apiKey 填个占位值就行。api 字段告诉 pi 用 OpenAI Chat Completions 协议通信。

model 数组里的每个对象只需要 id——也就是你 ollama pull 的模型名。

完整配置：自定义参数

当默认行为不够时，你可以逐模型设置详细参数：

{
  "providers": {
    "vllm": {
      "baseUrl": "http://localhost:8000/v1",
      "api": "openai-completions",
      "apiKey": "not-needed",
      "models": [
        {
          "id": "deepseek-v3",
          "name": "DeepSeek V3（本地）",
          "reasoning": true,
          "input": ["text", "image"],
          "contextWindow": 128000,
          "maxTokens": 16384,
          "cost": {
            "input": 0,
            "output": 0,
            "cacheRead": 0,
            "cacheWrite": 0
          }
        }
      ]
    }
  }
}

字段说明：

字段	说明
id	模型标识符，传给 API
name	人类可读的名称，显示在模型列表里
reasoning	是否支持 extended thinking（扩展思考）
input	支持的输入类型：["text"] 或 ["text", "image"]
contextWindow	上下文窗口大小（token 数）
maxTokens	最大输出 token 数
cost	每百万 token 的价格（用于显示成本）

兼容性设置

不是所有 OpenAI 兼容服务都完全实现了 OpenAI 的每个字段。用 compat 告诉 pi 怎么适配：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false,
        "supportsUsageInStreaming": false,
        "maxTokensField": "max_tokens"
      },
      "models": [
        { "id": "llama3.1:8b" }
      ]
    }
  }
}

常用 compat 选项：

选项	作用	默认值
supportsDeveloperRole	是否支持 developer 角色（否则回退为 system）	true
supportsReasoningEffort	是否支持 reasoning_effort 参数	true
supportsUsageInStreaming	流式响应是否返回 usage 信息	true
maxTokensField	用 max_tokens 还是 max_completion_tokens	max_completion_tokens
supportsFinishReason	流式响应是否返回 finish_reason	true

compat 可以放在 provider 级别（所有模型生效），也可以放在单个 model 级别（覆盖 provider 默认值）。

接入 Google AI Studio

Google AI Studio 的免费模型也可以用 models.json 加进来：

{
  "providers": {
    "my-google": {
      "baseUrl": "https://generativelanguage.googleapis.com/v1beta",
      "api": "google-generative-ai",
      "apiKey": "$GEMINI_API_KEY",
      "models": [
        {
          "id": "gemma-4-31b-it",
          "name": "Gemma 4 31B",
          "input": ["text", "image"],
          "contextWindow": 262144,
          "reasoning": true
        }
      ]
    }
  }
}

注意 api 是 google-generative-ai，不是 openai-completions。

覆盖内置 Provider

如果想把某个内置 provider 的请求走代理，不用重新定义模型列表，只改 baseUrl 就行：

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://my-proxy.example.com/v1"
    }
  }
}

所有 Anthropic 内置模型不变，但请求会发到你的代理。已有认证信息继续有效。

{
  "providers": {
    "openai": {
      "baseUrl": "https://api.openai-proxy.com/v1",
      "headers": {
        "x-custom-header": "my-value"
      }
    }
  }
}

---

支持的 API 协议

自定义 provider 可以用四种 API 协议跟模型通信：

API 类型	全称	适用场景
openai-completions	OpenAI Chat Completions	兼容性最广，Ollama/vLLM/LM Studio 首选
openai-responses	OpenAI Responses API	OpenAI 新协议
anthropic-messages	Anthropic Messages API	Anthropic 兼容服务
google-generative-ai	Google Generative AI	Google 模型直连

---

认证优先级

当你配置了多种认证方式时，pi 按以下顺序查找凭证：

1. CLI 的 --api-key 参数
2. auth.json 中对应 provider 的条目
3. 环境变量
4. models.json 中该 provider 的 apiKey

前面的找到就用前面的，不会再往下查。这个优先级设计让你可以在测试时用 --api-key 临时覆盖，平时让 auth.json 管理。

---

小结

pi 的 provider 体系核心思路就两个：不绑定厂商、配置即接入。内置的 provider 覆盖了主流云服务，models.json 覆盖了本地模型和自定义 API。拿到一个兼容 OpenAI API 或 Anthropic API 的服务地址，写几行 JSON，pi 就能用了。

下一章聊聊怎么用 AGENTS.md 和提示词模板来定制 pi 的行为和风格。