> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 마스트라Model게이트웨이

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

기본 클래스를 확장하지 않고 일반 객체 게이트웨이를 제공하려면 `MastraModelGatewayInterface`를 사용합니다.

## 수업 개요

```typescript
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은 다음 형식을 사용하여 액세스됩니다.

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

예:

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

## 내장 구현

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

## 관련된

- [사용자 정의 게이트웨이 가이드](https://mastra.zisheng.pro/ko/models/gateways/custom-gateways): 커스텀 게이트웨이 생성에 대한 전체 가이드
- [마스트라.추가게이트웨이()](https://mastra.zisheng.pro/ko/reference/core/addGateway): Mastra에 게이트웨이 추가
- [마스트라.getGateway()](https://mastra.zisheng.pro/ko/reference/core/getGateway): 등록키로 게이트웨이 받기
- [Mastra.getGatewayById()](https://mastra.zisheng.pro/ko/reference/core/getGatewayById): ID로 게이트웨이 가져오기
- [Mastra.listGateways()](https://mastra.zisheng.pro/ko/reference/core/listGateways): 모든 게이트웨이 나열