Azure App Service AI 시나리오: AI 파운드리 통합 완벽 샘플

이 샘플 애플리케이션은 Azure AI 파운드리를 사용하여 Azure App Service에서 다양한 AI 시나리오를 구현하는 방법을 보여줍니다. AIPlaygroundCode 패키지를 복사하고 통합 단계를 따르면 기존 Flask 애플리케이션에 통합할 수 있는 프로덕션 준비 코드를 제공합니다.

적합 대상: 기존 Flask 애플리케이션에 AI 기능을 추가하고, Azure AI 파운드리 통합 패턴을 학습하며, 최소한의 설정으로 엔터프라이즈급 AI 기능을 구현하려는 개발자에게 적합합니다.

주요 시나리오

대화형 AI: 컨텍스트 인식 및 세션 관리를 통한 자연어 처리 추론 모델: 단계별 분석적 사고를 통한 고급 문제 해결 기능 구조화된 출력: 시스템 통합을 위한 스키마 유효성 검사가 포함된 JSON 형식 응답 멀티모달 처리: 시각 및 오디오 모델을 사용한 이미지 분석 및 오디오 전사 엔터프라이즈 챗: 고객 서비스 및 비즈니스 인텔리전스 시나리오를 포함하는 소매점 최적화 AI 어시스턴트

빠른 시작 - Azure 배포 (권장)

필수 구성 요소

Azure CLI 설치
Azure Developer CLI (azd) 설치
기여자 액세스 권한이 있는 Azure 구독
선택 사항: 기존 엔드포인트를 사용하려는 경우 기존 모델 배포가 있는 Azure AI 파운드리 액세스:
- 챗/추론/이미지 모델: 대화형 AI, 추론 및 이미지 분석을 위한 gpt-4o-mini 또는 유사 모델
- 오디오 모델: 오디오 전사 및 처리를 위한 gpt-4o-mini-audio-preview 또는 유사 모델
- 모델 호환성: 배포 오류를 방지하려면 권장 모델(gpt-4o-mini, gpt-35-turbo)을 사용하세요. gpt-4o와 같은 고급 모델은 일부 지역에서 사용하지 못할 수 있습니다.

원-명령 배포

클론 및 배포

git clone https://github.com/Azure-Samples/azure-app-service-ai-scenarios-integrated-sample.git
cd azure-app-service-ai-scenarios-integrated-sample
azd up

배포 중 예상되는 사항

azd up을 실행하면 다음 프롬프트가 나타납니다.

고유한 환경 이름을 입력하세요: → myai-demo
구독 선택 → 화살표 키를 사용하여 선택
리소스 그룹 → 새로 만들거나 기존 항목 사용
리소스 그룹을 만들 위치를 선택하세요: 예: East US
새로 만들기(AI 서비스 생성) 또는 기존 [new/existing] 중에서 선택하세요: 예: existing
프로젝트 엔드포인트 URL을 입력하세요: 예: https://your-project.services.ai.azure.com/models
배포 이름을 입력하세요 (gpt-4o-mini, gpt-4, gpt-35-turbo): 예: gpt-4o-mini
오디오 배포 이름을 입력하세요 (gpt-4o-mini-audio-preview): 예: gpt-4o-mini-audio-preview
사용할 Azure 위치를 선택하세요: 예: East US

자동 단계: 패키지 빌드, RBAC 설정, 프로비저닝, 배포

예상 배포 시간: 완전한 프로비저닝 및 배포까지 4-5분 소요

배포 중 Azure AI 파운드리 통합 azd up 중 AI 설정을 구성하라는 메시지가 나타납니다.

프롬프트: "기존 Azure AI 파운드리 엔드포인트가 있습니까?"

