[ Azure OpenAI #6 ] 기본 실습: 리소스 생성부터 Playground, API, SDK 호출까지

들어가며

이전 글에서는 Azure OpenAI Service의 전체 구조를 정리했다.

Azure OpenAI를 사용하려면 단순히 모델 이름만 알고 있으면 되는 것이 아니라, Azure 안에서 다음 흐름을 이해해야 한다.

Resource Group 생성
→ Azure OpenAI Resource 생성
→ Azure AI Foundry 이동
→ 모델 배포
→ Endpoint / API Key 확인
→ Playground 테스트
→ API 또는 SDK로 호출

이번 글에서는 이 흐름을 실제 실습 순서대로 정리한다.

이번 글의 목표는 아주 명확하다.

Azure OpenAI를 처음 사용하는 사람이
리소스를 만들고, 모델을 배포하고, Playground와 코드에서 한 번 호출해보는 것

1. 실습 목표

이번 실습에서는 Azure OpenAI를 실제로 사용하기 위한 기본 흐름을 따라간다.

[사진 1] Azure OpenAI 기본 실습 전체 흐름도

1. Resource Group 생성
2. Azure OpenAI Resource 생성
3. Azure AI Foundry로 이동
4. Model Catalog에서 모델 선택
5. gpt-4o-mini 모델 배포
6. Deployment Name 설정
7. TPM 설정
8. Endpoint와 API Key 확인
9. Playground에서 테스트
10. API로 호출
11. Python SDK로 호출

이 글에서는 매개변수 실험이나 프롬프트 엔지니어링은 깊게 다루지 않는다.

이번 글의 핵심은 Azure OpenAI를 실제로 한 번 호출하는 데 필요한 전체 흐름 을 이해하는 것이다.

2. 실습 전 준비물

실습을 시작하기 전에 다음 항목이 필요하다.

준비물	설명
Azure 계정	Azure Portal에 접속할 수 있어야 한다.
Azure 구독	리소스를 생성할 수 있는 구독이 필요하다.
Azure OpenAI 사용 권한	조직이나 구독에 따라 권한이 제한될 수 있다.
Resource Group	Azure 리소스를 묶어 관리하는 단위다.
Python 환경	SDK 호출 실습을 위해 필요하다.
코드 에디터	VS Code 등을 사용하면 편하다.

Azure OpenAI Service는 모든 계정에서 바로 사용할 수 있는 것은 아니다. 구독이나 조직 설정에 따라 Azure OpenAI 리소스 생성 권한이 제한될 수 있다.

따라서 리소스 생성 단계에서 Azure OpenAI 항목이 보이지 않거나 생성이 되지 않는다면, 먼저 권한과 구독 상태를 확인해야 한다.

3. Resource Group 만들기

Azure에서는 여러 리소스를 Resource Group이라는 단위로 묶어서 관리한다.

Resource Group은 쉽게 말하면 프로젝트 폴더 같은 개념이다.

예를 들어 Azure OpenAI 실습을 한다면, 다음 리소스들을 하나의 Resource Group에 묶을 수 있다.

Resource Group
├── Azure OpenAI Resource
├── Azure AI Search
├── Storage Account
└── App Service

이번 실습에서는 먼저 Resource Group을 생성한다.

[사진 2 ] Azure Portal에서 Resource Group 생성 화면

Resource Group을 사용하는 이유

이유	설명
리소스 관리	관련 리소스를 한 곳에서 확인할 수 있다.
비용 관리	프로젝트별 비용을 추적하기 쉽다.
삭제 편의성	실습이 끝난 뒤 관련 리소스를 한 번에 정리할 수 있다.

실습용 리소스는 나중에 비용이 발생하지 않도록 정리하는 것이 중요하다. 따라서 처음부터 Resource Group을 따로 만들어두면 관리하기 쉽다.

4. Azure OpenAI Resource 만들기

Resource Group을 만들었다면 이제 Azure OpenAI Resource를 생성한다.

Azure OpenAI Resource는 Azure에서 OpenAI 모델을 사용하기 위한 실제 서비스 리소스다.

Resource Group = 프로젝트 폴더
Azure OpenAI Resource = OpenAI 모델을 사용할 서비스 공간

[사진 3]

Azure OpenAI Resource를 만들 때는 보통 다음 항목을 설정한다.

항목	설명
Subscription	사용할 Azure 구독
Resource Group	리소스를 넣을 그룹
Region	리소스를 생성할 지역
Name	리소스 이름
Pricing tier	가격 계층

여기서 특히 중요한 것은 Region이다.

Azure OpenAI는 모든 모델이 모든 Region에서 제공되는 것이 아니다. 따라서 원하는 모델이 보이지 않는다면 Region 문제일 수 있다.

5. Azure AI Foundry로 이동하기

Azure OpenAI Resource를 생성했다고 해서 바로 모델을 사용할 수 있는 것은 아니다.

실제로 모델을 배포하고 Playground에서 테스트하려면 Azure AI Foundry로 이동해야 한다.

Azure Portal에서 생성한 Azure OpenAI Resource 화면으로 들어간 뒤, Explore Azure AI Foundry portal 버튼을 클릭한다.

구분	역할
Azure Portal	Azure 리소스를 생성하고 관리하는 공간
Azure AI Foundry	모델 배포, Playground, AI 앱 개발을 진행하는 공간

즉, Azure Portal은 인프라 관리 화면에 가깝고, Azure AI Foundry는 생성형 AI 서비스를 개발하고 실험하는 작업 공간에 가깝다.

6. 모델 배포하기

Azure OpenAI에서는 모델을 바로 호출하지 않는다.

먼저 사용할 모델을 선택하고, 그 모델을 내 Azure OpenAI Resource 안에 배포해야 한다.

Model Catalog에서 모델 선택
→ Deploy 클릭
→ Deployment Name 설정
→ 배포 유형 선택
→ TPM 설정
→ 배포 완료

6-1. Model Catalog에서 모델 선택하기

Azure AI Foundry에 들어가면 Model Catalog에서 사용할 모델을 선택할 수 있다. 이번 실습에서는 gpt-4o-mini 모델을 사용한다고 가정한다.

gpt-4o-mini는 비교적 가볍고 비용 부담이 적어 기본 실습용으로 사용하기 좋다.

기준	설명
성능	복잡한 추론이 필요한지 확인한다.
비용	토큰당 비용이 어느 정도인지 확인한다.
속도	응답 속도가 중요한지 확인한다.
멀티모달	이미지, 오디오 등도 처리해야 하는지 확인한다.
Region 지원	현재 선택한 Region에서 제공되는지 확인한다.

6-2. Deploy 클릭하기

모델 상세 페이지로 들어가면 선택한 모델을 배포할 수 있다.

여기서 중요한 점은 Model과 Deployment는 다르다 는 것이다.

구분	의미
Model	Azure에서 제공하는 AI 모델 자체
Deployment	내 리소스에서 그 모델을 호출할 수 있도록 만든 실행 단위

모델명: gpt-4o-mini
배포명: dev-gpt-4o-mini

모델명은 Azure에서 제공하는 이름이고, 배포명은 내가 API에서 호출하기 위해 지정하는 이름이다.

6-3. Deployment Name 설정하기

배포를 만들 때 Deployment Name을 지정한다.

Deployment Name은 나중에 API나 SDK에서 모델을 호출할 때 사용한다. 따라서 너무 복잡하게 짓기보다는, 어떤 용도의 배포인지 알 수 있게 작성하는 것이 좋다.

gpt-4o-mini-chat
my-chat-model
aoai-basic-chat

헷갈리기 쉬운 부분은 다음과 같다.

모델명 = gpt-4o-mini
배포명 = 내가 정한 이름

Azure OpenAI SDK에서는 보통 model 파라미터에 실제 모델명이 아니라 배포명을 넣어 호출한다.

내 코드
→ deployment name 호출
→ Azure OpenAI Resource
→ 실제 연결된 모델이 응답 생성

6-4. 배포 유형 선택하기

모델 배포 시 배포 유형을 선택할 수 있다. 실습에서는 보통 기본 제공되는 표준 배포 방식을 사용하면 된다.

방식	설명
Pay-as-you-go	사용한 만큼 비용을 지불하는 방식
PTU	처리량을 미리 예약해서 사용하는 방식

처음 실습하는 단계에서는 일반적으로 Pay-as-you-go 방식이 적합하다. PTU는 일정한 처리량이 필요한 운영 서비스에서 고려하는 방식이다.

6-5. TPM 설정하기

모델 배포 과정에서 TPM 제한을 설정할 수 있다.

TPM은 Tokens Per Minute의 약자다.

TPM = 1분 동안 처리할 수 있는 토큰 수

여기서 토큰은 입력 토큰과 출력 토큰을 모두 포함한다. 사용자가 긴 문서를 입력하고, 모델이 긴 답변을 생성하면 많은 토큰을 사용한다.

입력 토큰 + 출력 토큰 = 전체 사용 토큰

TPM 제한이 낮으면 요청이 많거나 긴 답변을 생성할 때 제한에 걸릴 수 있다. 실습에서는 강의 자료나 실습 환경에서 안내하는 값에 맞춰 설정하면 된다.

7. Endpoint와 API Key 확인하기

모델 배포가 완료되면 API 호출에 필요한 정보를 확인해야 한다.

Endpoint
API Key
Deployment Name

항목	의미	쉽게 말하면
Endpoint	API 요청을 보낼 주소	문 주소
API Key	사용 권한을 증명하는 인증 키	출입증
Deployment Name	호출할 모델 배포 이름	사용할 모델 이름표

이 세 가지가 있어야 코드에서 Azure OpenAI를 호출할 수 있다.

API Key는 코드에 직접 쓰면 안 된다

API Key는 외부에 노출되면 안 되는 민감한 정보다. 따라서 코드에 직접 작성하는 것은 좋지 않다.

api_key = "실제_API_KEY_값"

이렇게 작성한 코드를 GitHub에 올리면 API Key가 그대로 노출될 수 있다. 대신 환경 변수나 .env 파일을 사용하는 것이 좋다.

AZURE_OPENAI_ENDPOINT=your_endpoint
AZURE_OPENAI_API_KEY=your_api_key
AZURE_OPENAI_DEPLOYMENT=your_deployment_name
AZURE_OPENAI_API_VERSION=your_api_version

Python 코드에서는 환경 변수에서 값을 불러온다.

import os

endpoint = os.getenv("AZURE_OPENAI_ENDPOINT")
api_key = os.getenv("AZURE_OPENAI_API_KEY")
deployment = os.getenv("AZURE_OPENAI_DEPLOYMENT")
api_version = os.getenv("AZURE_OPENAI_API_VERSION")

방식	권장 여부	이유
코드에 직접 작성	비권장	키가 노출될 수 있음
.env 파일 사용	개발 환경에서 권장	코드와 비밀값을 분리할 수 있음
환경 변수 사용	권장	배포 환경에서 관리하기 좋음
Azure Key Vault 사용	실무 권장	비밀값을 안전하게 중앙 관리 가능

8. Playground에서 테스트하기

코드를 작성하기 전에 Playground에서 모델을 테스트할 수 있다. Playground는 코드 없이 모델의 응답을 확인할 수 있는 실험 공간이다.

요소	설명
Model 또는 Deployment	사용할 모델 배포
System Message	모델의 역할과 규칙
User Message	사용자의 요청
Assistant Response	모델의 응답
Parameters	Temperature, Max Tokens 등 설정

이번 글에서는 매개변수를 깊게 조정하지 않고, 기본 설정으로 응답이 정상적으로 나오는지만 확인한다.

Chat Playground의 메시지 구조

Chat Playground에서는 대화가 역할 단위로 구성된다.

system
user
assistant

role	의미
system	모델의 역할, 말투, 규칙을 정하는 메시지
user	사용자가 입력하는 질문이나 요청
assistant	모델이 생성한 응답

system: 너는 친절한 AI 튜터야.
user: Azure OpenAI가 뭐야?
assistant: Azure OpenAI는 Azure에서 OpenAI 모델을 사용할 수 있게 해주는 서비스입니다.

이 구조는 나중에 API와 SDK에서도 그대로 사용된다.

9. API로 호출하기

Playground에서 모델이 정상적으로 응답하는 것을 확인했다면, 이제 API로 호출할 수 있다.

Client
→ Endpoint로 요청 전송
→ API Key로 인증
→ Deployment Name에 연결된 모델 실행
→ 응답 반환

API 호출 시 필요한 정보는 다시 한 번 다음과 같다.

Endpoint	요청을 보낼 주소	https://내리소스이름.openai.azure.com/
API Key	인증 키	긴 문자열
Deployment Name	내가 배포한 모델 이름표	gpt-4o-mini-chat
API Version	API 버전	2024-02-15-preview 등

REST API를 직접 사용할 때는 HTTP 요청을 구성해야 한다.

요청 body에는 messages 배열을 넣는다.

curl -X POST "https://my-aoai.openai.azure.com/openai/deployments/gpt-4o-mini-chat/chat/completions?api-version=2024-02-15-preview" \
  -H "Content-Type: application/json" \
  -H "api-key: YOUR_API_KEY" \
  -d '{
    "messages": [
      {
        "role": "system",
        "content": "너는 친절한 AI 튜터야."
      },
      {
        "role": "user",
        "content": "Azure OpenAI가 무엇인지 쉽게 설명해줘."
      }
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

여기서 중요한 것은 messages 구조다. Chat Completions API는 단순 문자열 하나만 보내는 것이 아니라, system, user, assistant 역할을 가진 메시지 배열을 전달한다.

10. Python SDK로 호출하기

REST API를 직접 호출해도 되지만, Python SDK를 사용하면 더 편하게 Azure OpenAI를 호출할 수 있다.

먼저 필요한 패키지를 설치한다.

pip install openai python-dotenv

.env 파일에는 다음과 같이 값을 저장한다.

AZURE_OPENAI_ENDPOINT=your_endpoint
AZURE_OPENAI_API_KEY=your_api_key
AZURE_OPENAI_DEPLOYMENT=your_deployment_name
AZURE_OPENAI_API_VERSION=2024-02-15-preview

Python 코드에서는 다음과 같이 작성할 수 있다.

import os
from openai import AzureOpenAI
from dotenv import load_dotenv

load_dotenv()

client = AzureOpenAI(
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION")
)

response = client.chat.completions.create(
    model=os.getenv("AZURE_OPENAI_DEPLOYMENT"),
    messages=[
        {
            "role": "system",
            "content": "너는 친절한 AI 튜터야."
        },
        {
            "role": "user",
            "content": "Azure OpenAI가 무엇인지 쉽게 설명해줘."
        }
    ]
)

print(response.choices[0].message.content)

여기서 model에 들어가는 값은 실제 모델명인 gpt-4o-mini가 아니라, 내가 Azure에서 설정한 Deployment Name이다.

11. 코드 구조 해석

1단계: 환경 변수 불러오기

load_dotenv()

.env 파일에 저장된 Endpoint, API Key, Deployment Name 등을 불러온다.

민감한 정보를 코드에 직접 작성하지 않기 위해 사용하는 방식이다.

2단계: 클라이언트 생성

client = AzureOpenAI(
    azure_endpoint=os.getenv("AZURE_OPENAI_ENDPOINT"),
    api_key=os.getenv("AZURE_OPENAI_API_KEY"),
    api_version=os.getenv("AZURE_OPENAI_API_VERSION")
)

이 코드는 Azure OpenAI 서비스에 요청을 보낼 클라이언트를 생성하는 부분이다.

항목	역할
azure_endpoint	요청을 보낼 Azure OpenAI 주소
api_key	인증을 위한 키
api_version	사용할 API 버전

3단계: messages 구성

messages=[
    {
        "role": "system",
        "content": "너는 친절한 AI 튜터야."
    },
    {
        "role": "user",
        "content": "Azure OpenAI가 무엇인지 쉽게 설명해줘."
    }
]

messages는 모델에게 전달하는 대화 내용이다.

system 메시지는 모델의 역할을 정하고, user 메시지는 실제 사용자의 요청을 전달한다.

4단계: 응답 출력

print(response.choices[0].message.content)

모델 응답은 여러 정보가 포함된 객체 형태로 반환된다. 그중 실제 답변 텍스트는 response.choices[0].message.content에 들어 있다.

12. 자주 나는 오류와 해결 방법

12-1. Deployment Name 오류

가장 흔한 오류는 모델명과 배포명을 헷갈리는 것이다.

model="gpt-4o-mini"

이렇게 실제 모델명을 넣었는데 오류가 발생할 수 있다. Azure OpenAI에서는 보통 model 자리에 배포명을 넣어야 한다.

model="내가 설정한 deployment name"

따라서 오류가 발생하면 Azure AI Foundry에서 배포 이름을 다시 확인해야 한다.

12-2. Region 문제

원하는 모델이 보이지 않는다면 Region 문제일 수 있다. Azure OpenAI는 지역마다 제공되는 모델이 다를 수 있다.

예를 들어 어떤 Region에서는 gpt-4o-mini가 보이지만, 다른 Region에서는 보이지 않을 수 있다.

12-3. API Key 노출 문제

실습 과정에서 캡처를 찍거나 코드를 공유할 때는 다음 정보를 반드시 가려야 한다.

API Key
Endpoint 일부
Subscription ID
Tenant ID
개인 계정 정보

캡처 이미지를 올릴 때는 민감한 정보가 보이지 않도록 모자이크 처리하는 것이 좋다.

13. 전체 흐름 정리

1. Azure Portal 접속
2. Resource Group 생성
3. Azure OpenAI Resource 생성
4. Azure AI Foundry로 이동
5. Model Catalog에서 모델 선택
6. gpt-4o-mini 배포
7. Deployment Name 설정
8. TPM 설정
9. Endpoint와 API Key 확인
10. Playground에서 응답 테스트
11. API 또는 SDK로 모델 호출

이번 실습에서 가장 중요한 개념은 세 가지다.

Endpoint
API Key
Deployment Name

이 세 가지를 정확히 이해하면 Azure OpenAI를 코드에서 호출하는 기본 흐름을 잡을 수 있다.

14. 마무리

이번 글에서는 Azure OpenAI를 실제로 사용하기 위한 기본 실습 흐름을 정리했다.

핵심은 모델을 바로 호출하는 것이 아니라, Azure OpenAI Resource 안에 모델을 배포한 뒤 그 배포를 호출한다는 점 이다.

Model 선택
→ Deployment 생성
→ Endpoint / API Key / Deployment Name 확인
→ Playground 테스트
→ API / SDK 호출

다음 글에서는 Azure OpenAI의 모델 매개변수를 정리할 예정이다.

같은 모델을 사용하더라도 Temperature, Top-P, Max Tokens 같은 설정에 따라 응답의 길이, 다양성, 창의성, 안정성이 달라진다.

따라서 다음 글에서는 생성 결과를 제어하는 모델 매개변수를 하나씩 살펴본다.

'Azure OpenAI Engineering > LLM' 카테고리의 다른 글

[ Azure OpenAI #8] 모델 매개변수 실험 기록: 설정값에 따라 GPT 답변은 어떻게 달라질까? (0)	2026.06.18
[Azure OpenAI #7] 모델 매개변수 완전 정리: Temperature, Top-P, Top-K, Max Tokens, Stop Sequence, Penalty (0)	2026.06.17
[Azure OpenAI #5] Azure OpenAI Service 전체 구조 이해하기: 리소스, 모델, 배포, Endpoint (1)	2026.06.17
[Azure OpenAI #4] Transformer와 GPT 구조 : 왜 문맥을 이해할 수 있을까? (0)	2026.06.17
[Azure OpenAI #3] GPT는 문장을 어떻게 이해할까? 토큰과 임베딩 이해하기 (0)	2026.06.17

yunalee-dev 님의 블로그

[ Azure OpenAI #6 ] 기본 실습: 리소스 생성부터 Playground, API, SDK 호출까지

들어가며

1. 실습 목표

2. 실습 전 준비물

3. Resource Group 만들기

Resource Group을 사용하는 이유

4. Azure OpenAI Resource 만들기

5. Azure AI Foundry로 이동하기

6. 모델 배포하기

6-1. Model Catalog에서 모델 선택하기

6-2. Deploy 클릭하기

6-3. Deployment Name 설정하기

6-4. 배포 유형 선택하기

6-5. TPM 설정하기

7. Endpoint와 API Key 확인하기

API Key는 코드에 직접 쓰면 안 된다

8. Playground에서 테스트하기

Chat Playground의 메시지 구조

9. API로 호출하기

10. Python SDK로 호출하기

11. 코드 구조 해석

1단계: 환경 변수 불러오기

2단계: 클라이언트 생성

3단계: messages 구성

4단계: 응답 출력

12. 자주 나는 오류와 해결 방법

12-1. Deployment Name 오류

12-2. Region 문제

12-3. API Key 노출 문제

13. 전체 흐름 정리

14. 마무리

'Azure OpenAI Engineering > LLM' 카테고리의 다른 글

티스토리툴바

[ Azure OpenAI #6 ] 기본 실습: 리소스 생성부터 Playground, API, SDK 호출까지

들어가며

1. 실습 목표

2. 실습 전 준비물

3. Resource Group 만들기

Resource Group을 사용하는 이유

4. Azure OpenAI Resource 만들기

5. Azure AI Foundry로 이동하기

6. 모델 배포하기

6-1. Model Catalog에서 모델 선택하기

6-2. Deploy 클릭하기

6-3. Deployment Name 설정하기

6-4. 배포 유형 선택하기

6-5. TPM 설정하기

7. Endpoint와 API Key 확인하기

API Key는 코드에 직접 쓰면 안 된다

8. Playground에서 테스트하기

Chat Playground의 메시지 구조

9. API로 호출하기

10. Python SDK로 호출하기

11. 코드 구조 해석

1단계: 환경 변수 불러오기

2단계: 클라이언트 생성

3단계: messages 구성

4단계: 응답 출력

12. 자주 나는 오류와 해결 방법

12-1. Deployment Name 오류

12-2. Region 문제

12-3. API Key 노출 문제

13. 전체 흐름 정리

14. 마무리

'Azure OpenAI Engineering > LLM' 카테고리의 다른 글

관련글

티스토리툴바