AI SDK 3.0.19 发布：凭证解析与 WebSocket 配置异步化

rss source: @ai-sdk/topaz@3.0.19

AI SDK 的 @ai-sdk/topaz 包发布了 3.0.19 版本，这是一次以补丁更新（patch）形式交付的变更，但其中两项改动对开发者接入鉴权与实时连接的方式都有实际影响。

凭证配置支持 Promise 与回调

本次更新最核心的变化来自 commit 7716e18：provider 的 API key 与 token 设置现在支持 Promise，以及同步或异步的回调函数。

在此之前，凭证通常在初始化时被同步读取并序列化，这意味着开发者很难把密钥托管在异步获取的来源上，例如远程密钥管理服务或运行时才可用的临时凭证。新版本允许在每个已认证请求发生时解析凭证，而非在构造阶段一次性固定。

官方说明强调，这一改动「在保留现有鉴权行为与同步凭证序列化能力的前提下」，按请求解析凭证。换句话说，同步写法仍然可用，异步写法是新增能力而非破坏性替换。对于需要多租户隔离或动态轮换密钥的应用，这减少了在业务层自行包一层异步取 key 逻辑的必要。

Provider（提供者） 在 AI SDK 中是描述某个模型服务（如 OpenAI、Anthropic 或自建推理端点）接入方式的抽象层：它封装了基础 URL、鉴权头、请求序列化等逻辑，并由 @ai-sdk/provider 包定义统一接口。每次调用 generateText、streamText 等方法时，SDK 会通过 provider 实例构造底层 HTTP 请求。正因如此，凭证配置的位置（构造期还是请求期）直接决定了密钥能否动态获取。

所谓凭证序列化，指 provider 在初始化时把 API key、token 等字段转成字符串并固定保存在配置对象中，后续请求直接复用该字符串。这种做法的优点是行为可预测、便于缓存，但缺点是无法表达「此刻还拿不到密钥」的异步场景。本次改为按请求解析后，provider 每次发出已认证请求前都会重新求值凭证配置，从而支持从异步来源读取。

getServerWebSocketConfig() 可异步返回

另一项面向实验性功能的变化是 OpenAI Live 的 getServerWebSocketConfig() 方法。该方法现在可以异步解析，官方提示调用方必须先 await 其结果，再使用返回的连接设置。

这对已经在使用 Live 相关能力的项目是一个需要主动适配的点：如果此前直接把返回值当作同步对象使用，升级后应改为先等待 promise。实验性 API 本身不承诺稳定性，但这类签名变化值得在升级清单里单独标注。

WebSocket 是一种在单个 TCP 连接上提供全双工通信的协议，与 HTTP 的「一问一答」不同，连接建立后服务端可主动向客户端推送数据。OpenAI 的实时语音/多模态接口（Realtime API）即基于 WebSocket 传输音频与事件流，因此 AI SDK 需要为服务端提供建立该连接的配置，包括 URL、鉴权头以及子协议等。

getServerWebSocketConfig() 返回的正是这组连接参数。将其改为可异步解析，通常是为了让配置在真正建立连接前才去获取短期有效的令牌或签名 URL——这类凭证生命周期短，无法在应用启动时静态写死。代价是调用方必须 await，否则拿到的是 Promise 对象而非配置，连接会直接失败。

依赖同步更新

该版本随附三项依赖更新，分别对应 commit 5c247e9 与 dcd2f8d，涉及：

@ai-sdk/provider-utils@5.0.72
@ai-sdk/provider@4.0.35

这类连带升级通常用于对齐底层 provider 抽象与工具函数的行为，尤其是凭证解析逻辑变更往往需要底层包的配合。升级时建议一并核对这两个包的版本，避免出现 provider 层与 utils 层行为不一致的情况。

语义化版本（SemVer） 中，3.0.19 的第三位数字递增表示补丁发布，按约定只应包含向后兼容的缺陷修复，不引入破坏性变更。但「API 表面兼容」不等于「运行时行为完全不变」：本次凭证解析时机的调整属于行为层面的变化，仍可能影响依赖旧时序的代码。

@ai-sdk/provider 与 @ai-sdk/provider-utils 是 AI SDK 生态的底层基础包，前者定义 provider 接口与类型，后者提供请求构造、流解析、错误处理等共享工具。上层具体 provider 包（如 @ai-sdk/topaz）依赖它们的能力实现鉴权。当凭证解析逻辑从构造期移到请求期时，往往需要底层 utils 提供对应的求值辅助函数，这也是两个包需要同步升级的原因。

升级建议

由于是补丁版本，API 表面变化有限，但凭证解析时机的改变会影响到对「key 何时被读取」有假设的代码。如果你的鉴权逻辑依赖构造期读取、或对凭证做了同步序列化缓存，升级后应验证这些路径是否仍按预期工作。使用 OpenAI Live 的项目则需要检查 getServerWebSocketConfig() 的调用点是否已加上 await。

整体来看，这次更新把凭证与连接配置的处理向异步模型推进了一步，方向与当前应用对动态密钥管理和实时连接的需求一致。