跳到主要内容

Azure OpenAI 标志Azure OpenAI

Azure OpenAI 通过专用部署提供企业级 OpenAI 模型访问，并具备安全、合规和 SLA 保障。

与使用固定模型名称的其他 Provider 不同，Azure 使用你在 Azure Portal 中配置的部署名称。

用法
用法的直接链接

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 模型可用性。

Azure 部署的工作方式
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 中创建部署。resource name 和 API key 位于 Azure Portal 的“Keys and Endpoint”下。

配置
配置的直接链接

实例化 Gateway 并将其传给 Mastra。常见配置模式如下。

静态部署
静态部署的直接链接

提供 Azure Portal 中的部署名称。

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 以列出部署。

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 文档。

Microsoft Entra ID 认证
Microsoft Entra ID 认证的直接链接

当 Azure OpenAI resource 禁用 API key 时，请使用 Microsoft Entra ID 认证。可以传入任意与 Azure SDK 兼容的凭据，例如 @azure/identity 提供的 DefaultAzureCredential。

如果使用 DefaultAzureCredential，请在 Mastra 项目中安装 @azure/identity。

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。

import { ManagedIdentityCredential } from '@azure/identity'

const credential = new ManagedIdentityCredential('client-id')

手动指定部署名称
手动指定部署名称的直接链接

只提供 resource name 和 API key，并在创建 Agent 时指定部署名称。此方式不提供 IDE 自动补全。

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 Responses API的直接链接

Azure OpenAI 通过 AI SDK Azure Provider 使用的 v1 API 路径支持 Responses API。当 Azure resource 和部署支持该路由时，设置 useResponsesAPI: true。随后 Gateway 会默认使用 apiVersion: "v1" 和 useDeploymentBasedUrls: false。

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 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" 启用。

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 结束后再继续响应链。

配置参考
配置参考的直接链接

选项类型必需说明
resourceNamestring是Azure OpenAI 资源名称
apiKeystring是*来自“密钥和终结点”的 API key
authenticationobject否Microsoft Entra ID 身份验证配置
authentication.type"entraId"是*身份验证模式
authentication.credentialTokenCredential是*与 Azure SDK 兼容、用于 entraId 身份验证模式的凭证
authentication.scopestring否Token scope（默认值：https://cognitiveservices.azure.com/.default）
apiVersionstring否API 版本（默认值：2024-04-01-preview；当 useResponsesAPI 为 true 或 useDeploymentBasedUrls 为 false 时为 v1）
useResponsesAPIboolean否通过 Azure OpenAI Responses API 解析 deployment（默认值：false）
useDeploymentBasedUrlsboolean否使用基于 Azure deployment 的 URL（默认值：true；当 useResponsesAPI 为 true 时为 false）
deploymentsstring[]否静态模式下的 deployment 名称
managementobject否Management API 凭证
management.tenantIdstring是*Azure AD tenant ID
management.clientIdstring是*Service Principal client ID
management.clientSecretstring是*Service Principal secret
management.subscriptionIdstring是*Azure subscription ID
management.resourceGroupstring是*resource group 名称

* 请提供 apiKey 或 authentication.type: "entraId"。如果提供 management，则必须填写 Management 相关字段。

On this page