퀵스타트: AI 게이트웨이 계층(미리보기) 인스턴스 생성

적용 대상: AI 게이트웨이 티어 (미리보기)

Important

AI 게이트웨이 티어는 현재 공개 미리보기 단계입니다. 공개 프리뷰 기간 동안 AI 게이트웨이 계층은 다음 지역에서 이용 가능합니다:

• 미국 - 미국 동부 2
• 유럽 - 스웨덴 중앙

이 퀵스타트에서는 AI 게이트웨이 계층(미리보기) 인스턴스를 생성하고, 채팅 모델을 추가하며, 게이트웨이를 호출하고, 런타임 액세스 키를 만들고, 텔레메트리를 확인할 수 있습니다.

Azure API Management의 AI Gateway 계층은 AI 워크로드를 위한 전용 계층입니다. Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI, Anthropic 또는 기타 제공업체 등에서 제공하는 모델과 기존 MCP 서버, OpenAPI 정의, 커넥터에서 생성된 도구들로의 트래픽 관리를 지원합니다. AI 게이트웨이 계층은 보통 1분 이내에 빠르게 프로비저닝을 합니다.

완료 시간: 약 20-30분 정도. 생성: 하나의 게이트웨이, 하나의 채팅 모델, 하나의 런타임 액세스 키, 그리고 하나의 성공적인 채팅 완료 요청.

메모

AI 게이트웨이 티어는 공개 미리보기 단계입니다. 미리보기 기능은 서비스 수준 협약 없이 제공되며, 조직이 미리보기 조건을 수용하지 않는 한 운영 워크로드에 사용해서는 안 됩니다.

필수 조건

• Microsoft Entra ID가 있는 Azure 계정. 현재 AI Gateway 티어 프리뷰에 대한 접근은 Microsoft Entra ID로 로그인한 Azure 사용자에게만 제한되어 있습니다.
• Azure 구독과 리소스 그룹에서 리소스를 생성할 수 있는 권한(예: 기여자 역할)이 필요합니다.
• Microsoft Foundry나 Azure OpenAI에 배포된 모델과 같은 최소 하나의 지원되는 모델 제공자에 접근할 수 있습니다.
• 제공업체가 API 키를 요구한다면, 키를 준비해 두세요.
• 게이트웨이를 호출하려면 curl(설치 필요 없음)이나 OpenAI SDK - Python 3.9 이상, 또는 Node.js 18 이후 패키지를 사용 openai 하세요.

1. AI 게이트웨이 티어 포털에 로그인하기

AI 게이트웨이 티어 포털은 독립형 웹 경험이며, Azure 포털을 사용하지 않습니다.

1. AI 게이트웨이 티어 포털 ai.gateway.azure.com에 접속하세요.
2. 로그인을 선택하고 Microsoft Entra ID로 인증하세요.

포털을 이용해 모델, MCP 서버, 런타임 접근 키, 정책 및 모니터링을 Entra ID 권한에 따라 관리할 수 있습니다. 런타임 호출자는 포털에 로그인하는 것이 아니라, 나중에 생성한 런타임 액세스 키로 게이트웨이를 호출합니다.

2. 게이트웨이 생성

1. 포털에서 게이트웨이 생성을 선택하세요. 기존 게이트웨이를 사용하려면 선택하고 다음 단계로 건너뛰세요.

2. 이름을 입력합니다. 이름은 런타임 엔드포인트의 일부가 됩니다:

   https://<gateway>.azure-api.net

3. 구독과 지원되는 미리보기 지역(East US 2 또는 Sweden Central)을 선택하세요.

4. 선택적으로 리소스 그룹 을 고급 모드로 설정하세요. 기본적으로 포털이 당신을 위해 하나를 만들어줍니다.

5. Create를 선택합니다. 활성화는 보통 1분 이내에 걸립니다.

게이트웨이는 Azure 구독 내의 전용 리소스입니다. 모델을 추가하기 전에 용량을 선택하거나 축척 단위를 추가하는 게 아닙니다. 자동화의 경우, 미리보기 관리 API 버전은 다음과 같습니다2026-05-01-preview; 런타임 요청은 Azure Resource Manager가 아닌 게이트웨이 호스트 이름을 사용합니다.

