添加提供商包
添加一个完整的、遵循当前提供商接口、仓库约定、安全要求和发布流程的第一方 @ai-sdk/<provider> 包。
阅读当前真相源
在实现任何内容之前，请阅读：
以 PR #18595 作为最近的端到端示例，但选择当前 API 形状和模型类型与新提供商最相似的提供商包作为实现参考。
第三方可以在本仓库之外发布提供商包。新的第一方 @ai-sdk/<provider> 包需要在 Issue 中事先讨论。在实现包之前，确认已达成一致意见。
发现 API 契约
在设计模型类之前，请在提供商的文档或仓库中查找官方的、带有版本号的 OpenAPI 或 Swagger 规范。优先使用第一方规范，并在实现说明或拉取请求中记录来源 URL、其版本、发布日期或提交。
使用规范和官方文档来识别：
- 基础 URL 和身份验证方案
- 支持的端点、模型类型和能力
- 请求参数和响应形状
- 流式传输协议和事件格式
- 错误响应包络
- 异步轮询和下载 URL 流程
将 OpenAPI 规范视为实现证据，而不是绝对真理。规范通常对服务器发送事件、流式增量、多态内容、工具调用、可空字段和错误描述不完整。默认不要添加生成的客户端或生成的生产类型。实现最小的手写类型和 Zod 模式，然后根据官方文档和捕获的 API 响应进行验证。
如果不存在官方规范，则从官方文档和真实响应固定值中推导出契约，并在拉取请求中注明该限制。
规划提供商形状
确定提供商支持的 AI SDK 模型接口，例如 LanguageModelV4、EmbeddingModelV4、ImageModelV4、SpeechModelV4、TranscriptionModelV4、RerankingModelV4 或 Experimental_VideoModelV4。
在引入依赖项、公共 API 模式或新抽象之前，请阅读 contributing/decisions/README.md 和相关已接受的 ADR。优先使用现有的提供商工具和实现模式。
脚手架化包
通过适配当前类似的提供商包来创建 packages/<provider>/。典型的包包含：
packages/<provider>/
├── src/
│ ├── index.ts
│ ├── version.ts
│ ├── <provider>-provider.ts
│ ├── <provider>-provider.test.ts
│ ├── <provider>-<model-type>-model.ts
│ ├── <provider>-<model-type>-model.test.ts
│ └── <provider>-<model-type>-options.ts
├── CHANGELOG.md
├── README.md
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsdown.config.ts
├── turbo.json
├── vitest.node.config.js
└── vitest.edge.config.js
保留当前包约定，而不是凭记忆重新创建配置：
- 将仓库包版本精确设置为
2.0.0，不带预发布后缀。 - 创建
CHANGELOG.md，以# @ai-sdk/<provider>作为初始标题。 - 使用来自类似提供商包的共享 tsdown 配置和当前包版本注入模式。
- 扩展
./node_modules/@vercel/ai-tsconfig/ts-library.json，启用复合项目，并为工作区依赖项添加包引用。 - 包含标准的构建、清理、类型检查、Node 测试和 Edge 测试脚本。
- 包含标准的
files、文档预打包、仓库、bugs、engines 和公共来源发布元数据。 - 对 AI SDK 工作区依赖项使用
workspace:*。仅在测试使用@ai-sdk/test-server时才添加它。 - 支持仓库的 Zod 3 和 Zod 4 对等依赖范围，并对新的实现模式使用
zod/v4。
在添加或更改工作区依赖项后，运行 pnpm update-references。
实现提供商工厂
遵循当前提供商工厂模式：
- 定义一个扩展
ProviderV4的提供商接口。 - 导出
create<Provider>(settings)和一个默认的提供商实例。 - 当提供商具有有意义的默认模型类型并且类似提供商遵循相同模式时，使提供商可调用；否则返回一个提供商对象。
- 设置
provider.specificationVersion = 'v4'。 - 实现
ProviderV4要求的完全指定的工厂方法，例如languageModel、embeddingModel和imageModel。 - 仅在改善提供商的 API 时添加简短的别名，例如
chat、embedding或image。 - 从不支持的必需模型工厂抛出
NoSuchModelError。 - 支持提供商适当的设置，例如
apiKey、baseURL、headers和自定义fetch实现。 - 使用
loadApiKey或适当的共享工具加载凭据，规范化可配置的基础 URL，并将包版本包含在用户代理后缀中。 - 从
src/index.ts中导出提供商工厂、默认实例、公共选项类型、模型 ID 类型和VERSION。
实现模型类
使用 @ai-sdk/provider 中的适当接口和 @ai-sdk/provider-utils 中的共享工具实现每个支持的模型。
提供商选项类型和模式必须遵循 仓库命名和导出规则。面向用户的选项字段应使用 .optional()，除非 null 有意义。响应模式应最小化，容忍未使用的提供商字段，并在 API 可能省略或返回 null 时使用 .nullish()。
所有模型类必须实现 提供商开发注意事项 中描述的工作流序列化契约：
- 使模型配置头部可选
- 添加
WORKFLOW_SERIALIZE和WORKFLOW_DESERIALIZE静态方法 - 使用
serializeModel、serializeModelOptions或匹配的现有模式 - 确保身份验证和其他不可序列化的函数可以从请求选项或工作流环境中恢复
安全处理响应、错误和 URL
- 切勿在生产代码中使用
JSON.parse。使用@ai-sdk/provider-utils中的parseJSON或safeParseJSON。 - 使用最小模式以及共享响应处理程序（例如
createJsonResponseHandler和createJsonErrorResponseHandler）验证成功和失败的响应。 - 仅当包需要新的公共 SDK 错误类型时，才引入自定义的
AISDKError子类；普通的提供商 HTTP 失败应使用共享的 API 错误处理。 - 在每次
getFromApi调用时显式设置validateUrl。 - 当 URL 主机或方案来自提供商响应时，使用
validateUrl: true；当它来自开发者配置的基本 URL 时，使用false。 - 对于可能指向已配置的私有或自托管端点的合法响应 URL，使用
trustedOrigin。 - 当凭据可能在第一次跳转时发送时，使用
credentialedOrigin，以便从非原始 URL 和重定向中保留凭据。
在实现任何轮询或提供商提供的下载 URL 流程之前，请阅读 安全 URL 处理。
针对真实契约进行测试
为重点添加测试：
- 提供商的默认值、自定义设置、工厂别名和不支持的模型类型
- 请求序列化和响应解析
- 流事件、使用量、完成原因、警告、工具调用和提供商元数据（如果支持）
- 错误响应解析和格式错误的响应
- 工作流的序列化和反序列化
- 轮询或下载的 URL 信任决策
- Node.js 和 Edge 运行时
在可行的情况下使用真实提供商响应作为固定值。在捕获它们之前，请阅读 捕获 API 响应测试固定值技能。仅在不改变其语义的情况下，修剪过大的固定值。
添加示例和仓库集成
在添加示例之前，请阅读 AI 函数示例技能。
对于每个支持的模型类型，将入口示例放在：
examples/ai-functions/src/<function>/<provider>/basic.ts
将其他示例放在相同的提供商目录中，使用描述性的 kebab-case.ts 名称。不要创建平坦的提供商文件，例如 src/generate-text/<provider>.ts。
同时更新相关的仓库集成点：
- 将
@ai-sdk/<provider>添加到examples/ai-functions/package.json - 将其项目引用添加到
examples/ai-functions/tsconfig.json - 将所需的凭据添加到
examples/ai-functions/.env.example - 在需要时将凭据名称添加到根
turbo.json环境配置中 - 运行
pnpm update-references以更新根和包的 TypeScript 引用
针对真实 API 运行代表性示例，并在支持时确认非流式和流式行为。
添加包和提供商文档
- 编写包的
README.md，包含安装、身份验证、配置、支持模型和基本用法。 - 添加
content/providers/01-ai-sdk-providers/<last number + 10>-<provider>.mdx，包含设置、模型能力、提供商标记和示例。 - 配置包的文档预打包脚本以包含该提供商页面。
准备发布
为新的提供商包创建一个主要变更集。仓库包版本保持在普通的 2.0.0；不要添加 -beta、-canary 或其他预发布后缀。
在第一次自动化发布之前，与 Vercel IT 团队协调，在 npm 上以 0.0.0 引导一个空的 @ai-sdk/<provider> 包，并配置其 Trusted Publisher。遵循 引导新的 @ai-sdk/* 包。临时的 npm 引导版本与仓库包版本是分开的。
当 main 处于预发布模式时，不要将新包反向移植到稳定的 vX.Y 分支。
验证完整更改
至少运行：
pnpm --filter @ai-sdk/<provider> build
pnpm --filter @ai-sdk/<provider> test
pnpm --filter @ai-sdk/<provider> type-check
pnpm type-check:full
pnpm check
同时使用所需的提供商标记运行新的示例。当对共享包或构建配置的更改使其相关时，运行根构建。
完成清单
- 第一方包在 Issue 中获得批准
- 已审查官方 OpenAPI 规范，或记录了其缺失
- API 规范已根据文档和真实响应进行检查
- 选择了可比较的当前提供商实现
- 已创建版本为
2.0.0的仓库包 - 添加了包、TypeScript、构建、测试、来源证明和文档配置
- 提供商工厂实现了
ProviderV4 - 实现了支持的模型类和公共选项类型
- 为每个模型类实现了工作流序列化
- 响应解析、错误处理和 URL 获取遵循了仓库安全规则
- Node 和 Edge 测试通过了，并使用了代表性的响应固定值
- 添加了嵌套的 AI 函数示例并成功运行
- 更新了示例依赖项、TypeScript 引用、环境变量和 Turbo 配置
- 添加了 README 和提供商文档
- 添加了主要变更集
- 协调了 npm 包和 Trusted Publisher 的引导
- 包构建、测试、完整类型检查和仓库检查均通过