自定义模型

通过 ~/.pi/agent/models.json 添加自定义提供商和模型（Ollama、vLLM、LM Studio、代理）。

目录

最小示例

对于本地模型（Ollama、LM Studio、vLLM），每个模型只需要 id：

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

apiKey 值是一个占位符，因为 Ollama 会忽略它。Pi 仍然会在模型出现在 /model 之前将其视为需要认证，因此无密钥的本地服务器应保留一个虚拟值、使用 /login 为该提供商保存一个密钥，或在选择模型时传入 --api-key。

某些 OpenAI 兼容服务器不理解具备推理能力的模型所使用的 developer 角色。对于这些提供商，请将 compat.supportsDeveloperRole 设置为 false，这样 Pi 会改为以 system 消息发送系统提示词。如果服务器也不支持 reasoning_effort，也请将 compat.supportsReasoningEffort 设置为 false。

你可以在提供商级别设置 compat 以应用于所有模型，或在模型级别设置以覆盖特定模型。这通常适用于 Ollama、vLLM、SGLang 以及类似的 OpenAI 兼容服务器。

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "compat": {
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": false
      },
      "models": [
        {
          "id": "gpt-oss:20b",
          "reasoning": true
        }
      ]
    }
  }
}

完整示例

当你需要特定值时覆盖默认值：

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        {
          "id": "llama3.1:8b",
          "name": "Llama 3.1 8B (Local)",
          "reasoning": false,
          "input": ["text"],
          "contextWindow": 128000,
          "maxTokens": 32000,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

每次打开 /model 时都会重新加载该文件。可在会话期间编辑；无需重启。

Google AI Studio 示例

使用带有 baseUrl 的 google-generative-ai 来添加来自 Google AI Studio 的模型，包括自定义 Gemma 4 条目：

{
  "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
        }
      ]
    }
  }
}

向 google-generative-ai API 类型添加自定义模型时，必须提供 baseUrl。

支持的 API

API描述
openai-completionsOpenAI Chat Completions（兼容性最好）
openai-responsesOpenAI Responses API
anthropic-messagesAnthropic Messages API
google-generative-aiGoogle Generative AI

在提供商级别设置 api（所有模型的默认值），或在模型级别设置（按模型覆盖）。

提供商配置

字段描述
baseUrlAPI 端点 URL
apiAPI 类型（见上文）
apiKey可选 API 密钥配置（见下方值解析）。当认证由 /login/auth.json 或 CLI --api-key 提供时可省略。
headers自定义请求头（见下方值解析）
authHeader设置为 true 时自动添加 Authorization: Bearer <apiKey>
models模型配置数组
modelOverrides此提供商上内置模型的按模型覆盖

对于带有 models 的提供商，非内置提供商配置需要在提供商或模型级别提供 baseUrl 和一个 api 值。加载文件不要求 apiKey：当通过 /login/auth.json、CLI --api-key 或提供商 apiKey 配置认证后，模型就会可用。如果未配置认证，模型会加载，但在 /model 和 --list-models 中保持不可用。

值解析

apiKey 和 headers 字段支持命令执行、环境变量插值和字面量：

  • Shell 命令： 以 "!command" 开头会将整个值作为命令执行，并使用 stdout
    "apiKey": "!security find-generic-password -ws 'anthropic'"
"apiKey": "!op read 'op://vault/item/credential'"
  • 环境变量插值： "$ENV_VAR" 或 "${ENV_VAR}" 使用命名变量的值。插值可用于更大的字面量内部。
    "apiKey": "$MY_API_KEY"
"apiKey": "${KEY_PREFIX}_${KEY_SUFFIX}"
    $FOO_BAR 是变量 FOO_BAR；当 BAR 是字面文本时，请使用 ${FOO}_BAR。缺失的环境变量会使该值无法解析。
  • 转义： "$$" 输出字面量 "$"；"$!" 输出字面量 "!"，且不会触发命令执行。
    "apiKey": "$$literal-dollar-prefix"
