MastraModelGateway

用于实现自定义模型网关的抽象基类。网关负责处理访问语言模型的特定提供商逻辑，包括提供商配置、认证、URL 构建以及模型实例化。

🌐 Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.

课程概览

🌐 Class Overview

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: ['model-1', 'model-2'],
        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);
  }
}

必填属性

🌐 Required Properties

id:

string

Unique identifier for the gateway. This ID is used as the prefix for all providers from this gateway (e.g., "netlify/anthropic"). Exception: models.dev is a provider registry and doesn't use a prefix.

name:

string

Human-readable name for the gateway.

必需的方法

🌐 Required Methods

fetchProviders()

从网关获取提供商配置。

🌐 Fetches provider configurations from the gateway.

返回值: Promise<Record<string, ProviderConfig>>

ProviderConfig Structure:

name:

string

Display name of the provider

models:

string[]

Array of available model IDs

apiKeyEnvVar:

string | string[]

Environment variable(s) for API key

gateway:

string

Gateway identifier

url?:

string

Optional base API URL

apiKeyHeader?:

string

Optional custom auth header name

docUrl?:

string

Optional documentation URL

buildUrl()

为特定模型/提供商组合构建 API URL。

🌐 Builds the API URL for a specific model/provider combination.

Parameters:

modelId:

string

Full model ID (e.g., "custom/my-provider/model-1")

envVars?:

Record<string, string>

Optional environment variables

返回值: string | undefined | Promise<string | undefined>

getApiKey()

获取用于身份验证的 API 密钥。

🌐 Retrieves the API key for authentication.

Parameters:

modelId:

string

Full model ID

返回值: Promise<string>

resolveLanguageModel()

创建一个语言模型实例。

🌐 Creates a language model instance.

Parameters:

modelId:

string

The model ID

providerId:

string

The provider ID

apiKey:

string

The API key for authentication

返回值: Promise<LanguageModelV2> | LanguageModelV2

实例方法

🌐 Instance Methods

getId()

返回网关的唯一标识符。

🌐 Returns the gateway's unique identifier.

返回值： string - 网关的 id 属性

型号格式

🌐 Model ID Format

对于真正的网关，网关 ID 用作前缀，并且可以使用以下格式访问模型：

🌐 For true gateways, the gateway ID is used as a prefix and models are accessed using this format:

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

示例：

🌐 Examples:

• 网关与 id = 'custom'：'custom/my-provider/model-1'

内置实现

🌐 Built-in Implementations

• NetlifyGateway - Netlify AI 网关集成
• ModelsDevGateway - OpenAI 兼容提供商注册表

相关

🌐 Related

• 自定义网关指南 - 创建自定义网关的完整指南
• Mastra.addGateway() - 向 Mastra 添加网关
• Mastra.getGateway() - 通过注册密钥获取网关
• Mastra.getGatewayById() - 通过ID获取网关
• Mastra.listGateways() - 列出所有网关