企业官网建设流程全解析

AI SDK 的 Cerebras Provider：接入 Wafer-Scale 高速推理的完整指南

【免费下载链接】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（TypeScript）中接入 Cerebras 的 Wafer-Scale Engine 高速推理服务，涵盖安装配置、Provider 实例创建、模型调用、推理模型（reasoning）使用以及全部 Provider 选项。读完本文，你将掌握用generateText/streamText驱动gpt-oss-120b等模型，并理解请求体转换与结构化输出等底层实现细节。

Cerebras Provider 是什么

Cerebras provider是 AI SDK 官方为 Cerebras 提供的语言模型接入模块，使 AI SDK 应用能够调用 Cerebras 的高速推理 API。Cerebras 的推理能力由其Wafer-Scale Engines（晶圆级引擎）和 CS-3 系统驱动，主打低延迟、高吞吐的模型服务。

在 AI SDK 生态中，Cerebras provider 属于"模型提供方"（model provider）角色：它把 Cerebras 的 Chat Completions 风格 API 统一适配为 AI SDK 的LanguageModelV4接口，从而让上层ai核心库的generateText、streamText、generateObject等函数无需关心底层 HTTP 协议差异。从源码结构看，cerebras-provider.ts 基于@ai-sdk/openai-compatible的 OpenAI 兼容层实现，因此 Cerebras API 的请求/响应协议与 OpenAI 兼容接口高度一致。

环境要求与安装

@ai-sdk/cerebras是@ai-sdk系列下的独立包，安装它即可获得 Provider 能力，无需安装额外的 Cerebras 官方 SDK：

npm i @ai-sdk/cerebras

安装前需要注意以下前提：

• 运行时版本：根据 package.json，本包要求node >= 22。
• Peer 依赖：需要zod ^3.25.76 || ^4.1.8，用于 Provider 选项的类型校验（见下文"Provider 选项的 Schema 定义"）。
• API Key：需要从 Cerebras 平台（cloud.cerebras.ai）获取 API Key，运行时通过环境变量CEREBRAS_API_KEY提供，也可在创建 Provider 实例时显式传入。
• 包体积策略：包的sideEffects被声明为false，可安全参与 tree-shaking。

如果你使用 Claude Code、Cursor 等编码 Agent，官方还建议把 AI SDK 的 skill 加入仓库，帮助 Agent 正确使用本模块：

npx skills add vercel/ai

创建 Provider 实例

使用默认实例

@ai-sdk/cerebras导出了一个开箱即用的默认 Provider 实例cerebras，大多数场景直接导入即可：

import { cerebras } from '@ai-sdk/cerebras';

自定义实例（createCerebras）

当需要自定义 API Key、Base URL、请求头或 fetch 实现时，使用createCerebras创建独立实例：

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

从 cerebras-provider.ts 的CerebrasProviderSettings定义可以看到，Provider 实例支持以下可选设置：

底层实现中，请求头会额外追加ai-sdk/cerebras/<版本号>形式的 User-Agent 后缀（见 cerebras-provider.ts），便于服务端识别 SDK 版本。

Provider 实例本身是一个可调用函数（callable），同时暴露了多种模型工厂方法。测试用例 cerebras-provider.test.ts 验证了provider(modelId)直接调用会返回聊天语言模型实例；对于不支持的模型类型，embeddingModel等方法会抛出NoSuchModelError（cerebras-provider.ts），即 Cerebras provider 目前只提供语言模型能力。

可用模型

Cerebras provider 在类型层面声明的生产可用模型 ID 定义于 cerebras-chat-options.ts：

export type CerebrasChatModelId = // production 'gpt-oss-120b' | 'gemma-4-31b' | (string & {});

• gpt-oss-120b：Cerebras 提供的 120B 级开源模型，支持推理（reasoning）；
• gemma-4-31b：支持图像输入的 31B 级模型；
• (string & {})：类型兜底，允许传入后续新增的任意模型 ID（具体以 Cerebras 官方模型列表为准）。

各模型的详细能力对比如下（依据 官方 Provider 文档 中的能力表）：

基本用法：文本生成与流式输出

一次性生成（generateText）

将模型实例传给 AI SDK 核心库的generateText即可完成一次完整生成：

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:', });

流式输出（streamText）

Cerebras 语言模型同样支持streamText流式调用，适合对话式 UI 与逐 token 展示场景：

import { cerebras } from '@ai-sdk/cerebras'; import { streamText } from 'ai'; const result = streamText({ model: cerebras('gpt-oss-120b'), prompt: 'Explain why the sky is blue.', }); for await (const part of result.stream) { if (part.type === 'text-delta') { process.stdout.write(part.textDelta); } }

其他模型工厂方法

除直接调用外，还可以使用.languageModel()或.chat()方法获得等价的语言模型实例：

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

推理模型（Reasoning Models）的使用

gpt-oss-120b和gemma-4-31b会在输出最终答案前生成中间思考 token（reasoning tokens）。在 AI SDK 中，这部分内容通过标准的 reasoning part 流式输出，因此可以像处理普通文本一样消费：

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); } }

