メインコンテンツへ移動

MastraModelGateway

カスタムモデル Gateway を実装するための抽象基底クラスです。Gateway は、Provider の設定、認証、URL の構築、モデルのインスタンス化など、言語モデルにアクセスするための Provider 固有のロジックを処理します。

基底クラスを拡張せず、プレーンオブジェクトの Gateway を提供する場合は MastraModelGatewayInterface を使用します。

クラスの概要
クラスの概要への直接リンク

import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm'
import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5'
import type { LanguageModelV2 } from '@ai-sdk/provider-v5'

class MyCustomGateway extends MastraModelGateway {
  readonly id = 'custom'
  readonly name = 'My Custom Gateway'

  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
    return {
      'my-provider': {
        name: 'My Provider',
        models: ['openai/gpt-5.6-sol', 'anthropic/claude-sonnet-4-6'],
        apiKeyEnvVar: 'MY_API_KEY',
        gateway: this.id,
      },
    }
  }

  buildUrl(modelId: string, envVars?: Record<string, string>): string {
    return 'https://api.my-provider.com/v1'
  }

  async getApiKey(modelId: string): Promise<string> {
    const apiKey = process.env.MY_API_KEY
    if (!apiKey) throw new Error('MY_API_KEY not set')
    return apiKey
  }

  async resolveLanguageModel({
    modelId,
    providerId,
    apiKey,
  }: {
    modelId: string
    providerId: string
    apiKey: string
  }): Promise<LanguageModelV2> {
    const baseURL = this.buildUrl(`${providerId}/${modelId}`)
    return createOpenAICompatible({
      name: providerId,
      apiKey,
      baseURL,
    }).chatModel(modelId)
  }
}

必須プロパティ
必須プロパティへの直接リンク

id:

string
Gateway の一意の識別子。この ID は、この Gateway に属するすべての Provider のプレフィックスとして使用されます（例: "netlify/anthropic"）。例外として、models.dev は Provider レジストリであるため、プレフィックスを使用しません。

name:

string
Gateway の人が読める名前。

必須メソッド
必須メソッドへの直接リンク

fetchProviders()
fetchprovidersへの直接リンク

Gateway から Provider の設定を取得します。

戻り値: Promise<Record<string, ProviderConfig>>

ProviderConfig の構造:

name:

string
Provider の表示名

models:

string[]
利用可能なモデル ID の配列

apiKeyEnvVar:

string | string[]
API キーの環境変数

gateway:

string
Gateway の識別子

url?:

string
任意のベース API URL

apiKeyHeader?:

string
任意のカスタム認証ヘッダー名

docUrl?:

string
任意のドキュメント URL

buildUrl()
buildurlへの直接リンク

特定のモデルと Provider の組み合わせに対する API URL を構築します。

Provider の URL に ${ACCOUNT_ID} などのプレースホルダーが含まれる場合は、最終的な URL を返す前に、buildUrl() 内で envVars または process.env から解決します。

パラメーター:

modelId:

string
完全なモデル ID（例: "custom/my-provider/model-1"）

envVars?:

Record<string, string>
任意の環境変数

戻り値: string | undefined | Promise<string | undefined>

getApiKey()
getapikeyへの直接リンク

認証用の API キーを取得します。

パラメーター:

modelId:

string
完全なモデル ID

戻り値: Promise<string>

resolveAuth()
resolveauthへの直接リンク

Mastra が言語モデルを作成する前に認証情報を解決します。Gateway が認証を担う場合は、この任意のフックを実装します。省略すると、Mastra は getApiKey() にフォールバックします。

パラメーター:

request:

GatewayAuthRequest
Gateway が検査して検証するための gatewayId、providerId、modelId、routerId を含む受信リクエストコンテキスト。

戻り値: GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>

GatewayAuthResult には apiKey、bearerToken、headers と、認証情報の取得元を追跡するための任意の source フィールドを含めることができます。

resolveLanguageModel()
resolvelanguagemodelへの直接リンク

言語モデルのインスタンスを作成します。

パラメーター:

modelId:

string
モデル ID

providerId:

string
Provider ID

apiKey:

string
認証用の API キー

戻り値: Promise<LanguageModelV2> | LanguageModelV2

インスタンスメソッド
インスタンスメソッドへの直接リンク

getId()
getidへの直接リンク

Gateway の一意の識別子を返します。

戻り値: string - Gateway の id プロパティ

モデル ID の形式
モデル ID の形式への直接リンク

実際の Gateway では、Gateway ID がプレフィックスとして使用され、次の形式でモデルにアクセスします。

[gateway-id]/[provider]/[model]

例:

  • id = 'custom' の Gateway: 'custom/my-provider/model-1'

組み込み実装
組み込み実装への直接リンク

  • NetlifyGateway - Netlify AI Gateway との統合
  • ModelsDevGateway - OpenAI 互換 Provider のレジストリ
On this page