AI 개발 가이드: 제10회 (추가 ②) 프로덕션 배포: FastAPI / Docker / 클라우드를 이용한 마이크로서비스화

【

신 연재: MCP・고도 RAG・자율 에이전트 현장 설계론】

.

총 10회에 걸쳐 전해 온 본 연재 『차세대 AI 개발: MCP・고도 RAG・자율 에이전트 현장 설계론』 역시, 본 기사에서 드디어 **감동적인 그랜드 피날레(최종회)**를 맞이합니다.

지금까지의 회차를 통해 우리는 MCP를 이용한 툴 연결, Context Engineering을 통한 문맥 최적화, Agentic RAG / GraphRAG, Self-Healing Agent, 로컬 SLM, 그리고 NeMo Guardrails를 통한 보안 방어에 이르기까지, AI 개발에 필요한 거의 모든 요소 기술을 마스터했습니다.

하지만 이러한 코드들을 로컬의 Python 스크립트(python script.py)로 실행하는 단계만으로는 아직 '실무 프로덕션에서 구동되는 시스템'이라고 할 수 없습니다.

최종회인 제10회에서는, 지금까지 구축해 온 AI 에이전트・MCP 시스템을 비동기 웹 프레임워크 FastAPI로 REST API화하고, 경량의 멀티 스테이지 Docker 컨테이너로 패키징하여, 클라우드 환경(Azure Container Apps, AWS, GCP 등)에 안전하게 배포하는 '마이크로서비스화'의 전 과정을 완벽히 설명합니다.

Python 버전: Python 3.10 이상 -
작동 확인된 주요 라이브러리:

fastapi>=0.110.0

(비동기 웹 프레임워크) -
uvicorn>=0.28.0

(ASGI 서버) -
pydantic>=2.7.0

(데이터 유효성 검사)

컨테이너 환경: Docker Engine 또는 Docker Desktop

단순한 스크립트 실행에서 웹 API + 컨테이너를 통한 '마이크로서비스(Microservice)'로 승화시킴으로써, AI 시스템은 비로소 엔터프라이즈 운영에 견딜 수 있는 견고함을 얻게 됩니다.

FastAPI를 채택함으로써, 웹 프런트엔드나 스마트폰 앱이 호출하는 'REST API 엔드포인트(POST /api/v1/agent)'와, 다른 AI 에이전트가 툴로 호출하는 'MCP 엔드포인트(/mcp`)'를 단일 코드베이스・단일 데이터베이스 연결로 공유 및 통합 제공할 수 있습니다.

AI 에이전트의 추론이나 RAG의 벡터 검색은 일반적인 웹 요청에 비해 CPU/메모리 부하와 처리 시간이 큽니다. 컨테이너화하여 스테이트리스(무상태)로 설계함으로써, 접근 급증 시 클라우드 측에서 컨테이너 인스턴스를 자동으로 수 배로 수평 스케일 아웃할 수 있습니다.

Docker를 사용함으로써 Python의 버전 차이, C++ 확장 라이브러리, 의존 패키지의 불일치를 완벽하게 캡슐화할 수 있습니다. 또한, 비Root 사용자 권한으로 컨테이너를 실행함으로써, 만에 하나 에이전트 내에서 부정 코드가 구동되더라도 호스트 OS를 보호하는 강력한 격리막 역할을 합니다.

본 기사에서 구축하는 상용 AI 마이크로서비스의 전체 아키텍처는 다음 구성을 취합니다.

FastAPI 웹 애플리케이션:
uvicorn ASGI 서버 위에서 async/await 비동기 구동으로 높은 병렬 접근을 처리합니다.

Multi-stage Build Dockerfile:
빌드용의 무거운 컴파일러 레이어와 실행용의 최소한 라이브러리 레이어를 분리하여 컨테이너 크기를 경량화(150MB~300MB 정도).

Health Check Endpoint (/health)

)- 클라우드 측의 로드 밸런서(ALB / Container Apps)는 컨테이너의 생존 여부를 초당 모니터링하기 위한 경량 엔드포인트를 제공합니다.

