第四章：模型供应商与认证体系

4.1 认证方式总览

Pi 的设计哲学之一是”不绑定任何一个模型供应商”。你可以今天用 Claude，明天用 DeepSeek，后天试试 Groq——切换的开销低到只是一条命令。为了支撑这种灵活性，Pi 提供 三种认证方式，覆盖从个人开发者到企业级部署的完整场景：

当同一模型供应商存在多种凭据来源时，Pi 遵循确定的解析优先级：

CLI --api-key > auth.json > 环境变量 > models.json 自定义

命令行 --api-key 参数拥有最高优先级（适合临时使用），然后是 auth.json 文件中配置的凭证（适合多 Key 池化），接着是环境变量（最传统的配置方式），最后才是 models.json 中嵌在 provider 定义里的内联 key（不推荐在生产中使用，仅用于本地测试）。

最佳实践：生产环境使用环境变量或者 auth.json。不要把 API Key 写在 models.json 里提交到版本控制系统——那个字段是为了本地跑 Ollama / LM Studio 这类本地模型时省一步 export 准备的。

4.2 环境变量方式（API Key）

这是最直接、最广泛使用的认证方式：在终端中或 Shell 配置文件中设置环境变量，Pi 启动时自动读取。支持的模型供应商极其广泛，以下逐一列出。

4.2.1 国际主流供应商

Anthropic（Claude 系列）

export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Anthropic Console → API Keys → Create Key。Pi 通过此 Key 访问 Claude 全系列模型：Claude Opus 4、Claude Sonnet 4、Claude Sonnet 3.5、Claude Haiku 3.5 等。

OpenAI（GPT 系列）

export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：OpenAI Platform → Create new secret key。覆盖 GPT-4o、GPT-4.1、o3、o4-mini、GPT-4 Turbo、GPT-3.5 Turbo 等全部模型。如果你使用的是 Azure 上托管的 OpenAI 服务，请见 4.4.3 节，那里的认证方式不同。

Google Gemini

export GEMINI_API_KEY="AIzaSyDxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Google AI Studio → Create API key。覆盖 Gemini 2.5 Pro、Gemini 2.5 Flash、Gemini 2.0 Flash 等模型。需要注意的是：此 Key 访问的是 Google AI（面向开发者的 API），而不是 Google Cloud Vertex AI——后者的认证方式见 4.4.2 节。

DeepSeek

export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：DeepSeek Platform → 创建 API Key。提供极具性价比的 DeepSeek-V3（最新）、DeepSeek-R1 系列模型，中国开发者使用非常广泛。

Mistral

export MISTRAL_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Mistral Console → Create new key。覆盖 Mistral Large 2、Codestral、Mistral Small、Mistral Nemo 等模型。Mistral 的 Code 系列在编码任务上表现出色。

Groq

export GROQ_API_KEY="gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Groq Console → Create API Key。Groq 以极低延迟著称，基于其自研 LPU 推理芯片。当前提供 DeepSeek-R1-Distill-Llama-70B、Llama 4 Scout/Maverick、Qwen 2.5 系列等模型的免费层。

Cerebras

export CEREBRAS_API_KEY="csk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Cerebras Cloud → API Keys。Cerebras 以每秒数千 token的推理速度闻名，使用自研 CS-3 晶圆级芯片。支持 Llama 4 系列、Llama 3.3 70B 等模型。

xAI（Grok）

export XAI_API_KEY="xai-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：xAI Console → API Keys。Elon Musk 的 xAI 出品，覆盖 Grok-4、Grok-3 系列模型。

OpenRouter

export OPENROUTER_API_KEY="sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：OpenRouter → Create Key。OpenRouter 是一个模型聚合网关，一个 Key 即可访问 300+ 个模型——包括 Anthropic、OpenAI、Google、Meta、Mistral、DeepSeek 等几乎所有供应商，按使用量统一计费。对于想”一把钥匙走天下”的开发者来说极为方便。

4.2.2 开源模型托管平台

Hugging Face

export HF_TOKEN="hf_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Hugging Face Settings → Create new token。通过 Hugging Face Inference API 访问 Llama、Qwen、Mistral、Gemma、Yi 等各类开源模型的托管推理服务。

Fireworks

export FIREWORKS_API_KEY="fw_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Fireworks Console。Fireworks 提供经优化的开源模型推理，支持 Llama 4、Qwen 2.5、DeepSeek 系列等，在速度和性价比上有不错表现。

