@ai-sdk/cerebras 提供者全解析：从 CHANGELOG 看 Cerebras 高速推理在 AI SDK 中的集成与演进

@ai-sdk/cerebras 提供者全解析：从 CHANGELOG 看 Cerebras 高速推理在 AI SDK 中的集成与演进

【免费下载链接】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/cerebras是 AI SDK 生态中面向 Cerebras（覆盖0.0.1至3.0.47共 2676 行变更记录）为主体骨架，结合 README.md、package.json 与src目录下的核心源码，系统梳理该提供者的安装配置、模型目录演进、请求协议转换、结构化输出、推理（Reasoning）序列化等关键技术细节。读完本文，你将掌握如何在 AI SDK 中接入 Cerebras 高速模型、如何正确使用 provider options 与结构化输出，并能理解 CHANGELOG 中每个关键变更背后的实现原理。

一、包定位与快速接入

@ai-sdk/cerebras是 AI SDK 的官方 Cerebras 提供者，包内只封装语言模型能力。从 package.json 可以看到，其运行时依赖仅为三个基础包：

• @ai-sdk/openai-compatible：提供 OpenAI 兼容协议的聊天模型基类；
• @ai-sdk/provider：定义LanguageModelV4、ProviderV4等核心抽象；
• @ai-sdk/provider-utils：提供 API Key 加载、请求头构造、User-Agent 后缀等工具函数。

因此该包本质上是一个薄封装层：协议解析、流式解析等重活全部复用 OpenAI 兼容实现，Cerebras 专属逻辑集中在请求体转换与结果后处理两个点位上（下文第五、六节详解）。

安装与首次调用（来自 README.md）：

npm i @ai-sdk/cerebras

import { cerebras } from '@ai-sdk/cerebras'; import { generateText } from 'ai'; const { text } = await generateText({ model: cerebras('gpt-oss-120b'), prompt: 'Write a JavaScript function that sorts a list:', });

从 index.ts 可以看到包的公共导出面：默认实例cerebras、工厂函数createCerebras、类型CerebrasProvider/CerebrasProviderSettings/CerebrasErrorData/CerebrasLanguageModelChatOptions，以及VERSION常量。

二、版本演进主线：从 0.0.1 到 3.0.47

CHANGELOG 是理解该提供者能力边界的最佳时间线。剔除纯依赖升级条目后，功能性变更可归纳为四条主线：

1. 与 AI SDK 大版本同步（4.x → 5 → 6 → 7）

• 0.0.1（14d77ff）：首次添加 Cerebras provider，对应 AI SDK 4.1 时代；
• 0.2.0（5bc638d）：AI SDK 4.2；
• 1.0.0（d5f588f）：AI SDK 5，同时伴随fa49207（provider options 机制转换）、e2aceaf（raw chunk 支持）、d1a034f/205077b（内部改用 Zod 4 并优化 Zod 兼容性）；
• 2.0.0（dee8b05）：AI SDK 6 beta，模型能力大幅扩充；
• 3.0.0：AI SDK 7 预发布起点，工程层面发生两处 breaking change（见第七节）。

2. 模型目录的持续增删

这是 CHANGELOG 中信息密度最高的部分，直接反映了 Cerebras 公开模型目录的漂移：

这一增删节奏表明：模型 ID 是强类型约束，而非自由字符串。当前 cerebras-chat-options.ts 中的联合类型即该演进的最终形态：

// https://inference-docs.cerebras.ai/models/overview export type CerebrasChatModelId = // production 'gpt-oss-120b' | 'gemma-4-31b' | (string & {});

其中(string & {})是 TypeScript 的惯用技巧：保留已知模型 ID 的自动补全，同时允许传入尚未收录进联合类型的自定义/新模型 ID。官方能力矩阵（见 40-cerebras.mdx）显示gpt-oss-120b与gemma-4-31b均支持对象生成、工具调用、工具流式与推理，其中gemma-4-31b还额外支持图像输入。

