跳到主要内容

模型 Provider

Mastra 提供统一接口，只需一个 API 即可使用 168 个 Provider 提供的 5458 个模型。

功能
功能的直接链接

  • 一个 API 使用任意模型：无需安装和管理额外的 Provider 依赖，即可访问任意模型。

  • 率先使用最新 AI：无论新模型来自哪个 Provider，发布后都能立即使用。Mastra 与 Provider 无关的接口还可以避免 Vendor lock-in。

  • 混合搭配模型：为不同任务使用不同模型。例如，使用 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，运行时错误会明确提示需要设置哪个变量。

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

模型目录
模型目录的直接链接

你可以通过左侧导航浏览可用模型目录，也可以在下方查看。

Gateway
OpenRouterOpenRouter
Netlify
VercelVercel
另有 3 个
Provider
OpenAIOpenAI
AnthropicAnthropic
GoogleGoogle
另有 159 个

你也可以直接在编辑器中查找模型。Mastra 为 model 字段提供完整的自动补全，只需开始输入，IDE 就会显示可用选项。

你也可以在 Studio 界面中浏览和测试模型。

信息

在开发环境中，本地模型列表每小时自动刷新一次，确保 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',
})

动态选择模型
动态选择模型的直接链接

由于模型只是字符串，因此可以根据 RequestContext、变量或其他逻辑动态选择模型。

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 专属选项的直接链接

不同模型 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' },
    },
  },
])

自定义 header
自定义 header的直接链接

如果需要指定自定义 header，例如组织 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 的配置有所不同。自定义 header 的详情请参阅左侧导航中的各 Provider 页面。

模型 fallback
模型 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 条目都可以拥有独立的 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，后者又优先于从模型路由器模型中提取的 header。运行时 header（Tracing、认证和租户信息）有意优先于模型级 header。

每个字段也接受基于 requestContext 的函数，与动态模型的解析方式一致。

在 Mastra 中使用本地模型
在 Mastra 中使用本地模型的直接链接

Mastra 也支持在自有硬件上运行的 gpt-oss、Qwen3、DeepSeek 等本地模型。运行本地模型的应用需要提供兼容 OpenAI 的 API Server，供 Mastra 连接。我们推荐使用 LMStudio（请参阅运行 LMStudio Server）。

对于自定义的 OpenAI 兼容 endpoint，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 兼容 endpoint 的 base URL，而不是单独的 chat endpoint。

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的直接链接

启动 LMStudio Server 后，可以通过 http://localhost:1234 访问本地 Server。它会提供 /v1/models、/v1/chat/completions 等 endpoint，因此 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
在 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。

On this page