MastraModelGateway

Classe de base abstraite permettant d'implémenter des gateways de modèles personnalisées. Les gateways gèrent la logique propre au Provider pour accéder aux modèles de langage, notamment la configuration du Provider, l'authentification, la construction des URL et l'instanciation des modèles.

Utilisez MastraModelGatewayInterface lorsque vous souhaitez fournir une gateway sous forme d'objet simple au lieu d'étendre la classe de base.

Présentation de la classe

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)
  }
}

Propriétés requises

id:

string

Identifiant unique de la gateway. Cet identifiant sert de préfixe à tous les Providers de cette gateway (par exemple, "netlify/anthropic"). Exception : models.dev est un registre de Providers et n'utilise pas de préfixe.

name:

string

Nom lisible de la gateway.

Méthodes requises

fetchProviders()

Récupère les configurations des Providers depuis la gateway.

Renvoie : Promise<Record<string, ProviderConfig>>

Structure de ProviderConfig :

name:

string

Nom d'affichage du Provider

models:

string[]

Tableau des identifiants de modèles disponibles

apiKeyEnvVar:

string | string[]

Variables d'environnement de la clé API

gateway:

string

Identifiant de la gateway

url?:

string

URL de base facultative de l'API

apiKeyHeader?:

string

Nom facultatif et personnalisé de l'en-tête d'authentification

docUrl?:

string

URL facultative de la documentation

buildUrl()

Construit l'URL de l'API pour une combinaison précise de modèle et de Provider.

Si l'URL de votre Provider contient des espaces réservés tels que ${ACCOUNT_ID}, résolvez-les dans buildUrl() à partir de envVars ou de process.env avant de renvoyer l'URL finale.

Paramètres :

modelId:

string

Identifiant complet du modèle (par exemple, "custom/my-provider/model-1")

envVars?:

Record<string, string>

Variables d'environnement facultatives

Renvoie : string | undefined | Promise<string | undefined>

getApiKey()

Récupère la clé API nécessaire à l'authentification.

Paramètres :

modelId:

string

Identifiant complet du modèle

Renvoie : Promise<string>

resolveAuth()

Résout les identifiants avant que Mastra ne crée le modèle de langage. Implémentez ce hook facultatif lorsque la gateway gère l'authentification. En cas d'omission, Mastra se rabat sur getApiKey().

Paramètres :

request:

GatewayAuthRequest

Contexte de la requête entrante contenant gatewayId, providerId, modelId et routerId, afin que la gateway puisse l'inspecter et le valider.

Renvoie : GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>

Un GatewayAuthResult peut comprendre apiKey, bearerToken, headers ainsi qu'un champ facultatif source permettant de retracer l'origine de l'authentification.

resolveLanguageModel()

Crée une instance de modèle de langage.

Paramètres :

modelId:

string

Identifiant du modèle

providerId:

string

Identifiant du Provider

apiKey:

string

Clé API nécessaire à l'authentification

Renvoie : Promise<LanguageModelV2> | LanguageModelV2

Méthodes d'instance

getId()

Renvoie l'identifiant unique de la gateway.

Renvoie : string - Propriété id de la gateway

Format des identifiants de modèles

Pour les véritables gateways, l'identifiant de la gateway sert de préfixe et les modèles sont accessibles au format suivant :

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

Exemples :

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

Implémentations intégrées

• NetlifyGateway - Intégration de Netlify AI Gateway
• ModelsDevGateway - Registre de Providers compatibles avec OpenAI

Ressources associées

• Guide des gateways personnalisées : guide complet pour créer des gateways personnalisées
• Mastra.addGateway() : ajoute une gateway à Mastra
• Mastra.getGateway() : obtient une gateway à partir de sa clé d'enregistrement
• Mastra.getGatewayById() : obtient une gateway à partir de son identifiant
• Mastra.listGateways() : répertorie toutes les gateways