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

# Providers de modèles

Mastra fournit une interface unifiée pour travailler avec des LLM chez plusieurs Providers et donne accès à 5 458 modèles provenant de 168 Providers via une seule API.

## Fonctionnalités

- **Une API pour tous les modèles** : accédez à n’importe quel modèle sans installer ni gérer de dépendances de Provider supplémentaires.

- **Accès aux IA les plus récentes** : utilisez les nouveaux modèles dès leur sortie, quel que soit leur Provider. Évitez l’enfermement propriétaire grâce à l’interface indépendante des Providers de Mastra.

- [**Combiner les modèles**](#mix-and-match-models) : utilisez des modèles différents pour des tâches différentes. Par exemple, utilisez GPT-5-mini pour traiter de grands contextes, puis Claude Opus 4.6 pour les tâches de raisonnement.

- [**Solutions de repli de modèle**](#model-fallbacks) : en cas d’indisponibilité d’un Provider, Mastra peut basculer automatiquement vers un autre Provider au niveau de l’application, en limitant la latence par rapport aux passerelles API.

## Utilisation de base

Que vous utilisiez OpenAI, Anthropic, Google ou une passerelle comme OpenRouter, indiquez le modèle sous la forme `"provider/model-name"` et Mastra s’occupe du reste.

Mastra lit la variable d’environnement correspondante (par exemple `ANTHROPIC_API_KEY`) et achemine les requêtes vers le Provider. Si une clé API est absente, une erreur d’exécution claire indique exactement quelle variable définir.

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

## Répertoire des modèles

Parcourez le répertoire des modèles disponibles avec la navigation de gauche, ou explorez-les ci-dessous.

- [Passerelles](https://mastra.ai/fr/models/gateways)
- [Providers](https://mastra.ai/fr/models/providers)

Vous pouvez aussi découvrir les modèles directement dans votre éditeur. Mastra propose l’autocomplétion complète pour le champ `model` : commencez à saisir du texte et votre IDE affichera les options disponibles.

Vous pouvez également parcourir et tester les modèles dans l’interface [Studio](https://mastra.zisheng.pro/fr/docs/studio/overview).

> **Info:** En développement, nous actualisons automatiquement votre liste locale de modèles chaque heure afin que l’autocomplétion TypeScript et Studio restent à jour. Pour désactiver cette fonction, définissez `MASTRA_AUTO_REFRESH_PROVIDERS=false`. L’actualisation automatique est désactivée par défaut en production.

## Combiner les modèles

Certains modèles sont plus rapides mais moins capables, tandis que d’autres offrent des fenêtres de contexte plus larges ou de meilleures capacités de raisonnement. Utilisez différents modèles d’un même Provider, ou combinez-les entre Providers selon chaque tâche.

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

## Sélection dynamique des modèles

Comme les modèles ne sont que des chaînes de caractères, vous pouvez les sélectionner dynamiquement en fonction du [contexte de requête](https://mastra.zisheng.pro/fr/docs/server/request-context), de variables ou de toute autre logique.

```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}`;
  },
});
```

Cela permet des modèles de conception puissants :

- Tests A/B : comparez les performances des modèles en production.
- Modèles sélectionnables par l’utilisateur : laissez les utilisateurs choisir leur modèle préféré dans votre application.
- Applications multi-locataires : chaque client peut fournir ses propres clés API et préférences de modèle.

## Options spécifiques aux Providers

Les différents Providers de modèles exposent leurs propres options de configuration. Avec OpenAI, vous pouvez ajuster `reasoningEffort`. Avec Anthropic, vous pouvez régler `cacheControl`. Mastra permet de définir ces `providerOptions` spécifiques au niveau de l’Agent ou pour chaque 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" }
    }
  }
]);
```

## En-têtes personnalisés

Si vous devez indiquer des en-têtes personnalisés, comme un ID d’organisation ou d’autres champs spécifiques à un Provider, utilisez cette syntaxe.

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

> **Info:** La configuration varie selon le Provider. Consultez les pages des Providers dans la navigation de gauche pour obtenir des détails sur les en-têtes personnalisés.

## Solutions de repli de modèle

S’appuyer sur un seul modèle crée un point de défaillance unique pour votre application. Les solutions de repli de modèle assurent un basculement automatique entre modèles et Providers. Si le modèle principal devient indisponible, les requêtes sont relancées avec la solution de repli configurée suivante jusqu’à ce que l’une réussisse.

```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 essaie d’abord votre modèle principal. S’il rencontre une erreur 500, une limite de débit ou un délai d’expiration, il bascule automatiquement vers votre première solution de repli. Si celle-ci échoue également, il passe à la suivante. Chaque modèle dispose de son propre nombre de tentatives avant le passage au suivant.

Vos utilisateurs ne subissent jamais l’interruption : la réponse revient au même format, mais depuis un autre modèle. Le contexte d’erreur est conservé au fil de la chaîne de repli, ce qui assure une propagation claire des erreurs tout en préservant la compatibilité avec le streaming.

### Paramètres par modèle

Chaque entrée de repli peut comporter ses propres `modelSettings`, `providerOptions` et `headers`, ce qui est utile lorsque les modèles de la chaîne nécessitent des températures ou des réglages propres au Provider différents pour produire des résultats comparables.

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

**Priorité :**

- `modelSettings` et `providerOptions` : l’entrée de repli remplace les options fournies à l’appel, lesquelles remplacent les `defaultOptions` de l’Agent. `modelSettings` effectue une fusion superficielle par clé. `providerOptions` effectue une fusion récursive, de sorte que la configuration Provider imbriquée (par exemple `google.thinkingConfig`) préserve les clés sœurs entre les couches.
- `headers` : `modelSettings.headers` fourni à l’appel remplace les `headers` de la solution de repli, qui remplacent les en-têtes extraits des modèles du routeur. Les en-têtes d’exécution (tracing, authentification, location) ont volontairement priorité sur les en-têtes au niveau du modèle.

Chaque champ accepte également une fonction de `requestContext`, conformément à la résolution des modèles dynamiques.

## Utiliser des modèles locaux avec Mastra

Mastra prend aussi en charge les modèles locaux comme `gpt-oss`, `Qwen3`, `DeepSeek` et bien d’autres, que vous exécutez sur votre propre matériel. L’application qui exécute votre modèle local doit fournir un serveur API compatible OpenAI auquel Mastra peut se connecter. Nous recommandons [LMStudio](https://lmstudio.ai/) (voir [Exécuter le serveur LMStudio](https://lmstudio.ai/docs/developer/core/server)).

Pour les points de terminaison personnalisés compatibles OpenAI, `id` est la forme de routage que Mastra envoie via le routeur de modèles.

Utilisez `provider/model` lorsque le service distant se comporte comme un Provider direct et attend un nom de modèle simple tel que `llama3.2`.

Utilisez `gateway/provider/model` lorsque le service distant se comporte comme une passerelle de modèles et que l’espace de noms du modèle en amont inclut le Provider, tel que `mastra/google/gemini-2.5-flash` ou `openrouter/google/gemini-2.5-flash`.

Pour `url`, il est **important** d’utiliser l’URL de base du point de terminaison compatible OpenAI avec le paramètre `model` de Mastra, et non les points de terminaison de chat individuels.

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

Si le service distant se comporte comme une passerelle de modèles, incluez le préfixe de passerelle dans `id` :

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

### Exemple : LMStudio

Après le démarrage du serveur LMStudio, le serveur local est disponible à l’adresse `http://localhost:1234` et fournit des points de terminaison tels que `/v1/models`, `/v1/chat/completions`, etc. La `url` sera `http://localhost:1234/v1`. Pour `id`, vous pouvez utiliser (`lmstudio/${modelId}`), qui sera affiché dans l’interface LMStudio.

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

## Utiliser AI SDK avec Mastra

Mastra prend en charge les modules Provider d’AI SDK si vous devez les utiliser directement.

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

Vous pouvez utiliser un modèle AI SDK (par exemple `groq('gemma2-9b-it')`) partout où une chaîne `"provider/model"` est acceptée, notamment dans les solutions de repli du routeur de modèles et les [scorers](https://mastra.zisheng.pro/fr/docs/evals/overview).