AI SDK 的 Groq 集成包 @ai-sdk/groq：能力全景、核心实现与版本演进深度解析

AI SDK 的 Groq 集成包 @ai-sdk/groq：能力全景、核心实现与版本演进深度解析

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai

本文围绕当前仓库packages/groq的完整变更记录（CHANGELOG.md）及其配套源码展开，系统梳理@ai-sdk/groq在 AI SDK 生态中的功能全貌：从文本生成、推理（reasoning）支持、结构化输出与工具调用，到语音转录和浏览器搜索工具，并结合源码逐一印证其内部实现，同时梳理从 0.0.1 到 4.0.x 的关键版本演进与迁移关注点，帮助开发者在接入 Groq 时选对版本、用对能力。

@ai-sdk/groq是 AI SDK 官方维护的 Groq 提供商包，基于 Groq 的 OpenAI 兼容 Chat/Completion API 提供语言模型支持，并额外提供语音转录（transcription）与浏览器搜索（browser search）工具能力。阅读本文后，你将掌握该包的能力矩阵、配置参数含义、内部实现原理，以及不同大版本之间的破坏性变更与迁移策略。

一、包定位与快速安装

@ai-sdk/groq位于仓库 packages/groq，提供面向 Groq 的完整接入能力，包括语言模型（chat/completion）、转录模型以及浏览器搜索工具。其安装方式与官方文档一致：

npm i @ai-sdk/groq

该包同时依赖@ai-sdk/provider与@ai-sdk/provider-utils两个基础包，二者承担模型规范（如LanguageModelV4）与通用工具（请求、响应解析、usage 换算等）的职责，CHANGELOG 中大量条目即是这两个依赖包的版本升级记录。

从 groq-provider.ts 的源码可以看到，包内默认导出createGroq工厂函数与一个默认实例groq：

import { groq } from '@ai-sdk/groq'; const { text } = await generateText({ model: groq('gemma2-9b-it'), prompt: 'Write a vegetarian lasagna recipe for 4 people.', });

Provider 实例与认证机制

createGroq(options: GroqProviderSettings)支持以下配置项（见 groq-provider.ts）：

认证头由getHeaders()统一生成：Authorization: Bearer <apiKey>，并通过withUserAgentSuffix追加ai-sdk/groq/<VERSION>的 User-Agent 后缀。CHANGELOG 中 2.1.0-beta 的feat: add provider version to user-agent header即对应此行为，便于 Groq 服务端识别 SDK 版本。

createGroq返回的 Provider 对象（ProviderV4）暴露如下入口：

• provider(modelId)/provider.languageModel(modelId)：创建文本生成模型（LanguageModelV4）；
• provider.chat(modelId)：与languageModel等价；
• provider.transcription(modelId)/provider.transcriptionModel(modelId)：创建转录模型（TranscriptionModelV4）；
• provider.tools：Groq 提供的内置工具集合（当前为browserSearch）；
• provider.embeddingModel/imageModel：当前不支持，调用会抛出NoSuchModelError。

二、文本生成模型与核心参数

GroqChatLanguageModel（见 groq-chat-language-model.ts）实现了LanguageModelV4规范，通过doGenerate/doStream分别支持一次性生成与流式生成。

内置模型 ID

源码 groq-chat-language-model-options.ts 中维护了当前支持的生产与预览模型列表，包括：

• 生产模型：gemma2-9b-it、llama-3.1-8b-instant、llama-3.3-70b-versatile、meta-llama/llama-guard-4-12b、openai/gpt-oss-120b、openai/gpt-oss-20b；
• 预览模型（节选）：deepseek-r1-distill-llama-70b、meta-llama/llama-4-maverick-17b-128e-instruct、meta-llama/llama-4-scout-17b-16e-instruct、moonshotai/kimi-k2-instruct-0905、qwen/qwen3.6-27b、qwen-qwq-32b、deepseek-r1-distill-qwen-32b等。

由于类型末尾包含(string & {})，任意字符串模型 ID 均被类型系统接受，便于动态接入 Groq 后续上线的新模型；CHANGELOG 中多次出现模型列表增删记录，例如 3.0.0 移除已停用的moonshotai/kimi-k2-instruct并新增moonshotai/kimi-k2-instruct-0905，2.0.18 移除过时的 saba 模型 ID，1.1.5 新增 deepseek r1，2.0.4 为 gpt-oss 补齐 reasoningEffort 的low/medium/high。

