阶段三 · 集成与实践

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 }
      ]
    }
  }
}

三个要点:

  1. 映射而不是列表:以标识为键,天然去重,也方便局部覆盖。
  2. 协议可以分层指定:服务商层给默认值,单个模型可以覆盖。
  3. apiKey 可以是占位符:本地服务忽略 key,但 Pi 仍按"需要认证"对待,所以要么放占位符并登录一次,要么显式传 key。

文件在打开模型选择器时会重新加载,不用重启。

四、两种自定义形态

形态 适合什么 代价
完整实现一个服务商 自定义认证、动态发现模型、特殊请求格式 要写代码,跟着版本维护
只提供服务商名 + 几个字段 改地址、加请求头、加几个模型 简单,但能力受限于内置实现

第二种的字段远比名字暗示的多:地址、请求头、认证头、key、协议、模型列表、OAuth、模型刷新、图像与分类模型都在其中。给已有服务商只改地址或加一个头时,它内置的模型清单和认证方式会被保留——这是它比"完整实现"省事的地方。

五、认证有四个来源

很多人以为认证只有"登录"和"环境变量"两条路。实际优先级是四层:

  1. 命令行临时传入的 key;
  2. 登录后存下来的凭据;
  3. 模型配置文件里写的 key;
  4. 环境变量,或云环境自带的身份(比如实例角色)。

前面的优先。这一层分离得比较彻底:描述"有哪些模型"的那部分数据里不含凭据,凭据是运行时另外解析的。所以"配置文件泄露 = 密钥泄露"这件事,在好的设计里不该成立。

六、虚拟模型:一个名字,多个真身

新版本还支持一种"虚拟模型":你注册一个名字,每次请求时现场决定用哪个真实模型、什么思考强度。

典型用途:

  • 按任务类型路由(写代码用强模型,改文案用便宜的);
  • 主备切换(首选不可用就换一个);
  • 灰度(一部分请求走新模型)。

路由状态跟着会话分支保存,所以回退到历史点时,路由选择也能还原。界面上会显示当前路由到了哪个真实模型,计费按真实模型算。

当前 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:三份一手参考。

失败与边界实验

服务商层的失败,几乎都出在"三件事被混在一起"的时候:

  1. 认证缺失被当成模型不存在。 早期的表现是:没有 key 的模型从列表里消失,用户以为不支持。现在的表现是:模型加载了,但选择器里不出现,配上凭据就出现。区别在于状态可解释——"加载了但没凭据"比"不存在"好诊断得多。
  2. 协议差异写进业务代码。 在循环里写"如果是某家服务商就怎样",会让每接一家都改循环。修法是把差异收敛在协议实现里,循环只面向统一的消息类型。
  3. 思考签名不匹配。 有些服务的思考块带签名,重放或转发时可能失配。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 只覆盖字段。
  • 认证四层:命令行 → 登录凭据 → 配置文件 → 环境变量/云身份。

模型调用会失败——网络抖动、限流、配额耗尽。下一章可靠性讲失败如何重试与隔离。