> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt # ![Azure OpenAI logo](https://models.dev/logos/azure.svg)Azure OpenAI Azure OpenAI fournit un accès aux modèles OpenAI de niveau entreprise via des déploiements dédiés, avec des garanties de sécurité, de conformité et de SLA. Contrairement aux autres Providers qui utilisent des noms de modèle fixes, Azure emploie des **noms de déploiement** que vous configurez dans le portail Azure. ## Utilisation ```typescript import { Agent } from "@mastra/core/agent"; const agent = new Agent({ id: "my-agent", name: "My Agent", instructions: "You are a helpful assistant", model: "azure-openai/my-gpt-5-4-deployment" // Use your Azure deployment name (autocompleted in dev mode) }); // Generate a response const response = await agent.generate("Hello!"); // Stream a response const stream = await agent.stream("Tell me a story"); for await (const chunk of stream) { console.log(chunk); } ``` Consultez la [disponibilité des modèles Azure OpenAI](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models) pour connaître les options propres à chaque région. ## Fonctionnement des déploiements Azure Les ID de modèle Azure suivent ce format : `azure-openai/your-deployment-name` Le nom de déploiement est **propre à votre compte Azure** et choisi lors de la création d’un déploiement dans le portail Azure. Exemples courants : - `azure-openai/my-gpt-5-4-deployment` - `azure-openai/production-gpt-5-4` - `azure-openai/staging-gpt-5-4-mini` ## Configuration Créez des déploiements dans [Azure OpenAI Studio](https://oai.azure.com/). Le nom de la ressource et la clé API se trouvent dans le portail Azure, sous « Keys and Endpoint ». ## Configuration Instanciez la passerelle et transmettez-la à Mastra. Les modes de configuration courants sont présentés ci-dessous. ### Déploiements statiques Indiquez les noms de déploiement du portail Azure. ```typescript import { Mastra } from "@mastra/core"; import { AzureOpenAIGateway } from "@mastra/core/llm"; export const mastra = new Mastra({ gateways: { "azure-openai": new AzureOpenAIGateway({ resourceName: "my-openai-resource", apiKey: process.env.AZURE_API_KEY!, deployments: ["gpt-5-4-prod", "gpt-5-4-mini-dev"], }), }, }); ``` ### Découverte dynamique Fournissez les identifiants de l’API Management. La passerelle interroge l’API Azure Management pour lister les déploiements. ```typescript import { Mastra } from "@mastra/core"; import { AzureOpenAIGateway } from "@mastra/core/llm"; export const mastra = new Mastra({ gateways: { "azure-openai": new AzureOpenAIGateway({ resourceName: "my-openai-resource", apiKey: process.env.AZURE_API_KEY!, management: { tenantId: process.env.AZURE_TENANT_ID!, clientId: process.env.AZURE_CLIENT_ID!, clientSecret: process.env.AZURE_CLIENT_SECRET!, subscriptionId: process.env.AZURE_SUBSCRIPTION_ID!, resourceGroup: "my-resource-group", }, }), }, }); ``` Le principal de service nécessite le rôle « Cognitive Services User ». Consultez la [documentation Azure](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal). ### Authentification Microsoft Entra ID Utilisez l’authentification Microsoft Entra ID lorsque les clés API sont désactivées pour votre ressource Azure OpenAI. Transmettez tout identifiant compatible avec le SDK Azure, tel que `DefaultAzureCredential` depuis `@azure/identity`. Installez `@azure/identity` dans votre projet Mastra si vous utilisez `DefaultAzureCredential`. ```typescript import { DefaultAzureCredential } from "@azure/identity"; import { Mastra } from "@mastra/core"; import { AzureOpenAIGateway } from "@mastra/core/llm"; export const mastra = new Mastra({ gateways: { "azure-openai": new AzureOpenAIGateway({ resourceName: "my-openai-resource", authentication: { type: "entraId", credential: new DefaultAzureCredential(), }, deployments: ["gpt-5-4-prod", "gpt-5-4-mini-dev"], }), }, }); ``` L’identité doit disposer de l’autorisation d’appeler Azure OpenAI, par exemple via le rôle `Cognitive Services OpenAI User`. Pour une identité managée spécifique, transmettez plutôt `ManagedIdentityCredential`. ```typescript import { ManagedIdentityCredential } from "@azure/identity"; const credential = new ManagedIdentityCredential("client-id"); ``` ### Noms de déploiement manuels Fournissez uniquement le nom de la ressource et la clé API. Indiquez les noms de déploiement lors de la création des Agents. Aucune autocomplétion IDE n’est disponible. ```typescript import { Mastra } from "@mastra/core"; import { AzureOpenAIGateway } from "@mastra/core/llm"; export const mastra = new Mastra({ gateways: { "azure-openai": new AzureOpenAIGateway({ resourceName: "my-openai-resource", apiKey: process.env.AZURE_API_KEY!, }), }, }); ``` ### API Azure Responses Azure OpenAI prend en charge l’API Responses via le chemin d’API `v1` utilisé par le Provider Azure d’AI SDK. Définissez `useResponsesAPI: true` lorsque votre ressource et votre déploiement Azure prennent en charge cette route. La passerelle utilise alors par défaut `apiVersion: "v1"` et `useDeploymentBasedUrls: false`. ```typescript import { Mastra } from "@mastra/core"; import { AzureOpenAIGateway } from "@mastra/core/llm"; export const mastra = new Mastra({ gateways: { "azure-openai": new AzureOpenAIGateway({ resourceName: "my-openai-resource", apiKey: process.env.AZURE_API_KEY!, useResponsesAPI: true, deployments: ["my-gpt-5-4-deployment"], }), }, }); ``` Omettez `useResponsesAPI` ou définissez-le sur `false` pour la route Azure existante des complétions de chat. Cette route conserve par défaut `apiVersion: "2024-04-01-preview"` et les URL basées sur les déploiements, pour assurer la compatibilité. Vous pouvez toujours configurer directement `apiVersion` et `useDeploymentBasedUrls`. Par exemple, définissez `useDeploymentBasedUrls: false` pour utiliser le format d’URL Azure `v1` avec le constructeur de modèle de chat ; la passerelle utilise par défaut `apiVersion: "v1"` pour cette route. Transmettre uniquement `apiVersion: "v1"` conserve l’URL par défaut basée sur les déploiements pour la compatibilité. Ne combinez pas `useResponsesAPI: true` et `useDeploymentBasedUrls: true` : la passerelle rejette cette configuration car la prise en charge de l’API Responses utilise la route Azure `v1`. Utilisez `apiVersion: "v1"` pour la route GA `v1`. Microsoft expose actuellement les fonctionnalités d’aperçu de `v1` via des en-têtes propres aux fonctionnalités, tels que `"aoai-evals": "preview"`, ou via des chemins d’API preview/alpha. La passerelle accepte toujours `apiVersion: "preview"` avec `useDeploymentBasedUrls: false` pour les configurations du Provider Azure qui requièrent la valeur de requête preview. Les versions d’API fondées sur une date ne s’appliquent qu’à l’ancienne route basée sur les déploiements ; la passerelle les rejette donc lorsque `useResponsesAPI` est à `true` ou `useDeploymentBasedUrls` à `false`. Les mêmes modes d’authentification par clé API et Microsoft Entra ID fonctionnent avec la route `v1`. ### Transport WebSocket Azure Responses Azure OpenAI prend également en charge le mode WebSocket sur l’API Responses. Utilisez-le pour les boucles d’Agent ou de Tool comportant de nombreux allers-retours entre modèle et Tool. Conservez le transport HTTP standard pour les requêtes uniques et les conversations courtes. Le transport WebSocket requiert `useResponsesAPI: true`, car Azure l’expose sur le chemin Responses `v1`. Activez-le ensuite pour chaque requête de stream avec `providerOptions.azure.transport: "websocket"`. ```typescript import { Agent } from "@mastra/core/agent"; const agent = new Agent({ id: "azure-ws-agent", name: "Azure WebSocket Agent", instructions: "Use tools when they are useful.", model: "azure-openai/my-gpt-5-4-deployment", }); const stream = await agent.stream("Find and improve the slow function.", { providerOptions: { azure: { transport: "websocket", store: false, websocket: { closeOnFinish: false, }, }, }, }); for await (const chunk of stream.textStream) { process.stdout.write(chunk); } stream.transport?.close(); ``` Définissez `closeOnFinish: false` si vous souhaitez garder le socket ouvert entre des tours de suivi. Azure conserve une chaîne de réponses dans la mémoire locale de la connexion ; poursuivre à partir du `previous_response_id` le plus récent peut donc réduire la latence. La connexion exécute une réponse à la fois et ne multiplexe pas les exécutions parallèles. N’envoyez pas de requêtes de suivi qui se chevauchent avec `previous_response_id` sur le même transport WebSocket. Mastra rejette les requêtes de continuation concurrentes, car Azure ne conserve qu’une réponse en cours par connexion. Attendez la fin du stream actif avant de poursuivre la chaîne de réponses. ## Référence de configuration | Option | Type | Obligatoire | Description | | --------------------------- | ----------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | `resourceName` | `string` | Oui | Nom de la ressource Azure OpenAI | | `apiKey` | `string` | Oui\* | Clé API provenant de « Keys and Endpoint » | | `authentication` | `object` | Non | Authentification Microsoft Entra ID | | `authentication.type` | `"entraId"` | Oui\* | Mode d’authentification | | `authentication.credential` | `TokenCredential` | Oui\* | Identifiant compatible avec le SDK Azure pour le mode d’authentification `entraId` | | `authentication.scope` | `string` | Non | Portée du jeton (par défaut : `https://cognitiveservices.azure.com/.default`) | | `apiVersion` | `string` | Non | Version de l’API (par défaut : `2024-04-01-preview`, ou `v1` lorsque `useResponsesAPI` vaut `true` ou `useDeploymentBasedUrls` vaut `false`) | | `useResponsesAPI` | `boolean` | Non | Résout les déploiements via l’API Responses d’Azure OpenAI (par défaut : `false`) | | `useDeploymentBasedUrls` | `boolean` | Non | Utilise les URL Azure basées sur les déploiements (par défaut : `true`, ou `false` lorsque `useResponsesAPI` vaut `true`) | | `deployments` | `string[]` | Non | Noms des déploiements pour le mode statique | | `management` | `object` | Non | Identifiants de l’API de gestion | | `management.tenantId` | `string` | Oui\* | ID du locataire Azure AD | | `management.clientId` | `string` | Oui\* | ID client du principal de service | | `management.clientSecret` | `string` | Oui\* | Secret du principal de service | | `management.subscriptionId` | `string` | Oui\* | ID de l’abonnement Azure | | `management.resourceGroup` | `string` | Oui\* | Nom du groupe de ressources | \* Fournissez soit `apiKey`, soit `authentication.type: "entraId"`. Les champs de gestion sont obligatoires lorsque `management` est fourni.