> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt # ![Azure OpenAI 标志](https://models.dev/logos/azure.svg)Azure OpenAI Azure OpenAI 通过专用部署提供企业级 OpenAI 模型访问，并具备安全、合规和 SLA 保障。 与使用固定模型名称的其他 Provider 不同，Azure 使用你在 Azure Portal 中配置的**部署名称**。 ## 用法 ```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) } ``` 各区域可用选项请查看 [Azure OpenAI 模型可用性](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)。 ## Azure 部署的工作方式 Azure 模型 ID 遵循以下格式：`azure-openai/your-deployment-name` 部署名称**由你的 Azure 账号自行定义**，在 Azure Portal 中创建部署时选择。常见示例如下： - `azure-openai/my-gpt-5-4-deployment` - `azure-openai/production-gpt-5-4` - `azure-openai/staging-gpt-5-4-mini` ## 设置 在 [Azure OpenAI Studio](https://oai.azure.com/) 中创建部署。resource name 和 API key 位于 Azure Portal 的“Keys and Endpoint”下。 ## 配置 实例化 Gateway 并将其传给 Mastra。常见配置模式如下。 ### 静态部署 提供 Azure Portal 中的部署名称。 ```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'], }), }, }) ``` ### 动态发现 提供 Management API 凭据。Gateway 会查询 Azure Management API 以列出部署。 ```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', }, }), }, }) ``` Service Principal 需要“Cognitive Services User”角色。请参阅 [Azure 文档](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal)。 ### Microsoft Entra ID 认证 当 Azure OpenAI resource 禁用 API key 时，请使用 Microsoft Entra ID 认证。可以传入任意与 Azure SDK 兼容的凭据，例如 `@azure/identity` 提供的 `DefaultAzureCredential`。 如果使用 `DefaultAzureCredential`，请在 Mastra 项目中安装 `@azure/identity`。 ```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'], }), }, }) ``` 该 identity 需要拥有调用 Azure OpenAI 的权限，例如 `Cognitive Services OpenAI User` 角色。 如需使用特定的 managed identity，请改为传入 `ManagedIdentityCredential`。 ```typescript import { ManagedIdentityCredential } from '@azure/identity' const credential = new ManagedIdentityCredential('client-id') ``` ### 手动指定部署名称 只提供 resource name 和 API key，并在创建 Agent 时指定部署名称。此方式不提供 IDE 自动补全。 ```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!, }), }, }) ``` ### Azure Responses API Azure OpenAI 通过 AI SDK Azure Provider 使用的 `v1` API 路径支持 Responses API。当 Azure resource 和部署支持该路由时，设置 `useResponsesAPI: true`。随后 Gateway 会默认使用 `apiVersion: "v1"` 和 `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'], }), }, }) ``` 使用现有 Azure chat completions 路由时，请省略 `useResponsesAPI` 或将其设为 `false`。为保持兼容性，该路径默认保留 `apiVersion: "2024-04-01-preview"` 和基于部署的 URL。 你仍可以直接配置 `apiVersion` 和 `useDeploymentBasedUrls`。例如，将 `useDeploymentBasedUrls` 设为 `false`，即可在 chat 模型构造函数中使用 Azure `v1` URL 格式；Gateway 会为该路由默认使用 `apiVersion: "v1"`。如果只传入 `apiVersion: "v1"`，为保持兼容性，仍会沿用基于部署的 URL 默认值。 不要同时设置 `useResponsesAPI: true` 和 `useDeploymentBasedUrls: true`。由于 Responses API 使用 Azure `v1` 路由，Gateway 会拒绝这种配置。 GA `v1` 路由请使用 `apiVersion: "v1"`。Microsoft 目前通过特定功能的 header（例如 `"aoai-evals": "preview"`）或 preview/alpha API 路径提供 `v1` 预览功能。对于要求 preview query 值的 Azure Provider 配置，Gateway 仍接受 `apiVersion: "preview"` 与 `useDeploymentBasedUrls: false` 的组合。基于日期的 API version 仅适用于旧的基于部署的路由，因此当 `useResponsesAPI` 为 `true` 或 `useDeploymentBasedUrls` 为 `false` 时，Gateway 会拒绝此类版本。 相同的 API key 和 Microsoft Entra ID 认证方式也适用于 `v1` 路由。 ### Azure Responses WebSocket transport Azure OpenAI 的 Responses API 也支持 WebSocket 模式。对于包含大量模型与 Tool 往返调用的 Agent loop 或 Tool loop，可以使用此模式；单次请求和短对话则继续使用标准 HTTP transport。 由于 Azure 在 `v1` Responses 路径上提供 WebSocket，因此 WebSocket transport 要求设置 `useResponsesAPI: true`。随后在每次流式请求中通过 `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() ``` 如果希望在后续轮次之间保持 socket 打开，请设置 `closeOnFinish: false`。Azure 会在连接本地 Memory 中保留一条响应链，因此从最新的 `previous_response_id` 继续可以减少延迟。每个连接一次只运行一个响应，不支持多路复用并行执行。 不要在同一个 WebSocket transport 上发送相互重叠且包含 `previous_response_id` 的后续请求。Azure 的每个连接只能保留一个进行中的响应，因此 Mastra 会拒绝重叠的续接请求。请等待当前 stream 结束后再继续响应链。 ## 配置参考 | 选项 | 类型 | 必需 | 说明 | | --------------------------- | ----------------- | --- | ---------------------------------------------------------------------------------------------------------- | | `resourceName` | `string` | 是 | Azure OpenAI 资源名称 | | `apiKey` | `string` | 是\* | 来自“密钥和终结点”的 API key | | `authentication` | `object` | 否 | Microsoft Entra ID 身份验证配置 | | `authentication.type` | `"entraId"` | 是\* | 身份验证模式 | | `authentication.credential` | `TokenCredential` | 是\* | 与 Azure SDK 兼容、用于 `entraId` 身份验证模式的凭证 | | `authentication.scope` | `string` | 否 | Token scope（默认值：`https://cognitiveservices.azure.com/.default`） | | `apiVersion` | `string` | 否 | API 版本（默认值：`2024-04-01-preview`；当 `useResponsesAPI` 为 `true` 或 `useDeploymentBasedUrls` 为 `false` 时为 `v1`） | | `useResponsesAPI` | `boolean` | 否 | 通过 Azure OpenAI Responses API 解析 deployment（默认值：`false`） | | `useDeploymentBasedUrls` | `boolean` | 否 | 使用基于 Azure deployment 的 URL（默认值：`true`；当 `useResponsesAPI` 为 `true` 时为 `false`） | | `deployments` | `string[]` | 否 | 静态模式下的 deployment 名称 | | `management` | `object` | 否 | Management API 凭证 | | `management.tenantId` | `string` | 是\* | Azure AD tenant ID | | `management.clientId` | `string` | 是\* | Service Principal client ID | | `management.clientSecret` | `string` | 是\* | Service Principal secret | | `management.subscriptionId` | `string` | 是\* | Azure subscription ID | | `management.resourceGroup` | `string` | 是\* | resource group 名称 | \* 请提供 `apiKey` 或 `authentication.type: "entraId"`。如果提供 `management`，则必须填写 Management 相关字段。