尧图网站设计 尧图网站设计YAOTU DESIGN
ARTICLE DETAIL

资讯详情

深耕网站设计与一线实操的经验洞察。

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

AI SDK Groq Provider 完整指南:从文本生成、语音转录到 Browser Search 工具 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 SDKThe 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.8Node.js 版本要求22。若使用 pnpm 或 yarn 管理依赖将npm i替换为对应命令即可。如果你使用 Claude Code、Cursor 等编码 Agent官方建议在仓库中添加 AI SDK skillnpx skills add vercel/ai创建 Provider 实例createGroq 与默认实例 groqai-sdk/groq提供了两种获取 Provider 实例的方式import { groq, createGroq } from ai-sdk/groq;groq是包默认导出的 Provider 实例开箱即用createGroq(options)允许传入自定义配置创建新实例。从 groq-provider.ts 源码可见GroqProviderSettings支持以下配置项配置项类型说明baseURLstringGroq API 基础地址默认为https://api.groq.com/openai/v1源码通过withoutTrailingSlash去除末尾斜杠后拼接路径apiKeystringAPI Key不传时自动读取环境变量GROQ_API_KEY通过loadApiKey实现headersRecordstring, string附加的自定义请求头会与默认的Authorization: Bearer apiKey合并fetchFetchFunction自定义 fetch 实现可用于请求拦截、代理或测试场景创建实例后请求头会自动携带形如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-itllama-3.1-8b-instantllama-3.3-70b-versatilemeta-llama/llama-guard-4-12bopenai/gpt-oss-120bopenai/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 参数AI SDK 参数Groq API 参数maxOutputTokensmax_tokenstemperaturetemperaturetopPtop_pfrequencyPenaltyfrequency_penaltypresencePenaltypresence_penaltystopSequencesstopseedseed值得注意的是topK参数在 Groq 上不受支持传入时会触发unsupported类型的 warning。响应中若包含reasoning字段推理模型会被解析为独立的reasoning内容块tool_calls则被转换为 AI SDK 标准的tool-call内容。Token 用量经过 convert-groq-usage.ts 转换为统一的inputTokens/outputTokens结构其中缓存读取 tokencached_tokens与推理 tokenreasoning_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.tsreasoningFormatparsed | raw | hidden控制推理内容的返回格式reasoningEffortnone | default | low | medium | high指定推理强度AI SDK 的reasoning参数minimal/low/medium/high/xhigh会被映射到对应的 effort 值parallelToolCallsboolean是否启用并行函数调用默认trueuserstring代表终端用户的唯一标识便于 Groq 侧监控与滥用检测structuredOutputsboolean默认true控制是否使用结构化输出strictJsonSchemaboolean默认true开启后模型使用受限解码constrained decoding保证输出严格符合 JSON SchemaserviceTieron_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-20bopenai/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 期间免费当前阶段不额外收费。最佳实践始终使用toolChoice: required确保搜索被激活只搭配受支持模型openai/gpt-oss-20b与openai/gpt-oss-120b使用工具自动工作无需传任何配置参数服务端执行意味着无需额外 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-turbowhisper-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以及以下可选参数可选参数说明language音频语言代码prompt提示词用于引导转录结果如专业术语、上下文response_format响应格式可指定为text纯文本或verbose_json带时间戳详情temperature采样温度取值范围01timestamp_granularities时间戳粒度数组形式序列化为timestamp_granularities[]当response_format为text时返回纯文本否则返回 JSON其中segments分段或words逐词会被转换为统一的segments数组含startSecond/endSecond秒级时间戳同时返回language与durationInSeconds。错误处理与可观测性Groq Provider 对 API 错误做了细粒度的映射见 groq-chat-language-model.ts 中的getGroqStreamErrorMetadata便于上层统一处理Groq 错误类型HTTP 状态码是否可重试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否流式响应中若某个 chunk 解析失败或携带错误对象会以error类型的流事件输出并将finishReason置为error。进一步探索完整 READMEpackages/groq/README.mdProvider 实例与配置src/groq-provider.ts聊天模型实现与参数映射src/groq-chat-language-model.tsGroq 专属选项 schemasrc/groq-chat-language-model-options.tsBrowser Search 工具定义src/tool/browser-search.ts工具预处理与模型校验src/groq-prepare-tools.ts转录模型实现src/groq-transcription-model.tsToken 用量换算src/convert-groq-usage.ts仓库内还提供了配套的测试与快照如 groq-chat-language-model.test.ts 及其 snapshot以及转录相关的 fixturegroq-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创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考
返回列表