"apiKey": "$!literal-bang-prefix"
  • 字面值： 直接使用。像 MY_API_KEY 这样的纯大写字符串是字面量；环境变量请使用 $MY_API_KEY。
    "apiKey": "sk-..."

对于 models.json，Shell 命令会在请求时解析。Pi 有意不会对任意命令应用内置 TTL、过期复用或恢复逻辑。不同命令需要不同的缓存和失败策略，Pi 无法推断哪一种才是正确的。

如果你的命令较慢、成本较高、受速率限制，或应在瞬时失败时继续使用先前的值，请将其包装到你自己的脚本或命令中，并实现你想要的缓存或 TTL 行为。

/model 可用性检查使用已配置认证是否存在来判断，并不会执行 Shell 命令。

自定义请求头

{
  "providers": {
    "custom-proxy": {
      "baseUrl": "https://proxy.example.com/v1",
      "apiKey": "$MY_API_KEY",
      "api": "anthropic-messages",
      "headers": {
        "x-portkey-api-key": "$PORTKEY_API_KEY",
        "x-secret": "!op read 'op://vault/item/secret'"
      },
      "models": [...]
    }
  }
}

模型配置

字段必需默认值描述
id是—模型标识符（传递给 API）
name否id人类可读的模型标签。用于匹配（--model 模式）并显示为次要模型详情文本。
api否提供商的 api覆盖此模型的提供商 API
reasoning否false支持扩展思考
thinkingLevelMap否省略将 Pi 思考级别映射到提供商值，并标记不支持的级别（见下文）
input否["text"]输入类型：["text"] 或 ["text", "image"]
contextWindow否128000上下文窗口大小（以 token 计）
maxTokens否16384最大输出 token 数
cost否全为零{"input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0}（每百万 token）
compat否提供商 compat提供商兼容性覆盖。当同时设置模型级和提供商级 compat 时会合并。

当前行为：

  • /model、--list-models 和交互式页脚按模型 id 显示条目。
  • 已配置的 name 用于模型匹配和次要模型详情文本。它不会替换页脚/状态栏中的模型 id。

思考级别映射

在模型上使用 thinkingLevelMap 来描述模型特定的思考控制。键是 Pi 思考级别：off、minimal、low、medium、high、xhigh。

值为三态：

值含义
省略支持该级别，并使用提供商的默认映射
字符串支持该级别，并将此值发送给提供商
null不支持该级别，并将其隐藏/跳过/钳制掉

仅支持关闭、高和最大推理的模型示例：

{
  "id": "deepseek-v4-pro",
  "reasoning": true,
  "thinkingLevelMap": {
    "minimal": null,
    "low": null,
    "medium": null,
    "high": "high",
    "xhigh": "max"
  }
}

无法禁用思考的模型示例：

{
  "id": "always-thinking-model",
  "reasoning": true,
  "thinkingLevelMap": {
    "off": null
  }
}

迁移：使用过 compat.reasoningEffortMap 的旧配置应将该映射移至模型级 thinkingLevelMap。对于不应出现在 UI 中的级别，请使用 null。

覆盖内置提供商

将内置提供商路由到代理，而无需重新定义模型：

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

所有内置 Anthropic 模型仍然可用。现有 OAuth 或 API 密钥认证会继续工作。

若要将自定义模型合并到内置提供商中，请包含 models 数组：

{
  "providers": {
    "anthropic": {
      "baseUrl": "https://my-proxy.example.com/v1",
      "apiKey": "$ANTHROPIC_API_KEY",
      "api": "anthropic-messages",
      "models": [...]
    }
  }
}

合并语义：

  • 保留内置模型。
  • 自定义模型按提供商内的 id 执行 upsert。
  • 如果自定义模型 id 与内置模型 id 匹配，自定义模型会替换该内置模型。
  • 如果自定义模型 id 是新的，则会与内置模型一起添加。

按模型覆盖

使用 modelOverrides 自定义特定内置模型，而无需替换提供商的完整模型列表。

{
  "providers": {
    "openrouter": {
      "modelOverrides": {
        "anthropic/claude-sonnet-4": {
          "name": "Claude Sonnet 4 (Bedrock Route)",
          "compat": {
            "openRouterRouting": {
              "only": ["amazon-bedrock"]
            }
          }
        }
      }
    }
  }
}

modelOverrides 支持每个模型的这些字段：name、reasoning、input、cost（部分）、contextWindow、maxTokens、headers、compat。

行为说明：

  • modelOverrides 会应用到内置提供商模型。
  • 未知模型 ID 会被忽略。
  • 你可以将提供商级 baseUrl/headers 与 modelOverrides 组合使用。
  • 覆盖 name 只会改变模型匹配和次要详情文本；页脚和主要模型列表仍继续显示模型 id。
  • 如果提供商也定义了 models，自定义模型会在内置覆盖之后合并。具有相同 id 的自定义模型会替换已覆盖的内置模型条目。

Anthropic Messages 兼容性

对于使用 api: "anthropic-messages" 的提供商或代理，请使用 compat 控制 Anthropic 特定的请求兼容性。

默认情况下，Pi 会发送每工具 eager_input_streaming: true。如果代理或 Anthropic 兼容后端拒绝该字段，请将 supportsEagerToolInputStreaming 设置为 false。Pi 将省略 tools[].eager_input_streaming，并改为针对启用工具的请求发送旧版 fine-grained-tool-streaming-2025-05-14 beta 请求头。

某些 Anthropic 模型需要自适应思考（thinking.type: "adaptive" 加 output_config.effort），而不是旧版基于预算的思考负载。内置模型会自动设置这一点。对于路由到这些模型的自定义提供商或别名，请将 forceAdaptiveThinking 设置为 true。

某些 Anthropic 兼容提供商会发出带有空签名的思考块，并且仍期望在重放时包含它们。仅对这些提供商将 allowEmptySignature 设置为 true；真正的 Anthropic 会拒绝空思考签名。

{
  "providers": {
    "anthropic-proxy": {
      "baseUrl": "https://proxy.example.com",
      "api": "anthropic-messages",
      "apiKey": "$ANTHROPIC_PROXY_KEY",
      "compat": {
        "supportsEagerToolInputStreaming": false,
        "supportsLongCacheRetention": true,
        "forceAdaptiveThinking": true,
        "allowEmptySignature": true
      },
      "models": [
        {
          "id": "claude-opus-4-7",
          "reasoning": true,
          "input": ["text", "image"]
        }
      ]
    }
  }
}
字段描述
supportsEagerToolInputStreaming提供商是否接受每工具 eager_input_streaming。默认值：true。设置为 false 可省略该字段，并在启用工具的请求中使用旧版细粒度工具流式 beta 请求头。
supportsLongCacheRetention提供商是否在缓存保留为 long 时接受 Anthropic 长缓存保留（cache_control.ttl: "1h"）。默认值：true。
sendSessionAffinityHeaders缓存启用时是否根据会话 id 发送 x-session-affinity。默认值：对已知提供商自动检测。
supportsCacheControlOnTools提供商是否接受工具定义上的 Anthropic 风格 cache_control 标记。默认值：true。
forceAdaptiveThinking是否为此模型发送自适应思考（thinking.type: "adaptive" 加 output_config.effort）。内置自适应模型会自动设置这一点。默认值：false。
allowEmptySignature是否将空思考签名重放为 signature: ""，而不是将思考转换为文本。默认值：false。

OpenAI 兼容性

对于部分兼容 OpenAI 的提供商，请使用 compat 字段。

  • 提供商级 compat 会将默认值应用到该提供商下的所有模型。
  • 模型级 compat 会覆盖该模型的提供商级值。
{
  "providers": {
    "local-llm": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "compat": {
        "supportsUsageInStreaming": false,
        "maxTokensField": "max_tokens"
      },
      "models": [...]
    }
  }
}
字段描述
supportsStore提供商支持 store 字段
supportsDeveloperRole使用 developer 还是 system 角色
supportsReasoningEffort支持 reasoning_effort 参数
supportsUsageInStreaming支持 stream_options: { include_usage: true }（默认值：true）
maxTokensField使用 max_completion_tokens 或 max_tokens
requiresToolResultName在工具结果消息上包含 name
requiresAssistantAfterToolResult在工具结果之后的用户消息之前插入一条 assistant 消息
requiresThinkingAsText将思考块转换为纯文本
requiresReasoningContentOnAssistantMessages推理启用时，在所有重放的 assistant 消息上包含空的 reasoning_content
thinkingFormat使用 reasoning_effort、openrouter、deepseek、together、zai、qwen、chat-template 或 qwen-chat-template 思考参数
chatTemplateKwargs用于 thinkingFormat: "chat-template" 的 chat_template_kwargs 值；使用 { "$var": "thinking.enabled" } 或 { "$var": "thinking.effort" } 作为由 Pi 控制的思考值
cacheControlFormat在系统提示词、最后一个工具定义以及最后一个用户/assistant 文本内容上使用 Anthropic 风格的 cache_control 标记。目前仅支持 anthropic。
supportsStrictMode在工具定义中包含 strict 字段
supportsLongCacheRetention提供商是否在缓存保留为 long 时接受长缓存保留：OpenAI 提示缓存使用 prompt_cache_retention: "24h"，或当 cacheControlFormat 为 anthropic 时使用 cache_control.ttl: "1h"。默认值：true。
openRouterRoutingOpenRouter 提供商路由偏好。此对象会原样发送到 OpenRouter API 请求 的 provider 字段中。
vercelGatewayRoutingVercel AI Gateway 用于提供商选择的路由配置（only、order）

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，例如 DeepSeek V3.x 模板的 chatTemplateKwargs: { "thinking": { "$var": "thinking.enabled" } }。

