跳到主要内容

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 注册表，不使用前缀。

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 的注册表
On this page