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

# MastraModelGateway

用於實作自訂模型 gateway 的抽象基礎類別。Gateway 負責處理存取語言模型時 Provider 特定的邏輯，包括 Provider 配置、驗證、URL 建構及模型實例化。

如要提供純物件 gateway，而非擴展基礎類別，請使用 `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`): Gateway 的唯一標識符。此 ID 會用作這個 gateway 所有 Provider 的前綴（例如 "netlify/anthropic"）。例外：models.dev 是 Provider 註冊表，不使用前綴。

**name** (`string`): 便於閱讀的 gateway 名稱。

## 必要方法

### `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()`

為特定的模型／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()`

取得用於驗證的 API key。

**參數：**

**modelId** (`string`): 完整模型 ID

**傳回：** `Promise<string>`

### `resolveAuth()`

在 Mastra 建立語言模型前解析憑證。當 gateway 負責驗證時，請實作這個可選 hook。如省略，Mastra 會改用 `getApiKey()`。

**參數：**

**request** (`GatewayAuthRequest`): 傳入的請求 context，包含 gatewayId、providerId、modelId 及 routerId，供 gateway 檢查及驗證。

**傳回：** `GatewayAuthResult | undefined | Promise<GatewayAuthResult | undefined>`

`GatewayAuthResult` 可包括 `apiKey`、`bearerToken`、`headers`，以及用於追蹤驗證資料來源的可選 `source` 欄位。

### `resolveLanguageModel()`

建立語言模型實例。

**參數：**

**modelId** (`string`): 模型 ID

**providerId** (`string`): Provider ID

**apiKey** (`string`): 用於驗證的 API key

**傳回：** `Promise<LanguageModelV2> | LanguageModelV2`

## 實例方法

### `getId()`

傳回 gateway 的唯一標識符。

**傳回：** `string` - gateway 的 `id` 屬性

## 模型 ID 格式

對於真正的 gateway，gateway ID 會用作前綴，並以下列格式存取模型：

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

範例：

- `id = 'custom'` 的 Gateway：`'custom/my-provider/model-1'`

## 內置實作

- **NetlifyGateway** - Netlify AI Gateway 整合
- **ModelsDevGateway** - OpenAI-compatible Provider 的註冊表

## 相關內容

- [自訂 Gateway 指南](https://mastra.zisheng.pro/zh-HK/models/gateways/custom-gateways)：建立自訂 gateway 的完整指南
- [Mastra.addGateway()](https://mastra.zisheng.pro/zh-HK/reference/core/addGateway)：在 Mastra 加入 gateway
- [Mastra.getGateway()](https://mastra.zisheng.pro/zh-HK/reference/core/getGateway)：按註冊 key 取得 gateway
- [Mastra.getGatewayById()](https://mastra.zisheng.pro/zh-HK/reference/core/getGatewayById)：按 ID 取得 gateway
- [Mastra.listGateways()](https://mastra.zisheng.pro/zh-HK/reference/core/listGateways)：列出所有 gateway