模型级选项（providerOptions 与顶层参数）

groq-chat-language-model-options.ts 定义了全部 Groq 特有选项（基于 zod 的groqLanguageModelChatOptionsschema）：

这些选项既可通过providerOptions.groq传入（2.0.0 的chore(providers/groq): convert to providerOptions完成了这一改造），也可作为顶层参数使用——4.0.0 的feat: migrate providers to support new top-level reasoning parameter使reasoning成为顶层参数，并由mapReasoningToProviderEffort映射为底层请求参数。

三、推理（reasoning）能力与 token 统计

推理输出处理

自 1.1.16 引入reasoning format支持后，Groq 模型的推理能力不断完善：

• reasoning 流顺序：3.0.6 修复了流式输出中reasoning-end必须先于text-start发送的顺序问题；
• 非推理模型兼容：2.0.10 修复了对非推理模型剥离不支持的reasoning字段的问题；4.0.31 进一步修复——当顶层reasoning设为none时，对受支持的 Groq 模型正确禁用推理；
• reasoning 回传：2.0.8 起 Groq API 接受 tool call 场景下的 reasoning 输入，实现多轮采样中的推理延续。

Token 使用统计的精细拆分

convert-groq-usage.ts 展示了 usage 的换算逻辑，也是 CHANGELOG 中多项修复的核心位置：

const promptTokens = usage.prompt_tokens ?? 0; const cacheReadTokens = usage.prompt_tokens_details?.cached_tokens ?? undefined; const reasoningTokens = usage.completion_tokens_details?.reasoning_tokens ?? undefined; const textTokens = reasoningTokens != null ? Math.max(0, completionTokens - reasoningTokens) : completionTokens;

换算后返回LanguageModelV4Usage：

• inputTokens：total（prompt_tokens）、noCache、cacheRead（来自cached_tokens）、cacheWrite（Groq 无缓存创建计费，恒为undefined）；
• outputTokens：total、text（完成 token 减去推理 token）、reasoning（3.0.12 起暴露reasoningTokens）；
• raw：保留原始 usage 对象。

与之相关的关键修复包括：

• 4.0.8：此前convertGroqUsage虽接受prompt_tokens_details.cached_tokens却从未读取，导致缓存命中被报告为cacheRead: undefined、整个 prompt 被计为noCache；修复后 Groq 隐式 prompt 缓存以usage.cachedInputTokens（映射为cacheRead）呈现；
• 4.0.31：防止 provider 报告 reasoning tokens 时出现负的文本输出 token 计数，Perplexity 的 reasoning tokens 被单独处理；
• 3.0.0 / 2.1.0-beta：track cached tokens usage的持续完善，配合 3.0.0 的extended token usage能力形成完整的用量拆分。

四、结构化输出与工具调用

结构化输出

2.0.0 引入结构化输出（structured outputs）支持，配合generateObject使用；3.0.7 增加strictJsonSchema，通过约束解码保证输出严格符合 JSON Schema；3.0.25 为工具调用传入 strict mode。prepareTools（见 groq-prepare-tools.ts）负责将 AI SDK 的工具 schema 转换为 Groq 请求格式。

流式工具调用的正确性保障

工具调用在流式场景下最容易出问题，CHANGELOG 记录了一系列修复，展示了该能力的严谨演进：

• 4.0.6 / 4.0.0：fix(security): prevent streaming tool calls from finalizing on parsable partial JSON——早期实现用isParsableJson()作为工具调用参数是否完整的启发式判断，但部分累积的 JSON 可能恰好是合法 JSON（实为更长参数的前缀），导致工具以截断参数被执行。修复后，工具调用仅在flush()（流完全消费后）阶段完成定型；
• 4.0.22：修复流式工具调用在索引非零、非连续、被重用或缺失时的处理问题；
• 4.0.29：修复空字符串 tool call ID 的处理；
• 4.0.0：StreamingToolCallTracker被抽取到@ai-sdk/provider-utils，在多个 OpenAI 兼容 provider 间去重，并保证所有 provider 在流 flush 时完成未完结工具调用的定型；同时为 Alibaba 的doGenerate路径补上了generateId()兜底；
• 1.0.5：修复 OpenAI/Groq 发送重复工具调用的问题。

