Vercel AI SDK カスタムプロバイダーのベースURL：Flatkey設定メモ

Vercel AI SDKカスタムプロバイダーのベースURL設定は、単なる文字列の置換ではありません。有用な部分はAI SDKプロバイダーをFlatkeyに向けることですが、安全な本番運用のためには、ユーザートラフィックを移行する前に、モデルエイリアス、エンドポイントファミリー、ストリーミング動作、ツール呼び出し、使用状況の証跡、クォータ制御、そしてロールバックを検証することが重要です。

このガイドは、Next.jsのルート、サーバーアクション、ワーカー、キュー、またはエージェントループでAI SDKを使用する開発者、AIプロダクトチーム、プラットフォームエンジニア、自動化構築者、財務担当者、および調達レビュー担当者を対象としています。これは2026年6月29日に、最新のAI SDKドキュメント、最新のAI SDKパッケージに対する型チェック、および公開されているFlatkeyのライブページに基づいて更新されました。コードスニペットはテンプレートです。このタスクでは有効なFlatkey APIキーは利用できなかったため、ご自身のキー、現在のFlatkeyコンソールのベースURL、そしてアカウントで有効になっているモデルエイリアスを使用してスモークテストを実行してください。

クイックアンサー：Vercel AI SDKカスタムプロバイダーのベースURL

FlatkeyでVercel AI SDKカスタムプロバイダーのベースURLを設定するには、公式のOpenAI互換プロバイダーパッケージから始めます。createOpenAICompatibleでプロバイダーを作成し、baseURLをコンソールから取得した現在のFlatkeyベースURLに設定し、apiKeyをFlatkeyキーに設定し、generateTextまたはstreamTextでFlatkeyモデルエイリアスを使用します。

npm install ai @ai-sdk/openai-compatible zod

export FLATKEY_API_KEY="fk_your_key"
export FLATKEY_BASE_URL="https://console.flatkey.ai/v1" # Copy the current value from Flatkey
export FLATKEY_MODEL="your-flatkey-model-alias"

import { createOpenAICompatible } from '@ai-sdk/openai-compatible';
import { generateText } from 'ai';

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short Flatkey AI SDK routing check.',
});

console.log(result.text);
console.log(result.finishReason);
console.log(result.usage);
console.log(result.warnings);

これが、Vercel AI SDKカスタムプロバイダーのベースURL移行における最小限の動作構成です。しかし、ここで止まらないでください。テキスト応答が成功したことは、1つのリクエスト形式が1つのモデルエイリアスに到達したことを証明するにすぎません。ストリーミングの使用、ツール、構造化出力、コストの可視性、クォータの動作、またはロールバックが証明されたわけではありません。

現在のAI SDKドキュメントがサポートするもの

現在のAI SDKドキュメントには、2つの関連するパスがあります。OpenAI互換プロバイダーパッケージは、OpenAI APIを実装するプロバイダー向けに構築されています。これはcreateOpenAICompatibleを公開しており、name、apiKey、baseURL、headers、queryParams、カスタムfetch、includeUsage、supportsStructuredOutputs、リクエストボディの変換、メタデータ抽出などのオプションを含みます。

OpenAIプロバイダーパッケージは、プロキシサーバーを含むカスタマイズされたセットアップのためにcreateOpenAI({ baseURL })もサポートしています。OpenAI互換プロバイダーは、Vercel AI SDKカスタムプロバイダーのベースURLにとってよりクリーンなデフォルトです。なぜなら、そのプロバイダー名、カスタムメタデータ抽出、プロバイダー固有のオプション、およびモデルファクトリ名が、OpenAIではないOpenAI互換ルート向けに設計されているからです。

慎重に扱うべきFlatkeyの最新情報

2026年6月29日に確認したFlatkeyのホームページには、One API gateway for production AI teamsというタイトルがあり、メタディスクリプションにはFlatkeyがモデルアクセス、ルーティング、請求、使用状況分析、および運用管理を統合すると記載されています。ライブ価格APIは、633のモデル行、23のベンダー、および/v1/chat/completions、/v1/responses、/v1/messages、/v1beta/models/{model}:generateContent、/v1/images/generations、/v1/video/generationsのエンドポイントファミリーを返しました。

これらの事実は、位置付けやカタログの形状に関する日付付きの公開情報として利用し、すべてのアカウントがすべてのルートを呼び出せる、すべてのモデルエイリアスが利用可能である、またはすべての機能が有効であることの証明として使用しないでください。本番トラフィックを流す前に、Vercel AI SDKカスタムプロバイダーのベースURLのチェックでは、アプリが送信するのとまったく同じキー、ベースURL、モデルエイリアス、エンドポイントファミリー、および機能パスを使用する必要があります。

