企业官网建设流程全解析

AI SDK Groq Provider 完整指南：从文本生成、语音转录到 Browser Search 工具

【免费下载链接】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 SDK（The AI Toolkit for TypeScript）中@ai-sdk/groq提供商的完整实战指南，覆盖安装配置、聊天文本生成、Whisper 语音转录，以及 Groq 独有的交互式 Browser Search 工具。读完本文，你将掌握如何在自己的 TypeScript 应用中接入 Groq 的 chat/completion API、转录 API 与浏览器搜索能力，并理解其底层实现与模型校验机制。

概览：Groq Provider 提供哪些能力

Groq Provider 是 AI SDK 官方内置的模型提供商适配器之一，位于 packages/groq 目录。根据 packages/groq/README.md，它提供三类核心能力：

• 语言模型支持：对接 Groq 的 chat 与 completion API，用于文本生成、函数调用、结构化输出等；
• 转录支持：通过 Groq 的 Whisper 系列模型完成语音到文本（Speech-to-Text）转换；
• 浏览器搜索工具：由 Groq 服务端提供的交互式网页浏览工具（基于 Exa 搜索引擎），支持实时联网检索。

从 源码入口 可以看到，该包对外导出createGroq、groq（默认实例）、browserSearch工具以及一系列类型定义，与@ai-sdk/provider中的ProviderV4/LanguageModelV4/TranscriptionModelV4规范一一对应。

安装与基本设置

Groq Provider 以独立 npm 包形式发布，名为@ai-sdk/groq。安装命令：

npm i @ai-sdk/groq

根据 package.json，该包运行时依赖@ai-sdk/provider与@ai-sdk/provider-utils（均为工作区内部包），并将zod声明为 peer dependency（^3.25.76 || ^4.1.8），Node.js 版本要求>=22。若使用 pnpm 或 yarn 管理依赖，将npm i替换为对应命令即可。

如果你使用 Claude Code、Cursor 等编码 Agent，官方建议在仓库中添加 AI SDK skill：

npx skills add vercel/ai

创建 Provider 实例：createGroq 与默认实例 groq

@ai-sdk/groq提供了两种获取 Provider 实例的方式：

import { groq, createGroq } from '@ai-sdk/groq';

• groq是包默认导出的 Provider 实例，开箱即用；
• createGroq(options)允许传入自定义配置创建新实例。

从 groq-provider.ts 源码可见，GroqProviderSettings支持以下配置项：

创建实例后，请求头会自动携带形如ai-sdk/groq/<版本号>的 User-Agent 后缀（由withUserAgentSuffix添加），便于在 Groq 侧识别调用来源。另外，groq('model-id')与groq.languageModel('model-id')等价，都是创建聊天语言模型；若使用new关键字调用模型函数，源码会直接抛出错误。

基础文本生成

在设置好GROQ_API_KEY环境变量（或通过createGroq({ apiKey })显式传入）之后，即可开始文本生成：

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

groq(modelId)的modelId会直接作为请求体中的model字段传给 Groq API。从 groq-chat-language-model-options.ts 的类型定义可以看到，内置的生产级模型 ID 包括：

• 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

此外还有一批 preview 模型（如deepseek-r1-distill-llama-70b、meta-llama/llama-4-maverick-17b-128e-instruct、qwen/qwen3.6-27b、moonshotai/kimi-k2-instruct-0905等）。由于类型定义最后以(string & {})兜底，传入列表中未列出的新模型 ID 也是允许的。

底层调用链路

文本生成最终由 GroqChatLanguageModel 实现。doGenerate通过postJsonToApi向${baseURL}/chat/completions发送请求，并把 AI SDK 标准化参数映射为 Groq API 参数：

