> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # ![Azure OpenAI logo](https://models.dev/logos/azure.svg)Azure OpenAI Azure OpenAI는 보안, 규정 준수 및 SLA 보장이 포함된 전용 배포를 통해 OpenAI Model에 대한 엔터프라이즈급 액세스를 제공합니다. Model 이름이 고정된 다른 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 Model 가용성](https://learn.microsoft.com/en-us/azure/ai-services/openai/concepts/models)을 확인하세요. ## Azure 배포 작동 방식 Azure Model 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"에서 확인할 수 있습니다. ## 구성 게이트웨이를 인스턴스화하여 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"], }), }, }); ``` ### 동적 검색 관리 API 자격 증명을 제공합니다. 게이트웨이는 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", }, }), }, }); ``` 서비스 주체에는 "Cognitive Services 사용자" 역할이 필요합니다. 보다[Azure documentation](https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-service-principal-portal). ### 마이크로소프트 엔트라 ID 인증 Azure OpenAI 리소스에서 API 키가 비활성화된 경우 Microsoft Entra ID 인증을 사용합니다. `@azure/identity`의 `DefaultAzureCredential`과 같은 Azure SDK 호환 자격 증명을 전달하세요. `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"], }), }, }); ``` ID에는 다음과 같은 Azure OpenAI를 호출할 수 있는 권한이 필요합니다.`Cognitive Services OpenAI User` role. 특정 관리 ID의 경우 통과`ManagedIdentityCredential` instead. ```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 응답 API Azure OpenAI는 AI SDK Azure Provider가 사용하는 `v1` API 경로를 통해 Responses API를 지원합니다. Azure 리소스와 배포가 해당 경로를 지원한다면 `useResponsesAPI: true`로 설정하세요. 그러면 게이트웨이는 기본적으로 `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 채팅 완성 경로를 사용하려면 `useResponsesAPI`를 생략하거나 `false`로 설정하세요. 이 경로는 호환성을 위해 기본적으로 `apiVersion: "2024-04-01-preview"`와 배포 기반 URL을 유지합니다. `apiVersion`과 `useDeploymentBasedUrls`를 직접 구성할 수도 있습니다. 예를 들어 채팅 Model 생성자에서 Azure `v1` URL 형식을 사용하려면 `useDeploymentBasedUrls: false`로 설정하세요. 이 경로에서는 게이트웨이가 `apiVersion`의 기본값을 `"v1"`로 설정합니다. `apiVersion: "v1"`만 전달하면 호환성을 위해 기존의 배포 기반 URL 기본값이 유지됩니다. `useResponsesAPI: true`와 `useDeploymentBasedUrls: true`를 함께 사용하지 마세요. Responses API 지원은 Azure `v1` 경로를 사용하므로 게이트웨이가 이 구성을 거부합니다. GA `v1` 경로에는 `apiVersion: "v1"`을 사용하세요. 현재 Microsoft는 `"aoai-evals": "preview"`와 같은 기능별 헤더나 미리 보기/알파 API 경로를 통해 미리 보기 `v1` 기능을 제공합니다. 미리 보기 쿼리 값이 필요한 Azure Provider 구성에서는 게이트웨이가 `useDeploymentBasedUrls: false`와 함께 `apiVersion: "preview"`를 사용하는 구성도 허용합니다. 날짜 기반 API 버전은 레거시 배포 기반 경로에서만 사용할 수 있으므로 `useResponsesAPI`가 `true`이거나 `useDeploymentBasedUrls`가 `false`이면 게이트웨이가 이를 거부합니다. 동일한 API 키와 Microsoft Entra ID 인증 모드가`v1` route. ### Azure 응답 WebSocket 전송 Azure OpenAI는 Responses API에서 WebSocket 모드도 지원합니다. Model-Tool 왕복이 많은 Agent 또는 Tool 루프에 사용하십시오. 단일 요청 및 짧은 대화를 위해 표준 HTTP 전송을 유지합니다. WebSocket 전송에는 Azure가 `v1` Responses 경로에서 이를 제공하므로 `useResponsesAPI: true`가 필요합니다. 그런 다음 각 스트림 요청에서 `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(); ``` 후속 턴에서도 소켓을 열린 상태로 유지하려면 `closeOnFinish: false`로 설정하세요. Azure는 연결 로컬 Memory에 하나의 응답 체인을 유지하므로 가장 최근의 `previous_response_id`에서 이어 가면 후속 응답 지연 시간을 줄일 수 있습니다. 연결은 한 번에 하나의 응답만 실행하며 병렬 실행을 멀티플렉싱하지 않습니다. 동일한 WebSocket 전송에서 `previous_response_id`를 사용하는 후속 요청을 중복으로 보내지 마세요. Azure는 연결당 진행 중인 응답을 하나만 유지하므로 Mastra는 서로 겹치는 후속 요청을 거부합니다. 응답 체인을 이어 가기 전에 활성 스트림이 완료될 때까지 기다리세요. ## 구성 참조 | 옵션 | 유형 | 필수 | 설명 | | ------------------------------------------------------------------------------------------------ | ----------------- | --- | ----------------------------------------------------------------------------------------------------------- | | `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` | 아니요 | 관리 API 자격 증명 | | `management.tenantId` | `string` | 예\* | Azure AD 테넌트 ID | | `management.clientId` | `string` | 예\* | 서비스 주체 클라이언트 ID | | `management.clientSecret` | `string` | 예\* | 서비스 주체 클라이언트 암호 | | `management.subscriptionId` | `string` | 예\* | Azure 구독 ID | | `management.resourceGroup` | `string` | 예\* | 리소스 그룹 이름 | | \* `apiKey` 또는 `authentication.type: "entraId"` 중 하나를 제공하세요. `management`를 제공하는 경우 관리 필드는 필수입니다. | | | |