阶段三 · 集成与实践
Provider 与模型 —— 接一家是配置,接十家是架构
Agent 要同时面对多家模型服务:认证方式不同、接口格式不同、模型清单不同。Pi 的做法是把三件事拆开——有哪些模型、怎么发请求、凭什么授权——让它们各自独立演进。这一章讲清这个拆分,以及"模型名不能用来推断能力和价格"这条实践结论。
具体回答三个问题:接十家服务商,怎么才不用改十遍代码?模型清单为什么要和认证分开?为什么选不到某个模型?
学习目标
- 理解三件事为什么要分开:模型清单、请求协议、认证。
- 看懂模型配置文件的形状:为什么它是"以服务商为键的映射",而不是列表。
- 分清两种自定义服务商的形态:完整实现,还是只覆盖几个字段。
- 知道认证的来源不止一处,以及它们的优先级。
一、问题:接一家是配置,接十家是架构
只用一个模型,写死调用代码就够了。但 Agent 要面对:订阅制的闭源服务、按 key 计费的 API、本机跑的模型、公司内网的网关。每家的认证方式、请求格式、模型清单都不一样。
如果每接一家就改一遍调用代码,代码很快会腐化。服务商层的存在,就是把这堆差异收敛成一个统一入口。
二、三件事必须分开
| 维度 | 回答什么 | 例子 |
|---|---|---|
| 模型清单 | 有哪些模型、多大窗口、支不支持思考、多少钱 | 元数据 |
| 请求协议 | 怎么把对话发出去、怎么收流式回复 | 协议实现 |
| 认证 | 凭什么允许你调用 | 订阅登录、API key、环境变量、云环境凭据 |
分开之后得到三个好处:
- 选模型时只看清单,但会按认证过滤:选择器只列出"这家服务商当前有可用凭据"的模型。所以"模型明明在清单里却选不到",通常是没有凭据,而不是模型不存在。
- 调用走统一入口:不管背后是哪家,都是"给我一个模型、一份上下文、一组选项,把流式回复吐出来"。
- 认证独立解析:同一个模型可以用订阅登录取用,也可以用 API key 用,互不影响。
实践结论只有一句:模型名不能用来推断权限或价格。同一个名字在不同服务商下,窗口、价格、能力可能完全不同;反过来,显示名相近的两个模型,能力也可能差很远。
内容这一点在新版本里还多了个变化:自定义服务商的流式函数拿到的上下文,系统提示词和工具声明不再放在字段里,而是存在对话记录的系统消息中,要用对应的读取函数取。这么改是为了让"提示词中途变了"也能被记录和回放。
三、模型清单是一个文件
用户自定义的模型写在用户目录下的 models.json 里。注意它是一个文件,不是目录;里面 providers 是一个以服务商标识为键的对象,不是数组:
{
"providers": {
"ollama": {
"baseUrl": "http://localhost:11434/v1",
"api": "openai-completions",
"apiKey": "ollama",
"models": [
{ "id": "llama3.1:8b", "name": "Llama 3.1 8B", "contextWindow": 128000 }
]
}
}
}
三个要点:
- 映射而不是列表:以标识为键,天然去重,也方便局部覆盖。
- 协议可以分层指定:服务商层给默认值,单个模型可以覆盖。
apiKey可以是占位符:本地服务忽略 key,但 Pi 仍按"需要认证"对待,所以要么放占位符并登录一次,要么显式传 key。
文件在打开模型选择器时会重新加载,不用重启。
四、两种自定义形态
| 形态 | 适合什么 | 代价 |
|---|---|---|
| 完整实现一个服务商 | 自定义认证、动态发现模型、特殊请求格式 | 要写代码,跟着版本维护 |
| 只提供服务商名 + 几个字段 | 改地址、加请求头、加几个模型 | 简单,但能力受限于内置实现 |
第二种的字段远比名字暗示的多:地址、请求头、认证头、key、协议、模型列表、OAuth、模型刷新、图像与分类模型都在其中。给已有服务商只改地址或加一个头时,它内置的模型清单和认证方式会被保留——这是它比"完整实现"省事的地方。
五、认证有四个来源
很多人以为认证只有"登录"和"环境变量"两条路。实际优先级是四层:
- 命令行临时传入的 key;
- 登录后存下来的凭据;
- 模型配置文件里写的 key;
- 环境变量,或云环境自带的身份(比如实例角色)。
前面的优先。这一层分离得比较彻底:描述"有哪些模型"的那部分数据里不含凭据,凭据是运行时另外解析的。所以"配置文件泄露 = 密钥泄露"这件事,在好的设计里不该成立。
六、虚拟模型:一个名字,多个真身
新版本还支持一种"虚拟模型":你注册一个名字,每次请求时现场决定用哪个真实模型、什么思考强度。
典型用途:
- 按任务类型路由(写代码用强模型,改文案用便宜的);
- 主备切换(首选不可用就换一个);
- 灰度(一部分请求走新模型)。
路由状态跟着会话分支保存,所以回退到历史点时,路由选择也能还原。界面上会显示当前路由到了哪个真实模型,计费按真实模型算。
当前 Pi 行为
- 内置模型清单随包发布,并可以叠加官方站点的较新数据;离线时用缓存,也可以手动强制刷新。
- 订阅制服务通过登录接入;API key 类可以登录,也可以走环境变量;本机模型接本地运行时;兼容接口写配置文件;自定义协议写服务商扩展。
- 认证优先级:命令行 → 登录凭据 → 配置文件 → 环境变量/云环境身份。
- 模型选择器按可用凭据过滤;未配置凭据的模型会加载但不出现。
- 没有可用模型时,一次性模式直接报错退出,交互模式在提交第一句话时才报错。
- 新版本把几个配置文件的字段参考做成了由 schema 生成的文档,改配置前建议直接查它。
- 历史上 Azure 的服务商标识改过名(接口标识没变),旧配置需要跟着改。
代码里的名字
| 通俗说法 | 代码里的名字 |
|---|---|
| 注册服务商 | registerProvider(两个重载) |
| 构造完整实现 | createProvider |
| 协议实现 | openAICompletionsApi() 等 |
| 兼容入口 | @earendil-works/pi-ai/compat 的 streamSimple |
| 上下文读取 | getCurrentSystemPrompt() / getCurrentTools() |
| 虚拟模型 | registerVirtualModel |
| 字段参考 | models-configuration.md |
源码位置
packages/ai/src/:模型元数据、各协议实现、兼容层。packages/coding-agent/src/core/model-runtime.ts:模型清单加载与运行时解析。packages/coding-agent/docs/models.md、models-configuration.md、providers.md:三份一手参考。
失败与边界实验
服务商层的失败,几乎都出在"三件事被混在一起"的时候:
- 认证缺失被当成模型不存在。 早期的表现是:没有 key 的模型从列表里消失,用户以为不支持。现在的表现是:模型加载了,但选择器里不出现,配上凭据就出现。区别在于状态可解释——"加载了但没凭据"比"不存在"好诊断得多。
- 协议差异写进业务代码。 在循环里写"如果是某家服务商就怎样",会让每接一家都改循环。修法是把差异收敛在协议实现里,循环只面向统一的消息类型。
- 思考签名不匹配。 有些服务的思考块带签名,重放或转发时可能失配。Pi 的做法是按轮次保留思考强度并安全恢复,而不是把整块思考丢掉——降级,而不是失败。
python3 -m learn_pi_lab lab providers
python3 -m unittest tests.test_08_provider_registry -v
在 Pi 里怎么操作
- 登录 / 登出:管理存下来的凭据。
- 选模型:打开选择器搜索,可以把某个模型设为新会话的默认。
- 调思考强度:只列出当前模型支持的那几档。
- 自定义模型写进配置文件;临时用 key 可以走环境变量或命令行。
Python 实验
provider_registry.py 只有八十行,演示"换模型不换代码":注册表只保存元数据(标识、显示名、窗口),执行经由统一的接口注入。
registry = ProviderRegistry()
registry.register("openai-completions", "demo-1", "Demo Model", 128_000)
selection = registry.select("openai-completions", "demo-1")
# catalog() 按 (服务商, 模型) 排序返回不可变清单
三件事做得比较讲究:
- 标识校验:服务商和模型标识用正则约束,防止拿不可靠的字符串当键。
- 重复检测:同一个"服务商 + 模型"注册两次直接报错,而不是悄悄覆盖。
- 稳定排序:清单按标识排序,输出可复现——测试才能断言它。
为什么这些都值得写?因为它们和 Pi 的模型清单职责同构:注册表不是"存一堆字符串",而是"提供一份可校验、可复现、可查询的目录"。如果目录本身不稳定,后面所有关于"选哪个模型"的推理都不成立。
Tau 的 tau_coding/provider_catalog.py 是内置目录:导入期加载,回答同一个问题——运行时从哪儿知道有哪些服务商。
python3 -m learn_pi_lab lab providers
这一模块的核心代码在核心代码导览 · Provider 注册表有逐段解读。
验证方式
python3 -m unittest tests.test_08_provider_registry -v
边界与安全
- 凭据不应该出现在示例、日志、版本库里;每个服务商使用最小范围的凭据。
- 显示名、窗口大小、协议类型不能互相推断;本地模型的 key 是占位符,不代表真实认证。
- 服务商扩展在 Pi 进程内运行,能看到凭据与请求内容——按"可信代码"对待。
自测三问
- 模型明明在配置里,选择器里却看不到,最可能是什么原因?
- 为什么"模型名"不能用来判断窗口大小和价格?
- 四层认证来源的优先级顺序是什么?配置文件里的 key 排第几?
回顾
- 三件事分开:清单、协议、认证各自独立;模型名推不出能力和价格。
- 清单是文件不是目录:
providers是映射;协议可以按模型覆盖;key 可以是占位符。 - 两种自定义形态:完整实现 vs 只覆盖字段。
- 认证四层:命令行 → 登录凭据 → 配置文件 → 环境变量/云身份。
模型调用会失败——网络抖动、限流、配额耗尽。下一章可靠性讲失败如何重试与隔离。