源码篇第3章 先开票,后办事——pi-ai ​

老Z递出空白流句柄,小A看着琥珀色光流中的零散事件汇聚成完整消息。

本章导读: 源码路线第 ② 站(核心层)。仍在 pi-ai 包,但深入 api/lazy.ts 和 api/transform-messages.ts。这一站要拆开那个让小A发愣的 AssistantMessageEventStream:厂商零散的增量事件,是怎么被收拢成循环能直接消费的统一形态的。

源码篇第2章走完,小A终于让模型“出发”了。可 Provider 交回来的东西又一次让他愣住:不是一段完整回答,而是一个 AssistantMessageEventStream。他盯着这个流,问老Z:“我到底该怎么接?等它全部结束,还是一个一个拿?”

“都不对。”老Z说,“源码篇第2章 目录与户口——pi-ai已经完成‘模型对象到 Provider’的分派,但 Provider 交回的不是一个完成的字符串,而是 AssistantMessageEventStream。你现在要核对三件事:异步设置为什么不会阻塞入口;一个真实 adapter 如何把厂商流变成统一事件;取消和异常最终以什么状态向上报告。”

本章证据固定在上游 pi 标签 v1.0.0(提交 a13d35a742c6ef8462812a28fbe1d8c8b7431c32)、@earendil-works/pi-ai 1.0.0。本章挑 packages/ai/src/api/openai-responses.ts 作为一个真实 adapter 来读,这不等于声称所有 Provider 或 API 都采用它的字段和失败策略;也不覆盖所有厂商协议、模型定价规则和 WebSocket adapter,更不把通用 retry 工具的存在写成所有调用都会重试。

返回流之前,先把设置留到稍后 ​

“ModelsImpl.stream 与 streamSimple 都调用 lazyStream,函数立刻把一个可迭代的流交到调用者手里,认证解析、动态模块加载、Provider 调用都在后台进行。”老Z说,“所以拿到流不等于‘请求一定已经开始’,它更不是一个普通的 Promise<AssistantMessage>。”

ts
// packages/ai/src/api/lazy.ts,lazyStream(v1.0.0,节选)
export function lazyStream(model, setup): AssistantMessageEventStream {
	const outer = new AssistantMessageEventStream();
	setup()
		.then((inner) => forwardStream(outer, inner))
		.catch((error) => {
			const message = createSetupErrorMessage(model, error);
			outer.push({ type: "error", reason: "error", error: message });
			outer.end(message);
		});
	return outer;
}

小A:“为什么要这样绕一圈?直接等 setup 完成再返回不行吗?”

“逐段看。”老Z指着代码说,“第一行构造 outer,调用点因此同步拿到同一类型的输出,不必区分‘尚在认证’和‘已在接收网络事件’。第二段不 await setup(),而是用 promise continuation 把 forwardStream 接上去,这正是延迟设置:ModelsImpl 里的 requireProvider、applyAuth 和 provider.stream* 都被放进传入的 async 回调。不过‘延迟’是相对同步返回说的,它不承诺等到第一次 for await 才执行,setup() 在函数体里就调用了。”

“第三段把 setup rejection 归一成一个 AssistantMessage:空 content、零 usage、stopReason: "error"、错误文字,随后 push error 事件并 end(message)。于是未知 Provider 或认证失败对消费者呈现为流内错误,而不是调用 Models.stream 时的同步 throw。”

比喻:先开票,后办事

lazyStream 像先给你一张取餐号(outer stream),后厨(setup)慢慢做。做砸了,也是通过“取餐口”告诉你“这单做不了”,而不是在你下单那一刻就摔盘子。

forwardStream 逐个 push 内流事件,迭代结束后若内流带有 .result() 就用它结束 outer。这一规则保留了 adapter 给出的最终消息;别从这里推断任何事件一定包含 text delta。

阶段 产物 正常下一步 设置失败时
Models.stream* 返回 outer stream 调用者订阅/迭代 尚无同步异常
setup() inner async iterable forwardStream .catch 创建 error message
inner events start、delta、done/error 等 原样推到 outer adapter 决定事件内容
inner 完结 result() 或 undefined outer.end 由 adapter 的终止行为决定

lazy API 是第二层延迟,不是第二种事件协议 ​

小A顺着问:“那 Provider 内部的适配器模块呢?也是懒加载?”

“对,但那是第二层延迟。”老Z打开 lazy.ts:

lazyApi(load, capabilities?) 返回一个 ProviderStreams 对象。其两个流方法都再以 lazyStream 包住 await load() 后的模块方法;v1.0.0 新增的 capabilities 声明这个 API 是否还支持 deferred 响应的取回与取消,本章不展开:

ts
// packages/ai/src/api/lazy.ts,lazyApi(v1.0.0,节选)
const api: ProviderStreams = {
	stream: (model, context, options) =>
		lazyStream(model, async () => (await load()).stream(model, context, options)),
	streamSimple: (model, context, options) =>
		lazyStream(model, async () => (await load()).streamSimple(model, context, options)),
};

“外层 ModelsImpl 的 lazy stream 覆盖的是‘Provider/认证设置’,这里的 lazy stream 覆盖的是‘适配器模块加载’。两层产出的都是同一种 AssistantMessageEventStream,所以会出现嵌套转发。模块 import cache 是否去重由宿主运行时负责,源码注释确实提到了 host import cache,但没为任意运行环境证明过性能结果。”

“收益是未使用的 adapter 不必在根入口加载;代价是模块加载错误推迟到第一次请求,排错时还得把 auth setup、import setup 和网络请求三层分开看。”

本章其余小节为付费内容

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