pi CLI自定义AI模型配置详解

通过 ~/.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。

提供商配置

对于包含 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": [...]
    }
  }
}

模型配置

成本层级提供一套完整的备选费率，当总输入使用量（input + cacheRead + cacheWrite）超过 inputTokensAbove 时，适用于整个请求。当多个层级匹配时，阈值最高的获胜。

{
  "cost": {
    "input": 5,
    "output": 30,
    "cacheRead": 0.5,
    "cacheWrite": 6.25,
    "tiers": [
      {
        "inputTokensAbove": 272000,
        "input": 10,
        "output": 45,
        "cacheRead": 1,
        "cacheWrite": 12.5
      }
    ]
  }
}

当前行为：

• /model、--list-models 和交互式底部栏按模型 id 显示条目。
• 配置的 name 用于模型匹配和辅助模型详细信息文本。它不会替换底部栏/状态栏的模型 id。

思考级别映射

在模型上使用 thinkingLevelMap 来描述模型特定的思考控制。键是 pi 思考级别：off、minimal、low、medium、high、xhigh、max。映射可能包含空缺；例如，一个模型可以公开 high 和 max 而不公开 xhigh。

支持 off、high 和 max 思考的模型示例：

{
  "id": "deepseek-v4-pro",
  "reasoning": true,
  "thinkingLevelMap": {
    "minimal": null,
    "low": null,
    "medium": null,
    "high": "high",
    "xhigh": null,
    "max": "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、thinkingLevelMap、input、cost（部分）、contextWindow、maxTokens、headers、compat。

Direct OpenAI 的 GPT-5.6 Sol、Terra 和 Luna 默认使用 272000 上下文窗口，以使请求保持在 OpenAI 的短上下文定价层级内。要选择使用 OpenAI 的 1.05M 上下文窗口，请为你使用的每个模型增加该值：

{
  "providers": {
    "openai": {
      "modelOverrides": {
        "gpt-5.6-sol": {
          "contextWindow": 1050000
        }
      }
    }
  }
}

该覆盖保留预置的定价元数据。总输入 token 超过 272K 的请求将对整个请求使用 GPT-5.6 的长上下文费率。在需要时，对 gpt-5.6-terra 或 gpt-5.6-luna 应用相同的覆盖。

行为说明：

• 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 会拒绝空的思考签名。

预置的 Anthropic 模型在其模型元数据中启用了 supportsStrictTools。自定义的兼容 Anthropic 模型在其端点接受严格的 JSON schema 工具定义时必须将其设置为 true。

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

OpenAI 兼容性

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

• 提供商级别的 compat 适用于该提供商下的所有模型。
• 模型级别的 compat 覆盖该模型的提供商级别值。

{
  "providers": {
    "local-llm": {
      "baseUrl": "http://localhost:8080/v1",
      "api": "openai-completions",
      "compat": {
        "supportsUsageInStreaming": false,
        "maxTokensField": "max_tokens"
      },
      "models": [...]
    }
  }
}

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

• 原文链接： github.com/badlogic/pi-m...
• 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～