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

# 模型 Provider

Mastra 提供統一介面，可跨多個 Provider 使用 LLM，透過單一 API 即可存取來自 168 個 Provider 的 5458 個模型。

## 功能

- **一套 API 適用所有模型**：無須安裝及管理額外的 Provider 相依套件，即可存取任何模型。

- **使用最新的 AI**：新模型一推出即可使用，無論它來自哪個 Provider。透過 Mastra 不受特定 Provider 限制的介面，避免遭供應商綁定。

- [**混搭模型**](#mix-and-match-models)：針對不同工作使用不同模型。例如，先用 GPT-5-mini 處理大型內容脈絡，再切換至 Claude Opus 4.6 執行推理工作。

- [**模型 fallback**](#model-fallbacks)：如果某個 Provider 發生服務中斷，Mastra 可在應用程式層級自動切換至另一個 Provider，相較於 API gateway，能將延遲降至最低。

## 基本用法

無論你使用 OpenAI、Anthropic、Google，或 OpenRouter 之類的 gateway，只要以 `"provider/model-name"` 指定模型，其餘部分由 Mastra 處理。

Mastra 會讀取相關的環境變數（例如 `ANTHROPIC_API_KEY`），並將請求路由至 Provider。如果缺少 API key，執行階段會顯示清楚的錯誤，明確指出需要設定的變數。

**OpenAI**:

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: 'openai/gpt-5.6-sol',
})
```

**Anthropic**:

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: 'anthropic/claude-sonnet-4-6',
})
```

**Google Gemini**:

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: 'google/gemini-2.5-flash',
})
```

**xAI**:

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: 'xai/grok-4.3',
})
```

**OpenRouter**:

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: 'openrouter/anthropic/claude-haiku-4.5',
})
```

## 模型目錄

使用左側導覽列瀏覽可用模型的目錄，或在下方探索。

- [Gateway](https://mastra.ai/zh-TW/models/gateways)
- [Provider](https://mastra.ai/zh-TW/models/providers)

你也可以直接在編輯器中探索模型。Mastra 會為 `model` 欄位提供完整的自動完成建議，只要開始輸入，IDE 就會顯示可用選項。

你也可以在 [Studio](https://mastra.zisheng.pro/zh-TW/docs/studio/overview) UI 中瀏覽及測試模型。

> **資訊:** 在開發環境中，我們每小時會自動重新整理你的本機模型清單，確保 TypeScript 自動完成建議與 Studio 隨時納入最新模型。如要停用，請設定 `MASTRA_AUTO_REFRESH_PROVIDERS=false`。正式環境預設會停用自動重新整理。

## 混搭模型

有些模型速度較快但能力較弱，其他模型則提供更大的內容脈絡窗口或更強的推理能力。你可以針對各項工作使用同一 Provider 的不同模型，或跨 Provider 混搭模型。

```typescript
import { Agent } from '@mastra/core/agent'

// Use a cost-effective model for document processing
const documentProcessor = new Agent({
  id: 'document-processor',
  name: 'Document Processor',
  instructions: 'Extract and summarize key information from documents',
  model: 'openai/gpt-5.6-sol',
})

// Use a powerful reasoning model for complex analysis
const reasoningAgent = new Agent({
  id: 'reasoning-agent',
  name: 'Reasoning Agent',
  instructions: 'Analyze data and provide strategic recommendations',
  model: 'anthropic/claude-opus-4-7',
})
```

## 動態選擇模型

由於模型只是字串，因此你可以根據[請求內容脈絡](https://mastra.zisheng.pro/zh-TW/docs/server/request-context)、變數或任何其他邏輯來動態選擇模型。

```typescript
const agent = new Agent({
  id: 'dynamic-assistant',
  name: 'Dynamic Assistant',
  model: ({ requestContext }) => {
    const provider = requestContext.get('provider-id')
    const model = requestContext.get('model-id')
    return `${provider}/${model}`
  },
})
```

這能實現以下強大模式：

- A/B 測試 — 比較模型在正式環境中的效能。
- 使用者可選擇的模型 — 讓使用者在你的應用程式中選擇偏好的模型。
- 多租戶應用程式 — 每位客戶都可使用自己的 API key 與模型偏好設定。

## Provider 專屬選項

不同的模型 Provider 會提供各自的設定選項。使用 OpenAI 時，你可能會調整 `reasoningEffort`；使用 Anthropic 時，則可能會微調 `cacheControl`。Mastra 可讓你在 Agent 層級或個別訊息中設定這些特定的 `providerOptions`。

```typescript
// Agent level (apply to all future messages)
const planner = new Agent({
  id: 'planner',
  name: 'Planner',
  instructions: {
    role: 'system',
    content: 'You are a helpful assistant.',
    providerOptions: {
      openai: { reasoningEffort: 'low' },
    },
  },
  model: 'openai/gpt-5.6-sol',
})

const lowEffort = await planner.generate('Plan a simple 3 item dinner menu')

