核心变化:工具调用参数改为增量切片

本次 @langchain/openai 1.7.0 的实质变化只有一项,但影响面广:工具调用与服务端工具调用的参数流式事件由原来的块快照改为增量切片。过去每个 block-delta 事件都会携带截至目前的参数全量快照,大工具调用会反复传输重复字节;现在改为 tool-call-delta 事件,只携带新增的参数分片,大调用在网络上的传输量降至与同长度文本相当。官方发布页明确,这一改动覆盖兼容桥、OpenAI 兼容转换器涉及的 OpenAI Completions、Groq、Mistral、IBM、OpenRouter、Perplexity、DeepSeek、Fireworks、Together AI 与 xAI Completions,以及 OpenAI 与 xAI Responses、Anthropic 客户端与服务端工具调用和 Bedrock Converse。Google 与 Ollama 仍为每次完整快照,不在此次优化范围内。工具调用的标识、名称与序号改由内容块开始事件承载且不带参数,后到的标识在内容块结束事件中补齐。

适用对象与兼容性

该版本面向使用 LangChain.js 构建智能体、工具调用与流式输出的中国前端与全栈开发者,尤其是有长参数、大工具调用与多模型路由的项目。常规的 await stream、toolCalls 取值与组装后消息行为不变,一般业务无需改业务逻辑。但直接读取原始事件中 block-delta 的 fields.args,或自写流转换器的项目属于破坏性影响范围,必须改读 tool-call-delta。客户端兼容有硬要求:旧客户端无法正确处理新事件,需先升级客户端再升级该包,配套要求为 @langchain/langgraph-sdk 1.12.6 及以上、@langchain/react、vue、svelte 或 angular 1.2.6 及以上,Python 侧客户端需 langchain-core 1.6.13 及以上。仓库归属为 langchain-ai 组织下的 langchainjs,许可证仍为 MIT,正式发布非预发布,可通过 npm 正常安装。

  • 先升级客户端依赖至上述最低版本并在测试环境验证流式解析;再将 @langchain/openai 升级至 1.7.0;如直接处理原始事件,将 block-delta 快照读取改为 tool-call-delta 增量拼接;全量回归工具调用、服务端工具调用与多模型路由;需暂缓时将 @langchain/core 锁定在 1.3.0 以下以保持快照行为。

迁移与访问条件

升级通过 npm 进行,国内用户可使用本地镜像源加速,但版本与完整性仍以 GitHub 官方 Release 与 npm 官方元数据为准。建议先在隔离或预发布环境验证,再进入生产,尤其要覆盖大参数工具调用、Anthropic 与 Bedrock 通道、以及自定义流转换器。如需暂缓,官方给出的保持方法是固定 @langchain/core 在 1.3.0 以下,这会同时保持 @langchain/openai、anthropic、aws 与 xai 相关版本停留在发送快照的旧行为,适合发布窗口紧张的团队作为短期策略,但不应作为长期停留方案。

限制与必要下一步

本次未涉及许可证变化、安全修复与维护状态变化,MIT 条件不变,也未声明性能以外的准确性提升,不应将其理解为模型能力增强。Google 与 Ollama 通道仍为完整快照,跨通道行为不一致,依赖统一解析的项目需保留分支处理。官方未提供中国区单独说明,网络与镜像差异需自行验证。下一步是检查自有代码是否读取 block-delta,升级客户端矩阵后在测试环境对比升级前后工具调用组装结果,确认无截断、无重复后再全量发布;预发布通道用户无需额外操作,正式版用户按上述顺序常规升级验证即可。