3. 能力开关的开启

• 4d34a89（1.1.0-beta.2）：开启结构化输出（structured outputs），对应 cerebras-provider.ts 中的supportsStructuredOutputs: true；
• 8dac895（1.1.0-beta.6）：升级到LanguageModelV3；
• ed329cb（1.1.0-beta.4）：升级到Provider-V3；
• 1cad0ab（1.1.0-beta.3）：在 User-Agent 头中加入 provider 版本号；
• 63f29e0（3.0.0）：添加 chat 语言模型 provider（即provider.chat(...)调用方式）；
• 5c5c0f5（3.0.5）：为转录模型加入实验性流式转录支持（主要由@ai-sdk/openai-compatible层提供，Cerebras 包随之联动升级）。

4. 协议细节修正

• ebfdcd5（3.0.0）：将 assistant 消息中的推理部分序列化为reasoning字段——这是 Cerebras 与 OpenAI 兼容协议的关键差异，详见第五节；
• d6a521a（3.0.34）：添加 typed provider options，并把maxOutputTokens以max_completion_tokens字段发送；
• 90e2d8a（3.0.0）：修复未被 lint 工具标记的未使用变量；
• 258c093（3.0.0）：保证导入处理的一致性，避免重复导入或循环依赖。

三、Provider 实例与配置项

README.md 与 40-cerebras.mdx 提供了两种创建实例的方式：直接使用默认实例cerebras，或通过createCerebras自定义配置：

import { createCerebras } from '@ai-sdk/cerebras'; const cerebras = createCerebras({ apiKey: process.env.CEREBRAS_API_KEY ?? '', });

从 cerebras-provider.ts 源码看，CerebrasProviderSettings支持四个可选配置项：

底层实现要点（cerebras-provider.ts）：

• baseURL会先经过withoutTrailingSlash归一化，再与路径拼接成最终请求 URL；
• 请求头通过withUserAgentSuffix追加ai-sdk/cerebras/${VERSION}后缀，便于服务端统计 SDK 使用情况（对应 CHANGELOG 中1cad0ab的变更）；
• API Key 通过loadApiKey加载，支持显式传入或环境变量回退；
• cerebrasErrorStructure使用 zod schema 定义错误响应结构（message/type/param/code），errorToMessage提取message作为错误文案；
• 该 provider仅提供语言模型：embeddingModel与imageModel均抛出NoSuchModelError，textEmbeddingModel是弃用别名，这解释了 CHANGELOG 中8d9e8ad（移除 EmbeddingModelV3 泛型）与366f50b（弃用 textEmbeddingModel 别名）两次重构的动机。

四、Provider 与模型的使用方式

官方文档（40-cerebras.mdx）展示了三种等价的语言模型获取方式：

const model = cerebras('gpt-oss-120b'); const model = cerebras.languageModel('gpt-oss-120b'); const model = cerebras.chat('gpt-oss-120b');

Cerebras 模型同时适用于generateText与streamText。仓库内的可运行示例集中在 examples/ai-functions/src/generate-text/cerebras/ 与 examples/ai-functions/src/stream-text/cerebras/ 目录下，覆盖四类典型场景：

• basic.ts：基础文本生成；
• output-object.ts：结构化对象生成（配合generateObject使用）；
• reasoning.ts：推理模型的使用与推理内容消费；
• tool-call.ts：工具调用（Function Calling）。

对应端到端测试见 examples/ai-functions/src/e2e/cerebras.test.ts，包内单元测试见 cerebras-provider.test.ts 与 cerebras-chat-language-model.test.ts。

推理（Reasoning）模型的使用

gpt-oss-120b、gemma-4-31b等模型会在最终回答前生成中间思考 token。官方文档（40-cerebras.mdx）给出的流式消费方式：