值得注意的是，topK参数在 Groq 上不受支持，传入时会触发unsupported类型的 warning。响应中若包含reasoning字段（推理模型），会被解析为独立的reasoning内容块；tool_calls则被转换为 AI SDK 标准的tool-call内容。Token 用量经过 convert-groq-usage.ts 转换为统一的inputTokens/outputTokens结构，其中缓存读取 token（cached_tokens）与推理 token（reasoning_tokens）会被单独拆分统计。

流式场景下，doStream会追加stream: true并以 EventSource 方式解析增量块，通过StreamingToolCallTracker逐步拼装工具调用参数，同时正确处理text-start/text-delta/text-end与reasoning-start/reasoning-delta/reasoning-end事件。

Groq 专属模型选项（providerOptions）

通过providerOptions.groq可以透传 Groq 专属参数（schema 定义同样在 groq-chat-language-model-options.ts）：

• reasoningFormat：'parsed' | 'raw' | 'hidden'，控制推理内容的返回格式；
• reasoningEffort：'none' | 'default' | 'low' | 'medium' | 'high'，指定推理强度；AI SDK 的reasoning参数（minimal/low/medium/high/xhigh）会被映射到对应的 effort 值；
• parallelToolCalls：boolean，是否启用并行函数调用，默认true；
• user：string，代表终端用户的唯一标识，便于 Groq 侧监控与滥用检测；
• structuredOutputs：boolean，默认true，控制是否使用结构化输出；
• strictJsonSchema：boolean，默认true，开启后模型使用受限解码（constrained decoding）保证输出严格符合 JSON Schema；
• serviceTier：'on_demand' | 'performance' | 'flex' | 'auto'，默认on_demand，用于选择服务等级（对延迟敏感负载可选performance）。

典型用法示例：

import { groq } from '@ai-sdk/groq'; import { generateText } from 'ai'; const { text } = await generateText({ model: groq('openai/gpt-oss-120b'), prompt: 'Explain quantum computing in one paragraph.', providerOptions: { groq: { reasoningEffort: 'high', reasoningFormat: 'parsed', serviceTier: 'performance', user: 'user-12345', }, }, });

Browser Search 工具：交互式联网搜索

这是 Groq Provider 的特色能力。与传统的"搜索引擎返回摘要"不同，Browser Search 会像人类用户一样交互式地浏览网页，从而获得更详细、更全面的结果，且在 Groq 的服务端执行，开发者无需配置任何浏览器或额外 API Key。

支持模型与校验机制

Browser Search 目前仅支持两个模型：

• openai/gpt-oss-20b
• openai/gpt-oss-120b

源码中由 groq-browser-search-models.ts 的BROWSER_SEARCH_SUPPORTED_MODELS常量维护，并通过isBrowserSearchSupportedModel做兼容性判断。在 groq-prepare-tools.ts 中，工具预处理逻辑会检查groq.browser_search工具是否用于受支持模型：

• 模型受支持 → 将工具转换为 Groq API 的{ type: 'browser_search' }请求体；
• 模型不受支持 →不报错中断，而是产生 warning 并忽略该工具，warning 内容为Browser search is only supported on the following models: openai/gpt-oss-20b, openai/gpt-oss-120b. Current model: ...。

基本用法

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', // 确保工具被调用 }); console.log(result.text);

要点：

• 通过groq.tools.browserSearch({})获取工具实例（等价于从包入口导入的browserSearch）；
• 该工具不需要任何输入参数或配置选项，其激活完全由 prompt 内容驱动；
• 建议配合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); } }

工具实现细节

从 tool/browser-search.ts 源码可以看到，browserSearch是基于createProviderExecutedToolFactory创建的 Provider 执行工具，工具 ID 为groq.browser_search，其inputSchema与outputSchema都是空对象{}（zod 校验），再次印证"无参数、自动工作"的设计。工具会在 groq-tools.ts 中统一挂载到groq.tools命名空间下。

关键特性与最佳实践

关键特性：

