langchain/groq 版本演进深度解读从 0.2.4 到 1.3.1 的关键能力升级与源码实现【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs本文以langchain/groq官方 CHANGELOG.md 为线索结合仓库内ChatGroq的源码实现系统梳理 Groq 集成包从 v0.2.4 到 v1.3.1 的完整演进脉络。你将了解到结构化输出structured output三种实现方式的底层差异、streamEvents原生 OpenAI 兼容事件流、中止abort信号处理机制、reasoning_effort推理强度控制以及 peer dependency 约束背后的真实原因——读完可直接把这些能力落地到基于 LangChain.js 与 Groq 的 LLM 应用中。一、包概况langchain/groq在 LangChain.js 中的定位langchain/groq是 LangChain.js 官方发布的 Groq 集成包位于仓库 libs/providers/langchain-groq通过官方groq-sdk提供完整的 Groq 聊天模型推理能力。其核心入口在 src/index.ts对外导出唯一的ChatGroq类当前版本 1.3.1 的依赖约束见 package.json运行时依赖groq-sdk^1.6.0peer 依赖langchain/core^1.1.30这是 1.3.1 版本收紧后的下限原因见下文Node.js 要求20同时提供 ESMdist/index.js与 CJSdist/index.cjs双构建产物从 CHANGELOG 的演进记录可以看出这个包经历了三个阶段早期0.2.x解决基础消息转换问题 → 中期1.0.x对齐 LangChain v1.0 与新核心能力profile、abort、结构化输出→ 当前1.1.x–1.3.x持续强化推理模型支持与流式事件能力。二、v1.3.xpeer 依赖收紧与原生 streamEvents2.1 为什么必须要求langchain/core 1.1.301.3.11.3.1 是一个看似简单却极具代表性的修复版本将 peer dependency 从^1.0.0收紧为^1.1.30。CHANGELOG 明确给出了根因——ChatGroq的源码直接导入了两个从langchain/core1.1.30起才引入的导出子路径langchain/core/utils/standard_schema对应 chat_models.ts 中的isSerializableSchema导入langchain/core/language_models/structured_output对应assembleStructuredOutputPipeline、createContentParser、createFunctionCallingParser导入旧的^1.0.0范围允许安装缺少这些导出子路径的旧版 core导致构建/运行期出现模块解析失败module-not-found。这是 npm 生态中典型的peer 依赖范围过宽问题peer 依赖的下限必须等于代码实际使用到的最老 API 的引入版本。对使用者而言这一变更意味着升级langchain/groq时需要同步检查langchain/core版本否则会在打包或启动阶段立即报错。2.2 原生 OpenAI 兼容 streamEvents1.3.01.3.0 引入了对streamEvents事件的原生支持。所谓原生 OpenAI 兼容在源码层面的体现是 _streamChatModelEvents 方法通过invocationParams(options, { streaming: true })构造带stream: true的请求参数调用completionWithRetry拿到ChatCompletionChunk的异步迭代流外层包一个abortableStream在signal.aborted时提前终止最终交由langchain/core/language_models/openai_completions_stream的convertOpenAICompletionsStream统一转换并显式传入{ streamUsage: true, provider: groq }。这意味着 Groq 的 SSE 流会被统一归一化为带类型的事件流可区分文本增量、推理reasoning文本、工具调用tool call增量以及 token 用量usage。仓库中的单元测试 chat_models_stream_events.test.ts 直接验证了这四类场景describe(ChatGroq.streamEvents, () { test(streams text, async () { await expect( mockGroq(openAITextOnlyChunks()).streamEvents(Hello) ).toHaveStreamText(Hello world); }); test(streams reasoning, async () { await expect( mockGroq(openAIReasoningTextChunks()).streamEvents(Hello) ).toHaveStreamReasoning(Let me reason...); }); test(streams tool calls, async () { await expect( mockGroq(openAIToolCallChunks()).streamEvents(Hello) ).toHaveStreamToolCalls([ { name: web_search, args: { query: weather } }, ]); }); test(streams usage, async () { await expect( mockGroq(openAITextWithUsage()).streamEvents(Hello) ).toHaveStreamUsage({ input_tokens: 10, output_tokens: 2, total_tokens: 12, }); }); });测试用vi.spyOn(model, completionWithRetry)以 fake chunk 数据模拟 Groq 响应验证事件流能正确输出文本、推理内容、工具调用与 usage——这说明streamEvents适合作为构建 Agent 流式 UI、实时展示思考过程与 token 消耗的统一入口。三、v1.1.x推理模型与结构化输出的能力跃升3.1reasoning_effort推理强度控制1.1.51.1.5 为ChatGroq增加了reasoning_effort支持。在 ChatGroqInput 接口 中该参数被约束为联合类型reasoningEffort?: none | default | low | medium | high | null;从源码注释看该能力针对推理类模型如openai/gpt-oss-20b、openai/gpt-oss-120b、qwen/qwen3-32b允许应用在快速低推理与深度高推理之间权衡。它在 invocationParams 中通过options?.reasoning_effort ?? this.reasoningEffort传递给 Groq API既可作为构造参数全局设定也可在单次invoke调用时覆盖。3.2 标准 Schema 支持的结构化输出1.1.4与 gpt-oss 原生 JSON Schema1.1.01.1.4 实现standard schema support for structured output——即withStructuredOutput不再只接受 zod 或裸对象也接受符合langchain/core/utils/standard_schema规范的SerializableSchema。这一点从 withStructuredOutput 的签名重载 可以确认outputSchema参数的类型为InteropZodTypeRunOutput | SerializableSchemaRunOutput | Recordstring, any三者的联合。1.1.0 则进一步为gpt-oss系列模型引入原生 JSON Schema 结构化输出。其底层决策逻辑在 groq-schema.ts 中关键函数是getGroqStructuredOutputMethod与groqStrictifySchemafunction supportsJsonSchema(model: string): boolean { return model.startsWith(openai/gpt-oss); } export const SUPPORTED_STRUCTURED_OUTPUT_METHODS [ jsonSchema, functionCalling, jsonMode, ] as const;决策规则与 groq-schema.test.ts 中的断言一一对应模型 / 指定 method默认/结果说明openai/gpt-oss-*且未指定jsonSchema前缀匹配新 gpt-oss 模型自动支持其它模型且未指定functionCalling退化为工具调用方式任意模型显式指定jsonModejsonMode使用response_format: { type: json_object }指定jsonSchema但模型不支持抛出异常提示改用functionCalling或jsonMode指定非法 method抛出异常仅允许三种方法三种方法对应 withStructuredOutput 实现 中的三条分支jsonSchema将 schema 经toJsonSchema转换后再经groqStrictifySchema严格化写入response_format: { type: json_schema, json_schema: { strict: true, ... } }配合createContentParser解析jsonMode使用response_format: { type: json_object }createContentParserfunctionCalling把 schema 包装成 tool function通过bindTools 强制tool_choice让模型以工具调用形式返回结构化结果再由createFunctionCallingParser解析。3.3 Groq 严格模式下的 Schema 变换原理Groq 的 strict JSON Schema 模式对 schema 有硬性要求groqStrictifySchemagroq-schema.ts通过递归变换满足这些约束所有对象必须additionalProperties: false所有属性必须进入required数组原来可选的属性也会被强制 required原可选属性必须变为 nullable类型联合加入null由makeNullable实现——注意它使用type: [T, null]的数组语法而非anyOf因为 Groq 严格模式禁止顶层anyOf根 schema 不允许anyOf/oneOf/enum/not遇到顶层oneOf或not直接抛错遇到顶层anyOf则尝试提取其中的 object 变体作为根 schema找不到 object 变体时抛错递归处理嵌套对象、数组items、$defs引用对$ref这类无法推断的结构保持原样返回。这些行为在 groq-schema.test.ts 中有超过 15 个用例覆盖包括可选属性变为 nullableenum 追加 null嵌套对象递归处理$defs 递归严格化根 oneOf/not 抛错等边界场景是理解该包结构化输出能力的最佳测试文档。四、v1.0.xLangChain v1.0 兼容与新基建4.1 整体升级 v1.01.0.01.0.0 将包升级为兼容 LangChain v1.0 的版本package.json 中langchain/corepeer 依赖为^1.1.30groq-sdk为^1.6.0。对使用方而言升级到 1.x 意味着整体迁移到新的 core 体系消息、runnable、callback 均为 v1 语义。4.2 模型能力 Profile1.0.11.0.1 为ChatModel增加了ModelProfile与.profile属性。在 chat_models.ts 中get profile(): ModelProfile { return PROFILES[this.model] ?? {}; }profile 数据由 profiles.ts 提供该文件头注释标明由脚本自动生成源自仓库根目录profiles.toml记录每个模型的输入/输出 token 上限、多模态支持、推理输出、工具调用与结构化输出能力。例如llama3-70b-8192maxInputTokens 8192、toolCalling true、structuredOutput falseqwen-qwq-32bmaxInputTokens 131072、maxOutputTokens 16384、reasoningOutput true、toolCalling true。这让上层应用可以在调用前查询模型能力如model.profile.maxInputTokens以决定是否截断上下文或判断是否支持工具调用。4.3 中止信号处理1.0.41.0.4 是 v1.0.x 中行为变化最大的一次统一了各 provider 的 abort 语义新增ModelAbortError定义于langchain/core/errors当invoke()在流式中途被中止时抛出该错误并携带累积的partialOutputstream()被中止时抛出普通AbortError因为 chunk 已经逐块交给调用方_generate()与_streamResponseChunks()都必须检查并传播 abort 信号。ChatGroq的实现与此完全对应_generate 开头 执行options.signal?.throwIfAborted()信号已中止时立即抛出_streamResponseChunks 流式循环内 每次迭代检查options.signal?.aborted并提前 return流结束后若信号已中止则抛出AbortError见 L1306-L1308_streamChatModelEvents中的abortableStream同样在信号中止时停止 yield。这套机制保证了使用 fallback 链时前一个 runnable 被中止后能正确流转到下一个 runnable使用流式 UI 时用户取消请求不会泄漏资源。4.4 其它 1.0.x 修复1.0.2修复moduleResolution: node兼容性保证在旧式模块解析配置下也能正确加载1.0.3修复推理 tokenreasoning tokens在 core 层的提升逻辑确保推理模型的思考过程能以正确消息类型呈现。五、其它值得关注的变更5.1 构造函数重载与包版本元数据1.1.2 / 1.1.31.1.2为聊天模型增加字符串式构造函数重载。ChatGroq的构造函数chat_models.ts因此支持两种等价写法// 写法一字符串模型名 可选字段 const m1 new ChatGroq(llama-3.3-70b-versatile, { temperature: 0 }); // 写法二对象形式官方 README 推荐 const m2 new ChatGroq({ model: llama-3.3-70b-versatile, temperature: 0, });1.1.3为每个包在构造时通过this._addVersion(langchain/groq, __PKG_VERSION__)见构造函数 L1044向metadata.versions打版本戳使 LangSmith trace 元数据中直接携带包版本便于排查线上跑的到底是哪个版本。5.2 groq-sdk 升级与依赖清理1.2.0 / 1.2.11.2.0 将groq-sdk从 0.37.0 升级到 1.1.2当前已进一步升至 ^1.6.01.2.1 移除了冗余的types/uuid声明——因为包实际经由langchain/core/utils/uuid获取 uuid 能力无需直接依赖类型桩。这类变更提醒集成包维护者类型依赖应跟随实际使用路径而非盲目复制。5.3 通用消息角色映射0.2.40.2.4 修复了generic messages 在messageToGroqRole中的支持。该函数chat_models.ts将 LangChain 消息类型映射为 Groq 角色system→system、ai→assistant、human→user、function→function、tool→tool其中generic类型通过extractGenericMessageCustomRole校验其 role 必须属于system | assistant | user | function之一否则抛错。这是保证消息能在 LangChain 与 Groq API 之间无损往返的基础设施。六、实践安装、初始化与能力对照6.1 安装与最小示例按官方 README.md 安装并设置环境变量npm install langchain/groq langchain/core export GROQ_API_KEY你的密钥import { ChatGroq } from langchain/groq; import { HumanMessage } from langchain/core/messages; const model new ChatGroq({ apiKey: process.env.GROQ_API_KEY, // 也可省略自动读取环境变量 model: llama-3.3-70b-versatile, }); const res await model.invoke([ new HumanMessage(What color is the sky?), ]);6.2 常用调用参数速查构造函数可用的关键参数来自 ChatGroqInput参数类型默认值说明modelstring必填Groq 模型名temperaturenumber0.7采样温度maxTokensnumber-单次响应最大 token 数对应max_completion_tokenstopP/topLogprobsnumber-核采样 / top-logprobsfrequencyPenalty/presencePenaltynumber-频率/存在惩罚reasoningEffort枚举-推理强度none/default/low/medium/highstreamUsagebooleantrue流式响应中是否附带 usagestop/stopSequencesstring[]-停止序列最多 4 个baseUrl/timeout/httpAgent/fetch--底层 HTTP 客户端定制streamingbooleanfalse是否默认流式运行期调用选项第二个参数传给.invoke/.stream/.batch还包括tool_choice、response_format、seed、reasoning_effort、stream_options.include_usage与自定义headers等其中tools支持 LangChain 风格工具定义。6.3 结构化输出与工具调用的落地范式工具调用使用.bindToolsimport { z } from zod; const GetWeather { name: GetWeather, description: Get the current weather in a given location, schema: z.object({ location: z.string().describe(The city and state, e.g. San Francisco, CA), }), }; const llmWithTools model.bindTools([GetWeather]); const aiMsg await llmWithTools.invoke( Which city is hotter today: LA or NY? ); console.log(aiMsg.tool_calls);结构化输出withStructuredOutput会根据模型自动选择方法const Joke z .object({ setup: z.string().describe(The setup of the joke), punchline: z.string().describe(The punchline to the joke), rating: z.number().optional().describe(How funny the joke is, from 1 to 10), }) .describe(Joke to tell user.); const structuredLlm model.withStructuredOutput(Joke, { name: Joke }); const jokeResult await structuredLlm.invoke(Tell me a joke about cats);若使用openai/gpt-oss-*模型将自动走原生 JSON Schema 严格模式其它模型默认走 functionCalling 方式。如需强制某种方式可在withStructuredOutput的config.method中显式指定jsonSchema | functionCalling | jsonMode。6.4 包内测试与质量保障仓库为langchain/groq准备了完整的测试矩阵见 src/tests单元测试.test.tschat_models.test.ts、chat_models_stream_events.test.ts、groq-schema.test.ts集成测试.int.test.tschat_models.int.test.ts、chat_models_structured_output.int.test.ts、agent.int.test.ts标准测试.standard.test.ts/.standard.int.test.ts对接仓库内internal/standard-tests的统一标准用例覆盖通用聊天模型行为、abort 语义与结构化输出。本地开发时可在包目录运行pnpm test单元与pnpm test:int集成或从仓库根目录pnpm build --filter langchain/groq构建具体命令见 package.json 的scripts字段。七、总结从 CHANGELOG 读懂一个生产级集成包的演进逻辑回看这份 CHANGELOG可以提炼出几条值得所有集成包维护者借鉴的规律peer 依赖的边界由实际 import 决定1.3.1代码用了哪个 core 子路径peer 下限就应钉在引入该子路径的版本上能力分层推进先补齐消息转换等基础0.2.x再对齐大版本与新核心基建1.0.x随后逐项强化推理模型、结构化输出与流事件1.1.x–1.3.x每项能力都有源码与测试佐证结构化输出的方法决策、严格 schema 变换、abort 语义、streamEvents 事件分类均可在 chat_models.ts、groq-schema.ts 与对应测试文件中找到可验证的实现。对应用开发者而言当前 1.3.1 版本已经具备生产可用的完整能力面流式事件、推理模型控制、三种结构化输出路径、健全的中止与 fallback 语义以及可查询的模型能力 profile——这些正是构建 Groq 驱动的 Agent 应用所需的核心拼图。【免费下载链接】langchainjsThe agent engineering platform项目地址: https://gitcode.com/GitHub_Trending/la/langchainjs创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考