import { cerebras } from '@ai-sdk/cerebras'; import { streamText } from 'ai'; const result = streamText({ model: cerebras('gpt-oss-120b'), providerOptions: { cerebras: { reasoningEffort: 'medium', }, }, prompt: 'How many "r"s are in the word "strawberry"?', }); for await (const part of result.stream) { if (part.type === 'reasoning') { console.log('Reasoning:', part.text); } else if (part.type === 'text-delta') { process.stdout.write(part.textDelta); } }

推理输出通过 AI SDK 标准的 reasoning part 流式透出，这意味着任何支持 AI SDK 推理渲染的前端组件都能直接消费。

五、请求体转换：Cerebras 与 OpenAI 兼容协议的差异缝合

CHANGELOG 中ebfdcd5与d6a521a两条变更的落地实现，就是 cerebras-provider.ts 中的transformCerebrasRequestBody函数。该函数在每次请求发出前执行字段映射：

return { ...restArgs, ...(maxTokens !== undefined && { max_completion_tokens: maxTokens }), ...(parallelToolCalls !== undefined && { parallel_tool_calls: parallelToolCalls }), ...(topLogprobs !== undefined && { top_logprobs: topLogprobs }), ...(logitBias !== undefined && { logit_bias: logitBias }), ...(serviceTier !== undefined && { service_tier: serviceTier }), ...(reasoningFormat !== undefined && { reasoning_format: reasoningFormat }), ...(promptCacheKey !== undefined && { prompt_cache_key: promptCacheKey }), // ... };

核心差异点：

1. max_tokens→max_completion_tokens：OpenAI 兼容层默认输出max_tokens，而 Cerebras 使用max_completion_tokens表达最大补全 token 数（对应d6a521a）。该转换在maxTokens未定义时不会输出该字段，避免破坏不传该参数的请求。

2. 推理历史字段重命名：Cerebras 期望 assistant 消息中的推理历史放在reasoning字段，而共享的 OpenAI 兼容转换器会序列化为reasoning_content。转换器对每条 assistant 消息检查：若存在reasoning_content且目标消息还没有reasoning字段，则将其重命名为reasoning（对应ebfdcd5）。这是多轮对话中保留推理上下文的关键，否则后续轮次会丢失模型此前的思考链。

3. 透传字段：parallel_tool_calls、top_logprobs、logit_bias、service_tier、reasoning_format、prompt_cache_key均按需透传，未定义时不携带。

六、结构化输出与混合响应的后处理

CHANGELOG 中4d34a89开启的结构化输出，不只是开关一个布尔值，cerebras-chat-language-model.ts 中的CerebrasChatLanguageModel继承自OpenAICompatibleChatLanguageModel，并针对一个真实边界情况做了专门修补：

Cerebras GLM 可能在返回合法结构化输出文本的同时，重复发出一次工具调用（finish reason 为tool_calls且伴随文本）。此时应将该混合响应视为最终答案。

具体实现是isStructuredOutputWithToolCallsFinishReason判定函数：当responseFormat.type === 'json'、原始 finish reason 为tool_calls、且响应中确实存在非空文本时：

• doGenerate（L54-L81）：从content中过滤掉tool-call类型 part，并把 finish reason 统一改写为stop；
• doStream（L83-L135）：通过TransformStream逐 part 过滤——先累计hasText，命中上述条件时把 finish part 的 finish reason 改为stop，同时丢弃 JSON 模式下已经产出文本之后的所有tool-input-*/tool-callpart。

这类修补正是"薄封装层"的典型形态：协议层差异交给请求转换器，响应语义差异交给模型子类覆写。模型还实现了WORKFLOW_SERIALIZE/WORKFLOW_DESERIALIZE静态方法（配合serializeModelOptions），使模型实例可被 AI SDK 的工作流（Workflow）机制序列化与反序列化。

七、Provider Options 全参数速查

以下参数通过providerOptions.cerebras传入，zod schema 定义见 cerebras-chat-language-model-options.ts，参数语义说明见官方文档（40-cerebras.mdx）：

组合使用示例（来自官方文档，类型标注为satisfies CerebrasLanguageModelChatOptions，可获得 IDE 级提示校验）：

import { cerebras, type CerebrasLanguageModelChatOptions, } from '@ai-sdk/cerebras'; import { generateText } from 'ai'; const result = await generateText({ model: cerebras('gpt-oss-120b'), prompt: 'Explain why the sky is blue.', providerOptions: { cerebras: { reasoningEffort: 'low', reasoningFormat: 'parsed', promptCacheKey: 'conversation-123', } satisfies CerebrasLanguageModelChatOptions, }, });

八、工程化演进：ESM-only、Node 版本与发布流水线

3.0.0是工程层面的分水岭，CHANGELOG 记录了三条对使用者有直接影响的变化：

1. 移除 CommonJS 导出，全面 ESM-only（ef992f8）："type": "module"写入 package.json，使用require()的消费者必须切换到 ESMimport语法；
2. 最低 Node.js 版本提升到 22（7fc6bd6）：官方支持的版本为 22、24、26，与 package.json 中"engines": { "node": ">=22" }一致；
3. 发布与供应安全：9f0e36c在所有包上配置 provenance（对应publishConfig.provenance: true），38fc777在 provider README 中加入 AI Gateway 提示，0c4c275/b8396f0则是 canary 与 beta 渠道的初始发布。

包的构建与测试脚本（package.json）体现了 monorepo 的工程规范：tsup构建、vitest 同时跑 Node 与 Edge 两套测试（vitest.node.config.js与vitest.edge.config.js）、prepack时从content/providers/01-ai-sdk-providers/40-cerebras.mdx拷贝官方文档进包。zod 被声明为 peerDependency（^3.25.76 || ^4.1.8），与内部使用zod/v4的实现保持一致。

九、从变更日志反推的实践建议

基于 CHANGELOG 的演进规律，可以沉淀出几条对该包使用者的实用结论：

• 升级前先查模型 ID 存活状态：模型增删频繁（llama3.1-70b → llama-3.3-70b → qwen 系列 → gpt-oss 系列），生产环境锁定版本时，应以 cerebras-chat-options.ts 中的联合类型为准，避免使用已被移除的 ID；
• 多轮对话依赖reasoning字段：若手动构造历史消息并发现推理内容丢失，需要按ebfdcd5的约定把推理文本放入 assistant 消息的reasoning字段，而非 OpenAI 习惯的reasoning_content；
• 结构化输出场景注意混合响应：generateObject/responseFormat: { type: 'json' }下，若遇到 finish reason 异常为tool_calls却带合法文本，CerebrasChatLanguageModel会自动将其归一为stop并过滤工具 part，无需应用层自行处理；
• Node 22+ 与 ESM 是硬约束：从3.0.0起该包仅支持 ESM 导入，且运行环境 Node 版本需 ≥22；
• 调试优先用自定义fetch：CerebrasProviderSettings.fetch是官方留出的拦截点，可用于记录请求/响应体、模拟错误或做本地缓存测试，单元测试也是通过该机制驱动。

十、进一步探索

• 完整变更时间线：packages/cerebras/CHANGELOG.md
• 使用与配置总览：packages/cerebras/README.md
• Provider 工厂与请求转换实现：packages/cerebras/src/cerebras-provider.ts
• 模型类与结构化输出修补：packages/cerebras/src/cerebras-chat-language-model.ts
• Provider Options 类型定义：packages/cerebras/src/cerebras-chat-language-model-options.ts
• 官方集成文档：content/providers/01-ai-sdk-providers/40-cerebras.mdx
• 可运行示例：examples/ai-functions/src/generate-text/cerebras/basic.ts、examples/ai-functions/src/stream-text/cerebras/tool-call.ts

结合 CHANGELOG 与源码共同阅读，能更准确地把握该提供者的能力边界：它不重复实现协议栈，而是通过"请求转换 + 响应修补"两个精确的缝点，把 Cerebras 的高速推理能力无缝接入 AI SDK 的统一编程模型。

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