add-provider-package by vercel/ai
npx skills add https://github.com/vercel/ai --skill add-provider-package本指南涵盖了创建新的 @ai-sdk/<provider> 包以将 AI 服务集成到 AI SDK 中的过程。
@ai-sdk/<provider> 包:如果您希望创建第一方包,请先创建一个议题进行讨论。查看 https://github.com/vercel/ai/pull/8136/files 以获取添加新提供商的完整示例。
AI SDK 采用遵循适配器模式的分层提供商架构:
@ai-sdk/provider):定义 LanguageModelV4、EmbeddingModelV4 等接口。@ai-sdk/provider-utils):用于实现提供商的共享代码。广告位招租
在这里展示您的产品或服务
触达数万 AI 开发者,精准高效
@ai-sdk/<provider>):每个 AI 服务的具体实现。ai):高级函数,如 generateText、streamText、generateObject。创建一个新文件夹 packages/<provider>,结构如下:
packages/<provider>/
├── src/
│ ├── index.ts # 主要导出
│ ├── version.ts # 包版本
│ ├── <provider>-provider.ts # 提供商实现
│ ├── <provider>-provider.test.ts
│ ├── <provider>-*-options.ts # 模型特定选项
│ └── <provider>-*-model.ts # 模型实现(例如语言、嵌入、图像)
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsup.config.ts
├── turbo.json
├── vitest.node.config.js
├── vitest.edge.config.js
└── README.md
不要创建 CHANGELOG.md 文件。它将自动生成。
设置您的 package.json,包含:
"name": "@ai-sdk/<provider>""version": "0.0.0"(初始版本,将由 changeset 更新)"license": "Apache-2.0""sideEffects": false@ai-sdk/provider 和 @ai-sdk/provider-utils(使用 workspace:*)@ai-sdk/test-server、@types/node、@vercel/ai-tsconfig、tsup、typescript、zod"engines": { "node": ">=18" }zod 的 peer 依赖(v3 和 v4):"zod": "^3.25.76 || ^4.1.8"导出配置示例:
{
"exports": {
"./package.json": "./package.json",
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.js"
}
}
}
tsconfig.json:
{
"extends": "@vercel/ai-tsconfig/base.json",
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}
tsconfig.build.json:
{
"extends": "./tsconfig.json",
"exclude": [
"**/*.test.ts",
"**/*.test-d.ts",
"**/__snapshots__",
"**/__fixtures__"
]
}
创建 tsup.config.ts:
import { defineConfig } from 'tsup';
export default defineConfig({
entry: ['src/index.ts'],
format: ['cjs', 'esm'],
dts: true,
sourcemap: true,
clean: true,
});
创建 vitest.node.config.js 和 vitest.edge.config.js(从现有提供商如 anthropic 复制)。
提供商实现模式:
// <provider>-provider.ts
import { NoSuchModelError } from '@ai-sdk/provider';
import { loadApiKey } from '@ai-sdk/provider-utils';
export interface ProviderSettings {
apiKey?: string;
baseURL?: string;
// provider-specific settings
}
export class ProviderInstance {
readonly apiKey?: string;
readonly baseURL?: string;
constructor(options: ProviderSettings = {}) {
this.apiKey = options.apiKey;
this.baseURL = options.baseURL;
}
private get baseConfig() {
return {
apiKey: () =>
loadApiKey({
apiKey: this.apiKey,
environmentVariableName: 'PROVIDER_API_KEY',
description: 'Provider API key',
}),
baseURL: this.baseURL ?? 'https://api.provider.com',
};
}
languageModel(modelId: string) {
return new ProviderLanguageModel(modelId, this.baseConfig);
}
// Shorter alias
chat(modelId: string) {
return this.languageModel(modelId);
}
}
// Export default instance
export const providerName = new ProviderInstance();
每种模型类型(语言、嵌入、图像等)都应实现 @ai-sdk/provider 中的相应接口:
LanguageModelV4 用于文本生成模型EmbeddingModelV4 用于嵌入模型ImageModelV4 用于图像生成模型模式指南:
提供商选项(面向用户):
null 有意义,否则使用 .optional()响应模式(API 响应):
.nullish() 而不是 .optional()包含:
__fixtures__ 子目录中的夹具进行 API 响应解析测试有关捕获真实 API 响应以进行测试,请参阅 capture-api-response-test-fixture 技能。
在 examples/ai-functions/src/ 中为提供商支持的每种模型类型创建示例:
generate-text/<provider>.ts - 基本文本生成stream-text/<provider>.ts - 流式文本generate-object/<provider>.ts - 结构化输出(如果支持)stream-object/<provider>.ts - 流式结构化输出(如果支持)embed/<provider>.ts - 嵌入(如果支持)generate-image/<provider>.ts - 图像生成(如果支持)根据需要添加特定功能示例(例如 <provider>-tool-call.ts、<provider>-cache-control.ts)。
在 content/providers/01-ai-sdk-providers/<last number + 10>-<provider>.mdx 中创建文档
包含:
运行 pnpm changeset 并:
major 版本(对于从 0.0.0 开始的新包)从工作区根目录运行 pnpm update-references 以更新 tsconfig 引用。
# 从工作区根目录
pnpm build
# 从提供商包目录
cd packages/<provider>
pnpm test # 运行所有测试
pnpm test:node # 运行 Node.js 测试
pnpm test:edge # 运行 Edge 测试
pnpm type-check # 类型检查
# 从工作区根目录
pnpm type-check:full # 完整类型检查(包括示例)
测试您的示例:
cd examples/ai-functions
pnpm tsx src/generate-text/<provider>.ts
pnpm tsx src/stream-text/<provider>.ts
languageModel(id)、imageModel(id)、embeddingModel(id)(必需).chat(id)、.image(id)、.embedding(id)(用于开发者体验)kebab-case.tskebab-case.test.tskebab-case.test-d.ts<Provider>Provider、<Provider>LanguageModel 等。JSON.parse - 使用 @ai-sdk/provider-utils 中的 parseJSON 或 safeParseJSON@ai-sdk/provider-utils 中的 loadApiKey 安全加载 API 密钥错误应继承自 @ai-sdk/provider 中的 AISDKError 并使用标记模式:
import { AISDKError } from '@ai-sdk/provider';
const name = 'AI_ProviderError';
const marker = `vercel.ai.error.${name}`;
const symbol = Symbol.for(marker);
export class ProviderError extends AISDKError {
private readonly [symbol] = true;
constructor({ message, cause }: { message: string; cause?: unknown }) {
super({ name, message, cause });
}
static isInstance(error: unknown): error is ProviderError {
return AISDKError.hasMarker(error, marker);
}
}
如果 main 分支设置为发布 beta 版本,则无需进一步操作。只需确保不要将其向后移植到 vX.Y 稳定分支,因为一旦我们在 main 分支上退出预发布模式,就会导致 npm 版本冲突。
packages/<provider> 中创建了包结构package.json 配置了正确的依赖项tsconfig.json、tsconfig.build.json)tsup.config.ts)vitest.node.config.js、vitest.edge.config.js)examples/ai-functions/src/ 中创建content/providers/01-ai-sdk-providers/pnpm update-referencespnpm test)pnpm type-check:full)pnpm update-referencespnpm type-check:full 以尽早发现问题tsup.config.ts 是否正确配置每周安装量
154
代码仓库
GitHub 星标数
23.0K
首次出现
2026年2月12日
安全审计
安装于
codex137
github-copilot135
gemini-cli134
opencode133
amp133
kimi-cli133
This guide covers the process of creating a new @ai-sdk/<provider> package to integrate an AI service into the AI SDK.
@ai-sdk/<provider> packages: If you prefer a first-party package, please create an issue first to discuss.See https://github.com/vercel/ai/pull/8136/files for a complete example of adding a new provider.
The AI SDK uses a layered provider architecture following the adapter pattern:
@ai-sdk/provider): Defines interfaces like LanguageModelV4, EmbeddingModelV4, etc.@ai-sdk/provider-utils): Shared code for implementing providers@ai-sdk/<provider>): Concrete implementations for each AI serviceai): High-level functions like generateText, streamText, generateObjectCreate a new folder packages/<provider> with the following structure:
packages/<provider>/
├── src/
│ ├── index.ts # Main exports
│ ├── version.ts # Package version
│ ├── <provider>-provider.ts # Provider implementation
│ ├── <provider>-provider.test.ts
│ ├── <provider>-*-options.ts # Model-specific options
│ └── <provider>-*-model.ts # Model implementations (e.g., language, embedding, image)
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsup.config.ts
├── turbo.json
├── vitest.node.config.js
├── vitest.edge.config.js
└── README.md
Do not create a CHANGELOG.md file. It will be auto-generated.
Set up your package.json with:
"name": "@ai-sdk/<provider>""version": "0.0.0" (initial version, will be updated by changeset)"license": "Apache-2.0""sideEffects": false@ai-sdk/provider and @ai-sdk/provider-utils (use workspace:*)@ai-sdk/test-server, @types/node, @vercel/ai-tsconfig, , , Example exports configuration:
{
"exports": {
"./package.json": "./package.json",
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.js"
}
}
}
tsconfig.json :
{
"extends": "@vercel/ai-tsconfig/base.json",
"include": ["src/**/*.ts"],
"exclude": ["node_modules", "dist"]
}
tsconfig.build.json :
{
"extends": "./tsconfig.json",
"exclude": [
"**/*.test.ts",
"**/*.test-d.ts",
"**/__snapshots__",
"**/__fixtures__"
]
}
Create tsup.config.ts:
import { defineConfig } from 'tsup';
export default defineConfig({
entry: ['src/index.ts'],
format: ['cjs', 'esm'],
dts: true,
sourcemap: true,
clean: true,
});
Create both vitest.node.config.js and vitest.edge.config.js (copy from existing provider like anthropic).
Provider implementation pattern :
// <provider>-provider.ts
import { NoSuchModelError } from '@ai-sdk/provider';
import { loadApiKey } from '@ai-sdk/provider-utils';
export interface ProviderSettings {
apiKey?: string;
baseURL?: string;
// provider-specific settings
}
export class ProviderInstance {
readonly apiKey?: string;
readonly baseURL?: string;
constructor(options: ProviderSettings = {}) {
this.apiKey = options.apiKey;
this.baseURL = options.baseURL;
}
private get baseConfig() {
return {
apiKey: () =>
loadApiKey({
apiKey: this.apiKey,
environmentVariableName: 'PROVIDER_API_KEY',
description: 'Provider API key',
}),
baseURL: this.baseURL ?? 'https://api.provider.com',
};
}
languageModel(modelId: string) {
return new ProviderLanguageModel(modelId, this.baseConfig);
}
// Shorter alias
chat(modelId: string) {
return this.languageModel(modelId);
}
}
// Export default instance
export const providerName = new ProviderInstance();
Each model type (language, embedding, image, etc.) should implement the appropriate interface from @ai-sdk/provider:
LanguageModelV4 for text generation modelsEmbeddingModelV4 for embedding modelsImageModelV4 for image generation modelsSchema guidelines :
Provider Options (user-facing):
.optional() unless null is meaningfulResponse Schemas (API responses):
.nullish() instead of .optional()Include:
__fixtures__ subdirectorySee capture-api-response-test-fixture skill for capturing real API responses for testing.
Create examples in examples/ai-functions/src/ for each model type the provider supports:
generate-text/<provider>.ts - Basic text generationstream-text/<provider>.ts - Streaming textgenerate-object/<provider>.ts - Structured output (if supported)stream-object/<provider>.ts - Streaming structured output (if supported)embed/<provider>.ts - Embeddings (if supported)generate-image/<provider>.ts - Image generation (if supported)Add feature-specific examples as needed (e.g., <provider>-tool-call.ts, <provider>-cache-control.ts).
Create documentation in content/providers/01-ai-sdk-providers/<last number + 10>-<provider>.mdx
Include:
Run pnpm changeset and:
major version (for new packages starting at 0.0.0)Run pnpm update-references from the workspace root to update tsconfig references.
# From workspace root
pnpm build
# From provider package
cd packages/<provider>
pnpm test # Run all tests
pnpm test:node # Run Node.js tests
pnpm test:edge # Run Edge tests
pnpm type-check # Type checking
# From workspace root
pnpm type-check:full # Full type check including examples
Test your examples:
cd examples/ai-functions
pnpm tsx src/generate-text/<provider>.ts
pnpm tsx src/stream-text/<provider>.ts
languageModel(id), imageModel(id), embeddingModel(id) (required).chat(id), .image(id), .embedding(id) (for DX)kebab-case.tskebab-case.test.tskebab-case.test-d.ts<Provider>Provider, <Provider>LanguageModel, etc.JSON.parse directly - use parseJSON or safeParseJSON from @ai-sdk/provider-utilsloadApiKey from @ai-sdk/provider-utilsErrors should extend AISDKError from @ai-sdk/provider and use a marker pattern:
import { AISDKError } from '@ai-sdk/provider';
const name = 'AI_ProviderError';
const marker = `vercel.ai.error.${name}`;
const symbol = Symbol.for(marker);
export class ProviderError extends AISDKError {
private readonly [symbol] = true;
constructor({ message, cause }: { message: string; cause?: unknown }) {
super({ name, message, cause });
}
static isInstance(error: unknown): error is ProviderError {
return AISDKError.hasMarker(error, marker);
}
}
If main is set up to publish beta releases, no further action is necessary. Just make sure not to backport it to the vX.Y stable branch since it will result in an npm version conflict once we exit pre-release mode on main.
packages/<provider>package.json configured with correct dependenciestsconfig.json, tsconfig.build.json)tsup.config.ts)vitest.node.config.js, vitest.edge.config.js)examples/ai-functions/src/content/providers/01-ai-sdk-providers/pnpm update-references from workspace rootpnpm type-check:full to catch issues earlytsup.config.ts is configured correctlyWeekly Installs
154
Repository
GitHub Stars
23.0K
First Seen
Feb 12, 2026
Security Audits
Gen Agent Trust HubPassSocketPassSnykPass
Installed on
codex137
github-copilot135
gemini-cli134
opencode133
amp133
kimi-cli133
React 组合模式指南:Vercel 组件架构最佳实践,提升代码可维护性
116,600 周安装
Claude快速阅读器 - 600+ WPM高速阅读AI回复,RSVP与Spritz ORP高亮技术
102 周安装
.NET和Python后端全局错误处理配置指南:异常中间件与自定义异常
211 周安装
ln-401-task-executor:AI驱动任务执行器,自动化代码实现与状态管理
212 周安装
Slack 代理开发指南:Chat SDK 与 Bolt for JavaScript 框架选择与部署教程
206 周安装
Claw 发布工具:ClawSec 技能自动化发布与版本管理工具
102 周安装
构建健康审计员 - 自动化代码质量与构建问题检测工具
210 周安装
tsuptypescriptzod"engines": { "node": ">=18" }zod (both v3 and v4): "zod": "^3.25.76 || ^4.1.8"pnpm update-references runpnpm test from package)pnpm type-check:full from root)