プロバイダーパッケージを追加する

現在のプロバイダーインターフェース、リポジトリの規約、セキュリティ要件、リリースプロセスに従った、完全なファーストパーティ @ai-sdk/<provider> パッケージを追加します。

現在のソース・オブ・トゥルースを読む

実装を始める前に、以下を読んでください：

新しいプロバイダーの追加 - 現在のパッケージとリリース要件について
プロバイダー開発ノート - 命名規則、スキーマ、ワークフローのシリアライゼーションについて
プロバイダーアーキテクチャ - プロバイダーの抽象化について
セキュアなURL処理 - プロバイダーがポーリング、画像、音声、動画、その他のURLを取得する場合

PR #18595 を最近のエンドツーエンドの例として使用しますが、新しいプロバイダーにAPI形状とモデルタイプが最も近い現在のプロバイダーパッケージを実装の参考として選択してください。

サードパーティはこのリポジトリの外部でプロバイダーパッケージを公開できます。新しいファーストパーティ @ai-sdk/<provider> パッケージには、事前のIssueでの議論が必要です。パッケージを実装する前に、その合意が存在することを確認してください。

API契約を発見する

モデルクラスを設計する前に、プロバイダーのドキュメントやリポジトリで、公式のバージョン管理されたOpenAPIまたはSwagger仕様を探してください。ファーストパーティの仕様を優先し、ソースURLとそのバージョン、公開日、またはコミットを実装ノートまたはプルリクエストに記録してください。

仕様と公式ドキュメントを使用して、以下を特定します：

ベースURLと認証スキーム
サポートされているエンドポイント、モデルタイプ、機能
リクエストパラメータとレスポンス形状
ストリーミングトランスポートとイベント形式
エラーレスポンスのエンベロープ
非同期ポーリングとダウンロードURLフロー

OpenAPI仕様は実装の証拠として扱いますが、絶対的な真実として扱わないでください。仕様は、サーバー送信イベント、ストリーミングデルタ、ポリモーフィックなコンテンツ、ツールコール、null許容フィールド、エラーに関して不完全なことがよくあります。デフォルトでは、生成されたクライアントや生成されたプロダクションタイプを追加しないでください。最小限の手書きタイプと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 に設定します。
初期ヘッダー # @ai-sdk/<provider> を持つ CHANGELOG.md を作成します。
同等のプロバイダーパッケージから、共有tsdown設定と現在のパッケージバージョンインジェクションパターンを使用します。
./node_modules/@vercel/ai-tsconfig/ts-library.json を拡張し、compositeプロジェクトを有効にし、ワークスペース依存関係のパッケージ参照を追加します。
標準のビルド、クリーン、タイプチェック、Nodeテスト、Edgeテストスクリプトを含めます。
標準の files、ドキュメントのprepack、リポジトリ、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 の共有ユーティリティを使用して、サポートされている各モデルを実装します。

プロバイダーオプションタイプとスキーマは、リポジトリの命名とエクスポートルールに従う必要があります。ユーザー向けのオプションフィールドは、null が意味を持つ場合を除き、.optional() を使用する必要があります。レスポンススキーマは最小限にし、未使用のプロバイダーフィールドを許容し、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 Functions例スキルを読んでください。

サポートされている各モデルタイプについて、エントリ例を次の場所に配置します：

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 を追加します。
そのプロバイダーページを含めるように、パッケージのドキュメントprepackスクリプトを設定します。

リリースの準備

新しいプロバイダーパッケージのためのメジャーchangesetを作成します。リポジトリパッケージはプレーンな 2.0.0 のままです。-beta、-canary、またはその他のプレリリースサフィックスを追加しないでください。

最初の自動リリースの前に、Vercel ITチームと調整して、npm上で @ai-sdk/<provider> パッケージを 0.0.0 でブートストラップし、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

また、必要なプロバイダー資格情報を使用して新しい例を実行します。共有パッケージまたはビルド設定への変更が関連する場合、ルートビルドを実行します。

プロバイダーパッケージ追加ガイド