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

本章导读: 源码路线第 ② 站(核心层)。仍在
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>。”
// 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 响应的取回与取消,本章不展开:
// 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?登录即解锁完整章节。