Together AI

export TOGETHER_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Together AI → Create API Key。覆盖 Llama 4、Qwen 2.5、DeepSeek、Mixtral、Gemma 等 200+ 开源模型的快速推理服务。

4.2.3 中国模型供应商

Kimi（月之暗面 Moonshot）

export KIMI_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Moonshot AI 开放平台 → 创建 API Key。Kimi 系列模型在超长上下文（128K~1M token）处理方面能力突出。

MiniMax

export MINIMAX_API_KEY="eyJxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：MiniMax 开放平台 → 账户管理 → 接口密钥。MiniMax 的 MiniMax-M1 系列、abab 系列模型综合能力扎实。

小米 MiMo

export XIAOMI_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：小米大模型开放平台 → API 密钥管理。小米 MiMo 系列模型在国内场景（中文理解、编程辅助）下表现优异。

智谱 GLM（Z.AI）

export ZAI_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：智谱 AI 开放平台 → API Keys。GLM-4 系列模型覆盖通用对话、代码生成、多模态等任务，GLM-Z1 在推理类任务上表现出色。

4.2.4 云平台及企业网关

NVIDIA NIM

export NVIDIA_API_KEY="nvapi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：NVIDIA API Catalog → Generate Key。NVIDIA NIM 提供 Llama Nemotron、Nemotron、Mistral 等模型的优化推理服务。

Azure OpenAI

export AZURE_OPENAI_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Azure Portal → Azure OpenAI 服务 → Keys and Endpoint。需要同时配置 API Key 和资源名称/终结点 URL（详见 4.4.3 节）。

Cloudflare Workers AI

export CLOUDFLARE_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Cloudflare Dashboard → Workers AI → API Tokens。在 Cloudflare 全球边缘网络上运行开源模型推理。

Vercel AI Gateway

export AI_GATEWAY_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

获取方式：Vercel AI Gateway → Create API Key。Vercel 的 AI 网关提供统一的模型路由层，背后可接入多种模型供应商。

4.2.5 设置方式

推荐将环境变量写入 Shell 配置文件，确保每次打开终端自动生效：

# 编辑 ~/.zshrc（macOS 默认）或 ~/.bashrc（Linux）
# 添加以下行：

export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxx"
export OPENAI_API_KEY="sk-proj-xxxxxxxxxxxxxxxxxxxx"
export DEEPSEEK_API_KEY="sk-xxxxxxxxxxxxxxxxxxxxxxxx"

然后执行 source ~/.zshrc 或重启终端使其生效。Pi 启动时会自动检测已设置的环境变量，并列出当前可用的模型供应商。

安全提醒：不要将含 API Key 的 Shell 配置文件上传到公开仓库。如果必须共享配置文件，使用 .env 文件并在 .gitignore 中排除，或者通过操作系统的密钥管理工具（如 macOS Keychain、Linux secret-tool）存储。

4.3 OAuth 登录方式（/login 命令）

API Key 方式虽然有普适性，但对于订阅制服务的用户来说并不方便——你已经在为 Claude Pro 或 ChatGPT Plus 付费，再去申请一个 API Key 等于额外开销。Pi 为此设计了 /login 交互命令，直接对接官方订阅的认证系统。

4.3.1 支持的订阅服务

GitHub Copilot 同时支持 github.com 和 GitHub Enterprise Server（自托管企业版）两种实例类型。

4.3.2 登录流程演示

以 Claude Pro 为例：

第一步：在 Pi 的 TUI 中输入 /login

> /login

Pi 会展示可用的登录提供商列表：

选择登录方式：

  1. Anthropic（Claude Pro / Max）
  2. OpenAI（ChatGPT Plus / Pro）
  3. GitHub Copilot

请选择（1-3）：

第二步：选择 1（Anthropic），Pi 启动浏览器 OAuth 流程

Pi 会打开系统默认浏览器，跳转到 https://console.anthropic.com/authorize 页面：

请在浏览器中授权 Pi 访问您的 Anthropic 账号...

  已经授权？按 Enter 继续
  取消登录？按 Ctrl+C

第三步：在浏览器中确认授权

浏览器中将显示：

Pi CLI Tool 请求以下权限：

  ✓ 读取您的账号信息
  ✓ 以您的身份调用 API（使用订阅配额，不产生额外费用）

[ 授权 ]  [ 取消 ]

点击”授权”后，浏览器显示”登录成功，请返回终端”。

