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

# 模型 Provider

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

## 功能

- **一個 API 適用於任何模型**：毋須安裝及管理額外的 Provider 依賴套件，即可存取任何模型。

- **使用最新 AI**：新模型發佈後即可使用，不受其所屬 Provider 限制。Mastra 不綁定特定 Provider 的介面亦可避免供應商鎖定。

- [**混合配搭模型**](#mix-and-match-models)：為不同工作使用不同模型。例如，以 GPT-5-mini 處理大型上下文，再切換至 Claude Opus 4.6 執行推理工作。

- [**模型後備切換**](#model-fallbacks)：如果 Provider 發生服務中斷，Mastra 可在應用程式層級自動切換至另一個 Provider；與 API Gateway 相比，可盡量減少延遲。

## 基本用法

不論你使用 OpenAI、Anthropic、Google，還是 OpenRouter 等 Gateway，只需以 `"provider/model-name"` 指定模型，其餘部分由 Mastra 處理。

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

**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-HK/models/gateways)
- [Provider](https://mastra.ai/zh-HK/models/providers)

你亦可直接在編輯器中探索模型。Mastra 為 `model` 欄位提供完整自動完成功能；只需開始輸入，IDE 便會顯示可用選項。

你也可以在 [Studio](https://mastra.zisheng.pro/zh-HK/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-HK/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 金鑰及模型偏好。

## 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 頁面。

## 模型後備切換

只依賴單一模型會為應用程式造成單點故障。模型後備切換可在模型及 Provider 之間自動容錯轉移。如果主要模型無法使用，系統會依次向已設定的後備模型重試請求，直至成功為止。

```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 錯誤、速率限制或逾時，便會自動切換至第一個後備模型；如仍然失敗，則繼續切換至下一個。每個模型均有獨立的重試次數，之後才會切換。

使用者不會感受到服務中斷；回應格式維持不變，只是改由另一個模型提供。系統沿後備鏈切換時會保留錯誤上下文，在維持串流相容性的同時確保錯誤能清晰傳遞。

### 個別模型設定

每個後備項目均可包含自己的 `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`：個別後備項目會覆寫呼叫時選項，而呼叫時選項會覆寫 Agent 的 `defaultOptions`。`modelSettings` 按鍵進行淺層合併；`providerOptions` 則遞迴深層合併，因此巢狀 Provider 設定（例如 `google.thinkingConfig`）可在各層保留同層鍵。
- `headers`：呼叫時的 `modelSettings.headers` 會覆寫個別後備項目的 `headers`，後者再覆寫從模型路由器模型擷取的標頭。執行階段標頭（追蹤、驗證及租戶資訊）會刻意優先於模型層級標頭。

每個欄位亦接受以 `requestContext` 為參數的函式，與動態模型的解析方式一致。

## 在 Mastra 使用本機模型

Mastra 亦支援在你自己的硬件上運行 `gpt-oss`、`Qwen3`、`DeepSeek` 等多種本機模型。運行本機模型的應用程式須提供與 OpenAI 相容的 API 伺服器，讓 Mastra 連接。我們建議使用 [LMStudio](https://lmstudio.ai/)（請參閱[運行 LMStudio 伺服器](https://lmstudio.ai/docs/developer/core/server)）。

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

當遠端服務的行為類似直接 Provider，並預期收到 `llama3.2` 等不含命名空間的模型名稱時，請使用 `provider/model`。

當遠端服務的行為類似模型 Gateway，且上游模型命名空間包含 Provider 時，請使用 `gateway/provider/model`，例如 `mastra/google/gemini-2.5-flash` 或 `openrouter/google/gemini-2.5-flash`。

設定 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 伺服器後，本機伺服器可透過 `http://localhost:1234` 存取，並提供 `/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')`），包括模型路由器的後備模型及[評分器](https://mastra.zisheng.pro/zh-HK/docs/evals/overview)。