AI SDK xAI 5.0.16 更新：新增 max 推理级别与跨提供商兼容

Vercel AI SDK 旗下的 xAI 提供商包 @ai-sdk/xai 发布了 5.0.16 补丁版本。虽然版本号只是一个小小的 patch 更新，但背后带来的变化却关系到所有使用推理（reasoning）能力的开发者——这次更新引入了一个可移植的 max 推理级别，并对多家底层模型提供商做了兼容性映射处理。

核心变更：可移植的 max 推理级别

本次更新最重要的改动，是在 provider 层新增了一个可移植（portable）的 max 推理级别，并配套提供了原生提供商映射、兼容性强制转换以及基于预算（budget-based）的回退支持。

这意味着开发者可以用统一的 reasoning: 'max' 配置来请求模型投入最高强度的推理资源，而无需关心每个底层提供商的具体参数命名。SDK 会在内部将这个抽象级别翻译成各家模型实际支持的参数。这是 AI SDK 一贯的设计哲学：用统一抽象层屏蔽不同模型厂商之间的差异，让上层代码保持可移植。

@ai-sdk/xai 5.0.16 发布说明

不过，这个看似简单的新增字段，在类型系统层面带来了需要开发者留意的连锁反应。

推理级别（reasoning level）是 AI SDK 对模型"思考强度"的抽象封装。不同模型厂商对此有各自的参数体系：Anthropic 用 budget_tokens 控制思考 token 上限，OpenAI 用 reasoning_effort（low/medium/high），Amazon Bedrock Nova 系列则用 maxReasoningEffort。AI SDK 在 provider 层引入统一的可移植级别枚举（如 minimal、low、medium、high、xhigh，现新增 max），开发者只需声明抽象意图，SDK 内部负责翻译为各家的实际参数。基于预算的回退（budget-based fallback）则是指：当目标提供商不原生支持某个抽象级别时，SDK 会换算成该提供商能理解的 token 预算数值来近似实现同等效果，而非直接报错或静默忽略。

TypeScript 类型兼容性需要注意

新增 max 会同时扩宽 LanguageModelV4CallOptions['reasoning'] 类型以及由此派生的 ReasoningLevel 类型。对于普通调用来说，使用现有推理级别的代码依然被完全接受，无需改动。

但有一类代码会受到影响：如果你的第三方 provider 实现或消费端代码使用了穷举式 switch 语句，或者依赖 Record<ReasoningLevel, ...> 这样的映射类型，那么在升级前必须先处理好 max 这个新成员，否则会触发 TypeScript 编译错误。这是典型的联合类型扩展带来的破坏性影响，值得在升级时重点排查。

联合类型扩展（union type widening）是 TypeScript 中一类常见的破坏性变更场景。当 ReasoningLevel 原本定义为 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' 时，穷举式 switch 语句可以在 default 分支中获得 never 类型保证，即编译器确认所有情况已被覆盖。一旦联合类型新增成员 'max'，原有的 switch 语句 default 分支就不再是 never，TypeScript 会报告类型错误。同理，Record<ReasoningLevel, SomeValue> 这类映射类型要求每个枚举成员都有对应键，新增成员意味着旧的对象字面量定义缺少 max 键，同样触发编译失败。排查时可以在项目中全局搜索 ReasoningLevel 以及字面量 'xhigh' 附近的 switch/Record 用法，逐一补全 max 分支。

各提供商的兼容性映射策略

这次更新的精细之处，在于它针对不同底层提供商给出了差异化的降级与映射方案，并通过兼容性警告（compatibility warning）明确告知开发者实际发送的参数。

Amazon Bedrock

现有使用可移植 reasoning: 'xhigh' 的 Nova 2 调用，现在会发送 maxReasoningEffort: 'high'，而不再发送不被支持的 'max'，同时返回一条兼容性警告。而 Bedrock 上的 Anthropic 和 OpenAI 模型则保留原有的 xhigh 行为。

此外，部分 Bedrock 推理配置会继续保留显式值并自动推导缺失字段；显式的 effort/budget 覆盖以及被禁用的 thinking 配置，不再对未实际发送的可移植映射发出警告——这降低了不必要的告警噪音。

Fireworks

在 Fireworks 平台上，可移植的 minimal 和 xhigh 调用分别保持映射到 low 和 high，但现在会在生成和流式结果中返回兼容性警告。新增的可移植 max 则映射到 high，并采用相同的警告行为。

这种做法的意图很清晰：在保证旧代码行为不变的前提下，通过警告机制提示开发者当前使用的抽象级别在该提供商上并非精确对应，而是经过了降级处理。

为什么这是一个 patch 版本

按照常理，扩展公开类型、新增字段往往会被归为 minor 甚至 major 版本。但官方在发布说明中特别解释了版本分类的逻辑：

根据该仓库的显式发布策略，patch 版本同时用于修复和功能发布。上文披露的 TypeScript 源码兼容性注意事项，已经作为透明的说明给出。维护者保留在未来 AI SDK 大版本中，用 major 标签重新对齐这一 provider-spec 新增项的权利。

换句话说，这是一个符合仓库发布规范的决策，而非疏忽。开发者在升级时仍应把它当作可能影响类型检查的变更来对待。

语义化版本（Semantic Versioning，SemVer）规范中，patch 版本通常仅限于向后兼容的 bug 修复，新增公开 API 或扩展类型应归为 minor，引入破坏性变更则需要 major。然而 SemVer 同时允许项目在 README 或发布策略文档中声明对该规范的定制性解释。Vercel AI SDK 采用了"patch 兼做功能发布"的策略，这在快速迭代的基础设施库中并不少见——其背后逻辑通常是：维护者认为变更的实际影响面足够小，或者已通过充分的类型说明将风险转移给消费方。对于使用方来说，无论官方如何定义版本号，升级时都应查阅 CHANGELOG，并在 CI 中运行完整的类型检查，而不能仅凭 patch 标签判断安全性。

其他改动与依赖更新

除了推理级别的核心变化，这个版本还包含两项值得一提的改动：

升级到 TypeScript 6：工程层面的工具链更新，为后续特性演进打好基础。
修复语音分离（speaker diarization）处理：当该能力不可用时，现在会正确保留或上报状态，而不是静默处理。

同时，本次发布也联动更新了多个依赖包，包括 @ai-sdk/provider-utils@5.0.55 和 @ai-sdk/provider@4.0.23。

小结

对于正在使用 AI SDK 构建推理型应用的团队来说，5.0.16 的 max 推理级别提供了更强、更统一的推理强度控制入口，而配套的兼容性映射和警告机制也体现了该项目对跨提供商一致性的持续投入。升级本身风险不大，但使用穷举式类型匹配的代码库务必在升级前检查 ReasoningLevel 的处理逻辑。