第四步：返回 Pi 终端，按 Enter

✓ 已成功登录为：your-email@example.com（Claude Pro）
  可用模型：claude-opus-4, claude-sonnet-4, claude-sonnet-3.5, claude-haiku-3.5

现在可以使用 /model 切换模型了

整个过程约 30 秒，OAuth Token 会持久化保存在 ~/.pi/auth.json 中，下次启动时自动使用，无需重复登录。如需切换账号，再次执行 /login 即可覆盖。

4.3.3 /login 与 API Key 的共存

当你同时配置了 API Key（环境变量）和 OAuth Token（/login），Pi 遵循”提供商独立”原则：每个供应商只使用自己的最高优先级凭据。举例：

• 你用 export ANTHROPIC_API_KEY 配置了 Anthropic 的 Key，同时 /login 登录了 OpenAI——两者互不干扰。
• 如果同一供应商存在 API Key 和 OAuth Token，API Key 优先级更高。你可以通过 /provider 命令查看当前各供应商的凭据状态，* 号标记实际生效的那个。

4.4 云服务提供商

除了直接调用模型供应商的 HTTP API，Pi 还支持三大公有云的 AI 服务：Amazon Bedrock、Google Vertex AI 和 Azure OpenAI。这些云服务的认证方式与普通 API Key 有所不同。

4.4.1 Amazon Bedrock

Amazon Bedrock 是 AWS 的托管模型服务，汇聚了 Anthropic Claude、Meta Llama、Cohere、Stability AI、Amazon Nova 等模型。其认证方式有三层选择：

方式一：AWS Profile（推荐）

使用已配置好的 AWS CLI Profile：

# 首先确保 AWS CLI 已配置
aws configure --profile my-project

# 指定使用的 Profile 和 Region
export AWS_PROFILE="my-project"
export AWS_REGION="us-east-1"

Pi 会通过 AWS SDK 从 ~/.aws/credentials 读取对应 Profile 的密钥。

方式二：AWS IAM 访问密钥

直接设置 Access Key（适合 CI/CD 环境）：

export AWS_ACCESS_KEY_ID="AKIAxxxxxxxxxxxxxxxx"
export AWS_SECRET_ACCESS_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export AWS_REGION="us-east-1"

方式三：Bearer Token

对于支持 Bearer Token 认证的 Bedrock 端点：

export AWS_BEARER_TOKEN="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Bedrock 可用的模型包括 Claude Opus 4、Claude Sonnet 4、Llama 4 Scout/Maverick、Nova Pro/Micro 等。与直接调用 Anthropic API 相比，Bedrock 的定价通常稍低，且数据不出 AWS 网络——这是企业级部署的重要考量。

4.4.2 Google Vertex AI

Vertex AI 是 Google Cloud 的企业级 AI 平台，认证方式与 Google AI（Gemini API）不同，使用的是 Google Cloud 标准认证机制：

Application Default Credentials（ADC，推荐）

# 登录 Google Cloud
gcloud auth application-default login

# 设置 GCP 项目 ID
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_REGION="us-central1"

ADC 会自动检测已认证的凭据（本地开发时使用 gcloud 登录的账号，生产环境使用关联到 GCE/GKE/Cloud Run 的服务账号）。

服务账号 JSON 密钥

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"
export GOOGLE_CLOUD_PROJECT="your-project-id"

Vertex AI 上可用的模型包括 Gemini 2.5 Pro（Preview）、Gemini 2.0 Flash、Claude Opus 4（通过 Anthropic on Vertex AI）、Claude Sonnet 4、Llama 4 系列等。

区别提示：GEMINI_API_KEY（4.2.1 节）访问的是面向开发者的 Google AI 服务；Vertex AI 使用 ADC 认证，功能更完整（支持更严格的区域控制、VPC Service Controls、数据驻留等企业特性），但需要 Google Cloud 账号。

4.4.3 Azure OpenAI

Azure OpenAI 的认证需要三个要素：

export AZURE_OPENAI_API_KEY="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
# 或者使用资源名称
export AZURE_OPENAI_RESOURCE_NAME="your-resource"

Azure 的特点是：你需要先在 Azure Portal 中创建 OpenAI 资源和模型部署，部署名称（deployment name）可能与模型原始名称不同。例如：

• Azure 中部署名称：gpt-4o-deployment
• Pi 中使用的模型名：需要指向你的部署名称

在 models.json 中配置 Azure 模型时，必须同时指定部署名称和 API 版本（如 2025-01-01-preview）。详细配置见 4.6 节。

4.5 切换模型

模型可以随时切换，而且是”运行时”切换——不需要重启 Pi。

4.5.1 命令行切换

# 通过模型名称切换
pi --model claude-sonnet-4 "帮我重构这个函数"

# 通过 供应商+模型 指定
pi --provider openai --model gpt-4o "用 Python 写一个快速排序"

# 一次性查询（不改变默认模型）
pi "你好，当前用的是哪个模型？"

4.5.2 交互式 TUI 内切换

在 Pi 的 TUI（终端用户界面）中，有两条路径切换模型：

/model 命令

> /model

弹出模型选择面板：

┌──────────── 切换模型 ────────────────┐
│                                      │
│  Anthropic                           │
│    → claude-opus-4              ✓    │
│      claude-sonnet-4                 │
│      claude-sonnet-3.5               │
│      claude-haiku-3.5                │
│                                      │
│  OpenAI                             │
│      gpt-4o                          │
│    → gpt-4.1                    ✓    │
│      o3                             │
│      o4-mini                        │
│                                      │
│  ... 更多提供商 ...                  │
│                                      │
│  ↑↓ 移动  Enter 选择  Esc 取消       │
└──────────────────────────────────────┘

列表中 → 指向当前选中的模型，✓ 标记当前会话正在使用的模型。

Ctrl+P 循环切换（enabledModels）

如果你在配置中设置了 enabledModels 列表：

{
  "enabledModels": [
    "claude-sonnet-4",
    "gpt-4o",
    "deepseek-v3"
  ]
}

在 TUI 中按 Ctrl+P 可在这些模型之间快速循环切换，无需打开面板——适合在编码间隙快速比较不同模型的输出质量。

4.5.3 模型简写

Pi 支持一系列便捷的模型简写，让你不用每次都敲完整的模型名称：

简写可以在任何接受模型名称的地方使用：

pi --model sonnet "这段 SQL 能否优化？"
pi --model sonnet:high "帮我设计这个系统的整体架构"   # 启用 Claude 扩展思考

4.6 自定义模型（models.json）

如果你使用的是本地模型（Ollama、vLLM、LM Studio）、自建 API 网关、企业内部模型服务，或者其它任何 OpenAI/Anthropic 兼容 API 端点，都可以通过 models.json 注册为 Pi 的一等公民——与官方模型使用体验完全一致。

4.6.1 位置与格式

~/.pi/agent/models.json

这是一个 JSON 数组，每个元素定义一个模型：

[
  {
    "id": "my-local-model",
    "name": "我的本地模型",
    "api": "openai-completions",
    "url": "http://localhost:11434/v1/chat/completions",
    "apiKey": "ollama",
    "headers": {}
  }
]

各字段说明：

4.6.2 常见场景配置示例

Ollama 本地模型

{
  "id": "llama4-ollama",
  "name": "Llama 4 Scout（Ollama）",
  "api": "openai-completions",
  "url": "http://localhost:11434/v1/chat/completions",
  "apiKey": "ollama"
}

Ollama 从 0.1.24 版本开始内置了 OpenAI 兼容 API，直接使用上述配置即可。如果 Ollama 运行在另一台机器上，将 localhost 替换为对应的 IP 地址。

{
  "id": "qwen2.5-coder-ollama",
  "name": "Qwen2.5-Coder 14B",
  "api": "openai-completions",
  "url": "http://192.168.1.100:11434/v1/chat/completions",
  "apiKey": "ollama"
}

vLLM 自建推理服务

{
  "id": "deepseek-v3-vllm",
  "name": "DeepSeek-V3（vLLM）",
  "api": "openai-completions",
  "url": "http://gpu-server:8000/v1/chat/completions"
}

vLLM 默认在 8000 端口暴露 OpenAI 兼容 API，无需 API Key。如果部署在需要认证的内网，可以加上 headers：

{
  "id": "deepseek-v3-vllm-auth",
  "name": "DeepSeek-V3（vLLM，内网认证）",
  "api": "openai-completions",
  "url": "http://gpu-server:8000/v1/chat/completions",
  "headers": {
    "Authorization": "Bearer internal-token-xxxx"
  }
}

LM Studio

LM Studio 的开发者模式会启动一个本地 API 服务器：

