AI SDK xAI 5.0.36 修复：不再误报 other，正确返回 length

一次小而关键的补丁：让 token 截断不再被误判

在构建依赖大模型的应用时，最令人头疼的问题之一不是模型能力不足，而是错误被悄悄吞掉。AI SDK 的 xAI 提供方刚刚发布了 @ai-sdk/xai@5.0.36 补丁版本，修复的正是这样一个容易被忽视但影响排查效率的问题：当响应因 max_output_tokens 被截断时，finish reason 不再错误地报成 other，而是正确映射为 length。

这一改动来自提交 3d6ac0a，在 Responses 模式下针对 generateText 调用，将 incomplete_details.reason 映射到 finish reason。版本发布由 GitHub Actions 自动完成，共包含 13 个提交，并附带了 GitHub 验证签名。

问题出在哪：other 是个信息黑洞

finish reason 是调用方判断模型输出是否完整的第一手信号。常见的取值如 stop、length、tool-calls、content-filter 等，各自对应明确的处理路径。而 other 本质上是一个兜底值——它告诉你"有东西不对劲"，却不告诉你"哪里不对劲"。

当一个请求设置了 max_output_tokens，模型输出达到上限被截断时，正确的语义是 length。调用方可以据此决定是提高上限重试、分段续写，还是提示用户内容不完整。但在修复前，xAI 提供方在 Responses 路径下返回的是 other，开发者只能靠猜或额外打日志去推断，自动化重试逻辑也无从触发。

为什么只在 Responses 出现

这次修复的提交信息明确指向 Responses 模式下的 generateText。AI SDK 对不同提供方和不同 API 形态做了适配层，xAI 的 Responses 接口在 incomplete_details.reason 字段里返回了截断原因，但适配层此前没有把它翻译成统一的 finish reason 枚举值。属于典型的"上游字段有了，下游没接上"的映射遗漏。

finish reason 与 incomplete_details.reason 的语义差异

finish reason 是 AI SDK 跨提供方统一抽象出的终止原因枚举，取值如 stop、length、tool-calls、content-filter、other 等，供调用方以同一套逻辑处理不同模型的输出。而 incomplete_details.reason 是 xAI Responses API 原生返回的字段，属于提供方私有表达，可能包含 max_output_tokens、content_filter 等更贴近底层的原因字符串。适配层的职责是在两者之间建立多对一映射：把提供方特有的 reason 翻译成 SDK 统一枚举。映射表遗漏某一项时，代码会落入 other 兜底分支——这正是本次 bug 的成因。理解这一层关系，有助于开发者在其他提供方或新接口出现类似问题时快速定位是映射缺失而非模型异常。

对开发者的实际影响

错误处理分支终于能命中

如果你的代码里有类似 if (finishReason === 'length') 的分支，这个补丁直接让它生效。对于长文本生成、代码补全、结构化输出等容易触碰 token 上限的场景，这意味着一处真实的逻辑缺陷被修复，而不是靠提高上限来掩盖问题。

可观测性提升

监控面板上 other 的计数会明显下降，length 的计数相应上升。这不是数字游戏——区分"模型正常结束"和"模型被强制截断"，是评估输出质量和容量的基础指标。此前被归入 other 的截断请求，在告警和报表里都是噪声。

升级建议

这是一个补丁级版本，改动范围收敛在映射逻辑，没有引入新的 API 面。依赖 @ai-sdk/xai 且使用 Responses 接口的团队，建议尽快升级；如果目前主要走 Chat Completions 路径，影响相对有限，但统一版本仍是更稳妥的做法。

补丁版本与语义化版本（SemVer）

5.0.36 属于语义化版本中的 patch 位，按约定只应包含向后兼容的缺陷修复，不引入新 API 或破坏性变更。因此升级风险很低，通常只需更新依赖并跑一遍现有测试即可。相对地，minor 位（如 5.1.0）可能新增功能，major 位（如 6.0.0）才允许破坏性改动。判断一个修复能否安全落地，先看它落在哪一位是高效的经验法则。本次改动收敛在映射逻辑内部，未改动函数签名或返回结构，符合 patch 版本的定位，团队可以放心将其纳入常规依赖更新流程。

从这次修复看适配层的价值

多提供方 AI SDK 的核心价值在于抹平差异，而抹平的难点恰恰在"语义对齐"而非"字段搬运"。incomplete_details.reason 是 xAI 侧的表达，finish reason 是 SDK 的统一抽象，两者之间的映射表每漏一项，调用方就要多写一层防御代码。

这类补丁不会出现在发布会的聚光灯下，却直接决定了开发者调试时是看一行清晰的枚举值，还是对着 other 翻文档。对于把 AI 能力嵌入生产系统的团队来说，选择维护活跃、映射及时的 SDK，其长期收益往往大于短期内的功能丰富度。

本次发布同时带有 GitHub 验证签名，供应链层面的可追溯性也值得留意——在 AI 工具链日益复杂的今天，这类基础卫生同样重要。