AI SDK Provider 模型 ID 维护指南在 TypeScript AI 工具库中安全新增与移除模型【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai导读本文基于 AI SDKThe AI Toolkit for TypeScript官方仓库中的维护技能文档 skills/update-provider-models/SKILL.md 展开系统讲解如何在 AI SDK monorepo 中为已有 Provider 新增模型 ID、移除过时模型 ID 的完整流程。你将掌握如何用精确搜索定位一个模型 ID 在packages/、content/、examples/中的全部引用点如何同步更新类型联合、能力表格、示例与测试以及如何在 AI Gateway 中保持模型路由一致。无论你是向xai、openai、google等主 Provider 增加一个刚发布的新模型还是清理某个已下线的旧模型这套双工作流都能保证改动准确、不破坏排序与快照。一、理解模型 ID 在仓库中的分布AI SDK 采用 pnpm monorepo 组织一个 Provider 的模型 ID 并非只存在于一处。从源码结构看模型 ID 至少会出现在以下四类位置位置作用示例路径类型定义提供编译期校验的模型 ID 联合类型packages/xai/src/xai-chat-language-model-options.tsAI Gateway 路由表统一网关的模型 ID 白名单packages/gateway/src/gateway-language-model-settings.ts文档能力表格展示模型支持的功能矩阵content/providers/01-ai-sdk-providers/*.mdx示例与测试可运行代码与快照断言examples/ai-functions/src/generate-text/provider/、packages/provider/src/**/*.test.ts以 xAI 的聊天模型为例packages/xai/src/xai-chat-language-model-options.ts 中通过(string {})保留了对任意字符串的开放能力同时用字面量联合提供 IDE 自动补全与文档提示export type XaiChatModelId | grok-4.20-non-reasoning | grok-4.20-reasoning | grok-4.3 | grok-4.5 | grok-4.6 | grok-latest | (string {});而 AI Gateway 侧的GatewayModelId则使用provider/model-id格式统一命名空间如openai/gpt-5.4、anthropic/claude-sonnet-4.5并同样以(string {})结尾保持向后兼容见 packages/gateway/src/gateway-language-model-settings.ts。结论新增或移除一个模型 ID本质上是围绕一个字符串 ID 的跨文件一致性维护任务。下面两套工作流正是围绕这一目标设计的。二、执行前的关键规则Critical Rules无论走哪套工作流以下规则必须始终遵守精确匹配杜绝子串误伤模型 ID 常常是其他 ID 的子串如grok-3与grok-3-mini、gpt-5.4与gpt-5.4-pro。每次搜索命中都必须人工核对该结果确实是目标模型而不是子串匹配。尊重既有排序向任何列表类型联合、表格行、数组插入条目时先观察现有顺序把新条目放到正确位置。AI SDK 各 Provider 的 options 文件普遍按字母序/版本序组织。示例文件命名用 kebab-case点号替换为连字符例如gpt-5.4-codex对应的示例文件名为gpt-5-4-codex.ts。批量任务逐个处理一次处理多个模型时必须完成一个模型的全部工作流后再开始下一个避免上下文混淆导致漏改。主 Provider AI Gateway 是必改项新模型 ID 永远要同时加入主 Provider 包和 AI Gateway。若模型同时出现在 Bedrock、Vertex、OpenAI-compatible 等其他包中或出现在这些包的测试/文档里也需要一并处理。不做无关改动只更新模型 ID 及其相关引用不要顺手修改文件中的其他代码、文本或格式。绝不触碰packages/codemod的CHANGELOG.mdChangelog 是历史记录codemod 是迁移脚本两者在更新模型 ID 时都不得编辑。三、工作流 A新增模型 IDadding-new-modelStep 1明确改动范围动手前先确定四件事Provider 名称如anthropic、openai、google、xai精确的模型 ID 字符串如claude-haiku-4-5-20260218、gemini-3.1-pro、gpt-5.4-codex模型类型chat对话、embedding嵌入、image图像等这决定了要更新的 options 文件与示例目录模型关系是旧模型的新版本还是某个 preview/experimental 模型的稳定版这直接决定 Step 4/5 是新增还是替换推荐引用。另外要判断是否有主 Provider 与 AI Gateway 之外的受影响包Bedrock、Vertex、OpenAI-compatible 等如果在这些包的源码或文档里已列出相似模型 ID那么新模型 ID 大概率也应加入。以 Bedrock 为例其聊天模型类型定义位于 packages/amazon-bedrock/src/amazon-bedrock-chat-language-model-options.tsVertex 对应packages/google-vertex/src/*-options.ts。Step 2搜索相似模型的全部引用用同一 Provider 的相似模型更低版本或即将被替代的 preview 版本作为探针在packages/、content/、examples/三个顶层目录中搜索即可暴露所有需要同步更新的位置。注意给模型 ID 加上引号以排除子串误报# 单引号TypeScript 源码、类型联合 grep -r similar-model-id packages/ content/ examples/ --include*.ts --include*.mdx --include*.md # 双引号快照中的 JSON、测试夹具内嵌 JSON、文档 grep -r similar-model-id packages/ content/ examples/ --include*.ts --include*.mdx --include*.md这不是穷举清单——Step 2 的搜索结果可能会揭示其他需要更新的文件如 README 代码示例、e2e 测试数组等。Step 3更新类型定义对 Step 2 找到的每个相关packages文件把新模型 ID 加入类型联合如存在 const 数组也一并加入并遵守排序。常见的类型定义位置packages/provider/src/*-options.ts—— 主 Provider 包packages/gateway/src/gateway-language-model-settings.ts—— AI Gateway 包语言模型packages/amazon-bedrock/src/**/*-options.ts—— 模型在 Amazon Bedrock 上可用时packages/google-vertex/src/*-options.ts—— 模型在 Google Vertex 上可用时。类型联合的插入示例注意注释标记插入点以及末尾的(string {})保留export type SomeModelId | existing-model-a | new-model-id // ← add in sorted position | existing-model-b | (string {});const 数组的插入示例如reasoningModelIdsexport const reasoningModelIds [ existing-model-a, new-model-id, // ← add in sorted position existing-model-b, ] as const;重要约束在类型定义中绝不替换旧模型 ID只做新增。把旧/preview 模型引用替换为新模型只发生在文档与示例中见 Step 4、Step 5。Step 4更新文档对content/下每个命中的.mdx文件能力表格为新模型在正确位置插入一行并用Check /支持或Cross /不支持标记各项能力。仓库中此类表格的实例如 content/docs/02-foundations/02-providers-and-models.mdx其中每个 Provider 一行、按模型版本降序排列、用能力列区分推理/结构化输出等差异。内联代码示例如果新模型是旧/preview 模型的稳定替代把代码片段中的const model provider(old-model)更新为使用新模型。Latest描述更新类似 Latest model with enhanced reasoning 的文案指向新模型。若 Step 2 发现相似模型 ID 出现在某 Provider 包的README.md代码示例中同样要更新那里的模型 ID。Step 5创建或更新示例新模型替代旧模型找到使用旧模型的现有示例并更新为新模型 ID。全新模型、无前身为每个与新模型相关的一级函数如generateText、streamText、generateImage创建一个新示例文件。例如新语言模型需要创建examples/ai-functions/src/generate-text/provider/model-kebab.ts examples/ai-functions/src/stream-text/provider/model-kebab.ts新图像模型则可能创建examples/ai-functions/src/generate-image/provider/model-kebab.ts在创建前先查看同目录下该 Provider 的既有示例作为参照。仓库中 xAI 的示例目录 examples/ai-functions/src/generate-text/xai/ 提供了大量参考basic.ts、tool-call.ts、structured-output.ts、responses-reasoning.ts等新示例应遵循同样的命名与结构约定。若在搜索中发现相似模型 ID 位于某个模型列表中例如测试或示例中的 options 数组则把新模型 ID 加入同一列表同样遵守排序。Step 6更新测试在新模型已成为推荐模型的情况下合理地将测试文件中对旧/preview 模型的引用替换为新模型。例外不要替换 fixtures 或 snapshots以及使用这些 fixtures/snapshots 的测试中的模型 ID——它们刻意保持稳定用于反映捕获到的真实 API 响应。快照中的模型 ID 通常以 JSON 序列化字符串形式存在如model:gpt-5.4改动会导致快照与真实响应失配。Step 7运行测试对受影响包逐个运行测试。AI SDK 使用 pnpm workspace按包名过滤即可pnpm --filter ai-sdk/provider test pnpm --filter ai-sdk/gateway test其他受影响包按需补充pnpm --filter ai-sdk/openai-compatible test # 若更新了快照/测试 pnpm --filter ai-sdk/amazon-bedrock test # 若更新了 Bedrock options pnpm --filter ai-sdk/google-vertex test # 若更新了 Vertex options四、工作流 B移除过时模型 IDremoving-obsolete-modelStep 1确定继任模型先确定哪个模型接替被移除的模型在示例、测试、文档中的引用。如果没有明确的继任者则示例、文档和测试中的旧引用应原样保留不做替换。Step 2搜索全部精确出现点与新增工作流相同用带引号的模型 ID 搜索以避免子串误报但这次要同时覆盖.snap文件# 单引号TypeScript 源码、类型联合 grep -r model-id packages/ content/ examples/ --include*.ts --include*.mdx --include*.md --include*.snap # 双引号快照中的 JSON、测试夹具内嵌 JSON、文档 grep -r model-id packages/ content/ examples/ --include*.ts --include*.mdx --include*.md --include*.snap逐条人工核验例如搜索grok-3时grok-3-mini的命中必须被排除。Step 3从类型定义中移除删除*-options.ts中的| model-id行以及 const 数组中的对应条目。与新增相反这里是纯删除、不做替换。Step 4更新文档从.mdx能力表格中移除对应行把引用被移除模型的内联代码示例与描述替换为继任模型同步更新社区 Provider 文档 content/providers/05-community-providers/。Step 5更新示例直接使用被移除模型的示例文件替换为继任模型模型列表数组中的条目移除专用示例文件文件以模型命名、且未演示模型本身之外的独特功能删除该文件。Step 6更新测试与快照*.test.ts把模型 ID 替换为继任者__snapshots__/*.snap替换序列化 JSON 字符串中的模型 ID测试夹具中的内嵌 JSON 字符串如model:old-model→model:new-modelexamples/ai-functions/src/e2e/*.test.ts从模型数组中移除或替换packages/provider/README.md若包含代码示例则一并更新。Step 7运行测试pnpm --filter ai-sdk/provider test其他受影响包与工作流 A 的 Step 7 相同。五、AI Gateway 中的模型 ID 特殊性AI Gateway 是新增模型时必改的第二处核心位置值得单独强调。其语言模型路由由 packages/gateway/src/gateway-language-model.ts 中的GatewayLanguageModel实现构造时接收GatewayModelId类型的modelId并在请求中把模型 ID 透传给后端见 packages/gateway/src/gateway-language-model.ts。因此主 Provider 包中的模型 ID 决定SDK 直连时能否通过编译检查Gateway 中的GatewayModelIdpackages/gateway/src/gateway-language-model-settings.ts决定经网关统一路由时该模型是否被接受。两者都基于(string {})开放尾项所以漏改不会直接导致编译失败但会丢失 IDE 补全与类型提示并使网关侧缺少该模型。这正是技能文档把主 Provider AI Gateway列为必改项的底层原因。六、常见陷阱与检查清单结合源码结构维护模型 ID 时最容易踩的坑子串误改grok-4.6与grok-4.6-fast、gpt-5.4与gpt-5.4-pro并存搜索必须带引号并人工复核。快照被顺手修改fixtures/snapshots 是稳定基线反映真实 API 响应只有明确的移除流程才允许替换其中模型 ID。漏掉 README 与社区文档Provider 包的README.md和 content/providers/05-community-providers/ 中也常有模型 ID 出现在代码示例中。破坏排序类型联合、能力表格、模型数组都有既定顺序字母序或版本序插入位置错误会造成 diff 噪音。一个模型一个循环批量任务务必逐个完成全流程避免在多个模型间跳转导致遗漏。最终提交前自检grep搜索结果已逐条核验为精确匹配主 Provider 与 AI Gateway 均已更新类型联合、const 数组、表格行、示例、测试全部同步未触碰packages/codemod的CHANGELOG.md相关包测试全部通过pnpm --filter ai-sdk/provider test等。七、总结模型 ID 维护看似只是字符串增删实则是横跨类型系统、文档、示例、测试四层的一致性工程。本文所述两套工作流skills/update-provider-models/SKILL.md的核心价值在于用相似模型探针搜索一次定位全部引用点用精确匹配 排序约束 快照豁免控制改动风险用主 Provider Gateway 必改 受影响包按需跟进保证覆盖完整。按此流程操作新增一个模型 ID 可以在数分钟内完成全仓库同步并通过测试移除一个过时模型 ID 也能在不破坏历史快照与社区文档的前提下干净落地。【免费下载链接】aiThe AI Toolkit for TypeScript. From the creators of Next.js, the AI SDK is a free open-source library for building AI-powered applications and agents项目地址: https://gitcode.com/GitHub_Trending/ai/ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考