v3 streaming: tool-call block-delta events are snapshots, so their size grows quadratically with the tool-call arguments

问题场景

使用 LangChain 的 v3 流式事件接口（stream_events(…, version=”v3″)）消费模型输出，且模型以流式方式返回工具调用（tool call）的 JSON 参数。典型场景是模型边生成工具参数边推送 content-block-delta 事件，上层服务（如回调处理器）对每个 delta 事件立即做序列化或转发。Issue 的最小复现使用自定义 FakeModel 把同一段 JSON 分别以普通文本和工具调用参数两种方式分块流式输出，观察到两种模式下 delta 事件总字节数差异明显。

报错原文

v3 streaming: tool-call block-delta events are snapshots, so their size grows quadratically with the tool-call arguments

原因分析

根据 Issue 评论中的定位：_compat_bridge.py 中的 chunks_to_events/achunks_to_events 在构造工具调用 delta 时使用累计状态（delta_source = current if is_block_delta else block），因此每个 block-delta 携带的是累积后的 tool_call_chunk；而 v3 stream 消费端把 fields 当作浅合并快照处理。结果参数越长，每次 delta 携带的内容越多，事件体积随参数长度呈二次增长（quadratic growth）。

评论区同时指出这与协议语义一致：block-delta 本身是浅合并的，JS 端发射器（langchain-ai/langgraphjs#2766）也发送累计 args，因此不能简单把 block-delta 改成只发增量，否则现有消费者会静默拼错参数。议题中提到的一个候选方向是新增显式的增量工具参数 delta 表示，同时保留现有快照形式以兼容旧消费者；但维护者最终的修复实现细节，Issue 中未展开。

环境排查

• 确认 langchain-core 的实际安装版本：低于 1.7.0 时此问题存在。
• 确认是否通过升级已锁定该包的其他依赖，导致 langchain-core 未被真正升级。
• 确认是否使用了 stream_events(version="v3")，并确实在流式接收工具调用的 args。
• 检查自定义回调处理器是否对每个 content-block-delta 立即序列化或转发，这会放大事件体积带来的影响。
• Issue 未提供操作系统、Python、CUDA、显卡等信息，这些不作为本次排查前提。

解决步骤

1. 查看当前 langchain-core 版本，确认是否低于 1.7.0。
2. 将 langchain-core 升级到 1.7.0（Issue 明确标注的修复版本）。
3. 如有依赖锁定文件（如 requirements、poetry.lock、uv.lock），同步更新，确保解析后的 langchain-core 为 1.7.0。
4. 若无法立即升级，可优先尝试在应用中减少对工具调用参数 delta 事件的即时序列化或转发，避免把二次增长的事件体积带到下游；这只是缓解，不是 Issue 中验证过的修复。

验证方法

用 Issue 中的最小复现脚本（FakeModel + Recorder，分别以文本和工具调用参数两种方式流式输出同一段 JSON）重新运行，对比各长度下 delta 事件总字节数。修复后，以工具调用参数方式流式输出时，事件体积应随参数长度线性增长，而不是随参数长度平方增长；同时确认最终拼接出的工具调用参数与完整 JSON 一致，.tool_calls/.output 结果不变。

参考来源

langchain-ai/langchain #40999

AI 工具推荐

想把多个 AI 模型放在一个入口？

GamsGo AI 集成 ChatGPT、DeepSeek、Gemini、Claude、Midjourney、Veo 等常用模型，适合写作、绘图、视频和日常 AI 工作流。

了解 GamsGo AI

推广链接：通过此链接购买，我可能获得佣金，不影响你的价格。