模型与凭据 —— 六种来源,一张 models.json
F01 收尾时留下的问题:pi --list-models 能列出四个模型,可你一按回车就报错。
Pi 认得这个模型,但拿不到 key。这两件事是分开的——模型目录管「有什么」,
凭据管「能不能用」。
三个问题:
- 同一把 key 可以放在四个地方,Pi 按什么顺序找?
- 本地跑 Ollama,为什么
apiKey要填个"ollama"这样的假值? - 内置模型的
contextWindow写错了,除了换掉整个 provider,还有别的办法吗?
模型从哪来 凭据从哪来 ───────────── ───────────── 内置目录(随包发行) --api-key(本次进程) pi.dev 远程目录(可离线缓存) ──> auth.json(/login 写) models.json 的 models[] ────────> models.json 的 apiKey 扩展 registerProvider() 环境变量 models.json 的 modelOverrides ← 只改元数据,不增模型<sub>图里那条 modelOverrides 的箭头故意画在最后:它不产生模型,只改已有模型的字段。</sub>
一、先分清两件事
/model 那个选择器只显示凭据可用的模型(models.md:29)。
这就是为什么你在 models.json 里写了一个 provider,/model 里却找不到它
——文件解析成功了,但 key 解析不出来,于是它不进列表。
验证顺序永远是这个:
$env:PI_OFFLINE="1"; pi --list-models能列出来,说明目录里有;然后开一次 /model,看不到,就是凭据的事。
两个问题的排查方向完全相反,先判断在哪个环节卡住,能省掉一半时间。
二、六种凭据来源,谁压谁
provider-composer.ts:112-116 有个类型定义,把答案直接写死在联合类型里:
// provider-composer.ts:112export type AuthStatus = { configured: boolean; source?: "stored" | "runtime" | "environment" | "fallback" | "models_json_key" | "models_json_command"; label?: string;};六个字符串就是全部来源。文档给的顺序(models.md:23)是
--api-key → auth.json → models.json 的 apiKey → provider 的环境变量。
把它和枚举对齐,就是完整的一张表:
| 优先级 | source |
从哪来 | 怎么设 |
|---|---|---|---|
| 1 | runtime |
运行时覆盖 | --api-key,或 SDK 的 setRuntimeApiKey |
| 2 | stored |
auth.json |
/login |
| 3 | models_json_key |
models.json 里的字面量 |
直接写字符串 |
| 4 | models_json_command |
models.json 里的 !命令 |
让命令吐出来 |
| 5 | environment |
进程环境变量 | $env:OPENAI_API_KEY="..." |
| 6 | fallback |
云厂商的隐式凭据 | 不改,交给 SDK 自己找 |
前两名的实现很直白。runtime-credentials.ts 是一个装饰器:
它包住真正的 CredentialStore,read() 先查自己的 overrides Map,
查不到才往下转(:27-31)。整个 read 方法的核心就一行三元:
override ? { type: "api_key", key: override } : this.store.read(...)。
有 override 就用自己的,没有就原封不动地交给真正的 store。
这一个 ?: 就定了第一名。这也解释了 CI 里最省事的做法:别碰 auth.json,
用 pi --api-key "$env:MY_KEY" -p "...",进程退出后什么都不留。
三、models.json:一个文件装三种东西
这个文件的顶层只有一个键:providers(model-config.ts:118-125)。
它同时承担三件不同的事,混在一起是理解它的最大障碍:
| 你写的东西 | 作用 | 会不会新增模型 |
|---|---|---|
providers.<新 id> |
定义一个全新的 provider | 会,models[] 里每个 id 一个 |
providers.<已有 id>.baseUrl |
把内置 provider 指向代理 | 不会,只是换地址 |
providers.<已有 id>.modelOverrides |
改内置模型的一个字段 | 不会,只改元数据 |
第二种最省事,models.md:69-77 给的就是它——只写 baseUrl,
模型列表和认证方式原封不动:
{ "providers": { "anthropic": { "baseUrl": "https://proxy.example.com/v1" } }}provider-composer.ts:311-323 有个守卫:一个 provider 条目里
baseUrl / headers / compat / modelOverrides / models 一个都没有,
就报 must specify "baseUrl", "headers", "compat", "modelOverrides", or "models"。
换句话说,空 provider 条目是错的,别拿它当占位。
3.1 本地模型:为什么 key 要填假值
接 Ollama、LM Studio、vLLM 这类服务,官方示例(models.md:49-63)里 apiKey 写的是 "ollama":
{ "$schema": "https://pi.dev/schemas/models.schema.json", "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "models": [ { "id": "qwen2.5-coder:7b" } ] } }}因为 Pi 的判断是「有 key 才算可用」,不是「服务要不要 key」。
填个字面量,模型立刻进 /model;Ollama 自己不校验这个头,所以无所谓。
api 字段只能是 Pi 已经支持的协议之一,model-config.ts:101-107 的
描述里列了四个:openai-completions、openai-responses、
anthropic-messages、google-generative-ai。协议对不上,
用 baseUrl 硬接是接不上的——那种情况要写 provider 扩展(F05 有骨架)。
3.2 默认值:不写也能跑,但要知道默认是什么
model-config.ts:60-65 给两个最关键的字段定了默认值:
| 字段 | 默认 | 写错的后果 |
|---|---|---|
contextWindow |
128000 |
低估 → 提前压缩,浪费上下文;高估 → 直接 400 |
maxTokens |
16384 |
低估 → 长回答被截断;高估 → 400 或空回复 |
本地小模型的窗口常常只有 8K、32K,这两个数必须手写,不能靠默认值。 反过来,如果你在接一个 200K 窗口的模型却忘了写,Pi 会在 128K 处就开始压缩 ——不报错,只是「怎么老是压缩」。
3.3 三个值得单说的字段
modelOverrides 改的是内置模型。applyModelOverride(provider-composer.ts:179)
逐字段 override.x ?? model.x,所以只写你要改的那个键,其它保持原样。
未知的 override ID 会被静默忽略(models.md:67)——写错了不报错,这是它最坑的地方。
promptCache 声明缓存寿命,单位秒,分 short / long 两档(models.md:106-110)。
没有对应档位的模型不参与缓存预热。文档建议取公开区间的保守端。
samplingParamsByThinkingLevel 让温度随思考等级变(models.md:116-138)。
键是 Pi 自己的七档:off minimal low medium high xhigh max,
不是 provider 那边 thinkingLevelMap 的值。合并顺序是
模型默认 → 该等级覆盖 → 请求级覆盖,逐键后者赢。
只对 openai-* 系协议生效,别的协议直接忽略。
四、值的三种写法:字面量、环境变量、命令
apiKey 和每个 header 的值都走同一个解析器 resolve-config-value.ts。
它的入口只有两个分支(:80-86):
<!-- file: pi-main/pi-main/packages/coding-agent/src/core/resolve-config-value.ts -->
function parseConfigValueReference(config: string): ConfigValueReference { if (config.startsWith("!")) { return { type: "command", config }; } return { type: "template", parts: parseConfigValueTemplate(config) };}以 ! 开头就是命令,其余一律当模板(字面量是「没有 $ 的模板」)。
模板里支持 $NAME 和 ${NAME} 两种写法,还有两个转义:$$ 变成 $,
$! 变成 !(:42-46)。这两个转义不是凑数的——如果你的 key 真以 ! 开头,
不转义就会被当成命令去执行。
三个必须知道的边界:
命令有 10 秒超时。 :157-160 的 spawnSync 写死了 timeout: 10000。
一个卡住的取凭据脚本会让整个请求晚十秒,而不是立刻失败。
没配全时报的是变量名,不是「没 key」。 环境变量缺失时,
resolveConfigValueOrThrow 会 throw 出具体名字(:240-248),
形如 Failed to resolve API key for provider "x" from environment variable: MY_KEY。
看到这条,别去查 key 对不对,先查变量有没有传进进程。
models.json 里走的确实是不缓存的那条路。 provider-composer.ts:472 调的是
resolveConfigValueOrThrow,它内部用 resolveConfigValueUncached(:221-227),
绕开了 resolveConfigValue 那个进程级 Map 缓存(:208-216)。
所以文档说「命令在请求时执行、不被 Pi 缓存」(models.md:65)是对的——
但注意 10 秒超时仍然在。每次请求都跑一次命令,如果你的取凭据脚本要 3 秒,
每个 turn 都多 3 秒。
4.1 一个能跑的最小配置
把真 key 留在环境变量里,文件只存引用:
$env:MY_GATEWAY_KEY = "sk-..."{ "providers": { "my-gateway": { "baseUrl": "https://gw.example.com/v1", "api": "openai-completions", "apiKey": "$MY_GATEWAY_KEY", "headers": { "X-Tenant": "acme" }, "models": [ { "id": "my-large", "name": "My Large", "contextWindow": 200000, "maxTokens": 32000, "reasoning": true } ] } }}headers 的值同样走那套解析,所以 "X-Tenant": "$TENANT_ID" 也能用。
五、这个文件什么时候重读
models.md:67 一句话:Opening /model reloads the file. 只有打开 /model 才重读。
F01 的坑四说的就是这个,这里补上原因。ModelConfig.load()(model-config.ts:169-207)
每次调用都完整地读文件、JSON.parse、跑一遍 TypeBox 校验、再 deepFreeze。
它是个纯粹的「一次加载」对象,没有任何 fs.watch。谁去找它、什么时候重新 load,
是调用方的事,而调用方是 /model。
所以调试顺序是固定的:改文件 → 开 /model → 还没变 → 才是文件写错了。
/reload 不重读它。
顺带一个好消息:这个文件的解析器先 stripBom 再 stripJsonComments(:185),
所以你可以在 models.json 里写注释。settings.json 没有这个待遇,
别把习惯带过去。
六、自己动手验证
三个实验,前两个不需要真的 key。
实验 1:看目录和凭据是两件事。
$env:PI_OFFLINE="1"; pi --list-modelspi auth check --provider funagent第一条能列出 funagent,第二条会告诉你这个 provider 的凭据状态。
注意 pi auth check 必须带 --provider 或 --model,
不带参数它只会回你一句 Auth checks require --provider <provider> or --model <model>。
实验 2:故意写坏一个字段,看报错长什么样。
把 models.json 里某个 provider 的 models 数组改成 "models": {}(对象),
保存,然后开 /model。Pi 不会崩,它把整份配置当无效。
校验失败那段(:193-200)做三件事:跑 TypeBox 校验、把每条错误格式化成
路径: 消息、带着文件名拼进一条 error 字符串。最后一行构造对象时
第一个参数就是 new Map()(这里把长参数折了行,便于阅读):
// model-config.ts:199-200(折行示意)return new ModelConfig( new Map(), `Invalid models.json schema:${errors}`,);空 Map = 整个文件的所有 provider 一起丢弃,
不是只丢坏的那一个。一个字段写错,四个模型全没了。
报错文本里带具体路径和文件名(:198),照它改就行。
实验 3:$ 转义的边界。
在 apiKey 里写 "pre$MY_KEY",然后不设 MY_KEY 直接 /model。
期望是报错里出现 MY_KEY 这个名字,而不是「没 key」。
再写 "pre$$MY_KEY"(存 $ 的字面量),这次不该报错,key 就是字面量 pre$MY_KEY。
改一处试试
给已有的 provider 加一个 modelOverrides,只改窗口大小:
{ "providers": { "svw": { "modelOverrides": { "doubao": { "contextWindow": 128000 } } } }}注意 svw 这条现在有了 modelOverrides,就满足了
provider-composer.ts:311-323 那个「至少写一个字段」的守卫,
不会触发 must specify 报错。开 /model 之后,doubao 的窗口变成 128K,
但它的 baseUrl、key、模型列表一样没动。改回来就是删掉这个键。
七、工程暗坑
坑一:modelOverrides 写错 ID 不报错。
models.md:67 明说 unknown override IDs are ignored。改完没效果,
先确认 ID 拼写和 /model 里显示的那个完全一致。
坑二:一个字段不合法,整个文件作废。 实验 2 已说明。大文件改的时候,最好先备份再动,否则四个模型一起消失。
坑三:!命令 每次请求都跑,且带 10 秒超时。
不是启动时跑一次。取凭据脚本尽量快,或者干脆用环境变量。
坑四:环境变量只在启动 Pi 的那个进程里有效。
models.md:215-217 专门写了这条。换一个终端窗口「key 就没了」,
不是 Pi 的问题。
坑五:maxTokens 的默认值会掩盖真实上限。
16384 对大多数模型都「够用」,所以你不会察觉自己压低了输出上限。
接新模型时把 contextWindow 和 maxTokens 都显式写上。
八、本章源码索引
| 文件 | 行数 | 本章用到的位置 |
|---|---|---|
packages/coding-agent/src/core/model-config.ts |
221 | models.json 的完整 schema 与加载 |
packages/coding-agent/src/core/provider-composer.ts |
738 | 凭据六来源、applyModelOverride、空 provider 守卫 |
packages/coding-agent/src/core/resolve-config-value.ts |
288 | $NAME / !command / $$ 转义、10 秒超时 |
packages/coding-agent/src/core/runtime-credentials.ts |
53 | 运行时 key 盖过持久化 store |
packages/coding-agent/src/core/auth-storage.ts |
508 | auth.json 的读写与加锁 |
packages/coding-agent/docs/models.md |
225 | 官方的连接方式选择表 |
packages/coding-agent/docs/models-configuration.md |
— | 逐字段的完整参考 |
九、下一章
模型能用了,下一个问题是「它能动手做多少事」。
F03 拆工具开关:八个内置工具、codemode 和 tool_search 两个模组、
--tools 三种写法,以及扩展才能碰到的 exposure 五档。