3. 모델 추가

모델을 만드는 가장 빠른 방법은 Microsoft Foundry 계정에서 가져오는 것입니다.

1. 홈>게이트웨이 구성 아래에서 시작 옵션을 선택하거나 경로 바로 설정 /settings/start 페이지를 열어보세요.

   

2. 하나 이상의 구독을 선택해 스캔하세요. 선택적으로 자원 그룹 필터를 적용해 결과를 좁히세요.

3. 발견한 계좌를 검토하세요. 배포는 상위 Foundry 계정(Azure 리소스)에 따라 그룹화됩니다. 선택은 계정별로 이루어집니다: 계정을 선택하면 마법사가 모든 모델 배포를 불러옵니다.

   

4. 이 가져오기를 위한 백엔드 인증 방법을 선택하세요:

   • 키 기반 (기본값). 게이트웨이는 계정의 API 키를 저장하고 헤더에 전송 api-key 합니다. 마법사는 가져오기 시점에 키를 가져옵니다.
   • 관리형 ID(Microsoft Entra ID). 게이트웨이는 관리되는 신원으로 인증합니다. 게이트웨이에 관리 신원이 없으면 마법사가 시스템 할당 신원을 활성화합니다. 이미 존재하는 정체성이 있다면 어떤 정체를 사용할지 선택합니다. 이 마법사는 선택한 각 계정에 대해 Foundry User 역할로 식별자를 부여합니다.

5. 가져오기를 선택합니다.

6. 가져오기를 선택하면 마법사는 항목을 생성하기 전에 선택한 각 계정에 대해 요구 사항 확인 검사를 실행합니다. 이 점검은 인증이 올바르게 설정되었는지, 그리고 모델 이름이 게이트웨이에 이미 등록된 모델과 충돌하지 않는지 확인합니다. 통과한 계정은 가져옵니다; 실패한 계정은 인라인 경고와 함께 건너뛰고, 나머지 실행은 계속됩니다.

비Foundry 제공업체(AWS Bedrock, Google Vertex, OpenAI, Anthropic)를 연결하려면 'custom model 추가'를 선택하세요. 모델 및 도구 관리(Manage Model and tools)를 참조하세요.

호출자는 OpenAI 호환 요청 필드에서 model 모델 이름을 전달합니다. 이 퀵스타트에서는 gpt-5.6-sol를 사용합니다. 등록한 모델로 교체하세요.

Tip

모델을 바로 사용해보려면, Discover 페이지를 열고 내장 플레이그라운드에서 모델을 선택해 호출하세요. 플레이그라운드는 게이트웨이의 내장 키를 사용하므로, 런타임 액세스 키를 만들기 전에 추가된 모델이나 도구를 탐색하고 테스트할 수 있습니다.

4. 게이트웨이에 호출하기

게이트웨이는 백엔드 모델이 지원하는 API를 노출합니다. Microsoft Foundry, Azure OpenAI, AWS Bedrock, Google Vertex, OpenAI 등 OpenAI 호환 제공업체의 모델이 OpenAI 호환 엔드포인트에서 제공됩니다. OpenAI 클라이언트가 게이트웨이 기본 URL을 가리키도록 설정하고, api-key 헤더를 보내고, model 필드에 모델 이름을 전달하세요. Anthropic 모델은 대신 Anthropic Messages API를 사용합니다; 모델 및 도구 관리(Manage of model and tools)를 참조하세요.

간단한 테스트용으로는 게이트웨이에 내장된 키를 사용하세요 — Discover 놀이터가 사용하는 것과 같은 키입니다. Keys 페이지에서 복사하면, 내장 키와 게이트웨이 내 모든 자산에 런타임 접근 권한을 부여하는 API 키가 나와 함께 나와 있습니다. 자신의 애플리케이션에서는 런타임 액세스 키를 생성하세요(다음 섹션 참조).

이 값들을 한 번 설정하세요:

export AI_GATEWAY_BASE_URL="https://<gateway>.azure-api.net/default/models/openai/v1"
export AI_GATEWAY_API_KEY="<gateway-key>"

Tip

직접 직접 만들지 말고 게이트웨이 개요 페이지에서 정확한 기본 URL을 복사하세요.

원하는 고객과 첫 통화를 하세요:

curl

curl "$AI_GATEWAY_BASE_URL/chat/completions" \
  -H "Content-Type: application/json" \
  -H "api-key: $AI_GATEWAY_API_KEY" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Give me three benefits of using an AI gateway." }
    ]
  }'

토큰을 서버 전송 이벤트로 스트리밍하려면 요청 본문에 "stream": true를 추가하세요.

Python

pip install openai로 클라이언트를 설치하세요.

import os
from openai import OpenAI

# The gateway reads the api-key header, not the api_key argument.
client = OpenAI(
    base_url=os.environ["AI_GATEWAY_BASE_URL"],
    api_key="unused",
    default_headers={"api-key": os.environ["AI_GATEWAY_API_KEY"]},
)

response = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Give me three benefits of using an AI gateway."},
    ],
)
print(response.choices[0].message.content)

토큰이 생성되는 대로 스트리밍하려면 stream=True를 추가하고 응답을 반복 처리하세요:

stream = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "Stream a short greeting."}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="", flush=True)

Node.JS

.로 npm install openai패키지를 설치하세요.

import OpenAI from "openai";

// The gateway reads the api-key header, not the apiKey argument.
const client = new OpenAI({
  baseURL: process.env.AI_GATEWAY_BASE_URL,
  apiKey: "unused",
  defaultHeaders: { "api-key": process.env.AI_GATEWAY_API_KEY },
});

const response = await client.chat.completions.create({
  model: "gpt-5.6-sol",
  messages: [
    { role: "system", content: "You are a helpful assistant." },
    { role: "user", content: "Give me three benefits of using an AI gateway." },
  ],
});
console.log(response.choices[0].message.content);

스트리밍하려면 stream: true를 추가하고 비동기 응답을 순회하세요.

/chat/completions 엔드포인트의 모든 응답은 어떤 OpenAI 호환 제공업체가 해당 모델을 지원하든 관계없이 OpenAI Chat Completions 형식을 사용합니다.

비스트리밍 통화는 채팅 완료 결과를 반환합니다:

{
  "id": "chatcmpl-...",
  "object": "chat.completion",
  "model": "gpt-5.6-sol",
  "choices": [
    {
      "index": 0,
      "message": { "role": "assistant", "content": "1. Centralized governance ...\n2. ...\n3. ..." },
      "finish_reason": "stop"
    }
  ],
  "usage": { "prompt_tokens": 24, "completion_tokens": 61, "total_tokens": 85 }
}

스트리밍이 활성화된 상태에서 게이트웨이는 다음과 같은 이벤트를 반환 chat.completion.chunk 합니다:

{
  "id": "chatcmpl-...",
  "object": "chat.completion.chunk",
  "model": "gpt-5.6-sol",
  "choices": [
    { "index": 0, "delta": { "content": "Hello" }, "finish_reason": null }
  ]
}

같은 기본 URL은 /responses의 OpenAI Responses API에도 사용됩니다.

요청이 실패하면 게이트웨이는 표준 HTTP 상태 코드를 반환합니다:

상태	Meaning	확인할 사항
400	잘못된 요청	요청 본문을 확인해 보세요.
400	콘텐츠 안전이나 IP 필터에 의해 차단되거나, 백엔드에서 거부당하는 경우도 있습니다	콘텐츠 안전 정책은 프롬프트나 응답을 차단할 수 있습니다; 또한 IP 필터 정책도 확인하세요. 관리 신원의 경우, 백엔드 자원의 게이트웨이 신원에 Foundry 사용자 역할을 할당합니다. 백엔드 인증을 위한 관리 신원 사용(Use managed identity)을 참조하세요.
401	누락 또는 유효하지 않은 런타임 액세스 키	키를 헤더에 보내 api-key 고 키가 활성화되어 있는지 확인하세요.
404	미상의 모델	model 페이지에서 값이 모델 이름과 일치하는지 확인하세요.
429	속도 제한 정책이나 백엔드에 의해 제한됨	토큰과 요청 요금 제한 정책을 검토하고, 응답 헤더를 Retry-After 존중하세요.
5xx	백엔드 오류	백엔드 제공자가 정상이고 제공자 자격 증명이 유효한지 확인하세요.