工具执行拒绝与 provider 定义工具

4.0.0 与 4.0.0-beta.31 完善了工具执行被拒绝时的默认提示消息（tool execution denial）；0.0.3 起支持 provider-defined tools（即由 Provider 声明而非用户定义的工具），2.0.9 与 4.0.0-beta 的provider tools规范演进（rename v3 provider defined tool to provider tool）为其发展提供了规范基础。

五、语音转录（Transcription）

2.0.0 起@ai-sdk/groq提供转录能力（feat(providers/groq): add transcribe），2.0.14 补齐缺失的provider.transcriptionModel入口。

支持的转录模型

groq-transcription-model-options.ts 中当前支持：

• whisper-large-v3-turbo
• whisper-large-v3

（3.0.0 已移除废弃的distil-whisper-large-v3-en模型。）

转录选项

时间戳与响应格式修复

• 4.0.17：当段级（segment）时间戳不可用时，将词级（word）时间戳映射到转录 segments；
• 4.0.17：responseFormat: 'text'时支持纯文本转录响应；
• 2.0.12：修复experimental_transcribe在传入合法Buffer时失败的问题。

从仓库测试夹具（packages/groq/src/fixtures/groq-transcription-text.json）与单测 groq-transcription-model.test.ts 可以看出转录请求的构造与响应解析均有完整测试覆盖。

六、浏览器搜索工具（Browser Search）

2.0.9 起 Groq 集成浏览器使用（browser search）工具，这是 Groq 侧的 provider-defined tool。其入口为groq.tools.browserSearch({})，源码见 tool/browser-search.ts：工具 ID 为groq.browser_search，输入输出 schema 均为空对象——该工具不接收参数，只要包含在tools数组中即自动激活，由 prompt 驱动，在 Groq 服务端执行（无需额外 API Key）。

支持的模型与校验

浏览器搜索仅支持openai/gpt-oss-20b与openai/gpt-oss-120b（模型常量见 groq-browser-search-models.ts）。对不支持的模型使用该工具，会输出警告Browser search is only supported on models: openai/gpt-oss-20b, openai/gpt-oss-120b并忽略该工具。

使用示例

