전체 아키텍처 개요
본 문서는 프로덕션 환경에서 운영 가능한 AI 에이전트 시스템의 7계층 아키텍처와 각 계층별 소프트웨어 스택을 상세히 정리합니다.
1. 핵심 계층별 소프트웨어 스택
1.1 데이터 지속성 계층 (Data Persistence Layer)
| 구성 요소 | 기술 스택 | 목적 | 주요 설정 |
|---|
| Database | PostgreSQL 16 + pgvector | 관계형 데이터 저장 및 벡터 검색 | pool_size=20, max_overflow=10 |
| ORM | SQLModel 0.0.24 | 타입 안전 데이터베이스 모델링 | Pydantic 통합 |
| Entity Models | SQLAlchemy 2.x | 데이터베이스 스키마 정의 | BaseModel 추상화 |
| DTOs | Pydantic 2.11+ | 입출력 검증 및 직렬화 | Field validators |
| Migration | Alembic | 스키마 버전 관리 | 자동 마이그레이션 |
1.2 보안 계층 (Security Layer)
| 구성 요소 | 기술 스택 | 목적 | 설정 예시 |
|---|
| Rate Limiting | SlowAPI 0.1.9 | API 호출 빈도 제한 | 로그인: 20/min, 채팅: 100/min |
| Input Sanitization | Custom validators | XSS/인젝션 방지 | HTML escape, script 태그 제거 |
| Context Control | LangChain trim_messages | 토큰 윈도우 관리 | MAX_TOKENS=2000 |
| Authentication | python-jose 3.4.0 | JWT 토큰 발급/검증 | HS256, 30일 만료 |
| Password Hashing | bcrypt 4.3.0 | 비밀번호 암호화 | 솔트 자동 생성 |
| Email Validation | email-validator 2.2.0 | 이메일 형식 검증 | RFC 5322 준수 |
1.3 AI 서비스 계층 (AI Service Layer)
| 구성 요소 | 기술 스택 | 목적 | 설정 예시 |
|---|
| Connection Pooling | psycopg2-binary 2.9.10 | 데이터베이스 연결 관리 | QueuePool, pre_ping=True |
| Circuit Breaker | Tenacity 9.1.2 | 장애 격리 및 복구 | 3회 재시도, 지수 백오프 |
| LLM Handling | LangChain 1.0.5 | LLM 추상화 계층 | 모델 체이닝 |
| LLM Provider | langchain-openai 1.0.2 | OpenAI API 통합 | gpt-4o, gpt-4o-mini |
| Retry Logic | Built-in Tenacity | API 호출 재시도 | wait_exponential(2s, 4s, 8s) |
| Model Registry | Custom LLMService | 다중 모델 관리 | Fallback 순환 전환 |
2. 인프라 및 운영 계층
2.1 API 게이트웨이 (API Gateway)
| 구성 요소 | 기술 스택 | 목적 | 버전 |
|---|
| 웹 프레임워크 | FastAPI 0.121.0+ | 비동기 API 서버 | Python 3.13+ |
| ASGI 서버 | Uvicorn 0.34.0 | 고성능 비동기 서버 | uvloop 0.22.1 |
| 프로세스 관리 | Gunicorn | 멀티워커 관리 | workers = CPU cores |
| Auth & Security | HTTPBearer | JWT 토큰 헤더 검증 | Authorization: Bearer |
| Real-Time Streaming | Server-Sent Events | 토큰 스트리밍 | StreamingResponse |
| CORS | FastAPI CORSMiddleware | 크로스 오리진 제어 | 명시적 도메인 화이트리스트 |
| Dependency Injection | FastAPI Depends | 재사용 가능한 종속성 | get_current_user |
2.2 환경 설정 (Environment Config)
| 구성 요소 | 기술 스택 | 목적 | 파일 예시 |
|---|
| 설정 관리 | pydantic-settings 2.8.1 | 타입 안전 설정 | Settings 클래스 |
| 환경 변수 | python-dotenv 1.1.0 | .env 파일 로딩 | .env.development, .env.production |
| 의존성 정의 | pyproject.toml | 패키지 관리 | PEP 621 준수 |
| 시크릿 관리 | Environment Variables | 민감 정보 보호 | JWT_SECRET_KEY, OPENAI_API_KEY |
2.3 데이터 스토리지 (Data Storage)
| 구성 요소 | 기술 스택 | 목적 | 설정 |
|---|
| 주 데이터베이스 | PostgreSQL 16 | 트랜잭션 데이터 | ACID 보장 |
| 벡터 스토어 | pgvector extension | 임베딩 검색 | 코사인 유사도 |
| 체크포인트 | LangGraph AsyncPostgresSaver | 에이전트 상태 저장 | 자동 체크포인팅 |
| 장기 기억 | Mem0 v1.0.0 | 사용자 컨텍스트 저장 | pgvector 백엔드 |
3. 멀티 에이전트 시스템
3.1 에이전트 오케스트레이션
| 구성 요소 | 기술 스택 | 목적 | 주요 기능 |
|---|
| 그래프 엔진 | LangGraph 1.0.5 | 상태 기반 워크플로우 | 노드, 엣지, 상태 관리 |
| 체크포인팅 | langgraph-checkpoint-postgres 3.0.1 | 내구성 실행 | 자동 상태 저장/복구 |
| 장기 기억 | Mem0ai 1.0.0 | 세션 간 기억 | 26% 정확도 향상 |
| Tool 사용 | DuckDuckGo Search | 웹 검색 통합 | duckduckgo-search 3.9.0 |
| 프롬프트 관리 | Markdown 파일 | 코드 분리 프롬프트 | 동적 변수 주입 |
| 도구명 | 라이브러리 | 용도 | 설정 |
|---|
| 웹 검색 | duckduckgo-search 3.9.0 | 실시간 정보 검색 | num_results=10 |
| 커스텀 도구 | LangChain BaseTool | 사용자 정의 기능 | handle_tool_error=True |
4. 평가 및 모니터링
4.1 평가 엔진 (Evaluation Engine)
| 구성 요소 | 기술 스택 | 목적 | 메트릭 |
|---|
| LLM-as-a-Judge | OpenAI gpt-4o | 자동 품질 평가 | Hallucination, Toxicity, Relevancy |
| 구조화된 출력 | Pydantic ScoreSchema | 평가 결과 스키마 | score (0.0-1.0), reasoning |
| 자동 채점 | Custom Evaluator | Langfuse 통합 | trace_id 기반 추적 |
| 메트릭 저장 | Langfuse API | 시계열 분석 | create_score() |
4.2 DevOps & 모니터링
| 구성 요소 | 기술 스택 | 목적 | 포트 |
|---|
| Metrics & Logging | Prometheus 최신 | 시계열 메트릭 수집 | 9090 |
| 시각화 | Grafana 최신 | 대시보드 | 3000 |
| LLM 추적 | Langfuse | 에이전트 관측성 | cloud.langfuse.com |
| 구조화 로깅 | structlog 25.2.0 | JSON 로그 | LOG_LEVEL=INFO |
| 컨테이너 메트릭 | cAdvisor 최신 | 리소스 모니터링 | 8080 |
| 자동화 테스트 | pytest 8.3.5 | 단위/통합 테스트 | markers 지원 |
5. 스트레스 테스팅 및 성능 분석
5.1 부하 테스팅 (Load Testing)
| 구성 요소 | 기술 스택 | 목적 | 설정 |
|---|
| 비동기 클라이언트 | aiohttp | 동시 요청 시뮬레이션 | ClientSession |
| 테스트 시나리오 | Custom scripts | 사용자 플로우 재현 | 로그인→세션→채팅 |
| 인스턴스 | AWS m6i.xlarge | 테스트 환경 | 4 vCPU, 16 GiB RAM |
| 분석 영역 | 도구 | 메트릭 | 목표값 |
|---|
| RPS 측정 | Prometheus | Requests Per Second | 180+ (채팅) |
| 레이턴시 | Grafana | P50, P95, P99 | P99 < 5s |
| 성공률 | Custom logs | Success rate | 98%+ |
| 비용 추적 | Langfuse | Cost per query | $0.0003-0.0005 |
6. 클라이언트 애플리케이션
6.1 프론트엔드 통합
| 구성 요소 | 기술 예시 | 목적 |
|---|
| 웹 클라이언트 | React, Vue, HTMX | SPA/MPA 프론트엔드 |
| 모바일 앱 | React Native, Flutter | 크로스 플랫폼 앱 |
| SSE 클라이언트 | EventSource API | 실시간 스트리밍 수신 |
| WebSocket | Socket.io (선택) | 양방향 통신 |
7. 서버 인프라
7.1 컨테이너화 및 배포
| 구성 요소 | 기술 스택 | 목적 | 파일 |
|---|
| 컨테이너화 | Docker 최신 | 일관된 실행 환경 | Dockerfile |
| 오케스트레이션 | Docker Compose | 다중 서비스 관리 | docker-compose.yml |
| 베이스 이미지 | python:3.13.2-slim | 경량 Python 런타임 | 멀티스테이지 빌드 |
| 리버스 프록시 | Nginx (선택) | SSL 종료, Rate Limiting | upstream 설정 |
7.2 클라우드 배포 (AWS 예시)
| 서비스 | AWS 제품 | 목적 |
|---|
| 컴퓨팅 | EC2, ECS, EKS | 애플리케이션 실행 |
| 데이터베이스 | RDS PostgreSQL | 관리형 DB |
| 로드 밸런서 | ALB | 트래픽 분산 |
| 시크릿 | AWS Secrets Manager | 민감 정보 관리 |
| 모니터링 | CloudWatch | 로그 집계 |
8. CI/CD 파이프라인
8.1 자동화 워크플로우
| 단계 | 도구 | 작업 |
|---|
| 소스 관리 | GitHub | 버전 관리 |
| CI/CD | GitHub Actions | 자동 빌드/배포 |
| 이미지 레지스트리 | Docker Hub | 컨테이너 이미지 저장 |
| 테스트 자동화 | pytest + GitHub Actions | PR별 테스트 실행 |
| 배포 전략 | Blue-Green / Rolling | 무중단 배포 |
9. 전체 기술 스택 요약표
9.1 언어 및 런타임
| 항목 | 기술 | 버전 |
|---|
| 프로그래밍 언어 | Python | 3.13+ |
| 패키지 관리 | pip, uv | 최신 |
| 가상 환경 | venv | 표준 라이브러리 |
9.2 핵심 프레임워크
| 분류 | 프레임워크 | 버전 | 용도 |
|---|
| 웹 | FastAPI | 0.121.0+ | API 서버 |
| 에이전트 | LangGraph | 1.0.5 | 상태 기반 워크플로우 |
| LLM | LangChain | 1.0.5 | LLM 오케스트레이션 |
| 메모리 | Mem0 | 1.0.0 | 장기 기억 |
| ORM | SQLModel | 0.0.24 | 데이터베이스 |
9.3 인프라 및 도구
| 분류 | 도구 | 용도 |
|---|
| 데이터베이스 | PostgreSQL 16 + pgvector | 메인 DB |
| 메트릭 | Prometheus + Grafana | 모니터링 |
| 추적 | Langfuse | LLM 관측성 |
| 컨테이너 | Docker + Docker Compose | 배포 |
| 웹 서버 | Gunicorn + Uvicorn | ASGI 서버 |
| 프록시 | Nginx | 리버스 프록시 |
10. 개발 환경 설정
10.1 로컬 개발
1
2
3
4
5
6
7
8
9
10
11
12
| # 의존성 설치
pip install uv
uv sync
# 개발 서버 실행
make dev
# 테스트 실행
pytest
# 평가 실행
make eval
|
10.2 Docker 환경
1
2
3
4
5
6
7
8
| # 개발 환경
make docker-run-env ENV=development
# 프로덕션 환경
make docker-run-env ENV=production
# 로그 확인
docker-compose logs -f app
|
11. 보안 체크리스트
| 항목 | 도구/방법 | 상태 |
|---|
| 비밀번호 해싱 | bcrypt | ✅ |
| JWT 서명 | 256bit secret | ✅ |
| Rate Limiting | SlowAPI | ✅ |
| Input Sanitization | Custom validators | ✅ |
| CORS 제한 | 명시적 화이트리스트 | ✅ |
| HTTPS 강제 | TLS 1.3 | ✅ |
| 환경 변수 암호화 | .env 파일 제외 | ✅ |
| SQL Injection 방지 | ORM 사용 | ✅ |
12. 성능 벤치마크
12.1 부하 테스트 결과
| 메트릭 | 값 | 조건 |
|---|
| 동시 사용자 | 1,500 | AWS m6i.xlarge |
| 성공률 | 98.4% | 1,476/1,500 |
| 평균 레이턴시 | 1.2s | LLM 워크플로우 |
| P99 레이턴시 | 2.10s | 99번째 백분위 |
| RPS (채팅) | 180 | /api/v1/chatbot/chat |
| RPS (로그인) | 245 | /api/v1/auth/login |
| 쿼리당 비용 | $0.0003-0.0005 | OpenAI API |
12.2 시스템 리소스
| 리소스 | 사용량 | 최대값 |
|---|
| CPU | 60-80% | 4 vCPU |
| 메모리 | 8-12 GiB | 16 GiB |
| DB 연결 | 15-25 | pool_size=20 |
| 네트워크 | 50-100 Mbps | 1 Gbps |
13. 비용 구조 (월간 추정)
13.1 인프라 비용
| 항목 | 서비스 | 예상 비용 |
|---|
| 컴퓨팅 | AWS m6i.xlarge (24/7) | $140 |
| 데이터베이스 | RDS db.t3.medium | $60 |
| 스토리지 | EBS 100GB | $10 |
| 네트워크 | 데이터 전송 | $20 |
| 합계 | - | $230 |
13.2 LLM API 비용
| 모델 | 쿼리당 비용 | 월 10만 쿼리 |
|---|
| gpt-4o | $0.0005 | $50 |
| gpt-4o-mini | $0.0002 | $20 |
| 평균 (Fallback 포함) | $0.0004 | $40 |
13.3 관측성 도구
| 도구 | 플랜 | 비용 |
|---|
| Langfuse | 클라우드 (80K 이벤트) | $80 |
| Grafana Cloud | Free tier | $0 |
| 합계 | - | $80 |
총 월간 운영 비용 (10만 쿼리 기준): ~$350
14. 확장성 로드맵
14.1 단기 (1-3개월)
- Redis 캐싱 레이어 추가
- 멀티 리전 배포
- 자동 스케일링 설정 (HPA)
- 비동기 작업 큐 (Celery)
14.2 중기 (3-6개월)
- Kubernetes 마이그레이션
- 마이크로서비스 분리
- GraphQL API 추가
- WebSocket 양방향 통신
14.3 장기 (6-12개월)
- 멀티 에이전트 협업 시스템
- 분산 추적 (OpenTelemetry)
- 엣지 컴퓨팅 통합
- AI 모델 자체 호스팅
15. 참고 자료
15.1 공식 문서
15.2 관련 프로젝트
문서 버전: 1.0
최종 업데이트: 2026-01-02
작성자: AI 시스템 아키텍처 팀