跳至主要內容

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 建立部署。資源名稱及 API 金鑰位於 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'],
    }),
  },
})

動態探索
動態探索 的直接連結

Provide Management API 憑證. The gateway queries Azure Management API to list deployments.

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 驗證 的直接連結

Use Microsoft Entra ID 驗證 when API keys are disabled for your Azure OpenAI resource. Pass any Azure SDK-compatible credential, such as DefaultAzureCredential from @azure/identity.

如使用 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'],
    }),
  },
})

該身分需要呼叫 Azure OpenAI 的權限，例如 Cognitive Services OpenAI User 角色。

如要指定受控識別，請改為傳入 ManagedIdentityCredential。

import { ManagedIdentityCredential } from '@azure/identity'

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

手動指定部署名稱
手動指定部署名稱 的直接連結

只提供資源名稱及 API 金鑰，並在建立 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 資源及部署支援該路由時，請設定 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，即可讓聊天模型建構函式使用 Azure v1 URL 格式；Gateway 會為該路由將 apiVersion 預設為 "v1"。如只傳入 apiVersion: "v1"，則會保留現有以部署為基礎的 URL 預設值，以維持相容性。

請勿同時設定 useResponsesAPI: true 及 useDeploymentBasedUrls: true；由於 Responses API 支援使用 Azure v1 路由，Gateway 會拒絕這項設定。

GA v1 路由請使用 apiVersion: "v1"。Microsoft 目前透過功能專屬標頭（例如 "aoai-evals": "preview"）或 preview/alpha API 路徑提供預覽版 v1 功能。對於需要 preview 查詢值的 Azure Provider 設定，Gateway 仍接受同時使用 apiVersion: "preview" 及 useDeploymentBasedUrls: false。以日期為基礎的 API 版本只適用於舊有、以部署為基礎的路由，因此當 useResponsesAPI 為 true 或 useDeploymentBasedUrls 為 false 時，Gateway 會拒絕這些版本。

The same API key and Microsoft Entra ID 驗證 modes work with the v1 route.

Azure Responses WebSocket 傳輸
Azure Responses WebSocket 傳輸 的直接連結

Azure OpenAI 的 Responses API 亦支援 WebSocket 模式。當 Agent 或 Tool 迴圈需要在模型與 Tool 之間進行多次來回時，可使用此模式；單次請求及短對話則應沿用標準 HTTP 傳輸。

WebSocket 傳輸要求設定 useResponsesAPI: true，因為 Azure 透過 v1 Responses 路徑提供此功能。然後在每個串流請求中以 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 會在連線本機記憶體保留一條回應鏈，因此從最新的 previous_response_id 繼續可降低延續延遲。每條連線一次只運行一個回應，不會多工處理平行運行。

請勿在同一 WebSocket 傳輸上使用 previous_response_id 傳送重疊的後續請求。由於 Azure 每條連線只保留一個處理中的回應，Mastra 會拒絕重疊的延續請求。請等待目前串流完成，才繼續回應鏈。

設定 Reference
設定 Reference 的直接連結

選項類型必填說明
resourceNamestring是Azure OpenAI 資源名稱
apiKeystring是*來自「Keys and Endpoint」的 API 金鑰
authenticationobject否Microsoft Entra ID 驗證
authentication.type"entraId"是*驗證模式
authentication.credentialTokenCredential是*適用於 entraId 驗證模式、與 Azure SDK 相容的憑證
authentication.scopestring否token 範圍（預設：https://cognitiveservices.azure.com/.default）
apiVersionstring否API 版本（預設：2024-04-01-preview；當 useResponsesAPI 為 true 或 useDeploymentBasedUrls 為 false 時則為 v1）
useResponsesAPIboolean否透過 Azure OpenAI Responses API 解析部署（預設：false）
useDeploymentBasedUrlsboolean否使用以 Azure 部署為基礎的 URL（預設：true；當 useResponsesAPI 為 true 時則為 false）
deploymentsstring[]否靜態模式的部署名稱
managementobject否Management API 憑證
management.tenantIdstring是*Azure AD 租戶 ID
management.clientIdstring是*Service Principal 用戶端 ID
management.clientSecretstring是*Service Principal 密碼
management.subscriptionIdstring是*Azure 訂閱 ID
management.resourceGroupstring是*資源群組名稱

* 請提供 apiKey 或 authentication.type: "entraId" 其中一項。如有提供 management，則所有 Management 欄位均為必填。

On this page