// Message level (apply only to this message)
const highEffort = await planner.generate([
  {
    role: 'user',
    content: 'Plan a simple 3 item dinner menu for a celiac',
    providerOptions: {
      openai: { reasoningEffort: 'high' },
    },
  },
])
```

## 自訂標頭

如果需要指定自訂標頭，例如組織 ID 或其他 Provider 專屬欄位，請使用以下語法。

```typescript
const agent = new Agent({
  id: 'custom-agent',
  name: 'Custom Agent',
  model: {
    id: 'openai/gpt-5.6-sol',
    apiKey: process.env.OPENAI_API_KEY,
    headers: {
      'OpenAI-Organization': 'org-abc123',
    },
  },
})
```

> **資訊:** 設定方式會因 Provider 而異。如需自訂標頭的詳細資訊，請參閱左側導覽列中的 Provider 頁面。

## 模型 fallback

僅依賴單一模型，會為應用程式帶來單點故障風險。模型 fallback 能在模型與 Provider 之間自動容錯移轉。如果主要模型無法使用，系統會依序使用後續設定的 fallback 重試請求，直到其中一個成功為止。

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'resilient-assistant',
  name: 'Resilient Assistant',
  instructions: 'You are a helpful assistant.',
  model: [
    {
      model: 'openai/gpt-5.6-sol',
      maxRetries: 3,
    },
    {
      model: 'anthropic/claude-sonnet-4-6',
      maxRetries: 2,
    },
    {
      model: 'google/gemini-2.5-pro',
      maxRetries: 2,
    },
  ],
})
```

Mastra 會先嘗試主要模型。如果遇到 500 錯誤、速率限制或逾時，就會自動切換至第一個 fallback。如果該 fallback 也失敗，則繼續嘗試下一個。切換至下一個模型前，每個模型都會依各自設定的重試次數嘗試。

你的使用者不會感受到服務中斷，回傳的回應格式維持不變，只是改由不同模型產生。系統沿 fallback 鏈逐一嘗試時會保留錯誤內容脈絡，在維持串流相容性的同時，確保錯誤能明確傳遞。

### 各模型設定

每個 fallback 項目都能有自己的 `modelSettings`、`providerOptions` 與 `headers`。當鏈中的模型需要不同的 temperature 或 Provider 專屬調整參數，才能產生可比較的輸出時，這項功能會很實用。

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'tuned-resilient',
  name: 'Tuned Resilient Agent',
  instructions: 'You are a helpful assistant.',
  model: [
    {
      model: 'google/gemini-2.5-flash',
      maxRetries: 2,
      modelSettings: { temperature: 0.3 },
      providerOptions: { google: { thinkingConfig: { thinkingBudget: 0 } } },
    },
    {
      model: 'openai/gpt-5-mini',
      maxRetries: 2,
      modelSettings: { temperature: 0.7 },
      providerOptions: { openai: { reasoningEffort: 'low' } },
    },
  ],
})
```

**優先順序：**

- `modelSettings` 與 `providerOptions`：各 fallback 項目的設定會覆寫呼叫時選項，而呼叫時選項又會覆寫 Agent 的 `defaultOptions`。`modelSettings` 會依 key 進行淺層合併。`providerOptions` 則會遞迴進行深層合併，因此巢狀 Provider 設定（例如 `google.thinkingConfig`）能在不同層級間保留同層的其他 key。
- `headers`：呼叫時的 `modelSettings.headers` 會覆寫各 fallback 的 `headers`，後者又會覆寫從模型路由器模型擷取的標頭。執行階段標頭（追蹤、驗證、租戶）則刻意優先於模型層級標頭。

每個欄位也接受以 `requestContext` 為引數的函式，與解析動態模型的方式相同。

## 搭配 Mastra 使用本機模型

Mastra 也支援在自有硬體上執行的 `gpt-oss`、`Qwen3`、`DeepSeek` 等許多本機模型。執行本機模型的應用程式需要提供與 OpenAI 相容的 API server，Mastra 才能連線。我們建議使用 [LMStudio](https://lmstudio.ai/)（請參閱[執行 LMStudio server](https://lmstudio.ai/docs/developer/core/server)）。

對於自訂的 OpenAI 相容端點，`id` 是 Mastra 透過模型路由器傳送的路由格式。

當遠端的運作方式類似直接連線的 Provider，並預期收到 `llama3.2` 這類不含命名空間的模型名稱時，請使用 `provider/model`。

當遠端的運作方式類似模型 gateway，而且上游模型命名空間包含 Provider（例如 `mastra/google/gemini-2.5-flash` 或 `openrouter/google/gemini-2.5-flash`）時，請使用 `gateway/provider/model`。

使用 Mastra 的 `model` 設定時，`url` **務必**使用 OpenAI 相容端點的基底 URL，而不是個別的聊天端點。

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: {
    id: 'custom/my-qwen3-model',
    url: 'http://your-custom-openai-compatible-endpoint.com/v1',
  },
})
```

如果遠端的運作方式類似模型 gateway，請在 `id` 中加入 gateway 前綴：

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: {
    id: 'mastra/google/gemini-2.5-flash',
    url: 'http://your-custom-openai-compatible-endpoint.com/v1',
  },
})
```

### 範例：LMStudio

啟動 LMStudio server 後，即可在 `http://localhost:1234` 使用本機 server，而它會提供 `/v1/models`、`/v1/chat/completions` 等端點。`url` 應設為 `http://localhost:1234/v1`。`id` 則可以使用 LMStudio 介面中顯示的（`lmstudio/${modelId}`）。

```typescript
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  instructions: 'You are a helpful assistant',
  model: {
    id: 'lmstudio/qwen/qwen3-30b-a3b-2507',
    url: 'http://localhost:1234/v1',
  },
})
```

## 搭配 Mastra 使用 AI SDK

如果需要直接使用 AI SDK Provider 模組，Mastra 也提供支援。

```typescript
import { groq } from '@ai-sdk/groq'
import { Agent } from '@mastra/core/agent'

const agent = new Agent({
  id: 'my-agent',
  name: 'My Agent',
  model: groq('gemma2-9b-it'),
})
```

任何接受 `"provider/model"` 字串的位置都可使用 AI SDK 模型（例如 `groq('gemma2-9b-it')`），包括模型路由器 fallback 與 [scorer](https://mastra.zisheng.pro/zh-TW/docs/evals/overview)。