Custom Models（自定义模型）
本页面是 Pi 官方文档 的中文翻译。仅供学习参考。
通过 ~/.pi/agent/models.json 添加自定义 Provider 和模型（Ollama、vLLM、LM Studio、代理等）。
目录
- 最小示例
- 完整示例
- Google AI Studio 示例
- 支持的 API 类型
- Provider 配置
- 模型配置
- 覆盖内置 Provider
- 逐模型覆盖
- Anthropic Messages 兼容性
- OpenAI 兼容性
最小示例
对于本地模型（Ollama、LM Studio、vLLM），每个模型只需 id：
apiKey 值只是一个占位符，因为 Ollama 会忽略它。Pi 仍然将模型视为需要认证后才会出现在 /model 中，因此无密钥的本地服务器应保留一个虚拟值、通过 /login 为该 Provider 保存密钥，或在选择模型时传入 --api-key。
某些 OpenAI 兼容服务器不支持用于推理能力模型的 developer 角色。对于这些 Provider，设置 compat.supportsDeveloperRole 为 false，这样 Pi 会将系统提示作为 system 消息发送。如果服务器也不支持 reasoning_effort，同时设置 compat.supportsReasoningEffort 为 false。
你可以在 Provider 级别设置 compat 以应用于所有模型，也可以在模型级别设置以覆盖特定模型。这通常适用于 Ollama、vLLM、SGLang 等 OpenAI 兼容服务器。
完整示例
在需要特定值时覆盖默认设置：
该文件在每次打开 /model 时重新加载。在会话期间编辑，无需重启。
Google AI Studio 示例
使用 google-generative-ai 配合 baseUrl 添加 Google AI Studio 的模型，包括自定义 Gemma 4 条目：
向 google-generative-ai API 类型添加自定义模型时需要 baseUrl。
支持的 API 类型
在 Provider 级别（所有模型的默认值）或模型级别（逐个覆盖）设置 api。
Provider 配置
对于带 models 的 Provider，非内置 Provider 配置需要在 Provider 或模型级别提供 baseUrl 和 api 值。apiKey 不是加载文件的必要条件：当通过 /login/auth.json、CLI --api-key 或 Provider 的 apiKey 配置认证后，模型才可用。如果未配置认证，模型仍会加载，但在 /model 和 --list-models 中不可用。
值解析
apiKey 和 headers 字段支持三种格式：
-
Shell 命令：
"!command"执行命令并使用 stdout -
环境变量插值：
"$ENV_VAR"或"${ENV_VAR}"使用命名环境变量的值。插值可以在更大的字面值内工作。$FOO_BAR是变量FOO_BAR；当BAR是字面文本时使用${FOO}_BAR。缺少的环境变量会使值变为未解析状态。 -
字面值： 直接使用。纯大写字符串如
MY_API_KEY是字面量；使用$MY_API_KEY表示环境变量。 -
转义：
"$$"产生字面值"$"；"$!"产生字面值"!"而不触发命令执行。
对于 models.json，Shell 命令在请求时解析。Pi 有意不对任意命令应用内置 TTL、过期复用或恢复逻辑。不同的命令需要不同的缓存和失败策略，Pi 无法推断出正确策略。
如果你的命令较慢、昂贵、受速率限制，或者希望在瞬态失败时继续使用之前的值，请将其包装在你自己的脚本或命令中，实现所需的缓存或 TTL 行为。
/model 可用性检查使用已配置的认证信息，不会执行 Shell 命令。
自定义请求头
模型配置
当前行为：
/model、--list-models和交互式页脚按模型id显示条目。- 配置的
name用于模型匹配和次要模型详情文本。它不会替换页脚/状态栏中的模型 id。
Thinking Level Map
在模型上使用 thinkingLevelMap 来描述模型特定的 thinking 控制。键是 Pi 的 thinking level：off、minimal、low、medium、high、xhigh。
值为三态：
仅支持 off、high 和 max 推理的模型示例：
不可禁用 thinking 的模型示例：
迁移：使用 compat.reasoningEffortMap 的旧配置应将映射移至模型级别的 thinkingLevelMap。对于不应在 UI 中显示的 level，使用 null。
覆盖内置 Provider
通过代理路由内置 Provider，无需重新定义模型：
所有内置 Anthropic 模型保持可用。现有的 OAuth 或 API Key 认证继续有效。
要将自定义模型合并到内置 Provider 中，包含 models 数组：
合并语义：
- 内置模型被保留。
- 自定义模型按 Provider 内的
id进行更新（upsert）。 - 如果自定义模型
id与内置模型id匹配，则替换该内置模型。 - 如果自定义模型
id是新的，则与内置模型并列添加。
逐模型覆盖
使用 modelOverrides 自定义特定内置模型，无需替换 Provider 的完整模型列表。
modelOverrides 支持每个模型的以下字段：name、reasoning、input、cost（部分）、contextWindow、maxTokens、headers、compat。
行为说明：
modelOverrides应用于内置 Provider 的模型。- 未知模型 ID 被忽略。
- 你可以将 Provider 级别的
baseUrl/headers与modelOverrides结合使用。 - 覆盖
name仅会改变模型匹配和次要详情文本；页脚和主模型列表仍继续显示模型id。 - 如果 Provider 也定义了
models，自定义模型在内置覆盖之后合并。具有相同id的自定义模型会替换已覆盖的内置模型条目。
Anthropic Messages 兼容性
对于使用 api: "anthropic-messages" 的 Provider 或代理，使用 compat 控制 Anthropic 特定请求兼容性。
默认情况下，Pi 发送每个工具的 eager_input_streaming: true。如果代理或 Anthropic 兼容的后端拒绝此字段，将 supportsEagerToolInputStreaming 设为 false。Pi 会省略 tools[].eager_input_streaming，并在启用工具的请求中发送旧的 fine-grained-tool-streaming-2025-05-14 beta 头。
某些 Anthropic 模型需要 adaptive thinking（thinking.type: "adaptive" 加 output_config.effort），而非旧的基于 token 预算的 thinking 负载。内置模型会自动设置此项。对于路由到这些模型的自定义 Provider 或别名，将 forceAdaptiveThinking 设为 true。
OpenAI 兼容性
对于部分 OpenAI 兼容的 Provider，使用 compat 字段。
- Provider 级别的
compat应用于该 Provider 下的所有模型。 - 模型级别的
compat覆盖该模型的 Provider 级别值。
openrouter 使用 reasoning: { effort }。together 使用 reasoning: { enabled }，并在 supportsReasoningEffort 启用时也使用 reasoning_effort。qwen 使用顶级 enable_thinking。对需要 chat_template_kwargs.enable_thinking 和 preserve_thinking 的本地 Qwen 兼容服务器，使用 qwen-chat-template。对需要可配置 chat_template_kwargs 的 vLLM/Hugging Face chat-template，使用 chat-template，例如 DeepSeek V3.x 模板使用 chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }。
cacheControlFormat: "anthropic" 适用于那些在文本内容和工具定义上通过 cache_control 标记暴露 Anthropic 风格提示缓存的 OpenAI 兼容 Provider。
示例：
Vercel AI Gateway 示例：
法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。