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

# モデル Provider

Mastra は複数の Provider の LLM を扱う統一 interface を提供し、単一の API から 168 Provider、5458 モデルを利用できます。

## 機能

- **すべてのモデルに 1 つの API**: Provider ごとの依存関係を追加でインストール、管理せずに、任意のモデルを利用できます。

- **最新の AI をすぐに利用**: Provider を問わず、新しいモデルのリリース直後から利用できます。Mastra の Provider 非依存 interface により vendor lock-in を避けられます。

- [**モデルを組み合わせる**](#mix-and-match-models): タスクに応じて異なるモデルを使用します。たとえば、大きな context の処理には GPT-5-mini を使い、推論タスクには Claude Opus 4.6 に切り替えます。

- [**モデル fallback**](#model-fallbacks): Provider に障害が発生した場合、Mastra は application level で別の Provider に自動切り替えできます。API Gateway と比べてレイテンシーを抑えられます。

## 基本的な使用方法

OpenAI、Anthropic、Google、OpenRouter などの Gateway のいずれを使う場合も、モデルを `"provider/model-name"` 形式で指定すれば、残りは Mastra が処理します。

Mastra は対応する環境変数（例: `ANTHROPIC_API_KEY`）を読み取り、リクエストを Provider に routing します。API key がない場合は、設定すべき変数を示す明確な runtime error が発生します。

**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"
})
```

## モデル directory

左側の navigation または以下の一覧から、利用可能なモデルを探せます。

- [Gateway](https://mastra.ai/ja/models/gateways)
- [Provider](https://mastra.ai/ja/models/providers)

エディターから直接モデルを探すこともできます。Mastra は `model` フィールドの完全な自動補完に対応しており、入力を始めると IDE に選択肢が表示されます。

また、[Studio](https://mastra.zisheng.pro/ja/docs/studio/overview) UI でモデルを探して試すこともできます。

> **情報:** 開発環境では、ローカルのモデル一覧が 1 時間ごとに自動更新され、TypeScript の自動補完と Studio が最新のモデルに保たれます。無効にするには `MASTRA_AUTO_REFRESH_PROVIDERS=false` を設定します。本番環境ではデフォルトで無効です。

## モデルを組み合わせる

高速だが機能が限られるモデルもあれば、より大きな context window や強力な推論能力を持つモデルもあります。タスクに合わせて、同じ 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"
})
```

## 動的なモデル選択

モデルは単なる文字列なので、[request context](https://mastra.zisheng.pro/ja/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 test - 本番環境でモデルの性能を比較する
- ユーザーが選べるモデル - application でユーザーが好みのモデルを選択できるようにする
- multi-tenant application - 顧客ごとに独自の API key とモデル設定を使用する

## Provider 固有の option

モデル Provider ごとに固有の設定 option があります。OpenAI では `reasoningEffort`、Anthropic では `cacheControl` などを調整できます。Mastra では、これらの `providerOptions` を Agent level または message ごとに設定できます。

```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

organization ID やその他の Provider 固有フィールドなど、カスタム header を指定する場合は次の構文を使用します。

```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 の詳細は、左側の navigation から各 Provider のページを参照してください。

## モデル fallback

単一モデルへの依存は application の単一障害点になります。モデル fallback は、モデルと Provider の間で自動 failover を行います。primary model が利用できなくなると、成功するまで設定済みの次の 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 は最初に primary model を試します。500 error、rate limit、timeout が発生すると、最初の fallback に自動で切り替えます。それも失敗した場合は次へ進みます。各モデルは、次へ進む前に個別の回数で再試行されます。

ユーザーが切り替えを意識することはありません。別のモデルから同じ形式のレスポンスが返ります。fallback chain を進む間も error context が保持されるため、streaming との互換性を維持しながらエラーを適切に伝播できます。

### モデルごとの設定

各 fallback entry には独自の `modelSettings`、`providerOptions`、`headers` を指定できます。chain 内のモデルで、同等の出力を得るために異なる 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 entry ごとの設定が呼び出し時の option より優先され、呼び出し時の option は Agent の `defaultOptions` より優先されます。`modelSettings` は key ごとに shallow merge されます。`providerOptions` は再帰的に deep merge されるため、入れ子の Provider 設定（例: `google.thinkingConfig`）では layer 間で隣接 key が保持されます。
- `headers`: 呼び出し時の `modelSettings.headers`、fallback entry ごとの `headers`、モデルルーターのモデルから抽出された header の順に優先されます。runtime header（Trace、認証、tenancy）は意図的にモデル level の header より優先されます。

各フィールドには、動的モデルの解決方法と同様に `requestContext` の function も指定できます。

## Mastra でローカルモデルを使用する

Mastra は、`gpt-oss`、`Qwen3`、`DeepSeek` など、自分の hardware で実行する多くのローカルモデルにも対応しています。ローカルモデルを実行する application は、Mastra が接続できる OpenAI 互換 API server を提供する必要があります。[LMStudio](https://lmstudio.ai/) の使用を推奨します（[LMStudio server の実行](https://lmstudio.ai/docs/developer/core/server)を参照）。

カスタム OpenAI 互換 endpoint では、`id` は Mastra がモデルルーターに渡す routing 形式です。

remote が直接接続する Provider として動作し、`llama3.2` のような単純なモデル名を受け取る場合は、`provider/model` を使用します。

remote がモデル Gateway として動作し、upstream のモデル namespace に Provider が含まれる場合は、`mastra/google/gemini-2.5-flash` や `openrouter/google/gemini-2.5-flash` のように `gateway/provider/model` を使用します。

`url` には個別の chat endpoint ではなく、Mastra の `model` 設定とともに OpenAI 互換 endpoint の base 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"
  }
})
```

remote がモデル Gateway として動作する場合は、`id` に Gateway prefix を含めます。

```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 を起動すると、ローカル server は `http://localhost:1234` で利用でき、`/v1/models`、`/v1/chat/completions` などの endpoint を提供します。`url` は `http://localhost:1234/v1` です。`id` には、LMStudio interface に表示される `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 を使用する

Mastra は、直接使用する場合のために AI SDK Provider module に対応しています。

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

AI SDK モデル（例: `groq('gemma2-9b-it')`）は、モデルルーターの fallback や [scorer](https://mastra.zisheng.pro/ja/docs/evals/overview) など、`"provider/model"` 文字列を受け取る任意の場所で使用できます。