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 命令。
自定义请求头
模型配置
一个成本阶梯提供一套完整的替代费率，并在总输入使用量（input + cacheRead + cacheWrite）超过 inputTokensAbove 时应用于整个请求。多个阶梯同时匹配时，最高阈值生效。
当前行为：
/model、--list-models和交互式页脚按模型id显示条目。- 配置的
name用于模型匹配和次要模型详情文本。它不会替换页脚/状态栏中的模型 id。
采样参数
samplingParams 是一个自由形式对象，按原样合并到该模型的每个请求体中，位置在 pi 自身设置的字段之后，因此其键优先。用它发送 pi 未建模的采样参数——包括服务器特定的参数，如 llama.cpp 的 min_p 或 vLLM 的 top_k：
只有 OpenAI 兼容 API 会应用它（openai-completions、openai-responses、azure-openai-responses）；其他 API 会忽略它。键会覆盖 pi 的命名请求字段（例如这里的 temperature 键会胜过请求级 temperature），因此建议将其作为模型的唯一采样真相来源。在 modelOverrides 中，samplingParams 按 key 与基础模型的值合并。
Thinking Level Map
在模型上使用 thinkingLevelMap 来描述模型特定的 thinking 控制。键是 Pi 的 thinking level：off、minimal、low、medium、high、xhigh、max。映射可以包含空洞；例如，一个模型可以暴露 high 和 max 而不暴露 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、thinkingLevelMap、input、cost（部分）、contextWindow、maxTokens、samplingParams（按 key 合并）、headers、compat。
直接 OpenAI 的 GPT-5.6 Sol、Terra 和 Luna 默认使用 272000 上下文窗口，使请求保持在 OpenAI 的短上下文定价阶梯内。要选择使用 OpenAI 的 1.05M 上下文窗口，为每个使用的模型增加它：
该覆盖会保留内置定价元数据。总输入 token 超过 272K 的请求会在整个请求中使用 GPT-5.6 的长上下文费率。需要时对 gpt-5.6-terra 或 gpt-5.6-luna 应用相同的覆盖。
行为说明：
modelOverrides应用于内置 Provider 模型和匹配的扩展注册 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。
某些 Anthropic 兼容 Provider 会发出签名为空的 thinking 块，并在重放时仍然期望它们。仅在这些 Provider 上将 allowEmptySignature 设为 true；真正的 Anthropic 会拒绝空的 thinking 签名。
内置 Anthropic 模型在模型元数据中启用 supportsStrictTools。自定义 Anthropic 兼容模型在其端点接受严格 JSON Schema 工具定义时必须将其设为 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" } }。使用 thinkingFormat: "baseten" 搭配 chatTemplateArgs，适用于通过 chat_template_args 暴露开关控制并可选支持顶层 reasoning_effort 的 Provider。
cacheControlFormat: "anthropic" 适用于那些在文本内容和工具定义上通过 cache_control 标记暴露 Anthropic 风格提示缓存的 OpenAI 兼容 Provider。
示例：
Vercel AI Gateway 示例：
法律声明：本页面是 pi.dev 官方文档的中文翻译版本，仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。