그럼, 실제로 AI 에이전트를 호출하는 FastAPI 웹 애플리케이션 main.py와 프로덕션용 Dockerfile을 구축해 봅시다.

새 파일 main.py를 생성하고 다음 전체 코드를 작성합니다.

# 동작 확인 완료된 라이브러리 버전: fastapi>=0.110.0, uvicorn>=0.28.0, pydantic>=2.7.0
import os
import sys
...

같은 디렉터리에 Dockerfile이라는 이름으로 다음 내용을 저장합니다.

# =====================================================================
# Stage 1: 빌드 환경 (Dependencies Builder)
# =====================================================================
...

같은 디렉터리에 requirements.txt를 생성합니다.

fastapi>=0.110.0
uvicorn>=0.28.0
pydantic>=2.7.0
...

구현한 main.py와 Dockerfile의 핵심 포인트를 설명합니다.

• POST /api/v1/agent/run 엔드포인트를 정의하는 것만으로도 FastAPI가 자동으로 /docs(Swagger UI) 및 /redoc에 대화형 웹 API 문서를 자동 생성합니다. -
  AgentRequest 타입 덕분에 클라이언트로부터 도착한 JSON 데이터의 타입 체크가 전자동화되며, 부적절한 요청은 즉시 400 Bad Request로 거부됩니다.

• **Stage 1 (builder)**에서 컴파일용 gcc나 헤더 파일을 설치하여 Python 패키지를 빌드하고, **Stage 2 (runner)**에는 완성된 라이브러리(/root/.local)만 복사했습니다. - 이를 통해 불필요한 빌드 도구를 포함하지 않은 매우 가볍고 공격 표면(Attack Surface)이 적은 안전한 프로덕션 컨테이너 이미지가 완성됩니다.

• 기본 Docker 컨테이너는 root 권한으로 실행되기 때문에, 만약 에이전트 내에서 RCE(Remote Code Execution) 공격을 받으면 컨테이너 탈옥(Container Escape)의 위험이 발생합니다. - 일반 사용자 appuser를 생성하여 USER appuser로 실행함으로써 최소 권한의 원칙(Least Privilege)을 철저히 지켰습니다.

구축한 Docker 이미지를 실제 퍼블릭 클라우드 환경(예: Azure Container Apps)에 배포하는 절차와, 연재 전체의 총괄 내용을 다룹니다.

# 1. Docker 이미지 빌드 및 레지스트리 푸시
az acr build --registry myregistry --image ai-agent-microservice:v1 .
# 2. Azure Container Apps에 무제한 스케일 설정으로 배포
...

이렇게 배포함으로써, 요청 수에 따라 자동으로 1~10대의 컨테이너로 자동 수평 확장(Horizontal Scaling)되며, API 키는 Key Vault / SecretRef를 통해 안전하게 숨겨 관리됩니다.

총 10회에 걸친 신연재 『차세대 AI 개발: MCP・고도 RAG・자율 에이전트의 현장 설계론』을 애독해 주셔서 대단히 감사드립니다!

마지막으로, 본 연재에서 마스터한 '차세대 AI 개발의 풀스택 로드맵'을 되돌아봅니다.

단순한 프롬프트의 시행착오(Prompt Engineering)라는 태동기 AI 활용 단계를 벗어나, 프로토콜(MCP), 컨텍스트(Context Engineering), 지식 그래프(GraphRAG), 폐쇄 루프 자동 복구(Self-Healing), 안전성(Guardrails), 그리고 클라우드 인프라(Docker/FastAPI)라는 '진정한 소프트웨어 엔지니어링'으로 AI 시스템을 바라보는 시각을 갖추게 되었을 것입니다.

본 연재에서 설명한 코드와 아키텍처 설계론이 독자 여러분의 향후 AI 프로덕트 개발 및 실무 프로젝트에 흔들림 없는 강력한 무기가 되기를 진심으로 기원합니다.

전체 10회 동안 애독해 주셔서 정말 감사드립니다!