源码篇第2章 目录与户口——pi-ai ​

小A在目录柜台递出模型令牌,老Z核验认证后将其引向一个 Provider 通道,通道中流出串起光点的消息流。

本章导读: 源码路线第 ① 站(核心层)。你在 pi-ai 包,主要读 models.ts、auth/resolve.ts 和 providers/index.ts。这一站要弄清楚的是:手里那个 Model 对象怎么一路走过认证合并、Provider 选择,最终变成一条流。

小A照着 源码篇第1章的地图打开了 pi-ai,信心满满地写下三行代码:拿一个模型、调 stream、收事件。结果卡在第一行:手里明明有一个 Model 对象,他却不知道它从哪来、要往哪去。

“老Z,”他说,“我有一个 Model,可它就是不动。”

“‘有一个 Model’离‘发出请求’还差四步。”老Z说,“找到运行时 Provider、解析认证、合并请求配置、按 API 类型挑中流实现。这一章就跟着走一遍,把每步的先后看清楚,尤其是不配置密钥时,到底在哪一层失败。”

以下源码事实均来自上游 pi 标签 v1.0.0(提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32)、@earendil-works/pi-ai 版本 1.0.0。本章只跟 ModelsImpl.stream/streamSimple 的请求前半段;不枚举厂商 URL、OAuth 页面或每个模型目录的生成过程,也不展开 v1.0.0 新增的图像模型、分类器模型和 deferred 响应。

先分清三种“模型集合” ​

“Model 到底从哪来?我猜 getModel 一下就有了。”

“查目录确实靠 getModel,但别急着把它当成流入口的门票,不然你会被 undefined 和异常搞晕。”老Z打开 models.ts,“ModelsImpl 私有地持有 Map<string, Provider>。getModel(provider, id) 只是从同步的最后已知目录中找一个 Model,找不到返回 undefined,这是查询结果;真正的流入口不接受‘可选 Provider’,缺了会经 requireProvider 抛出 ModelsError,那是不可继续的请求错误。两个行为不能混同。”

比喻:目录与户口

getModel 像翻电话簿:查得到,拿到的就是 undefined 之外的结果;查不到,就是没有。requireProvider 像办业务必须出示户口:没有这个人,直接报错,不会“查无此人”地继续办下去。

操作 输入 成功结果 失败/边界语义
getProvider(id) Provider ID Provider undefined
getModels(id) Provider ID 当前目录 未知或 getModels 抛错时空数组
getModel(id, modelId) 两个 ID Model undefined
getAvailable() 可选 Provider ID 已认证且过滤后的目录 未认证的不进入结果;认证读取错误会拒绝
stream(model, …) 带 provider 的 Model 立即返回事件流 设置期错误变成流的 error event
getAuth(model, …) Provider/模型与覆盖项 AuthResult 未知/未配置时 undefined

“可 getModel 不是已经把模型给我了吗,requireProvider 再查一遍 Provider,图什么?”

“Model 只是数据,可能来自缓存、配置,也可能是调用者手工构造的;ModelsImpl 的 Provider Map 才是本次运行真正可执行的那一份。”老Z说,“两边可能不同步,所以流入口要重新验证。”

Provider 把运行时责任收在一处 ​

先看 packages/ai/src/models.ts 的接口节选。删去的说明与可选目录刷新方法,不改变这里的调用关系。

ts
// packages/ai/src/models.ts,Provider(v1.0.0,节选)
export interface Provider<TApi extends Api = Api> {
	readonly id: string;
	readonly name: string;
	readonly auth: ProviderAuth;
	getModels(): readonly Model<TApi>[];
	stream<T extends TApi>(
		model: Model<T>, context: TranscriptContext, options?: ApiStreamOptions<T>,
	): AssistantMessageEventStream;
	streamSimple(
		model: Model<TApi>, context: TranscriptContext, options?: SimpleStreamOptions,
	): AssistantMessageEventStream;
}

“先说已确认的:这个接口同时管着身份、认证定义、目录读取和两种流入口,stream 保留 API 类型参数,streamSimple 使用简化选项,两者的输出都是 AssistantMessageEventStream。”老Z说,“注意 context 的类型是 TranscriptContext,不是调用者传进来的 Context:ModelsImpl 先用 normalizeContext 把 system prompt 和工具声明并进 system message,Provider 只看规范化后的 transcript。从它能推断的是,上层循环不必知道某个厂商的 SDK 类型;不能推断的是,所有 Provider 都支持同一组选项。”

删去的可选成员里,v1.0.0 还加了 getAllModels、fetchDeferred/cancelDeferred、generateImages 和 classify。后两个服务图像模型和分类器模型,注释写明它们从不 reject,失败以结果对象返回。本章只跟聊天模型的流。

小A指着接口里的两个可选成员:“那 refreshModels? 和 filterModels? 呢?”

“前者恢复/刷新动态目录,后者在认证通过后按 credential 过滤目录。这两个方法把‘目录里存在’和‘此凭据可用’分成了两件事;至于刷新本身能不能联网成功,接口不保证。”

本章其余小节为付费内容

登录后可购买;已购 Pi Cookbook Pro?登录即解锁完整章节。