import { groq } from '@ai-sdk/groq'; import { generateText } from 'ai'; const result = await generateText({ model: groq('openai/gpt-oss-120b'), // 必须使用受支持模型 prompt: 'What are the latest developments in AI? Please search for recent news.', tools: { browser_search: groq.tools.browserSearch({}), }, toolChoice: 'required', // 确保工具被调用 });

流式场景同样支持：

import { groq } from '@ai-sdk/groq'; import { streamText } from 'ai'; const result = streamText({ model: groq('openai/gpt-oss-120b'), prompt: 'Search for the latest tech news and summarize it.', tools: { browser_search: groq.tools.browserSearch({}) }, toolChoice: 'required', }); for await (const delta of result.stream) { if (delta.type === 'text-delta') process.stdout.write(delta.text); }

最佳实践要点：使用toolChoice: 'required'强制触发搜索；仅限两个 gpt-oss 模型；无需任何配置参数。

七、请求与响应的底层处理

流式错误规范化

groq-chat-language-model.ts 中的getGroqStreamErrorMetadata将 Groq 的错误类型映射为标准的 HTTP 状态码与可重试标志，4.0.32 起流式中间错误被规范化为公共的StreamProviderError实例，保留 provider 原始的错误type、code、status、retry与raw载荷：

同时，流式响应通过createEventSourceResponseHandler解析 SSE 事件流，非流式通过createJsonResponseHandler解析 JSON；convertToGroqChatMessages（见 convert-to-groq-chat-messages.ts）负责将 AI SDK 的消息格式转换为 Groq 格式。

Workflow 序列化支持

4.0.0 为所有 provider 模型引入了 workflow 序列化能力：模型类新增WORKFLOW_SERIALIZE与WORKFLOW_DESERIALIZE静态方法（groq-chat-language-model.ts），配合@ai-sdk/provider-utils的serializeModel()帮助函数，只提取可序列化属性（过滤函数与含函数的对象），使模型实例可以安全跨 workflow 步骤边界传递；同时headers在 provider 配置类型中变为可选，便于认证在步骤边界单独注入。对 Groq 而言，其 config 中的headers是函数形式，序列化时会自动过滤，认证由目标环境的getHeaders()重新生成。

八、版本演进脉络与迁移关注点

CHANGELOG 完整记录了从 0.0.1（feat (provider/groq): add groq provider）到 4.0.40 的演进。按大版本划分的迁移要点如下：

v4（AI SDK 7，当前主线）

• ESM-only：移除所有包的 CommonJS 导出，"type": "module"，使用require()的消费者必须改用 ESMimport；
• Node 版本要求：最低 Node.js 22，支持 22 / 24 / 26；
• 顶层reasoning参数：provider 迁移到新的顶层reasoning参数，替代旧的 providerOptions 方式；
• streamText结果fullStream弃用：改用stream；
• Provider 实现一致性重构：部分导出符号更名（旧名称以 deprecated alias 继续可用）；
• 文件上传与 provider references：文件 part 数据属性按类型标记，移除 image part 类型；
• Workflow 序列化（见上文）。

v3（AI SDK 6）

• Provider-V3 / LanguageModelV3 规范：新增specificationVersion、共享 spec v3；
• textEmbeddingModel→embeddingModel重命名（旧名称保留为 deprecated alias）：

  // 之前 model.textEmbeddingModel("my-model-id"); // 之后 model.embeddingModel("my-model-id");

• Transcription Model v3 spec、扩展 token usage、tool execution approval、raw finish reason 暴露；
• reasoningEffort 限制为枚举值：非法值在选项解析阶段即被拒绝；
• 依赖 zod v4、@ai-sdk/test-server移至 devDependencies。

v2（AI SDK 5）

• 引入transcribe与structured outputs；
• 新增service tierprovider option；
• 新增browser search tool、kimi k2、llama 4 模型；
• providerOptions 化改造：Groq 特有选项统一通过providerOptions传入；
• raw chunk support：流式消费时可访问原始数据块。

升级建议

• 从 v2 升级 v3/v4 时，优先处理 ESM 化、Node 版本与符号更名三件事；
• 若依赖流式工具调用，建议升级到 4.0.6+（含StreamingToolCallTrackerflush 定型修复与索引修复）；
• 若关注成本统计，升级到 4.0.8+ 以获得准确的 prompt 缓存读取计数；
• 使用转录功能时注意模型 ID 变更（如distil-whisper-large-v3-en已移除）。

九、源码阅读路线图

若希望深入理解@ai-sdk/groq的实现，推荐按以下顺序阅读仓库源码：

1. 入口与 Provider 工厂：groq-provider.ts；
2. 文本生成模型实现：groq-chat-language-model.ts；
3. 模型选项 schema 与内置模型 ID：groq-chat-language-model-options.ts；
4. Usage 换算：convert-groq-usage.ts 及测试 convert-groq-usage.test.ts；
5. 转录模型与选项：groq-transcription-model.ts、groq-transcription-model-options.ts；
6. 浏览器搜索工具：tool/browser-search.ts；
7. 流式/非流式测试夹具：packages/groq/src/fixtures与快照 groq-chat-language-model.test.ts.snap。

这些文件共同构成了对该包能力的完整、可验证的说明，也是本文章全部技术结论的仓库依据。

结语

从最初仅支持基础文本生成的 0.0.1，到如今集文本生成、推理、结构化输出、流式工具调用、语音转录与浏览器搜索于一体的 4.0.x，@ai-sdk/groq的 CHANGELOG 本身就是一份高质量的工程实践档案：它既展示了能力边界的持续扩张，也记录了流式工具调用安全性、token 统计精确性、错误规范化等关键细节的反复打磨。对于正在接入或升级 Groq 的开发者，结合本仓库的 CHANGELOG 与源码阅读，可以准确判断每个版本的能力边界与迁移成本，从而做出稳妥的技术选型。

【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai