企业官网建设流程全解析

为 AI SDK 添加新模型：Vercel AI SDK 仓库贡献指南全解析

【免费下载链接】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

本篇指南基于仓库中的 contributing/add-new-model.md 展开，系统讲解为 AI SDK（The AI Toolkit for TypeScript）贡献新模型的完整流程：从把模型 ID 写入设置项以获得编辑器自动补全，到更新 Provider 文档页的模型能力表（Model Capabilities），再到通过 Changesets 提交 PR 并发布 NPM 包。读完本文，你将掌握一条从"新增模型 ID"到"随新版@ai-sdk/*包发布"的可复现路径，并理解每一步对应的仓库文件位置与底层实现依据。

一、总览：一次模型贡献要动哪些文件

为 AI SDK 添加新模型，本质上是让模型 ID 在三个层面"可见"：

1. 开发体验层：模型 ID 进入设置项（settings），供 IDE / 交互式代码预览中的自动补全使用；
2. 文档层：模型 ID 进入对应 Provider 页面的 Model Capabilities 能力表，并（对知名模型）进入汇总型文档的模型清单；
3. 发布层：随 PR 提交 changeset，触发 Changesets 发布流程，最终更新到 NPM 上的对应 provider 包。

原文档给出的步骤清单如下（本仓库 contributing/add-new-model.md）：

1. 将 model id 添加到 settings（model ids），以获得自动补全；
2. 将 model id 添加到/content/providers/...下对应 provider 页面的 Model Capabilities 表格（位于页面底部）；
3. 如果该模型较为知名（notable），还需要添加到：
   • content/providers/01-ai-sdk-providers/index.mdx
   • content/docs/02-foundations/02-providers-and-models.mdx
4. 提交带 changeset 的 PR；
5. 通过 Changesets PR 完成 NPM 发布。

下文将逐条展开，并结合仓库源码给出每一步的实际落点。

二、第一步：把模型 ID 加入设置项以启用自动补全

原文档要求"Add model id to settings (model ids) for auto-complete"。从仓库源码结构看，这里的"settings (model ids)"对应的是文档站点中交互式代码预览（interactive code preview）组件的模型选择配置，位于 apps/docs/components/docs/interactive-code-preview.tsx。

该组件内部定义了modelIds的类型与状态管理逻辑：

• 类型上使用Partial<Record<ModelKind, string>>与Record<ModelKind, string>（interactive-code-preview.tsx 中第 83、88 行附近），ModelKind表示模型类别（如语言模型、嵌入模型、图像模型等）；
• 状态通过useState维护，并将modelIds持久化到本地存储（safeLocalStorage.setItem({ modelIds, tab })等逻辑，见同文件第 664、699–702 行附近）；
• 组件据此渲染可选的模型下拉列表，供读者在文档示例中实时切换模型运行示例。

因此，当你新增一个模型 ID 时，需要把它登记到这类模型选择配置中，IDE 或交互式预览才能在下拉补全中"认出"这个 ID。这属于纯文档侧（apps/docs）的改动，与 provider 包源码解耦，但直接影响读者体验。

三、第二步：更新 Provider 页面底部的 Model Capabilities 表格

每个官方 provider 的文档页都维护着一张模型能力表，位于页面底部的## Model Capabilities小节。表格列通常包括：

能力项用<Check />（支持）与<Cross />（不支持）两个文档组件渲染。以 content/providers/01-ai-sdk-providers/30-deepseek.mdx 底部的表格为例：

从该表可以看到，deepseek-v4-flash-vision-exp是带视觉能力的实验模型，因此Image Input为<Check />，而纯文本模型该项为<Cross />。新增模型时，需按此格式在对应 provider 文档（content/providers/01-ai-sdk-providers/目录下，如30-deepseek.mdx、03-openai.mdx等）中追加一行，能力标记务必与模型实际能力及 provider 实现保持一致。

提示：content/providers/01-ai-sdk-providers/目录下已按数字序号维护了 xAI、OpenAI、Azure、Anthropic、Google、DeepSeek、Moonshot AI 等 40 余个 provider 的文档页，新增模型时应先定位到对应 provider 的文件。

四、第三步：知名模型同步更新汇总清单

如果新增的模型属于"知名模型"（notable model），仅更新单个 provider 页面还不够，还要同步维护两处聚合型文档，保证首页与入门文档中的模型清单保持一致：

4.1 Provider 总览页

content/providers/01-ai-sdk-providers/index.mdx 是 AI SDK Providers 的入口页，结构如下：

• 顶部通过<OfficialModelCards />与<CommunityModelCards />两个组件自动渲染官方与社区模型卡片；
• 中部是"Provider support"小节，用一张大表对比各 provider 热门模型的能力（列同样为 Image Input / Object Generation / Tool Usage / Tool Streaming），例如grok-4.6、gpt-6-astra、claude-sonnet-5、gemini-3.8-flash、deepseek-v4-flash、qwen3-max等均在此列出；
• 表尾附<Note>提示"该表并非穷举，更多模型请参考各 provider 文档页"。

新增知名模型后，应在此表追加一行，并与单 provider 页中的能力标记保持一致，避免两处数据冲突。

4.2 入门基础篇：Providers and Models

content/docs/02-foundations/02-providers-and-models.mdx 是入门基础（Foundations）章节中的核心页面，面向刚接触 AI SDK 的读者：

• 前半部分介绍"Provider 与 Model"的基本概念，说明各家厂商 API 差异带来的供应商锁定风险，以及 AI SDK 通过 语言模型规范（packages/provider包内的 language-model/v3 目录）统一接口来解耦不同 provider 的设计；
• 中间依次列出官方 provider（@ai-sdk/openai、@ai-sdk/anthropic、@ai-sdk/google、@ai-sdk/deepseek等）与社区 provider（Ollama、OpenRouter、Voyage AI 等）的完整清单；
• 末尾同样有一张 Model Capabilities 对比表，列出各 provider 代表模型的 Image Input / Object Generation / Tool Usage / Tool Streaming 能力，并同样以<Note>声明非穷举。

因此，"知名模型"的门槛意味着该模型会同时出现在上述两处汇总表中。判断依据是模型的业界知名度与代表性——例如某厂商的主力旗舰模型通常属于此列。

五、第四步：带 Changeset 的 PR

原文档要求 "PR with changeset"。AI SDK 仓库使用 Changesets 管理版本与发布（根目录 package.json 与各包目录中的turbo.json、tsup.config.ts构成了 pnpm workspace + Changesets + tsup 的标准发布链路），因此每个会改动@ai-sdk/*包或文档的 PR 都必须附带 changeset 文件，用于声明：

• 变更影响的包名（如@ai-sdk/deepseek）；
• 变更类型（major/minor/patch）；
• 面向用户的变更说明（release note）。

changeset 文件一般放在各包的.changeset目录下，由pnpm changeset命令交互式生成，再随代码改动一起提交到 PR。随后进入第五步的发布环节。

六、第五步：通过 Changesets PR 发布 NPM 包

当带 changeset 的 PR 合并到主干后，Changesets 机器人会自动开启一个"版本发布 PR"（Changesets version PR / release PR），该 PR 会：

1. 依据各 changeset 汇总并升级相关包的版本号；
2. 重写各包的 CHANGELOG.md（仓库内每个包目录都维护自己的 CHANGELOG，如 packages/deepseek/CHANGELOG.md、packages/openai/CHANGELOG.md）；
3. 合并后触发 CI 将更新后的包发布到 NPM。

也就是说，"添加新模型"的改动最终通过@ai-sdk/<provider>包的新版本（通常是minor或patch）随正常发版流程送达用户，用户升级依赖即可使用新模型 ID。

七、一个完整示例：从模型 ID 到发布

综合上述五个步骤，一次完整的"为某 provider 添加新模型"改动大致如下：

1. 登记 ID：在 apps/docs/components/docs/interactive-code-preview.tsx 的模型选择配置中补充新模型 ID，启用自动补全；
2. 更新能力表：在对应 provider 文档页（如 content/providers/01-ai-sdk-providers/30-deepseek.mdx）底部的## Model Capabilities表中新增一行，按实际能力填写<Check />/<Cross />；
3. 知名模型同步汇总：若模型足够知名，在 content/providers/01-ai-sdk-providers/index.mdx 与 content/docs/02-foundations/02-providers-and-models.mdx 的能力对比表中各补一行；
4. 提交 changeset：为 PR 附带 changeset，声明受影响的@ai-sdk/*包与变更说明；
5. 等待发布：PR 合并后由 Changesets 版本 PR 完成版本提升、CHANGELOG 重写与 NPM 发布。

八、注意事项与自查清单

• 能力标记要与实现一致：Model Capabilities 表中的<Check />/<Cross />是给读者和搜索引擎的关键信息，务必依据 provider 包源码（如packages/deepseek/src/下各 provider 实现）确认模型是否真正支持图片输入、对象生成、工具调用与工具流式输出，不要凭印象填写。
• 多处表格保持同步：单个 provider 页、provider 总览页（index.mdx）、入门页（02-providers-and-models.mdx）三处能力表对同一模型的信息必须一致，避免文档自相矛盾。
• 发布时机由 Changesets 控制：代码合并后不要手动改版本号或手动发布，一切交给 Changesets 版本 PR 与 CI 流程，避免与仓库的版本管理约定冲突。

遵循以上步骤，你就能以符合 AI SDK 仓库规范的方式，让一个新模型 ID 完整走完"编辑器补全 → 文档能力表 → 汇总清单 → changeset → NPM 发布"的全流程，成为可被所有 AI SDK 用户检索与使用的一等公民。

【免费下载链接】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