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工厂函数与一个默认实例groqimport { 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配置项类型说明baseURLstringGroq API 基础地址默认https://api.groq.com/openai/v1会去除尾部斜杠apiKeystringAPI 密钥不传时从环境变量GROQ_API_KEY加载headersRecordstring, string自定义请求头与默认头合并fetchFetchFunction自定义 fetch 实现可用于拦截请求或测试认证头由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)创建文本生成模型LanguageModelV4provider.chat(modelId)与languageModel等价provider.transcription(modelId)/provider.transcriptionModel(modelId)创建转录模型TranscriptionModelV4provider.toolsGroq 提供的内置工具集合当前为browserSearchprovider.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-09052.0.18 移除过时的 saba 模型 ID1.1.5 新增 deepseek r12.0.4 为 gpt-oss 补齐 reasoningEffort 的low/medium/high。模型级选项providerOptions 与顶层参数groq-chat-language-model-options.ts 定义了全部 Groq 特有选项基于 zod 的groqLanguageModelChatOptionsschema参数可选值默认说明reasoningFormatparsed/raw/hidden—推理内容输出格式1.1.16 起支持reasoningEffortnone/default/low/medium/high—推理强度级别3.0.0 起被限制为枚举值parallelToolCallsbooleantrue是否启用并行函数调用userstring—终端用户标识用于滥用监控structuredOutputsbooleantrue是否使用结构化输出2.0.0 起支持strictJsonSchemabooleantrue严格 JSON Schema 校验配合约束解码保证 schema 合规3.0.7 起serviceTieron_demand/performance/flex/autoon_demand服务层级performance面向延迟敏感场景flex面向可容忍偶发失败的吞吐场景auto先走 on_demand 限额、超限回退 flex2.0.13 起支持4.0.0 起补齐performance这些选项既可通过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;换算后返回LanguageModelV4UsageinputTokenstotalprompt_tokens、noCache、cacheRead来自cached_tokens、cacheWriteGroq 无缓存创建计费恒为undefinedoutputTokenstotal、text完成 token 减去推理 token、reasoning3.0.12 起暴露reasoningTokensraw保留原始 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-betatrack cached tokens usage的持续完善配合 3.0.0 的extended token usage能力形成完整的用量拆分。四、结构化输出与工具调用结构化输出2.0.0 引入结构化输出structured outputs支持配合generateObject使用3.0.7 增加strictJsonSchema通过约束解码保证输出严格符合 JSON Schema3.0.25 为工具调用传入 strict mode。prepareTools见 groq-prepare-tools.ts负责将 AI SDK 的工具 schema 转换为 Groq 请求格式。流式工具调用的正确性保障工具调用在流式场景下最容易出问题CHANGELOG 记录了一系列修复展示了该能力的严谨演进4.0.6 / 4.0.0fix(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.0StreamingToolCallTracker被抽取到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 denial0.0.3 起支持 provider-defined tools即由 Provider 声明而非用户定义的工具2.0.9 与 4.0.0-beta 的provider tools规范演进rename v3 provider defined tool to provider tool为其发展提供了规范基础。五、语音转录Transcription2.0.0 起ai-sdk/groq提供转录能力feat(providers/groq): add transcribe2.0.14 补齐缺失的provider.transcriptionModel入口。支持的转录模型groq-transcription-model-options.ts 中当前支持whisper-large-v3-turbowhisper-large-v33.0.0 已移除废弃的distil-whisper-large-v3-en模型。转录选项参数说明language音频语言prompt转录提示词responseFormat响应格式设为text时返回纯文本4.0.17 起支持temperature采样温度范围 01timestampGranularities时间戳粒度3.0.11 修复了该参数的传递处理时间戳与响应格式修复4.0.17当段级segment时间戳不可用时将词级word时间戳映射到转录 segments4.0.17responseFormat: text时支持纯文本转录响应2.0.12修复experimental_transcribe在传入合法Buffer时失败的问题。从仓库测试夹具packages/groq/src/fixtures/groq-transcription-text.json与单测 groq-transcription-model.test.ts 可以看出转录请求的构造与响应解析均有完整测试覆盖。六、浏览器搜索工具Browser Search2.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载荷Groq 错误类型状态码可重试rate_limit_error429是api_error/internal_server_error/server_error500是overloaded_error/service_unavailable503是timeout/timeout_error504是authentication_error/invalid_api_key401否permission_error403否not_found_error/model_not_found404否bad_request/context_length_exceeded/invalid_request_error400否同时流式响应通过createEventSourceResponseHandler解析 SSE 事件流非流式通过createJsonResponseHandler解析 JSONconvertToGroqChatMessages见 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.1feat (provider/groq): add groq provider到 4.0.40 的演进。按大版本划分的迁移要点如下v4AI SDK 7当前主线ESM-only移除所有包的 CommonJS 导出type: module使用require()的消费者必须改用 ESMimportNode 版本要求最低 Node.js 22支持 22 / 24 / 26顶层reasoning参数provider 迁移到新的顶层reasoning参数替代旧的 providerOptions 方式streamText结果fullStream弃用改用streamProvider 实现一致性重构部分导出符号更名旧名称以 deprecated alias 继续可用文件上传与 provider references文件 part 数据属性按类型标记移除 image part 类型Workflow 序列化见上文。v3AI SDK 6Provider-V3 / LanguageModelV3 规范新增specificationVersion、共享 spec v3textEmbeddingModel→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。v2AI 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的实现推荐按以下顺序阅读仓库源码入口与 Provider 工厂groq-provider.ts文本生成模型实现groq-chat-language-model.ts模型选项 schema 与内置模型 IDgroq-chat-language-model-options.tsUsage 换算convert-groq-usage.ts 及测试 convert-groq-usage.test.ts转录模型与选项groq-transcription-model.ts、groq-transcription-model-options.ts浏览器搜索工具tool/browser-search.ts流式/非流式测试夹具packages/groq/src/fixtures与快照 groq-chat-language-model.test.ts.snap。这些文件共同构成了对该包能力的完整、可验证的说明也是本文章全部技术结论的仓库依据。结语从最初仅支持基础文本生成的 0.0.1到如今集文本生成、推理、结构化输出、流式工具调用、语音转录与浏览器搜索于一体的 4.0.xai-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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考