ベースURLと環境設定

ベースURL、キー、モデルエイリアスは環境変数に保持してください。そうすることで、Vercel AI SDKカスタムプロバイダーのベースURLのロールアウトが、ルートハンドラー、プロンプトファイル、ワーカーの内部に埋もれるのではなく、デプロイメント設定でレビュー可能になります。

function requiredEnv(name: string): string {
  const value = process.env[name];
  if (!value) {
    throw new Error(`Missing ${name}`);
  }
  return value;
}

const flatkey = createOpenAICompatible({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
  includeUsage: true,
});

次に、ワークロードのルーティングをトランスポート設定から分離してください。ベースURLはSDKにリクエストの送信先を伝えます。モデルエイリアスは、どのFlatkeyルートとアップストリームモデルを要求しているかを決定します。

const MODEL_ROUTES = {
  supportTriage: 'FLATKEY_SUPPORT_MODEL',
  workflowPlanning: 'FLATKEY_PLANNING_MODEL',
  codeReview: 'FLATKEY_CODE_MODEL',
  fallback: 'FLATKEY_FALLBACK_MODEL',
} as const;

function modelFor(routeName: keyof typeof MODEL_ROUTES) {
  return flatkey.chatModel(requiredEnv(MODEL_ROUTES[routeName]));
}

このパターンにより、チームがプロバイダー名、モデルエイリアス、ベースURLをコードベース全体に散在させるのを防ぎます。また、財務および運用チームが使用状況の行と照合するための安定したワークロード名のセットを提供します。

最初に非ストリーミングテキストのスモークテストを行う

まずgenerateTextから始めます。これは、テキスト、終了理由、使用状況、警告、ステップ、レスポンスメタデータを含む単純な結果オブジェクトを提供します。ストリーミングやツールをテストする前に、これを使用して認証、ベースURLの形式、モデルエイリアス、使用状況の可視性を証明します。

import { generateText } from 'ai';

const result = await generateText({
  model: modelFor('supportTriage'),
  prompt: 'Reply with one short migration readiness check.',
});

console.log({
  text: result.text,
  finishReason: result.finishReason,
  usage: result.usage,
  warnings: result.warnings,
});

生成されたテキスト、モデルエイリアス、終了理由、使用状況のフィールドが、アプリケーションのロギングとレビュー担当者のニーズに十分である場合にのみ、この最初のVercel AI SDKカスタムプロバイダーのベースURLチェックを承認してください。呼び出しがテキストを返しても、使用状況がFlatkeyのレコードに見つからない場合、移行は本番環境に対応できていません。

ストリーミングは別途テストする

ストリーミングには異なる障害発生箇所があります。レスポンスストリーミング、サーバーレスのタイムアウト、UIのキャンセル、エラーハンドリング、使用状況の会計処理に関わります。AI SDKのドキュメントには、streamText、result.textStream、onErrorコールバック、そしてresult.usageのような結果プロミスが示されています。OpenAI互換プロバイダーには、プロバイダーがサポートしている場合にストリーミングレスポンスメタデータのためのincludeUsageもあります。

import { streamText } from 'ai';

const stream = streamText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Stream three short setup checks.',
  onError({ error }) {
    console.error(error);
  },
});

for await (const textPart of stream.textStream) {
  process.stdout.write(textPart);
}

const usage = await stream.usage;
console.log({ usage });

選択したFlatkeyモデルエイリアスが実際のリクエスト形式で安定していることが証明された後にのみ、ストリーミングを有効にしてください。ストリーミングされたテキストは機能するが使用状況が不完全な場合は、ユーザートラフィックを移行する前に、チームがストリームレスポンスの代わりにFlatkeyレコードから使用状況を収集できるかどうかを決定してください。

同じエイリアスでツール呼び出しを検証する

AI SDKのツールAPIは、toolsオブジェクト、toolヘルパー、inputSchema、およびオプションのexecute関数を使用します。通常のチャットパスではツール呼び出しは承認されません。まず小さなスキーマでテストし、次にエージェントが実際に使用するツールセットに拡張してください。

import { generateText, isStepCount, tool } from 'ai';
import { z } from 'zod';

const result = await generateText({
  model: flatkey.chatModel(requiredEnv('FLATKEY_TOOL_MODEL')),
  tools: {
    routeReadiness: tool({
      description: 'Return the readiness state for a Flatkey route.',
      inputSchema: z.object({
        routeName: z.string().describe('Internal route name to inspect'),
      }),
      execute: async ({ routeName }) => ({
        routeName,
        checked: true,
      }),
    }),
  },
  stopWhen: isStepCount(2),
  prompt: 'Use the tool for route supportTriage.',
});

