模型与思考级别
智能体跑在哪个模型上、它思考得多用力、凭据如何解析,以及为什么一个模型选择可以解释一个你归因于自己代码的行为。
有东西不对劲。智能体没有在用你的工具。它在无视一条指令。它做到一半停下。在 去你的扩展里翻找之前,先检查正在运行的是哪个模型、它的思考级别设成了什么。
这不是一个关于"都怪模型"的笑话。它是对这个系统如何分层的一种描述:模型选择 与思考级别坐在本书每一个机制的下面,而它们改变行为的方式,看起来跟上一层里 的 bug 一模一样。
模型、provider 与凭据
三个词,文档始终把它们分清楚,而人们习惯把它们混为一谈。
一个模型生成 Pi 的响应。一个 provider 是 Pi 用来触达那个模型的服务 或账户。一条凭据是使连接成为可能的东西——一个订阅、一个 API 密钥,或某种 环境自带的凭据。
由此产生的是一个具体而又非常常见的失败。你的自定义模型配置好了、条目解析通过
了、文件也重载了,而 /model 里什么也没出现。原因通常是身份验证:选择器显示
的正是其 provider 拥有可用身份验证的那些模型。一个模型可以从 models.json
加载,却在 Pi 能为它解析出凭据之前仍然不可用。
进行身份验证
运行 /login,选择一个 provider,按提示操作。凭据存放在智能体目录的
auth.json 里。/logout 会为某一个 provider 移除它们。
或者通过该 provider 的环境变量提供一个 API 密钥。这是 CI 中的正确选择,也是 任何 Pi 不应把凭据写到磁盘的地方的正确选择。
当配置了多个来源时,Pi 按这个顺序解析它们:
flowchart TD
A["1 一个运行时 --api-key"] --> B["2 一条已存储的 auth.json 凭据"]
B --> C["3 一个来自 models.json 的 apiKey"]
C --> D["4 provider 环境变量,<br/>或云环境自带的凭据"]
provider 扩展可以定义它们自己的行为。
第一个产出一条凭据的来源胜出,其余的根本不会被查询。这条单一规则解释了一整类
令人困惑的症状。你在运行时传入的一个密钥,胜过一个过期的 auth.json,而后者
又胜过一个你写进 models.json 的 apiKey,而后者又胜过你刚刚导出的那个环境
变量。而如果你改了环境变量、智能体还是无法通过身份验证,检查一下那个变量是否
真的存在于启动 Pi 的那个进程里——这是"在我的 shell 里能用,在 Pi 里不能用"的
常见原因。
注意这个顺序,因为它与直觉相反,而这也是上面那张图所说的。models.json 里的
一条凭据位于已存储的身份验证之下,而不是之上:它是给一个自定义或自托管模型
提供密钥的方式,不是覆盖一个你已经登录所用的密钥的方式。
错误:“我的密钥在环境里,所以 Pi 一定在用。”
正确:“我的密钥在环境里,所以 Pi 在用,除非链条里更高的 来源先解析成功了。”
有一则警告该放在这里。auth.json 和任何凭据命令都是私有的,而一旦你信任一个
项目,项目设置与扩展就会在 Pi 进程内执行。第 8 章讲信任;第 42 章讲它的代价。
选择模型
/model
会打开一个带有可用身份验证的可用模型选择器。在某个模型上按 Ctrl+S 会把它保
存为新会话的默认模型。
Ctrl+P 在可用模型之间循环。/scoped-models 控制那个循环并保存选择,而你还
可以通过设置配置模型模式。
两个值得记住的行为:
**一个会话会记录它的模型变更。**恢复会话会还原它当时在用的模型和思考级别,而 不会更改你对新会话的默认设置。所以"它现在的行为不一样了"可能意味着会话在两 小时前切换了模型,而且再没切回来。
**目录不是静态的。**Pi 从一个随附的目录开始,并可以用来自 pi.dev 的更新数据覆
盖它;缓存的数据在离线时仍然可用。用 pi update --models 强制刷新。
思考级别
/thinking
为当前模型选择思考级别,而 Pi 把选项限制在该模型支持的级别上。Ctrl+S 保存启
动级别。
设置值的完整集合是 "off"、"minimal"、"low"、"medium"、"high"、
"xhigh"、"max"。启动默认值是 "medium"。
minimal、low、medium 和 high 的 token 预算来自 thinkingBudgets。
modelThinkingLevels 按精确的 provider/modelId 设置每个模型的启动级别。
{
"defaultThinkingLevel": "medium",
"modelThinkingLevels": {
"anthropic/claude-sonnet-5": "high"
},
"thinkingBudgets": {
"high": 32000
}
}
思考块会出现在转录记录里。hideThinkingBlock 会隐藏它们。这是一个显示设置,
而它对扩展作者很重要:你在终端里看到的,不一定就是被存下来的。
**这正是智能体行为变得更难调试、而不是更容易的地方。**就如何着手一个任务
而言,一个 off 的模型和一个 high 的模型是两个不同的系统。如果你扩展的工
具被以一种你没预期到的方式调用,先确认思考级别,再去改工具。
按思考级别的采样参数(1.0.2)
自 1.0.2 起,在兼容 OpenAI 的 API 上,一个模型条目可以携带 samplingParams
作为自由形式的默认值,并携带 samplingParamsByThinkingLevel 作为按级别的覆盖
值。
{
"id": "qwen-thinking-model",
"reasoning": true,
"samplingParams": { "temperature": 1.0, "top_p": 0.95 },
"samplingParamsByThinkingLevel": {
"off": { "temperature": 0.7, "top_p": 0.8 },
"high": { "top_k": 20 }
}
}
有三个细节值得说出来,因为它们是你不这样做就会弄错的那几个。那些键是 Pi 自己
的思考级别名——off、minimal、low、medium、high、xhigh、max——
而不是 provider 自己的 thinkingLevelMap 值。合并顺序是:先把不支持的级别截
断,然后应用模型的 samplingParams,再应用有效级别的覆盖值,再应用任何请求级
的 samplingParams,后出现的值按键取胜。而一个你没有列出的级别只是继承模型默
认值,而不是失败。
该字段仅限于 openai-completions、openai-responses 以及
azure-openai-responses;其他 API 会无声地忽略它,而这正是那种在你断定某个
旋钮没用之前值得知道的事。
有一个合理的论点:思考级别与采样温度是同一个决定被做了两遍。如果你要用这个,
就要刻意地用它:high 推理下的低温和 off 下的高温是一种策略,不是意外。第
42 章论证:应用特有的策略应该住在应用旁边,而不是住在一个 provider 形状的
字段里,而这就是一个很好的例子,说明为什么那条区分值得保留——旋钮在模型配置
里,但那些数字背后的推理是你的。
工具、启动与默认值
有三个设置决定什么从哪里开始:
| 设置 | 它做什么 |
|---|---|
defaultProvider |
启动时的 provider;默认自动 |
defaultModel |
启动时的模型 ID;默认自动 |
enabledModels |
用于启动选择与循环的模型模式 |
enabledModels 默认为所有可用模型,并使用与 --models 标志相同的格式。
提示词缓存,以及它为什么出现在这里
缓存是模型层的关注点,而它在智能体行为里出现的频率比你预期的更高。
promptCache 为 short 或 long 保留档声明该 provider 尽力而为的缓存寿命,
以秒为单位:
{ "id": "claude-sonnet-5", "promptCache": { "short": 300, "long": 3600 } }
在任何已公布范围的保守那一端取值。一个没有为当前档声明寿命的模型,没有资格参 与缓存预热。
cacheWarming 是 "off"、"streaming" 或 "idle",默认 "streaming"。预热
只在模型声明了缓存寿命、且 Pi 估计至少可避免 $0.05 的缓存未命中开销时运行。刷
新的用量计入会话总计,但不进入模型上下文——这是当你的上下文核算与你的账单
不一致时值得记住的一个细节。
showCacheMissNotices 会显示显著的缓存未命中、成功的预热、压缩用量和 provider
恢复。如果你看到无法解释的延迟或无法解释的 token 计数,在做任何插桩之前先把它
打开。
不是聊天模型的模型
有两个类别不出现在 /model 里,而知道它们存在可以避免一整类困惑。
分类器模型不聊天。它们回答关于 JSON 状态的带类型问题:在若干选项中选
一个、回答是或否、或产出一个分数,各自附带概率。截至 1.0.1,那个列表包括
了 Cloudflare 的 Clef 和来自 Workers AI 的 Clef Flash,以及 TypeSafe Jev 模
型;新条目是 cloudflare-workers-ai provider 下的 @cf/cloudflare/clef 和
@cf/cloudflare/clef-flash,它们可以从 codemode 脚本和从扩展中使用。分类与
聊天这两者的区分并没有随它们而改变,而这正是要点:一个新的分类器出现在目录的
一行里,却从不出现在 /model 里,而没有把这一点内化进去的读者会花时间去找
它。
图像模型从一条提示词和可选的输入图像生成图像。
两者都不出现在 /model 选择器里。两者都通过 codemode 工具触达,而一个内置
扩展以未激活状态注册它。你自己这样启用它:
{ "defaultTools": ["+codemode"] }
扩展则绕过 codemode 直接触达它们,通过 ctx.modelRegistry.classify() 与
ctx.modelRegistry.generateImages()。
如果你一直在 /model 里找图像模型而它不在那里,这就是原因,而它不是一个
bug。
你能对话的端点
当 Pi 还不支持你需要的 provider 或端点时,有三级台阶,按付出努力递增排列:
-
**一个兼容的端点。**如果该端点说的是一种 Pi 已支持的 API——大多数 Ollama、LM Studio、vLLM、SGLang 和代理部署——把它加到智能体目录的
models.json里。{ "providers": { "ollama": { "baseUrl": "http://localhost:11434/v1", "api": "openai-completions", "apiKey": "ollama", "models": [ { "id": "qwen2.5-coder:7b" } ] } } }那个假密钥使模型可用;Ollama 会忽略它。对一个需要身份验证的端点,
apiKey和头部值接受$NAME或${NAME}环境变量插值、一个字面量,或 者一个以!开头的命令。命令在请求时运行,并且不会被 Pi 缓存。打开
/model会重新加载该文件。 -
一个自定义 provider 扩展,当该 provider 需要自定义流式传输、模型发现或 身份验证行为时。
-
一个虚拟模型,它用你自己的名字注册,并把每一个请求路由到你决定的任何 东西——包括一个分类器。第 42 章会回到这里,因为"把它路由到别处"和"它可以那 样做"是不同的决定。
文档里有一则警告值得重述,因为它是一个常见而又代价高昂的错误:在你的兼容性设 置里,只描述已验证的差异——即某个端点在请求或响应行为上的差异。不要因为一 个端点宣称兼容 OpenAI 或 Anthropic 就启用它们。
这一章是干什么的
实用的内容是那些表格和优先级顺序。这个想法更小,也更有用:
模型选择 影响什么是有可能做到的
思考级别 影响它如何着手这个任务
凭据 决定究竟有没有事会发生
缓存行为 影响延迟与报告的用量
这些没有一个是你的扩展。它们全都能产生一个症状,否则你会在错误的层里调试一 小时。当某样东西的表现不可能时,先查本章的清单,再查你的代码。
跑了什么
examples/ch03-credentials/ 通过 Pi 真实的 ModelRuntime、在真实的
auth.json 和 models.json 文件之上运行凭据解析:
- 当没有配置别的东西时使用环境变量,而在什么都没有的情况下,没有任何凭据;
- 一条已存储的
auth.json凭据胜过环境变量,models.json里的 一个apiKey也是如此; - **顺序正是上面给出的那个。**四个来源都在时,运行时密钥胜出。移除它,
auth.json胜出。再移除,models.json胜出。再移除,使用了环境变量。第一个 产出一条凭据的来源胜出,其余的不被查询; - 一个模型可以从
models.json加载却仍然不可用:条目解析了、模型也存在, 但在该 provider 有了身份验证之前,它不在可用列表里,而一个假密钥就足以让它 出现。
一个测试还检查了"provider 配置不是智能体行为"这个论断。同一个扩展(强制推送
守卫)和同一个脚本,以三种写法运行 provider 的密钥:一个字面量、$PI_TEST_KEY
和 !echo from-a-command。三者解析出三条不同的凭据,而智能体在它们之下的行
为完全一样:同样的角色、同样的两个工具结果、同样的请求次数,守卫在每种情况下
都拦住了那次强制推送。改变凭据从哪来,丝毫没改变智能体做了什么。
下一章
现在你知道这个循环跑在什么之上了。它带着什么跑是下一个约束,而它是有限 的:每个请求都在争夺一个固定的窗口,而你的指令是若干行项目中的一行,而不是整 个容器。知道这一点,会把"智能体变差了"变成你能读懂的计算。
第 4 章:作为预算的上下文窗口。