> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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/) 中建立部署。資源名稱與 API 金鑰位於 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 資源已停用 API 金鑰，請使用 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'], }), }, }) ``` 此身分需要呼叫 Azure OpenAI 的權限，例如 `Cognitive Services OpenAI User` 角色。 若要使用特定的受控識別，請改為傳入 `ManagedIdentityCredential`。 ```typescript import { ManagedIdentityCredential } from '@azure/identity' const credential = new ManagedIdentityCredential('client-id') ``` ### 手動指定部署名稱 僅提供資源名稱與 API 金鑰。建立 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 資源與部署支援該路由時，請設定 `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` 設為使用 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 OpenAI 的 Responses API 也支援 WebSocket 模式。請將其用於模型與 tool 之間需要多次往返的 Agent 或 tool 迴圈。單次請求與簡短對話則維持使用標準 HTTP 傳輸。 WebSocket 傳輸需要 `useResponsesAPI: true`，因為 Azure 透過 `v1` Responses 路徑提供此功能。接著，在每個串流請求中使用 `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 會在連線本機記憶體中保留一條回應鏈，因此從最近的 `previous_response_id` 繼續，可降低延續作業的延遲。每條連線一次執行一個回應，且不會多工處理平行執行作業。 請勿在相同 WebSocket 傳輸上，使用 `previous_response_id` 傳送重疊的後續請求。Mastra 會拒絕重疊的延續請求，因為 Azure 在每條連線上只保留一個處理中的回應。請等待進行中的串流完成，再繼續回應鏈。 ## 組態參考 | 選項 | 類型 | 必填 | 說明 | | --------------------------- | ----------------- | --- | ---------------------------------------------------------------------------------------------------------- | | `resourceName` | `string` | 是 | Azure OpenAI 資源名稱 | | `apiKey` | `string` | 是\* | 來自「Keys and Endpoint」的 API 金鑰 | | `authentication` | `object` | 否 | Microsoft Entra ID 驗證 | | `authentication.type` | `"entraId"` | 是\* | 驗證模式 | | `authentication.credential` | `TokenCredential` | 是\* | `entraId` 驗證模式使用的 Azure SDK 相容認證 | | `authentication.scope` | `string` | 否 | 權杖範圍（預設：`https://cognitiveservices.azure.com/.default`） | | `apiVersion` | `string` | 否 | API 版本（預設：`2024-04-01-preview`；當 `useResponsesAPI` 為 `true` 或 `useDeploymentBasedUrls` 為 `false` 時則為 `v1`） | | `useResponsesAPI` | `boolean` | 否 | 透過 Azure OpenAI Responses API 解析部署（預設：`false`） | | `useDeploymentBasedUrls` | `boolean` | 否 | 使用 Azure 以部署為基礎的 URL（預設：`true`；當 `useResponsesAPI` 為 `true` 時則為 `false`） | | `deployments` | `string[]` | 否 | 靜態模式的部署名稱 | | `management` | `object` | 否 | Management API 認證資訊 | | `management.tenantId` | `string` | 是\* | Azure AD 租戶 ID | | `management.clientId` | `string` | 是\* | Service Principal 使用者端 ID | | `management.clientSecret` | `string` | 是\* | Service Principal 祕密 | | `management.subscriptionId` | `string` | 是\* | Azure 訂閱 ID | | `management.resourceGroup` | `string` | 是\* | 資源群組名稱 | \* 請提供 `apiKey` 或 `authentication.type: "entraId"` 其中之一。若提供 `management`，則必須提供 Management 欄位。