对gpt-oss-120b，可通过reasoningEffort控制推理深度。在测试夹具（cerebras-structured-output-tools.1.json）对应的流式响应中可以看到，usage 信息会区分reasoning与text两类输出 token，completion_tokens_details中单独记录reasoning_tokens，方便对推理开销进行观测与计费分析。

Provider 选项详解

Cerebras 语言模型支持一组 Provider 选项，通过generateText/streamText的providerOptions.cerebras字段传入。这些选项的类型由 zod schema 约束，定义在 cerebras-chat-language-model-options.ts，并从包的入口导出为CerebrasLanguageModelChatOptions类型。

组合使用示例：

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, }, });

cerebrasLanguageModelChatOptions的 zod schema 还给出了几个值得注意的约束：topLogprobs被限制为min(0).max(20)的整数；logitBias的值域为-100到100；promptCacheKey最大 1024 字符。这些约束会在请求组装前完成校验，避免向服务端发送非法参数。

源码级原理：请求体转换与输出归一化

请求体字段映射（transformCerebrasRequestBody）

Provider 在把 AI SDK 的调用参数发送给 Cerebras 之前，会经过 cerebras-provider.ts 中的transformCerebrasRequestBody转换，主要做两件事：

1. 参数命名从 camelCase 转为 snake_case：如max_tokens→max_completion_tokens、parallelToolCalls→parallel_tool_calls、logitBias→logit_bias、serviceTier→service_tier、reasoningFormat→reasoning_format、promptCacheKey→prompt_cache_key。测试 cerebras-chat-language-model.test.ts 验证了这些映射，并确认转换后请求体中不再残留 camelCase 字段。

2. 推理历史的字段兼容：Cerebras 期望助手（assistant）的推理历史放在reasoning字段中，而共享的 OpenAI 兼容转换器序列化时用的是reasoning_content。该函数会把reasoning_content重写为reasoning（若消息中不存在reasoning字段），保证多轮对话中的推理上下文能被 Cerebras 正确理解。对应的测试用例见 cerebras-provider.test.ts。

结构化输出与工具调用的混合响应处理

CerebrasChatLanguageModel继承自OpenAICompatibleChatLanguageModel（cerebras-chat-language-model.ts），并在doGenerate与doStream中覆写了 finish reason 归一化逻辑：

• 当请求为 JSON 结构化输出（responseFormat.type === 'json'）且原始 finish reason 为tool_calls，但同时已产生有效文本内容时，说明 Cerebras GLM 模型在输出合规结构化文本后又重复了一次工具调用。此时 Provider 会把这种混合响应视为最终答案：丢弃多余的工具调用、将 unified finish reason 归一化为stop（cerebras-chat-language-model.ts）。
• 流式场景下，通过TransformStream在text-delta出现后过滤掉后续的tool-input-*与tool-call分片，与doGenerate的行为保持一致（cerebras-chat-language-model.ts）。

上述行为均有对应测试佐证：doGenerate的 finish reason 归一化用例见 cerebras-chat-language-model.test.ts，流式场景见同文件 L243-L323，测试数据来自 fixtures 目录下的真实请求/响应夹具。

错误结构与鉴权

Provider 为 Cerebras API 定义了 zod 驱动的错误解析 schema（message/type/param/code四字段），错误消息直接取自message字段（cerebras-provider.ts），并导出CerebrasErrorData类型供上层做错误分类。API Key 的加载统一走loadApiKey，支持显式传入或回退到CEREBRAS_API_KEY环境变量（cerebras-provider.ts）。

结合 AI SDK 生态的典型落地路径

Cerebras provider 与 AI SDK 的核心能力天然打通，可以在同一套代码中组合使用：

• 结构化输出：配合generateObject或responseFormat使用strictJsonSchema: true，借助 Cerebras 的约束解码获得严格符合 Schema 的 JSON；
• Agent / 工具调用：在generateText/streamText中传入tools，配合parallelToolCalls开启并行工具调用，多轮对话中 Cerebras 的推理历史通过reasoning字段正确回传；
• 观测与缓存：通过promptCacheKey提升缓存命中率，结合 usage 中的cacheRead/cacheWrite字段观测实际缓存效果（见 cerebras-chat-language-model.test.ts 中inputTokens.cacheRead的断言）。

小结

@ai-sdk/cerebras以极小的接入成本把 Cerebras 的 Wafer-Scale 高速推理能力带入 AI SDK 生态：安装一个包、导入cerebras实例、传入模型 ID 即可开始调用。在源码层面，它通过@ai-sdk/openai-compatible复用成熟的 OpenAI 兼容协议处理链路，并用请求体转换（reasoning_content→reasoning）、结构化输出混合响应的 finish reason 归一化等定制逻辑，解决了与 Cerebras API 的实际差异。

进一步阅读：

• Cerebras Provider 官方文档（同时会随包发布到docs/目录）
• Provider 实例与设置实现
• 语言模型实现
• Provider 选项 Schema
• Provider 测试 与 语言模型测试

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