AI SDK xAI 5.0.33 发布：统一推理选项映射逻辑

AI SDK 的 xAI 供应商包发布 5.0.33 补丁版本，核心改动围绕一个看似不起眼、实际影响面很广的问题：不同模型供应商对 reasoning（推理强度）参数的理解并不一致。这次更新把跨供应商的映射规则统一成一套可预期的逻辑，直接影响到 OpenAI、Fireworks、Anthropic、Bedrock、DeepSeek、Gemini 等多个接入方。

推理参数为什么需要"翻译"

在 AI SDK 的抽象层里，调用方通常只需要给出一个顶层的 reasoning 值，比如 'high'、'medium' 或 'none'。但底层各家 API 的档位划分并不相同：有的模型支持 'xhigh'，有的只到 'high'；有的模型根本不允许关闭推理；还有的对某些档位直接报错。

于是 SDK 需要做一层映射。此前这层映射是各供应商各自实现、各自拍板的，结果就是同一句调用在不同 provider 上行为不一致。5.0.33 的补丁提交（61a315e）把这个逻辑收敛为一条统一规则。

AI SDK 的分层抽象：AI SDK（原名 Vercel AI SDK）是一个面向 TypeScript/JavaScript 的模型调用统一层，核心价值在于让开发者用同一套接口调用不同厂商的模型。它的抽象分为几层：顶层是 generateText/streamText 这类通用函数，以及 reasoning 这样的跨模型通用参数；中间层是 provider 适配器（如 @ai-sdk/openai、@ai-sdk/anthropic）；底层是各厂商原生 API。providerOptions 则是官方留出的"逃生舱口"，允许调用方按供应商命名空间直接传递原厂参数，绕过通用层的归一化处理。理解这一分层，才能明白为什么"顶层参数自动映射"与"providerOptions 原样透传"会并存——前者追求一致性，后者保留精确控制能力。

推理强度（reasoning effort）：这是 2025 年后随推理模型普及而出现的参数概念，用于控制模型在给出答案前进行"思维链"计算的预算。OpenAI 的 reasoning_effort 取值包括 minimal/low/medium/high，Anthropic 通过 thinking.budget_tokens 以 token 数表达，Google Gemini 则用 thinkingBudget。不同厂商不仅档位名称不同，连"能否关闭"都不一致——有的模型强制推理，有的允许 none。这正是映射层必须存在、且必须谨慎设计的根本原因。

新规则：尽量贴近调用方的本意

根据发布说明，统一后的解析逻辑分几种情况：

第一，providerOptions 里的专属设置原样透传。 如果调用方显式写了 providerOptions.openai.reasoningEffort，这个值会原封不动发给 OpenAI，SDK 不再因为该值不在模型的档位列表里就把它丢掉。Fireworks 同理，不再改写 providerOptions.fireworks.reasoningEffort。

第二，顶层 reasoning 尽量映射到模型支持的最接近档位，优先向下取整。 只有在没有更低档位可选时才向上取整。发布说明给了两个具体例子：在缺少 xhigh 档位的 Anthropic 和 Bedrock 模型上，'xhigh' 现在映射为 'high'，而不是此前可能出现的 'max'；在 DeepSeek^广告、Kimi K3 和 Mistral GLM-5.3 这类模型上，'medium' 映射为 'low'，而不是 'high'。

第三，无法关闭推理的模型，'none' 降级到最低档并给出兼容性警告。 此前这类请求要么被静默丢弃，要么直接发出去被 API 拒绝。新逻辑改为映射到模型的最低推理档位，同时发出 compatibility warning。受影响的包括不支持 'none' 的 GPT-6 系列、xAI grok-4.5 及之后的版本、Groq 上的 GPT-OSS、Kimi K3、Perplexity、QuiverAI、Bedrock 上的 OpenAI gpt-oss 模型，以及 Gemini 2.5 Pro（最小思考预算）。Gemini 3 以及 Anthropic、Bedrock 的 between_tools 映射现在也会发出同样的警告。

第四，Fireworks 的例外清单。 Fireworks 现在直接发送顶层 reasoning 值，不再统一压到 'high' 封顶——但对已知会拒绝特定值的模型家族保留例外：GPT-OSS、GLM-5.3、Muse Spark 拒绝 'none'，Nemotron 和 Inkling 拒绝 'minimal'。

compatibility warning 机制：AI SDK 在遇到"调用方意图无法被目标模型完整满足"的情况时，会通过 warnings 数组返回兼容性警告，而不是抛出异常中断请求。这些警告可从 generateText/streamText 的结果对象中读取，通常带有 type: 'unsupported-setting' 之类的标识。对生产环境而言，这一设计意味着请求仍能成功完成，但调用方可据此做埋点监控、上报或降级提示。相比静默丢弃参数（问题被掩盖）和 API 报错（请求直接失败），警告机制在"可用性"与"可观测性"之间取了折中，是多模型路由场景下推荐主动消费的信号。

两个映射函数的签名变化

这次补丁还调整了两个内部工具的接口，对直接使用它们的开发者有影响：

• mapReasoningToProviderEffort 现在接受任意 reasoning 值，返回可选的 providerOptionsEffort（保持原值不变），并对 effort map 中缺失的档位按最接近的受支持档位取整。
• mapReasoningToProviderBudget 把 'none' 映射到最小推理预算，并且总是返回一个预算值；对于 budgetPercentages 中缺失的档位，使用默认百分比。

另外，OpenAICompatibleChatConfig 新增了一个可选的 mapReasoning 函数，供兼容 OpenAI 协议的供应商自定义顶层 reasoning 的映射方式。

预算式与档位式两种推理控制：映射函数之所以分成 mapReasoningToProviderEffort 和 mapReasoningToProviderBudget 两个，是因为厂商控制推理深度的方式本质不同。档位式（effort）用离散标签表达，如 OpenAI 的 low/medium/high；预算式（budget）用 token 数量表达，如 Anthropic 的 thinking.budget_tokens 和 Gemini 的 thinkingBudget。预算式通常需要结合模型的上下文窗口或最大输出 token 数按百分比换算，因此函数签名中出现 budgetPercentages 配置，并在档位缺失时回退到默认百分比。这也解释了为什么后者"总是返回一个预算值"——预算式接口没有"不设置"的中间态，必须给出具体数值才能发出合法请求。

对开发者的实际意义

这次改动表面上是一次 patch 级别的依赖更新（同时升级了 @ai-sdk/provider-utils@5.0.71），但它解决的是一个长期困扰多模型应用的隐患：同一个推理强度配置在不同 provider 上产生截然不同的行为。

对于需要跨模型切换、做 A/B 对比或构建模型路由层的团队来说，统一映射意味着更少的"玄学"调参。尤其是 'none' 的处理方式从"静默丢弃或报错"变成"降级加警告"，让不可关闭推理的模型行为变得可预测，也便于在上层捕获警告做监控。

需要留意的是，向下取整的默认策略意味着部分场景下实际推理强度会低于调用方预期。如果你的应用依赖 'xhigh' 或 'medium' 这类较高档位的精确语义，建议通过 providerOptions 显式指定，而不是依赖顶层参数自动映射。

升级方式为常规的依赖版本更新，该版本基于 main 分支的 2 个提交构建。