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

# 模型 Provider

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

## 功能

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

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

- [**混合搭配模型**](#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/models/gateways)
- [Provider](https://mastra.ai/models/providers)

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

你也可以在 [Studio](https://mastra.zisheng.pro/docs/studio/overview) 界面中浏览和测试模型。

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

## 动态选择模型

由于模型只是字符串，因此可以根据 [RequestContext](https://mastra.zisheng.pro/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' },
    },
  },
])
```

## 自定义 header

如果需要指定自定义 header，例如组织 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 的配置有所不同。自定义 header 的详情请参阅左侧导航中的各 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 条目都可以拥有独立的 `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`，后者又优先于从模型路由器模型中提取的 header。运行时 header（Tracing、认证和租户信息）有意优先于模型级 header。

每个字段也接受基于 `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 兼容 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。

```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` 等 endpoint，因此 `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/docs/evals/overview)。