마스트라Model게이트웨이

사용자 정의 Model 게이트웨이를 구현하기 위한 추상 기본 클래스입니다. 게이트웨이는 공급자 구성, 인증, URL 구성 및 Model 인스턴스화를 포함하여 언어 Model에 액세스하기 위한 공급자별 논리를 처리합니다.

기본 클래스를 확장하지 않고 일반 객체 게이트웨이를 제공하려면 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

게이트웨이의 고유 식별자입니다. 이 ID는 해당 게이트웨이의 모든 Provider에 대한 접두사로 사용됩니다(예: "netlify/anthropic"). 예외: models.dev는 Provider 레지스트리이므로 접두사를 사용하지 않습니다.

name:

string

사람이 읽을 수 있는 게이트웨이 이름입니다.

필수 방법

fetchProviders()

게이트웨이에서 공급자 구성을 가져옵니다.

보고: Promise<Record<string, ProviderConfig>>

공급자 구성 구조:

name:

string

Provider의 표시 이름

models:

string[]

사용 가능한 Model ID 배열

apiKeyEnvVar:

string | string[]

API 키의 환경 변수

gateway:

string

게이트웨이 식별자

url?:

string

선택적 기본 API URL

apiKeyHeader?:

string

선택적 사용자 정의 인증 헤더 이름

docUrl?:

string

선택적 문서 URL

buildUrl()

특정 Model/공급자 조합에 대한 API URL을 구축합니다.

Provider URL에 ${ACCOUNT_ID}와 같은 자리 표시자가 포함되어 있으면 최종 URL을 반환하기 전에 buildUrl() 내부에서 envVars 또는 process.env를 사용하여 해석합니다. 매개변수:

modelId:

string

전체 Model ID(예: "custom/my-provider/model-1")

envVars?:

Record<string, string>

선택적 환경 변수

보고: string | undefined | Promise<string | undefined>

getApiKey()

인증을 위한 API 키를 검색합니다.

매개변수:

modelId:

string

전체 Model ID

보고: Promise<string>

resolveAuth()

Mastra가 언어 Model을 생성하기 전에 자격 증명을 확인합니다. 게이트웨이가 인증을 소유하는 경우 이 선택적 후크를 구현하십시오. 생략하면 Mastra는 다음으로 돌아갑니다.getApiKey().

매개변수:

request:

GatewayAuthRequest

게이트웨이가 검사하고 검증할 수 있도록 gatewayId, providerId, modelId 및 routerId를 포함하는 수신 요청 컨텍스트입니다.

보고: GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>

GatewayAuthResult에는 apiKey, bearerToken, headers와 인증의 출처를 추적하기 위한 선택적 source 필드가 포함될 수 있습니다.

resolveLanguageModel()

언어 Model 인스턴스를 만듭니다.

매개변수:

modelId:

string

Model ID

providerId:

string

Provider ID

apiKey:

string

인증에 사용할 API 키

보고: Promise<LanguageModelV2> | LanguageModelV2

인스턴스 메소드

getId()

게이트웨이의 고유 식별자를 반환합니다.

반환: string - 게이트웨이의 id 속성

Model ID 형식

실제 게이트웨이의 경우 게이트웨이 ID가 접두사로 사용되며 Model은 다음 형식을 사용하여 액세스됩니다.

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

예:

• 게이트웨이id = 'custom': 'custom/my-provider/model-1'

내장 구현

• Netlify게이트웨이- Netlify AI Gateway 통합
• ModelDevGateway- OpenAI 호환 Provider 등록

관련된

• 사용자 정의 게이트웨이 가이드: 커스텀 게이트웨이 생성에 대한 전체 가이드
• 마스트라.추가게이트웨이(): Mastra에 게이트웨이 추가
• 마스트라.getGateway(): 등록키로 게이트웨이 받기
• Mastra.getGatewayById(): ID로 게이트웨이 가져오기
• Mastra.listGateways(): 모든 게이트웨이 나열