{
  "id": "lmstudio-local",
  "name": "LM Studio 本地模型",
  "api": "openai-completions",
  "url": "http://localhost:1234/v1/chat/completions"
}

LM Studio 默认监听 1234 端口，不支持认证，直接填 url 即可。模型名称由 LM Studio 加载的具体模型决定，id 可任意填写。

4.6.3 支持的 API 类型（api 字段）

绝大多数本地模型托管工具都提供 openai-completions 兼容端点，因此这也是最常用的 api 类型。

4.7 自定义提供商（Extensions 方式）

当你的场景不仅仅是”加一个兼容端点”这么简单——比如企业内部需要走自定义的 OAuth/SSO 流程、需要动态生成每 15 分钟轮换的临时 Token、需要在请求/响应中注入自定义的业务头部——这时 models.json 的静态配置就不够了。Pi 通过 Extensions API 提供了 pi.registerProvider() 接口，让你用 TypeScript 实现完整的自定义模型供应商。

4.7.1 pi.registerProvider() API 概览

interface PiProvider {
  /** 供应商唯一标识，如 "mycorp-internal" */
  id: string;

  /** TUI 中显示的名称 */
  name: string;

  /** 提供的模型列表 */
  models: PiModelDefinition[];

  /** 创建聊天补全请求 */
  createChatCompletion(request: PiChatRequest): Promise<PiChatResponse>;

  /** （可选）流式聊天补全 */
  createChatCompletionStream?: (
    request: PiChatRequest
  ) => AsyncIterable<PiChatChunk>;
}

interface PiModelDefinition {
  /** 模型 ID，如 "my-gpt-custom" */
  id: string;
  /** 显示名称 */
  name: string;
  /** 最大上下文窗口（tokens） */
  contextWindow: number;
  /** 支持的输入类型 */
  inputTypes?: ("text" | "image" | "file")[];
}

pi.registerProvider() 在 Extension 的 activate 函数中调用。注册后，你的自定义供应商会直接出现在 Pi 的 /model 面板中，与 Claude、GPT 等官方模型并列。

4.7.2 适用场景

场景一：企业内部模型网关

公司搭建了统一的 LLM 网关，所有模型调用需要携带 JWT Token，且 Token 每 30 分钟过期。

// 在 Extension 的 activate 中
let tokenCache: { token: string; expiresAt: number } | null = null;

async function getJwtToken(): Promise<string> {
  if (tokenCache && Date.now() < tokenCache.expiresAt) {
    return tokenCache.token;
  }
  // 调用内部 SSO 端点刷新 Token
  const resp = await fetch("https://sso.mycorp.com/api/token", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({ client_id: "pi-agent", grant_type: "client_credentials" }),
  });
  const data = await resp.json();
  tokenCache = { token: data.access_token, expiresAt: Date.now() + data.expires_in * 1000 };
  return tokenCache.token;
}

