跳至主要內容

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

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

提供 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 資源已停用 API 金鑰，請使用 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'],
    }),
  },
})

此身分需要呼叫 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 格式搭配 chat 模型建構函式；gateway 會將該路由的 apiVersion 預設為 "v1"。若僅傳入 apiVersion: "v1"，為了相容性，仍會保留現有以部署為基礎的 URL 預設值。

請勿同時使用 useResponsesAPI: true 與 useDeploymentBasedUrls: true；gateway 會拒絕該組態，因為 Responses API 支援使用 Azure v1 路由。

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

相同的 API 金鑰與 Microsoft Entra ID 驗證模式也適用於 v1 路由。

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

Azure OpenAI 的 Responses API 也支援 WebSocket 模式。請將其用於模型與 tool 之間需要多次往返的 Agent 或 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 傳送重疊的後續請求。Mastra 會拒絕重疊的延續請求，因為 Azure 在每條連線上只保留一個處理中的回應。請等待進行中的串流完成，再繼續回應鏈。

組態參考
「組態參考」的直接連結

選項類型必填說明
resourceNamestring是Azure OpenAI 資源名稱
apiKeystring是*來自「Keys and Endpoint」的 API 金鑰
authenticationobject否Microsoft Entra ID 驗證
authentication.type"entraId"是*驗證模式
authentication.credentialTokenCredential是*entraId 驗證模式使用的 Azure SDK 相容認證
authentication.scopestring否權杖範圍（預設：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