본문으로 건너뛰기

Azure OpenAI logoAzure OpenAI

Azure OpenAI는 보안, 규정 준수 및 SLA 보장이 포함된 전용 배포를 통해 OpenAI Model에 대한 엔터프라이즈급 액세스를 제공합니다.

Model 이름이 고정된 다른 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 Model 가용성을 확인하세요.

Azure 배포 작동 방식
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에서 생성합니다. 리소스 이름과 API 키는 Azure Portal의 "Keys and Endpoint"에서 확인할 수 있습니다.

구성
구성에 대한 직접 링크

게이트웨이를 인스턴스화하여 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"],
    }),
  },
});

동적 검색
동적 검색에 대한 직접 링크

관리 API 자격 증명을 제공합니다. 게이트웨이는 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",
      },
    }),
  },
});

서비스 주체에는 "Cognitive Services 사용자" 역할이 필요합니다. 보다Azure documentation.

마이크로소프트 엔트라 ID 인증
마이크로소프트 엔트라 ID 인증에 대한 직접 링크

Azure OpenAI 리소스에서 API 키가 비활성화된 경우 Microsoft Entra ID 인증을 사용합니다. @azure/identity의 DefaultAzureCredential과 같은 Azure SDK 호환 자격 증명을 전달하세요. 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"],
    }),
  },
});

ID에는 다음과 같은 Azure OpenAI를 호출할 수 있는 권한이 필요합니다.Cognitive Services OpenAI User role.

특정 관리 ID의 경우 통과ManagedIdentityCredential instead.

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 응답 API
Azure 응답 API에 대한 직접 링크

Azure OpenAI는 AI SDK Azure Provider가 사용하는 v1 API 경로를 통해 Responses API를 지원합니다. Azure 리소스와 배포가 해당 경로를 지원한다면 useResponsesAPI: true로 설정하세요. 그러면 게이트웨이는 기본적으로 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 채팅 완성 경로를 사용하려면 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 응답 WebSocket 전송에 대한 직접 링크

Azure OpenAI는 Responses API에서 WebSocket 모드도 지원합니다. Model-Tool 왕복이 많은 Agent 또는 Tool 루프에 사용하십시오. 단일 요청 및 짧은 대화를 위해 표준 HTTP 전송을 유지합니다.

WebSocket 전송에는 Azure가 v1 Responses 경로에서 이를 제공하므로 useResponsesAPI: true가 필요합니다. 그런 다음 각 스트림 요청에서 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();

후속 턴에서도 소켓을 열린 상태로 유지하려면 closeOnFinish: false로 설정하세요. Azure는 연결 로컬 Memory에 하나의 응답 체인을 유지하므로 가장 최근의 previous_response_id에서 이어 가면 후속 응답 지연 시간을 줄일 수 있습니다. 연결은 한 번에 하나의 응답만 실행하며 병렬 실행을 멀티플렉싱하지 않습니다. 동일한 WebSocket 전송에서 previous_response_id를 사용하는 후속 요청을 중복으로 보내지 마세요. Azure는 연결당 진행 중인 응답을 하나만 유지하므로 Mastra는 서로 겹치는 후속 요청을 거부합니다. 응답 체인을 이어 가기 전에 활성 스트림이 완료될 때까지 기다리세요.

구성 참조
구성 참조에 대한 직접 링크

옵션유형필수설명
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아니요관리 API 자격 증명
management.tenantIdstring예*Azure AD 테넌트 ID
management.clientIdstring예*서비스 주체 클라이언트 ID
management.clientSecretstring예*서비스 주체 클라이언트 암호
management.subscriptionIdstring예*Azure 구독 ID
management.resourceGroupstring예*리소스 그룹 이름
* apiKey 또는 authentication.type: "entraId" 중 하나를 제공하세요. management를 제공하는 경우 관리 필드는 필수입니다.
On this page