模型 Provider

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

功能

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

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

• 混搭模型：針對不同工作使用不同模型。例如，先用 GPT-5-mini 處理大型內容脈絡，再切換至 Claude Opus 4.6 執行推理工作。

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

基本用法

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

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

OpenAI

src/mastra/agents/my-agent.ts

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

src/mastra/agents/my-agent.ts

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

src/mastra/agents/my-agent.ts

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

src/mastra/agents/my-agent.ts

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

src/mastra/agents/my-agent.ts

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

OpenRouter

Netlify

Vercel

另有 3 個

Provider

OpenAI

Anthropic

Google

另有 159 個

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

你也可以在 Studio UI 中瀏覽及測試模型。

資訊

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

混搭模型

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

src/mastra/agents/reasoning-agent.ts

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',
})

動態選擇模型

由於模型只是字串，因此你可以根據請求內容脈絡、變數或任何其他邏輯來動態選擇模型。

src/mastra/agents/dynamic-assistant-agent.ts

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。

src/mastra/agents/planner-agent.ts

// 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 專屬欄位，請使用以下語法。

src/mastra/agents/custom-agent.ts

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 重試請求，直到其中一個成功為止。

src/mastra/agents/resilient-assistant-agent.ts

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 專屬調整參數，才能產生可比較的輸出時，這項功能會很實用。

src/mastra/agents/tuned-resilient-agent.ts

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（請參閱執行 LMStudio 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，而不是個別的聊天端點。

src/mastra/agents/my-agent.ts

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 前綴：

src/mastra/agents/my-agent.ts

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}）。

src/mastra/agents/my-agent.ts

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 也提供支援。

src/mastra/agents/my-agent.ts

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。