"existing"으로 답변: 기존 Azure AI 파운드리 리소스가 있는 경우
- 엔드포인트 URL(예: https://your-project.services.ai.azure.com/models)을 제공하라는 메시지가 나타납니다.
- 관리 ID 역할 권한이 엔드포인트에 자동으로 구성됩니다.
- 기존 모델 배포 이름(챗 모델 이름 예: gpt-4o-mini 및 오디오 모델 이름 예: gpt-4o-mini-audio-preview)을 지정합니다.
"new"로 답변: 새 Azure AI 파운드리 리소스가 자동으로 생성됩니다.
- 필수 종속성이 포함된 새 Azure AI 파운드리 프로젝트를 프로비저닝합니다.
- 구성 가능한 이름(기본값: gpt-4o-mini 및 gpt-4o-mini-audio-preview)으로 챗 및 오디오 모델을 배포합니다.
- 관리 ID 통합을 구성하고 필요한 모든 설정을 업데이트합니다.

구성 자동화 - 모든 환경 변수 및 권한은 배포 중에 자동으로 설정됩니다!

참고: 더 이상 AI 설정을 수동으로 구성하거나 API 키를 관리할 필요가 없습니다. 모든 것이 관리 ID 통합을 통해 자동으로 처리됩니다.

애플리케이션 테스트

"🧪 Test Config"를 클릭하여 연결을 확인한 다음 AI 시나리오를 사용하기 시작하세요!
아래의 사용 예시 섹션을 참조하여 샘플 시나리오로 수동 테스트를 수행하세요.

배포되는 항목

Azure App Service (Basic B2 SKU) with Python 3.11
Azure AI 파운드리 리소스 ("new"를 선택한 경우):
- 인지 서비스 다중 서비스 계정을 포함한 AI Hub
- 모델 배포(gpt-4o-mini, gpt-4o-mini-audio-preview)를 포함한 AI 프로젝트 작업 공간
- AI 프로젝트 데이터 및 모델 아티팩트용 스토리지 계정
관리 ID 구성 (새 엔드포인트 및 기존 엔드포인트 모두에 대해 자동):
- App Service에 시스템 할당 관리 ID 활성화
- AI 엔드포인트에 액세스하기 위해 "Cognitive Services OpenAI User" 역할 할당
- Azure AI 파운드리 프로젝트 액세스를 위해 "AI Developer" 역할 할당
App Service에 필요한 모든 환경 변수 자동 구성

로컬 개발 설정

필수 구성 요소

Python 3.8+
- 버전 확인: python --version
- 다운로드: https://python.org/downloads/
Azure AI 파운드리 (배포된 모델 포함)
- 📖 설정 가이드: Azure AI 파운드리에서 프로젝트 생성 및 모델 배포
- 필수 모델: gpt-4o-mini (챗/추론/이미지) 및 gpt-4o-mini-audio-preview (오디오)
- 대안: 자동 설정을 위해 위의 azd up 배포 방식을 사용하세요.

단계별 설치 및 설정

1단계: 애플리케이션 설치 및 시작

종속성 설치

pip install -r requirements.txt

애플리케이션 시작

python app.py

애플리케이션 실행 확인

브라우저에서 http://localhost:5000 열기
애플리케이션 홈페이지가 표시되어야 합니다.

2단계: AI 설정 구성

설정 페이지 열기
- http://localhost:5000/settings로 이동
구성 필드 채우기
- Azure AI 파운드리 엔드포인트: https://your-project.services.ai.azure.com/models
- API 키: Azure AI 파운드리 API 키 (참고: 프로덕션 배포의 경우 관리 ID가 자동으로 구성됩니다.)
- 챗 모델 이름: 배포된 챗 모델 이름 (예: gpt-4o-mini)
- 오디오 모델 이름: 오디오 모델 배포 (예: gpt-4o-mini-audio-preview)
구성 저장 및 테스트
- 저장을 클릭하여 설정을 저장
- **"🧪 Test Config"**를 클릭하여 연결 확인
- 성공 확인 메시지 대기

3단계: 핵심 기능 테스트

샘플 시나리오를 사용한 자세한 테스트 지침은 아래의 핵심 기능 테스트 섹션을 참조하세요.

✅ 성공 지표:

구성 테스트에 성공 메시지 표시
http://localhost:5000에서 애플리케이션 로드
챗 인터페이스에 액세스 가능하며 기능 정상

핵심 기능 테스트

참고: 이 테스트는 로컬 개발 및 Azure 배포 설정 모두에 적용됩니다.

단계별 테스트 가이드

1. 챗 인터페이스 액세스

http://localhost:5000으로 이동
떠 있는 AI 챗 버튼 (오른쪽 하단 모서리) 클릭
챗 팝업이 올바르게 열리는지 확인

2. 기본 대화형 AI 테스트

정확히 다음 메시지들을 테스트하세요 (복사 및 붙여넣기):

정체성 테스트:
- 메시지: "당신은 누구이며 무엇을 도울 수 있나요?"
- 예상: AI가 엔터프라이즈 AI 어시스턴트임을 식별하고 기능을 설명합니다.
제품 문의 테스트:
- 메시지: "Pro Gaming X1의 기능 및 가격에 대해 알려주세요."
- 예상: 관련 제품 정보 응답
고객 서비스 테스트:
- 메시지: "반품 정책은 무엇이며, 고객 환불은 어떻게 처리하나요?"
- 예상: 유용한 고객 서비스 안내

3. 멀티모달 기능 테스트

이미지 분석 테스트:

메시지 입력: "이 노트북을 분석하고 사양을 알려주세요."
📎 버튼을 클릭하여 파일 업로드
파일 선택: tests/test_inputs/laptop.jpeg
메시지 전송
예상: AI가 이미지에서 노트북 사양을 설명합니다.

오디오 처리 테스트:

메시지 입력: "이 고객 서비스 통화를 전사해 주세요."
📎 버튼을 클릭하여 파일 업로드
파일 선택: tests/test_inputs/test_customer_service_audio.mp3
메시지 전송
예상: AI가 오디오 콘텐츠의 전사본을 제공합니다.

4. 고급 추론 기능 테스트

복잡한 비즈니스 분석 테스트: 메시지: "이번 분기 Zava의 매출이 15% 감소했습니다. 근본 원인을 파악하고 실행 계획을 개발하기 위한 체계적인 접근 방식을 설명해 주세요." 예상: 단계별 추론 과정을 포함한 구조화된 분석 접근 방식

✅ 성공 지표:

모든 챗 응답이 관련성이 높고 유용함
이미지 분석이 노트북 기능을 정확하게 식별함
오디오 전사가 오디오 파일에서 읽을 수 있는 텍스트를 제공함
추론 응답이 구조화된 분석적 사고를 보여줌
챗 인터페이스에 오류 메시지 없음
파일 업로드 성공적으로 완료
긴 콘텐츠에 대한 응답이 잘림 메시지를 표시할 수 있음 (정상입니다)
구성 테스트에 녹색 성공 메시지 표시

📁 샘플 테스트 파일: 멀티모달 기능을 테스트하기 위한 추가 샘플 이미지 및 오디오 파일은 tests/test_inputs/ 폴더를 참조하세요.

기존 애플리케이션과의 통합

이 섹션에서는 기존 Flask 애플리케이션에 AI 기능을 통합하기 위한 지침을 제공합니다. 이 작업에는 추가 Azure 리소스 설정 및 종속성 관리가 필요합니다.

통합을 위한 필수 구성 요소

모델 배포가 있는 Azure AI 파운드리 엔드포인트:
- 챗/추론/이미지 모델 (예: gpt-4o-mini)
- 오디오 모델 (예: gpt-4o-mini-audio-preview)

1단계: Azure 리소스 설정

Azure AI 파운드리를 위한 App Service 관리 ID 구성:

# App Service에 시스템 할당 관리 ID 활성화
az webapp identity assign --name <your-app-name> --resource-group <your-rg>

# Azure AI 파운드리 액세스를 위해 App Service에 필요한 역할 부여
az role assignment create \
  --role "Cognitive Services OpenAI User" \
  --assignee <managed-identity-principal-id> \
  --scope <your-ai-foundry-resource-id>

# Azure AI 파운드리 프로젝트 액세스를 위한 AI Developer 역할 부여
az role assignment create \
  --role "Azure AI Developer" \
  --assignee <managed-identity-principal-id> \
  --scope <your-ai-foundry-resource-id>

2단계: 파일 복사 및 병합

AIPlaygroundCode 폴더 복사:

cp -r AIPlaygroundCode/ /path/to/your-existing-app/

종속성 병합 (중요!):

requirements.txt: 이 샘플의 requirements.txt에 있는 종속성을 기존 requirements 파일과 병합
wsgi.py: 기존 wsgi.py 파일이 있는 경우 Flask 앱 인스턴스를 올바르게 참조하는지 확인
app.py 라우트: 샘플 app.py의 AI 관련 라우트를 기존 Flask 애플리케이션에 복사

requirements.txt 병합 예시:

# 기존 종속성
flask==2.3.3
# ... 기타 종속성

# 샘플에서 AI 관련 종속성 추가
azure-identity==1.15.0
openai==1.35.13
pillow==10.0.0
pydub==0.25.1

3단계: App Service 구성 업데이트

AI 구성을 App Service 환경 변수로 추가:

# Azure AI 파운드리 구성을 App Service 환경 변수로 추가
az webapp config appsettings set --name <your-app-name> --resource-group <your-rg> --settings \
  AZURE_INFERENCE_ENDPOINT="https://your-project-name.region.models.ai.azure.com/models" \
  AZURE_AI_CHAT_DEPLOYMENT_NAME="gpt-4o-mini" \
  AZURE_AI_AUDIO_DEPLOYMENT_NAME="gpt-4o-mini-audio-preview" \
  AZURE_CLIENT_ID="system-assigned-managed-identity"

4단계: Flask 앱에 AI 설정 라우트 추가

기존 Flask 애플리케이션에 설정 라우트 추가:

# 기존 app.py에 다음 import 추가
from AIPlaygroundCode.config import get_model_config, update_model_config, is_configured

# AI 구성 라우트 추가
@app.route('/settings')
def settings():
    from flask import render_template
    config = get_model_config()
    return render_template('AIPlaygroundCode/templates/settings.html', config=config)

@app.route('/settings', methods=['POST'])
def update_settings():
    # 샘플 app.py에서 전체 설정 업데이트 로직을 복사하세요.
    # 여기에는 양식 처리, 유효성 검사 및 구성 업데이트가 포함됩니다.
    pass

5단계: 애플리케이션에 AI 인터페이스 추가

AIPlaygroundCode/templates/retail_home.html에서 특정 섹션을 복사하여 AI 챗 인터페이스를 기존 애플리케이션 페이지에 통합하세요.

retail_home.html에서 다음 마커를 찾아 템플릿에 복사하세요.

HTML 구조 (로 표시된 섹션 복사):

<!-- AI Chat Interface Start -->
<div id="chat-popup" class="chat-popup">
    <!-- 전체 챗 팝업 구조 -->
</div>
<!-- AI Chat Interface End -->

CSS 스타일 (/* AI Chat Styles Start */로 표시된 섹션 복사):

<style>
/* AI Chat Styles Start */
.chat-popup { /* ... */ }
/* AI Chat Styles End */
</style>

JavaScript 함수 (// AI Chat JavaScript Start로 표시된 섹션 복사):

<script>
// AI Chat JavaScript Start
function toggleChat() { /* ... */ }
// AI Chat JavaScript End
</script>

통합 단계:

retail_home.html에서 표시된 각 섹션을 메인 애플리케이션 템플릿에 복사
챗 버튼이 페이지에 표시되는지 확인 (오른쪽 하단에 떠 있는 형태)
챗 인터페이스가 열리고 메시지를 보낼 수 있는지 테스트
멀티모달 기능을 위한 파일 업로드 기능이 작동하는지 확인

통합 후 얻게 되는 것:

새 라우트: AI 구성을 위한 /settings
설정 페이지: Azure AI 파운드리 엔드포인트를 위한 셀프 서비스 구성 인터페이스
AI 챗 인터페이스: 애플리케이션 페이지 내 통합된 챗 기능
보안 구성: Azure AI 파운드리를 사용한 관리 ID 인증 (API 키 필요 없음)

리소스 정리

불필요한 요금 발생을 방지하려면 애플리케이션 작업 완료 후 Azure 리소스를 정리하는 것이 중요합니다.

정리 시점

애플리케이션 테스트 또는 데모를 마친 후
애플리케이션이 더 이상 필요 없거나 다른 프로젝트로 전환한 경우
개발을 완료하고 애플리케이션을 서비스 중단할 준비가 된 경우

Azure 리소스 제거

연결된 모든 리소스를 삭제하고 애플리케이션을 종료하려면 다음 명령을 실행하세요.

azd down

이 과정은 완료하는 데 최대 10분이 소요될 수 있습니다.

대안: Azure Portal에서 리소스 그룹을 직접 삭제하여 리소스를 정리할 수 있습니다.

가이드

비용

가격은 지역 및 사용량에 따라 다르므로 사용량에 대한 정확한 비용을 예측할 수 없습니다. 이 인프라에 사용되는 대부분의 Azure 리소스는 사용량 기반 요금제를 따릅니다.

다음 리소스에 대한 Azure 가격 계산기를 사용해 볼 수 있습니다.

핵심 리소스 (항상 배포됨):

Azure App Service: 3.5GB RAM, 10GB 스토리지를 갖춘 Basic B2 계층. 가격 책정

Azure AI 파운드리 리소스 (기존 엔드포인트에 대해 "아니요"를 선택한 경우 배포됨):

Azure AI 서비스: 모델 사용량(토큰)에 대한 사용량 기반 요금제를 사용하는 다중 서비스 계정. 가격 책정
Azure AI Hub: AI 프로젝트를 위한 관리 계층 (최소 비용)
Azure 스토리지 계정: AI 프로젝트 데이터 및 모델 아티팩트용 표준 LRS (최소 비용). 가격 책정

비용 절감 팁: 기존 리소스를 재사용하고 중복 요금을 방지하려면 기존 Azure AI 파운드리 엔드포인트에 대한 프롬프트가 나타날 때 "예"를 선택하세요.

비용 관리: 불필요한 비용을 피하려면 azd down을 실행하거나 Azure Portal에서 리소스 그룹을 삭제하여 더 이상 필요하지 않은 리소스를 정리하는 것을 잊지 마세요.

보안 지침

이 템플릿은 Azure 서비스 간의 보안 인증을 위해 관리 ID를 사용합니다.

고려해야 할 추가 보안 조치:

Azure 리소스 보안을 위해 Microsoft Defender for Cloud 활성화
App Service에 가상 네트워크로 네트워크 보안 구현
추가 보호를 위해 Azure 웹 애플리케이션 방화벽 구성
리포지토리에서 GitHub 비밀 스캔 활성화

중요 보안 알림 이 템플릿은 Azure AI 서비스 및 도구를 시연하기 위해 제작되었습니다. 이 코드를 프로덕션 환경에서 사용하기 전에 추가 보안 기능을 구현하는 것을 적극 권장합니다.

지원 및 피드백

이슈: GitHub 이슈를 통해 버그를 보고하거나 기능 요청
질문: 구현 관련 질문은 GitHub 토론을 이용
샘플 평가: 이 샘플이 프로젝트에 도움이 되었다면 리포지토리에 스타를 눌러주세요.

참고 자료

구현 가이드

GitHub 리포지토리 - 전체 구현 가이드 및 소스 코드
프로젝트 구조 - 상위 수준 구성 및 아키텍처 학습
구성 가이드 - 구성 옵션 및 환경 설정 이해
테스트 가이드 - 로컬 및 Azure에서 애플리케이션 테스트 방법 학습
FAQ 및 문제 해결 - 자주 묻는 질문 및 문제 해결 가이드

Azure AI 파운드리 문서

챗 완성 - 기본 대화형 AI 구현
추론 모델 - 고급 추론 기능
멀티모달 AI - 이미지 및 오디오 처리
구조화된 출력 - JSON 스키마 유효성 검사