• 交互式浏览：像人类用户一样在网站间导航，而非只取搜索摘要；
• 结果更全面：比传统搜索片段更详细、更完整；
• 服务端执行：运行在 Groq 的基础设施上，零额外配置；
• Exa 搜索引擎驱动：底层使用 Exa 搜索引擎以获取最优结果；
• Beta 期间免费：当前阶段不额外收费。

最佳实践：

1. 始终使用toolChoice: 'required'确保搜索被激活；
2. 只搭配受支持模型（openai/gpt-oss-20b与openai/gpt-oss-120b）使用；
3. 工具自动工作，无需传任何配置参数；
4. 服务端执行意味着无需额外 API Key 或本地环境搭建。

模型兼容性验证

// ✅ 受支持——正常执行搜索 const result = await generateText({ model: groq('openai/gpt-oss-120b'), tools: { browser_search: groq.tools.browserSearch({}) }, }); // ❌ 不受支持——产生 warning 并忽略工具（不会中断请求） const result = await generateText({ model: groq('gemma2-9b-it'), tools: { browser_search: groq.tools.browserSearch({}) }, }); // Warning: "Browser search is only supported on models: openai/gpt-oss-20b, openai/gpt-oss-120b"

语音转录（Speech-to-Text）

除文本生成外，Groq Provider 还实现了TranscriptionModelV4规范（见 groq-transcription-model.ts），支持 Whisper 系列模型。从 groq-transcription-model-options.ts 可知，可用转录模型为：

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

调用方式（通过 AI SDK 的transcribe入口）：

import { groq } from '@ai-sdk/groq'; import { transcribe } from 'ai'; const { text } = await transcribe({ model: groq.transcription('whisper-large-v3-turbo'), audio: audioBytes, // Uint8Array 或 base64 编码的音频数据 mediaType: 'audio/mpeg', });

底层实现通过postFormDataToApi向${baseURL}/audio/transcriptions发送multipart/form-data请求，自动将音频字节封装为File并推断文件扩展名（mediaTypeToExtension）。请求体字段包括model、file，以及以下可选参数：

当response_format为text时，返回纯文本；否则返回 JSON，其中segments（分段）或words（逐词）会被转换为统一的segments数组（含startSecond/endSecond秒级时间戳），同时返回language与durationInSeconds。

错误处理与可观测性

Groq Provider 对 API 错误做了细粒度的映射（见 groq-chat-language-model.ts 中的getGroqStreamErrorMetadata），便于上层统一处理：

流式响应中若某个 chunk 解析失败或携带错误对象，会以error类型的流事件输出，并将finishReason置为error。

进一步探索

• 完整 README：packages/groq/README.md
• Provider 实例与配置：src/groq-provider.ts
• 聊天模型实现与参数映射：src/groq-chat-language-model.ts
• Groq 专属选项 schema：src/groq-chat-language-model-options.ts
• Browser Search 工具定义：src/tool/browser-search.ts
• 工具预处理与模型校验：src/groq-prepare-tools.ts
• 转录模型实现：src/groq-transcription-model.ts
• Token 用量换算：src/convert-groq-usage.ts

仓库内还提供了配套的测试与快照（如 groq-chat-language-model.test.ts 及其 snapshot），以及转录相关的 fixture（groq-transcription-text.json），可作为理解请求/响应格式的第一手资料。

小结

@ai-sdk/groq让 TypeScript 开发者以统一的 AI SDK 抽象访问 Groq 的文本生成、语音转录与 Browser Search 能力：默认实例groq配合GROQ_API_KEY环境变量即可快速上手；createGroq提供baseURL、headers、fetch等自定义入口；providerOptions.groq可精细控制推理强度、结构化输出与服务等级；而groq.tools.browserSearch({})则提供了一种零配置、服务端执行的交互式联网检索方案。理解其参数映射与模型校验逻辑，能帮助你在实际项目中更准确地选择配置、规避兼容性问题。

【免费下载链接】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