跳至主要內容

MastraModelGateway

用於實現自訂模型 gateway 的抽象基類。Gateway 負責存取語言模型時特定於 Provider 的邏輯，包括 Provider 設定、身分驗證、URL 建構和模型執行個體化。

如果要提供普通物件形式的 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 registry，不使用前綴。

name:

string
gateway 的人類可讀名稱。

必需方法
「必需方法」的直接連結

fetchProviders()
「fetchproviders」的直接連結

從 gateway 取得 Provider 設定。

傳回值： Promise<Record<string, ProviderConfig>>

ProviderConfig 結構：

name:

string
Provider 的顯示名稱

models:

string[]
可用模型 ID 的陣列

apiKeyEnvVar:

string | string[]
API key 的環境變數

gateway:

string
Gateway 識別碼

url?:

string
選用的 API 基礎 URL

apiKeyHeader?:

string
選用的自訂身分驗證 header 名稱

docUrl?:

string
選用的文件 URL

buildUrl()
「buildurl」的直接連結

為指定的模型/Provider 組合建置 API URL。

如果 Provider URL 包含 ${ACCOUNT_ID} 等預留位置，請先在 buildUrl() 內從 envVars 或 process.env 解析它們，再傳回最終 URL。

參數：

modelId:

string
完整模型 ID（例如 "custom/my-provider/model-1"）

envVars?:

Record<string, string>
選用的環境變數

傳回值： string | undefined | Promise<string | undefined>

getApiKey()
「getapikey」的直接連結

取得用於身分驗證的 API key。

參數：

modelId:

string
完整模型 ID

傳回值： Promise<string>

resolveAuth()
「resolveauth」的直接連結

在 Mastra 建立語言模型之前解析認證資訊。當 gateway 自行負責身分驗證時，請實作此選用 hook。如果省略，Mastra 會改用 getApiKey()。

參數：

request:

GatewayAuthRequest
傳入的請求情境，包含 gatewayId、providerId、modelId 和 routerId，供 gateway 檢查和驗證。

傳回值： GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>

GatewayAuthResult 可包含 apiKey、bearerToken、headers，以及用於追蹤身分驗證來源的選用 source 欄位。

resolveLanguageModel()
「resolvelanguagemodel」的直接連結

建立語言模型執行個體。

參數：

modelId:

string
模型 ID

providerId:

string
Provider ID

apiKey:

string
用於身分驗證的 API key

傳回值： 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 的 registry
On this page