Effect 源码解析：ResponseIdTracker 从 WeakMap 到 Map 的增量对话优化

Effect 源码解析ResponseIdTracker 从 WeakMap 到 Map 的增量对话优化【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect导读本文以 Effect 仓库中一条 Changeset 记录.changeset/pre/eff-716-response-id-tracker-map.md为核心深入剖析effect/unstable/ai中ResponseIdTracker服务的内部实现与优化动机为什么从每次重置时重新分配 WeakMap改为在普通Map上调用clear()。读完本文你将理解该服务如何在多轮对话中通过previousResponseId实现增量发送 prompt只发送新消息、如何识别前缀发散并自动重置状态以及这一数据结构改动对内存、性能与并发安全的影响同时掌握其在LanguageModel.generateText/streamText与 OpenAI 等 Provider 中的完整调用链。一、Changeset 说了什么该 Changeset 是 Effect 包的 patch 级变更原文如下Use a normal Map in ResponseIdTracker and clear it on divergence / reset instead of reallocating a WeakMap.翻译过来即在ResponseIdTracker中使用普通Map并在检测到前缀发散divergence或重置时调用clear()清空而不是重新分配一个新的 WeakMap。对应变更记录也出现在 packages/effect/CHANGELOG.md 中。一条简短的变更描述背后涉及三个值得展开的技术点底层数据结构由WeakMap换成Map状态重置方式由重新分配实例改为原地clear()重置触发时机包括显式重置clearUnsafe与自动的发散即重置divergence 时清空旧状态。下面结合源码逐一还原。二、ResponseIdTracker 是什么增量 LLM 调用的响应 ID 追踪器2.1 解决的问题某些 LLM Provider如 OpenAI Responses API支持续接之前的响应调用方可以传入previousResponseId并只附带该响应之后新增的消息从而减少每次请求的 token 传输量。ResponseIdTracker正是为这一机制服务的可变mutable服务定义于 packages/effect/src/unstable/ai/ResponseIdTracker.ts。从源码注释可见其核心职责记住每个 Provider 响应中包含哪些 prompt 消息对象当后续调用延续同一段对话时构造一个更短的 prompt只含新增消息配合前一次的响应 ID 发送。该模块通过Context.Service注册服务标签为effect/ai/ResponseIdTracker自since 4.0.0起提供。2.2 服务接口三个方法源码中的Service接口ResponseIdTracker.ts定义如下方法签名职责clearUnsafe(): void丢弃全部已追踪状态显式重置markParts(parts: ReadonlyArrayobject, responseId: string): void记录产生某次响应的 prompt 消息对象与该响应 ID 的对应关系prepareUnsafe(prompt: Prompt.Prompt): Option.OptionPrepareResult当 prompt 前缀被完整追踪时返回previousResponseId与仅含新增消息的 prompt 片段其中PrepareResultResponseIdTracker.ts包含两个字段previousResponseId: string—— 要传给 Provider 的上一响应 IDprompt: Prompt.Prompt—— 上一个 assistant 回合之后新增的消息片段。三、核心实现Map clear() 的分发与重置逻辑3.1 数据结构与构造器make构造器ResponseIdTracker.ts当前实现的核心行是export const make: Effect.EffectService Effect.sync(() { const sentParts new Mapobject, string() // ... })sentParts以消息对象身份object identity为键、Provider 响应 ID 为值。注意这里使用的是普通Mapobject, string而非 WeakMap。3.2 为什么用 Map 而不是 WeakMap这是本次 Changeset 的核心。两者的差异决定了重置策略WeakMap 无法迭代、无法清空WeakMap 没有clear()方法ES2015 规范中删除也没有任何遍历 API。要做重置只能把整个实例丢弃、重新new WeakMap()即重新分配reallocating。Map 支持原地clear()普通Map提供clear()可以在保持同一个实例引用的前提下清空全部键值对避免反复分配新对象带来的内存与 GC 压力。从源码结构看改动后make只在初始化时创建一次Map此后无论是显式clearUnsafe()还是发散时自动重置都调用同一个sentParts.clear()这正是 Changeset 中clear it on divergence / reset instead of reallocating a WeakMap的落地方式。3.3 markParts登记响应 IDmarkParts(parts, responseId) { for (let i 0; i parts.length; i) { sentParts.set(parts[i], responseId) } }将本次请求发出的每条消息对象与返回的响应 ID 关联。测试 ResponseIdTracker.test.ts 验证了同一对象被连续标记两次时后标记的 ID 覆盖先前的resp_2胜出。3.4 prepareUnsafe识别可增量发送的前缀prepareUnsafe是算法核心逻辑分四步ResponseIdTracker.ts第一步判断是否命中任何已追踪消息。let anyTracked false for (let i 0; i messages.length; i) { if (sentParts.has(messages[i])) { anyTracked true break } } if (!anyTracked) return none()如果当前 prompt 中的消息没有任何一条在追踪表中全新对话或状态已被清空调用内部none()辅助函数const none () { sentParts.clear() return Option.nonePrepareResult() }注意返回None的同时会清空整个追踪表这是divergence / reset 即清空策略的一部分。第二步定位最后一个 assistant 消息。let lastAssistantIndex -1 for (let i messages.length - 1; i 0; i--) { if (messages[i].role assistant) { lastAssistantIndex i break } } if (lastAssistantIndex -1) return none()没有 assistant 消息说明对话尚未产生任何已消费的回合无法续接返回None并清空。第三步校验 assistant 之前的全部前缀消息都被追踪。let responseId: string | undefined for (let i 0; i lastAssistantIndex; i) { const id sentParts.get(messages[i]) if (id undefined) return none() responseId id } if (responseId undefined) return none()只要前缀中任意一条消息未被追踪即认为 prompt 发生了发散divergence——例如 system 消息对象被替换、用户消息被重新构造即便结构相同但身份不同。此时返回None并清空全部旧状态避免把过期的响应 ID 误用于内容已变化的新对话。最后一个 assistant 之前被追踪消息的响应 ID 即作为previousResponseId。第四步取 assistant 之后的新增消息作为增量 prompt。const partsAfterLastAssistant messages.slice(lastAssistantIndex 1) if (partsAfterLastAssistant.length 0) { return none() } return Option.some({ previousResponseId: responseId, prompt: Prompt.fromMessages(partsAfterLastAssistant) })若 assistant 之后没有任何新增消息无法增量返回None否则返回Some包含前一次响应 ID 与仅含新增消息的 prompt 片段。3.5 身份键 vs 结构相等追踪表以对象身份Map的 SameValueZero 键语义识别消息而非结构化相等。测试 ResponseIdTracker.test.ts 专门验证了这一点userMessage(msg1)与其结构完全相同的副本userMessage(msg1)是两个不同对象markParts标记前者后用后者构造的 prompt 会被判定为未追踪而返回None。这一设计确保了 prompt 内容一旦被重新构造哪怕内容相同也会安全地回退到全量发送而不是冒险复用旧的响应 ID。四、与 LanguageModel 的集成generateText / streamText 调用链ResponseIdTracker通过Effect.serviceOption从 Context 中按需获取未提供时静默跳过调用点位于LanguageModel.tsgenerateTextLanguageModel.tsstreamText以generateText为例集成流程LanguageModel.tsif (tracker) { const prepared tracker.prepareUnsafe(providerOptions.prompt) if (Option.isSome(prepared)) { providerOptions.previousResponseId prepared.value.previousResponseId providerOptions.incrementalPrompt prepared.value.prompt } } const rawContent yield* generateWithNonIncrementalFallback() const content yield* Schema.decodeEffect(ResponseSchema)(rawContent) if (tracker) { const responseMetadata content.find((part) part.type response-metadata) if (Predicate.isNotUndefined(responseMetadata) Predicate.isNotUndefined(responseMetadata.id)) { tracker.markParts(providerOptions.prompt.content, responseMetadata.id) } }关键细节请求前调用prepareUnsafe(prompt)若命中则把previousResponseId与incrementalPrompt写入 Provider options请求后从响应中提取response-metadata部件携带id将本次实际发出的 prompt 消息对象标记到该响应 ID 下失败回退generateWithNonIncrementalFallbackLanguageModel.ts在增量请求抛出AiError的InvalidRequestError例如 Provider 返回过期的previousResponseId时自动清除incrementalPrompt与previousResponseId改用全量 prompt 重试一次streamText侧同样存在streamWithNonIncrementalFallbackLanguageModel.ts且规定仅有response-metadata部件不足以禁用全量回退防止误判。集成级测试位于 LanguageModelTrackerLifecycle.test.ts覆盖了跨回合追踪与掉线恢复第一轮全量发送previousResponseId: undefined第二轮携带resp_1与仅含user2的增量 prompt调用tracker.clearUnsafe()后第三轮退回全量发送第四轮再次恢复增量L48-L116过期 ID 回退后继续追踪generateObject场景下 stale 响应 ID 触发全量回退L118-L168streamText 的元数据部件跨轮追踪L170-L221未提供 tracker 时保持previousResponseId/incrementalPrompt为undefinedL244-L312。五、Provider 侧落地previousResponseId 如何变成 HTTP 参数previousResponseId最终由各 Provider 适配器翻译成协议字段。以 OpenAI 为例在 packages/ai/openai/src/OpenAiLanguageModel.ts 中if (options.previousResponseId) request.previous_response_id options.previousResponseId即把 Effect 层的previousResponseId映射为 OpenAI Responses API 请求体中的previous_response_id。这印证了Provider 可通过接受previousResponseId来续接此前响应的机制说明。六、并发与生命周期测试如何验证 Map 方案的安全性本次改动把弱引用的 WeakMap 换成了强引用的普通 Map一个自然的顾虑是键的强引用是否会导致消息对象无法被 GC 回收。从代码与测试来看该问题由两条机制兜底清空即释放无论是clearUnsafe()显式调用还是prepareUnsafe在发散/无命中时自动clear()都会成批移除引用避免长期驻留并发安全markParts/clearUnsafe/prepareUnsafe均为同步操作在 JS 单线程模型下天然原子测试 ResponseIdTracker.test.ts 用 200 轮markParts与clearUnsafe并发交替借助Effect.yieldNow调度验证了追踪器在竞争后仍可正常使用。生命周期测试还覆盖了多种边界场景ResponseIdTracker.test.ts场景预期结果全新 tracker 首次prepareUnsafeNone且清空状态首个回合仅 system userNone无 assistant 回合已追踪前缀 assistant 新 userSome增量 prompt 仅含新 userassistant 工具调用后跟 tool 结果Some增量 prompt 仅含 tool 结果多步工具流 新 userSome增量 prompt 含 tool 结果与新 userassistant 之后无新消息Nonesystem/user 消息对象被替换发散None旧状态被清空发散后重新markParts新前缀恢复Some使用新响应 ID同一 tracker 上两个独立对话互不串扰各自命中各自前缀结构相等但身份不同的前缀消息None身份键语义七、总结一条 Changeset 背后的工程取舍eff-716这条 patch 级别变更本质是一次数据结构层面的微优化从 WeakMap 到 Map弱引用在消息对象可能被整体丢弃的场景下本可自动回收键但 WeakMap 无法遍历也无法清空重置只能整体换新实例普通 Map 牺牲了键的弱引用语义由显式clear()补偿换来了可枚举、可原地清空的能力从重新分配到原地 clearclear()复用同一个Map实例避免高频多轮对话中反复创建、丢弃对象带来的分配与 GC 开销同时让服务在其整个生命周期内保持单一状态容器行为更可预测发散即重置的自动恢复prepareUnsafe一旦发现前缀未被完整追踪内容发散或身份变化立即clear()旧状态并返回None配合LanguageModel的全量 prompt 回退逻辑保证增量机制在对话漂移、会话掉线后仍能安全收敛。这套机制使得多轮 LLM 调用可以在保持正确性的前提下仅向 Provider 发送新增消息减少 token 传输量而Map clear()的落地方式则为高频率对话场景提供了更稳定的内存与性能表现。若需深入源码可继续阅读 ResponseIdTracker.ts、LanguageModel.ts以及配套测试 ResponseIdTracker.test.ts 与 LanguageModelTrackerLifecycle.test.ts。【免费下载链接】effectBuild production-ready applications in TypeScript项目地址: https://gitcode.com/GitHub_Trending/ef/effect创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考