OpenAI SDK는 이러한 상태 코드에 대해 타입 예외를 발생시키므로, 기존 오류 처리 방식이 작동합니다:

from openai import AuthenticationError, RateLimitError, APIStatusError

try:
    response = client.chat.completions.create(
        model="gpt-5.6-sol",
        messages=[{"role": "user", "content": "Hello"}],
    )
except AuthenticationError:
    ...  # 401 — check the api-key header and that the key is active
except RateLimitError:
    ...  # 429 — back off and honor the Retry-After header
except APIStatusError as e:
    ...  # inspect e.status_code for 400, 403, 404, or 5xx

5. 런타임 액세스 키 생성

애플리케이션은 내장 키가 아닌 런타임 액세스 키로 게이트웨이에 인증을 합니다. 각 애플리케이션과 환경에 대해 별도의 키를 만드세요.

1. 키를 선택합니다.
2. API 키 만들기를 선택합니다.
3. 와 같은 quickstart-client이름을 입력합니다.
4. Create를 선택합니다.
5. 키 값을 복사해서 안전하게 저장하세요. 또한 나중에 키 페이지에서 다시 볼 수 있습니다.

게이트웨이 수준에서 런타임 액세스 키를 생성합니다. 이 키들은 게이트웨이 내 모든 모델과 도구에 접근할 수 있게 해줍니다. 비밀처럼 대하세요. 애플리케이션을 위한 비밀 저장소에 키를 저장하고, 정기적으로 회전시키며, 더 이상 필요하지 않은 키는 취소하세요. 런타임 액세스 키로 게이트웨이를 호출하려면, 앞서 보여준 호출에서 그 값으로 설정 AI_GATEWAY_API_KEY 하세요.

6. 텔레메트리 참조

AI 게이트웨이 계층은 OpenTelemetry 토큰 사용 지표를 발표합니다. 이를 확인하려면 먼저 텔레메트리 목적지를 설정한 후 요청을 전송하세요:

1. 게이트웨이에 대한 텔레메트리 목적지(예: Application Insights)를 설정하세요. 관리, 보안 및 운영을 참조하세요.
2. 게이트웨이를 통해 하나 이상의 요청을 보내세요. 앞서 ' 게이트웨이 호출'에서 보았듯이요.
3. 텔레메트리 목적지를 열어 토큰 사용 상태를 확인하세요. Application Insights를 사용하면 포털이 내장된 토큰 소비 대시보드를 제공합니다.

텔레메트리는 목적지를 연결한 후에만 전송되기 때문에, 모니터링에 의존하기 전에 미리 설정하세요. 현재 토큰 사용만이 유일한 지표입니다; 로그, 트레이스 및 기타 모델과 도구의 지표가 곧 제공될 예정입니다. 발신자는 게이트웨이 수준의 런타임 액세스 키를 사용하여, 클라이언트 애플리케이션에 제공자 자격 증명을 노출하지 않고 트래픽을 모니터링할 수 있습니다. 텔레메트리 대상 구성을 설정하려면 관리, 보안 및 운영을 참조하세요.

자원을 정리하세요

다 끝나면 필요 없는 자원은 삭제하세요. 평가용으로만 만든 AI 게이트웨이 계층 인스턴스, 제공자 테스트 배포, 런타임 액세스 키를 제거하세요.

다음 단계

• 에이전트가 호출할 수 있는 MCP 도구 추가로
• 거버넌스 정책을 모델과 도구에 적용하세요
• 프라이빗 네트워킹 구성
• 모델 및 도구 관리
• AI 게이트웨이 계층 개요