console.log(result.toolCalls);
console.log(result.toolResults);
console.log(result.usage);

エージェントのトラフィックについては、モデルが期待されるツールを呼び出したか、入力が検証されたか、ツール結果がクリーンに返されたか、そしてFlatkeyの使用状況の行が同じルートに結び付けられるかを記録してください。厳密なスキーマ、承認フロー、または並列ツール呼び出しが重要な場合は、それらの機能を正確なモデルエイリアスでテストしてください。

代わりにcreateOpenAIを使用する場合

アプリがすでにどこでも@ai-sdk/openaiを使用している場合、OpenAIプロバイダーのbaseURLオプションは、差分の少ない移行パスになり得ます。これもVercel AI SDKカスタムプロバイダーのベースURL設定ですが、モデルAPIの選択についてはより明示的にする必要があります。

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';

const flatkeyViaOpenAIProvider = createOpenAI({
  name: 'flatkey',
  apiKey: requiredEnv('FLATKEY_API_KEY'),
  baseURL: requiredEnv('FLATKEY_BASE_URL'),
});

const result = await generateText({
  model: flatkeyViaOpenAIProvider.chat(requiredEnv('FLATKEY_MODEL')),
  prompt: 'Reply with one short OpenAI-provider base URL check.',
});

現在のOpenAIプロバイダーのドキュメントによると、.chat(...)のようなルートを指定しない限り、AI SDK 5以降、OpenAIプロバイダーのデフォルトAPIはResponsesです。そのため、上記の例では.chat(...)を明示的に使用しています。Flatkeyの/v1/responsesエンドポイントファミリーをテストする場合は、それを別のモデルエイリアスとロールバックパスを持つ個別のルートチェックとして扱ってください。

セットアップチェックリスト

一般的な失敗モード

他のFlatkeyガイドとの関連性

より広範な移行パスが必要な場合は、OpenAI互換API移行ガイドから始めてください。関連するツール設定パターンについては、Cherry Studio API設定ガイドおよびcc-switch Claude Code Flatkeyガイドをご覧ください。Flatkeyの料金を使用して現在のモデルカタログを確認し、自身のアカウントでスモークテストを実行する準備ができたらキーを取得してください。

よくある質問

Flatkey用にVercel AI SDKのカスタムプロバイダーベースURLを設定するにはどうすればよいですか？

createOpenAICompatibleでOpenAI互換プロバイダーを作成し、baseURLを現在のFlatkeyベースURLに設定し、apiKeyをあなたのFlatkeyキーに設定し、FlatkeyモデルエイリアスをgenerateTextまたはstreamTextに渡します。

@ai-sdk/openai-compatibleと@ai-sdk/openaiのどちらを使用すべきですか？

新しいFlatkeyセットアップには、OpenAI互換プロバイダー向けに設計されている@ai-sdk/openai-compatibleを使用してください。アプリがすでにOpenAIプロバイダーで標準化されており、コードの差分を小さくしたい場合は、@ai-sdk/openaiをcreateOpenAI({ baseURL })と共に使用してください。

ベースURLに/v1を含める必要はありますか？

現在のFlatkeyコンソールに表示されている値を使用してください。ほとんどのOpenAI互換SDKパターンでは、ベースURLにバージョンプレフィックスが含まれているため、SDK呼び出しは/chat/completionsのようなパスを正しく追加できます。

1つのFlatkeyベースURLで複数のモデルをルーティングできますか？

Flatkeyの公的な位置付けは、モデルアクセス、ルーティング、請求、使用状況分析、および運用管理のための単一のゲートウェイです。アプリ内では、各ワークロードを明示的なFlatkeyモデルエイリアスにマッピングし、トラフィックを移動させる前に実際のエイリアスをテストしてください。

これらのAI SDKスニペットはテスト済みですか？

これらのスニペットは、2026年6月29日にai@7.0.4、@ai-sdk/openai-compatible@3.0.1、@ai-sdk/openai@4.0.2、TypeScript、およびZodに対して型チェックが行われました。このランタイムでは有効なFlatkey APIキーが利用できなかったため、Flatkeyに対しては実行されていません。

結論

Vercel AI SDK カスタムプロバイダーのベースURLへの移行は、小規模なプロバイダー変更と捉え、厳密な検証チェックリストを伴うべきです。FlatkeyプロバイダーにはcreateOpenAICompatibleを使用し、ベースURLとモデルエイリアスは設定に保持し、まず非ストリーミングテキストをテストし、ストリーミングとツールコールは個別にテストし、Flatkeyでの使用実績を確認し、本番トラフィックが安定するまでロールバックの準備を整えておきます。チェックの準備ができたら、キーを取得し、独自のモデルエイリアスでスモークテストを実行してください。