pi-custom-model

Pi 自定义／变体模型

适用场景

只有当 Pi 保存的默认模型对应的 provider/id 完全存在于模型注册表中时，Pi 才会加载它。Pi 为每个提供方内置了一份静态列表，因此 OpenRouter 的路由快捷变体（:nitro = 按吞吐量排序，:floor = 最便宜，:exacto = 工具使用质量优先）以及任何全新的 slug 都不在其中。默认模型无法解析时，Pi 会静默回退到内置的各提供方默认模型（对于 openrouter，是 moonshotai/kimi-k2.6），看起来就像 Pi“重置”了你的模型。解决方法 = 将 slug 注册为自定义模型，使 find(provider, id) 能匹配到它。

文件（全局）

• ~/.pi/agent/settings.json — defaultProvider、defaultModel、defaultThinkingLevel
• ~/.pi/agent/models.json — 按提供方索引的自定义模型
• ~/.pi/agent/auth.json — 提供方凭据（确认对应提供方的密钥存在）

步骤

1. 添加前先确认 slug 确实存在（例如，检查 OpenRouter 上是否有对应的模型／变体）。id 拼写错误也会导致静默回退。
2. 确认身份验证信息。 提供方必须在 auth.json 中有密钥（或设置类似 OPENROUTER_API_KEY 的环境变量）。没有身份验证信息 → 模型虽已注册但不可用 → 仍会回退。
3. 在 models.json 的 providers.<provider>.models 下添加模型。对于内置提供方（openrouter、anthropic 等），只需提供元数据 — api、baseUrl 和身份验证信息会继承自内置默认值。示例：

   {
     "providers": {
       "openrouter": {
         "models": [
           {
             "id": "z-ai/glm-5.2:nitro",
             "name": "Z.ai: GLM 5.2 (nitro)",
             "reasoning": true,
             "thinkingLevelMap": { "xhigh": "xhigh" },
             "input": ["text"],
             "cost": { "input": 0.95, "output": 3, "cacheRead": 0.18, "cacheWrite": 0 },
             "contextWindow": 1048576,
             "maxTokens": 32768,
             "compat": { "supportsDeveloperRole": false, "thinkingFormat": "openrouter" }
           }
         ]
       }
     }
   }
   

   从基础模型复制 cost/contextWindow/compat（该变体与基础模型共用这些值）— 在 <pi-pkg>/node_modules/@earendil-works/pi-ai/dist/providers/<provider>.models.js 中找到对应的内置条目。如果实际模型更大，不要硬编码通用的 128k/16k。
4. 在 settings.json 中设置默认模型：defaultProvider + defaultModel = 完全匹配的 id。保留用户现有的 defaultThinkingLevel。
5. 验证： pi --list-models | grep <id> 应能显示该模型，并且 JSON 能正常解析。也可以选择进行冒烟测试：pi --provider <p> --model "<id>" "which model are you?"。

注意事项

• 仅支持完全匹配。 find() 会精确匹配 provider+id — 对于保存的默认模型路径，不会模糊匹配或移除冒号。settings.json 和 models.json 中的 slug 必须逐字节一致。
• 静默回退。 默认模型无法解析时，Pi 不会显示错误，只会在页脚中显示另一个模型。这就是判断依据。
• 不要只编辑 settings.json。 将 defaultModel 设为未注册的 slug 不会生效 — 真正的修复方法是编辑 models.json。
• enabledModels（可选）可固定模型选择器，避免按 Ctrl+P 切换时又选回其他模型："enabledModels": ["<provider>/<id>:<thinking>"]。
• 项目级覆盖。 仓库的 .pi/settings.json 会覆盖全局设置。如果默认模型只在某个项目中还原，请先检查该文件。
• 完全重启 Pi — 注册表会在启动时加载。