pi.registerProvider({
  id: "mycorp-gateway",
  name: "公司内部 LLM 网关",
  models: [
    { id: "my-gpt-4o", name: "GPT-4o（内部）", contextWindow: 128000 },
    { id: "my-claude-sonnet", name: "Claude Sonnet（内部）", contextWindow: 200000 },
  ],
  async createChatCompletion(request) {
    const token = await getJwtToken();
    const resp = await fetch("https://llm-gateway.mycorp.com/v1/chat/completions", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${token}`,
        "X-Request-Source": "pi-cli",
      },
      body: JSON.stringify(request),
    });
    return resp.json();
  },
});

场景二：OAuth/SSO 企业认证

企业内部使用 Okta/Azure AD 等 SSO 方案，需要交互式浏览器登录。

Extension 可以调用 pi.openBrowser(url) 打开系统浏览器完成 OAuth 流程，然后通过本地 HTTP 回调获取 authorization_code，最后换取 access_token 用于所有后续 API 调用。

场景三：费用追踪与用量控制

在 createChatCompletion 中包装一层，每次调用后上报 Token 用量到内部监控系统，并支持硬限 QPM（每分钟查询数）和 TPM（每分钟 Token 数）：

async createChatCompletion(request) {
  // 检查是否超出配额
  if (quotaTracker.exceedsLimit()) {
    throw new Error("今日 API 配额已用完，请明天再试");
  }
  const response = await originalProvider.createChatCompletion(request);
  // 上报用量
  quotaTracker.report(response.usage);
  return response;
}

4.7.3 与 models.json 的分工

简单来说：

• models.json：你的模型端点已经是一个标准的 OpenAI / Anthropic 兼容 API。只需几行 JSON，无需写代码。
• Extensions（registerProvider）：你的认证逻辑、Token 管理、请求流程、额外处理需要自定义逻辑。需要写 TypeScript，但换来完全的灵活性。

两种方式可以共存——在 models.json 中定义简单模型，在 Extensions 中注册复杂供应商，它们一起出现在你的 /model 面板中。

4.8 跨提供商上下文交接

当你在一个会话中从 Claude 切换到 DeepSeek，或者从 GPT-4o 切换到本地的 Llama 4——会发生什么？对话历史中的消息，有些可能包含特定于前一个模型的”思考链痕迹”（chain-of-thought traces）或”工具调用格式”，新模型能理解吗？

4.8.1 切换机制

Pi 在 Session 中切换模型时，会自动做以下处理：

1. 角色映射：不同 API 协议对 roles 的命名略有不同（如 Anthropic 用 assistant，但部分推理内容在 user 角色下），Pi 会根据目标 API 协议做转换。

2. 思维链痕迹 → 文本块：当你从支持”思考输出”的模型（如 Claude extended thinking、DeepSeek R1、o3）切换到不支持该特性的模型时，Pi 会将前一个模型产生的 thinking 内容——

   [推理过程]
   用户的要求是...，首先我需要...，然后考虑...，
   最终答案应该是...
   [/推理过程]
   

   ——转换为普通文本消息追加到历史中。新模型虽然不能生成新的思考块，但可以看到前任的推理轨迹，从而保持决策的一致性。当然，这样做会消耗新模型的上下文窗口，切换前可以评估一下 Token 用量。

3. 工具调用格式标准化：不同 API 的工具调用 schema 格式不同（OpenAI 用 tool_calls 数组，Anthropic 用 tool_use 内容块）。Pi 内部维护了一套中间表示（Intermediate Representation），切换模型时自动转换格式，确保新模型能正确解析之前的工具调用历史。

4. 系统提示词保留：会话级别的 system prompt 在切换模型时保持不变。但如果你使用 /clear 重置会话后切换模型，新模型将使用其供应商默认的系统提示词。

4.8.2 实践建议

• 同级别模型之间切换最平滑：Claude ↔ GPT ↔ DeepSeek 之间的工具调用格式都经过充分测试。
• 跨 API 协议切换时注意：从 anthropic-messages 切换到 google-generative-ai 时，Gemini 对某些内容类型有独特限制（如严格的安全过滤），你可能会看到部分响应被屏蔽。这时可以换回其它协议的模型。
• 大上下文模型 → 小上下文模型：如果你用 Claude（200K 上下文）跑了很长一段对话，再切换到上下文窗口只有 32K 的模型，Pi 会自动截断早期消息。截断策略是保留 system prompt + 最近 N 轮对话，确保核心信息不丢失。

4.9 本章小结

这一章我们详细讲解了 Pi 的模型供应商与认证体系：

• 三种认证方式——环境变量（最通用）、OAuth 登录（订阅用户首选）、auth.json（Key 池化管理）——覆盖了从个人到企业的全部场景，凭据解析有明确的优先级顺序。
• 20+ 模型供应商的原生支持，从国际主流（Anthropic、OpenAI、Google、DeepSeek、Mistral）到中国本土（Kimi、MiniMax、智谱 GLM），从开源托管平台（Hugging Face、Together AI、Fireworks）到云服务（Bedrock、Vertex AI、Azure OpenAI），一应俱全。
• /login 命令让你用已付费的订阅（Claude Pro、ChatGPT Plus、GitHub Copilot）直接驱动 Pi，无需额外申请 API Key。
• 模型切换可以随时进行——命令行 --model、TUI 中的 /model 面板、Ctrl+P 快捷键循环、模型简写——哪种方便用哪种。
• models.json 和 Extensions 提供了两个层级的自定义能力：静态配置适配标准 API，动态代码适配企业级 SSO/Token 自动刷新/用量追踪等复杂场景。
• 跨提供商上下文交接：切换模型时 Pi 自动处理角色映射、思考痕迹转换、工具调用格式标准化，让切换尽可能无感。

下一章：第五章：配置体系全解 将深入 Pi 的配置体系全解——包括 ~/.pi/agent/settings.json 的每一个配置项、Prompt Templates、Themes 主题系统，以及如何通过配置文件精确控制 Agent 的行为。