模型 Provider

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

功能

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

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

• 混合配搭模型：為不同工作使用不同模型。例如，以 GPT-5-mini 處理大型上下文，再切換至 Claude Opus 4.6 執行推理工作。

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

基本用法

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

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

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 金鑰及模型偏好。

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

模型後備切換

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

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

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

個別模型設定

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

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

在 Mastra 使用本機模型

Mastra 亦支援在你自己的硬件上運行 gpt-oss、Qwen3、DeepSeek 等多種本機模型。運行本機模型的應用程式須提供與 OpenAI 相容的 API 伺服器，讓 Mastra 連接。我們建議使用 LMStudio（請參閱運行 LMStudio 伺服器）。

對於自訂的 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，而非個別聊天端點。

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 伺服器後，本機伺服器可透過 http://localhost:1234 存取，並提供 /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')），包括模型路由器的後備模型及評分器。