> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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'], }), }, }) ``` ### 動態探索 Provide Management API 憑證. The gateway queries Azure Management API to list deployments. ```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 驗證 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`。 ```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 格式；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 OpenAI 的 Responses API 亦支援 WebSocket 模式。當 Agent 或 Tool 迴圈需要在模型與 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` 傳送重疊的後續請求。由於 Azure 每條連線只保留一個處理中的回應，Mastra 會拒絕重疊的延續請求。請等待目前串流完成，才繼續回應鏈。 ## 設定 Reference | 選項 | 類型 | 必填 | 說明 | | --------------------------- | ----------------- | --- | ---------------------------------------------------------------------------------------------------------- | | `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` | 否 | token 範圍（預設：`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 欄位均為必填。