Pi Agent 源码级教程
F02

模型与凭据 —— 六种来源,一张 models.json

2,294 字 · 含 76 行代码 · 约 15 分钟

F01 收尾时留下的问题:pi --list-models 能列出四个模型,可你一按回车就报错。 Pi 认得这个模型,但拿不到 key。这两件事是分开的——模型目录管「有什么」, 凭据管「能不能用」。

三个问题:

  1. 同一把 key 可以放在四个地方,Pi 按什么顺序找?
  2. 本地跑 Ollama,为什么 apiKey 要填个 "ollama" 这样的假值?
  3. 内置模型的 contextWindow 写错了,除了换掉整个 provider,还有别的办法吗?
text
  模型从哪来                              凭据从哪来  ─────────────                          ─────────────  内置目录(随包发行)                      --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 解析不出来,于是它不进列表。

验证顺序永远是这个:

powershell
$env:PI_OFFLINE="1"; pi --list-models

能列出来,说明目录里有;然后开一次 /model,看不到,就是凭据的事。 两个问题的排查方向完全相反,先判断在哪个环节卡住,能省掉一半时间。


二、六种凭据来源,谁压谁

provider-composer.ts:112-116 有个类型定义,把答案直接写死在联合类型里:

ts
// 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, 模型列表和认证方式原封不动:

json
{  "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":

json
{  "$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 -->

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 留在环境变量里,文件只存引用:

powershell
$env:MY_GATEWAY_KEY = "sk-..."
json
{  "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:看目录和凭据是两件事。

powershell
$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()(这里把长参数折了行,便于阅读):

ts
// 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,只改窗口大小:

json
{  "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 五档。