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

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

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

## 设计思想
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` 是**对象**（键为自定义提供商名）：

```json
{
  "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`。

## 用法
### 查看与登录
```bash
pi --list-models          # 列出所有可用模型
pi --list-models claude   # 按关键词过滤
```
```text
pi        # 启动后输入 /login → 选择提供商 → 完成认证
/session  # 查看当前 provider、model、tokens、cost 等会话信息
```

### 切换模型
```bash
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 切思考级别。

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

### 刷新模型目录
```bash
pi update --models
```

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