Cloudflare createAI 更新：全栈项目如何迁移模型接入层

这次更新影响哪些项目

旧接入包进入功能冻结

Cloudflare 在2026年10月21日的更新中，将 Workers AI 与 AI Gateway 的主要模型接入能力整合到 Agents SDK 的 createAI 函数中，同时把 workers-ai-provider 和 ai-gateway-provider 标记为弃用、停止新增功能。官方建议安排迁移，但公告没有给出强制停服日期。已经使用这两个包的聊天、检索和智能体应用，应先盘点依赖，不必把“弃用”理解为当天必须紧急替换。官方更新

新入口仍处于 Beta

模型文档明确标注新 provider 仍为 Beta，次版本更新可能改变接口；AI SDK 和 Pi AI 有各自入口。因此，团队应将这次升级当作有兼容性风险的依赖迁移。本文后续的测试与发布步骤属于工程分析和实施建议，并非 Cloudflare 宣布的额外产品保证。Models 文档

先画出调用链，再替换导入

区分应用入口与模型入口

一个全栈聊天应用通常同时包含浏览器状态、服务端鉴权、模型调用和工具执行。建议先列出“用户请求经过哪些组件”，再找出旧 provider 所在位置。这样可以把改动限制在服务端适配层，避免为了换一个包而同步重写前端消息协议、数据库结构与业务工具。

盘点表至少记录路由名称、模型来源、流式或非流式调用、是否输出结构化对象、是否执行工具，以及错误如何传递给前端。若一条入口还承担支付确认或数据修改，应单独标记，不能用普通文本聊天成功来代替其验收。

模型字符串与厂商对象要分开检查

新接口可接收 Workers AI 标识、网关目录标识、动态路由，或厂商 provider 创建的模型对象。不同形式的路由与请求处理并不完全相同，目录名称还应使用网关目录中的拼写。Models 文档

因此，迁移时不宜全局替换字符串。建议把现有模型配置整理成一份受版本控制的清单，逐项核对实际请求走向。测试环境先保持模型和提示词不变，单独观察接入层变化；若同时换模型，即使结果变好，也难判断收益来自哪里。

三组容易遗漏的回归测试

依赖版本与输出结构

AI SDK 接入文档列出的依赖要求包括 ai 的第七代版本和 provider 的第四代版本；AI Search 则使用独立的 ai-search-provider。迁移前应核对锁文件与实际安装版本，而不是只看顶层包名。AI SDK 接入文档

建议保留一组固定输入，覆盖空消息、长对话、中文文本、工具参数和结构化输出。断言应检查字段、类型、结束原因及错误分类，而非逐字比较具有随机性的回答。对于业务必须满足的约束，例如订单编号不能缺失，应由应用校验，不要交给模型文字承诺。

回退与恢复不是同一条路径

文档区分了两种能力：fallback 在模型尚未输出时尝试后备模型；通过 binding 调用的目录模型或动态路由，可以在流中断后恢复。后者不覆盖全部模型形式，也不是无限重试。AI SDK 接入文档

测试可以设置三种场景：首个输出前失败、已有部分输出后断开、用户主动取消。分别观察前端是否重复追加内容、是否及时退出加载状态，以及服务端是否仍在执行。不要把一次恢复成功推广成所有网络错误都能透明消失。涉及工具副作用时，还应使用业务请求编号防止重复执行。

错误不能只剩一个通用提示

建议将权限不足、模型配置错误、限流、上游故障和用户取消分开记录。前端可以显示简短提示，但日志应保留可定位的信息。否则升级后出现大量“稍后重试”，团队很难区分配置问题与服务故障，也可能把本不该重试的请求反复发送。

回归报告最好附带请求编号、部署版本和触发条件，并使用脱敏样本。客户原始输入不应为了排查方便而默认复制到每一套日志系统。

凭证、日志与成本也要一起验收

检查环境隔离

建议明确开发、预览和生产使用哪个账户、网关与凭证来源。迁移分支只使用测试权限，避免预览部署意外消耗生产额度。密钥应留在服务端受控配置中，前端只访问自家应用接口；也不要把调试用令牌写进示例代码或错误响应。

权限调整与代码合并可以分开审核。这样即使代码回滚，团队也能知道是否还遗留新的访问授权，防止“功能已撤回、权限却仍扩大”的状态。

用实际链路核对计费

统一调用入口会减少适配代码，但不能据此推导成本自动下降。建议对比正常请求与失败请求的总调用次数、耗时和实际回答模型，再检查重试与回退是否叠加。测试数据应注明样本规模和配置，不能把少量请求的结果直接写成普遍节省比例。

对缓存和日志，也应按业务敏感度逐项检查。共享答案与个性化答案可以采用不同策略，避免为了命中率而把用户隔离要求模糊掉。

一个可回滚的迁移顺序

第一阶段：建立基线

在旧接入层保留时记录关键路径的成功率、首个输出耗时、完整响应耗时和取消行为。挑选既有稳定样本，也加入已知失败样本。基线的作用是让新旧版本可比较，而不是证明旧版本没有问题。

第二阶段：局部切换

先迁移低风险、只读的一条服务端入口，保持前端协议不变。通过配置开关控制新旧实现，并提前演练回滚。若出现错误分类丢失、工具参数变化或取消失效，先恢复原路径，再分析原因，不要一边扩大流量一边补基本测试。

灰度阶段还应明确谁负责观察和决定退出。如果只设一个总错误率，低频但重要的工具调用失败可能被大量普通对话掩盖。建议按入口分别查看指标，并把一次重复写入、一次权限越界等严重问题设置为立即停止扩大的信号；阈值由业务风险确定，不套用统一百分比。

第三阶段：扩大覆盖并清理旧依赖

确认核心路径满足验收条件后，再扩展到其他模型和多模态功能。删除旧包之前，应扫描直接与间接引用、部署脚本和测试夹具。发布记录保留版本、路由清单及回滚条件，方便后续 Beta 迭代继续复测。

这次更新给全栈团队带来的直接机会，是减少分散的模型适配代码。迁移是否成功，最终仍要看真实业务路径能否保持正确的输出、权限和故障处理，而不只是项目能否编译通过。