cacheControlFormat: "anthropic" 适用于通过文本内容和工具定义上的 cache_control 标记公开 Anthropic 风格提示缓存的 OpenAI 兼容提供商。

示例：

{
  "providers": {
    "openrouter": {
      "baseUrl": "https://openrouter.ai/api/v1",
      "apiKey": "$OPENROUTER_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "openrouter/anthropic/claude-3.5-sonnet",
          "name": "OpenRouter Claude 3.5 Sonnet",
          "compat": {
            "openRouterRouting": {
              "allow_fallbacks": true,
              "require_parameters": false,
              "data_collection": "deny",
              "zdr": true,
              "enforce_distillable_text": false,
              "order": ["anthropic", "amazon-bedrock", "google-vertex"],
              "only": ["anthropic", "amazon-bedrock"],
              "ignore": ["gmicloud", "friendli"],
              "quantizations": ["fp16", "bf16"],
              "sort": {
                "by": "price",
                "partition": "model"
              },
              "max_price": {
                "prompt": 10,
                "completion": 20
              },
              "preferred_min_throughput": {
                "p50": 100,
                "p90": 50
              },
              "preferred_max_latency": {
                "p50": 1,
                "p90": 3,
                "p99": 5
              }
            }
          }
        }
      ]
    }
  }
}

Vercel AI Gateway 示例：

{
  "providers": {
    "vercel-ai-gateway": {
      "baseUrl": "https://ai-gateway.vercel.sh/v1",
      "apiKey": "$AI_GATEWAY_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "moonshotai/kimi-k2.5",
          "name": "Kimi K2.5 (Fireworks via Vercel)",
          "reasoning": true,
          "input": ["text", "image"],
          "cost": { "input": 0.6, "output": 3, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 262144,
          "maxTokens": 262144,
          "compat": {
            "vercelGatewayRouting": {
              "only": ["fireworks", "novita"],
              "order": ["fireworks", "novita"]
            }
          }
        }
      ]
    }
  }
}
最近更新：:
Contributors: seepine