서비스_아키텍처_모듈화_backup - 100-hours-a-week/16-Hot6-wiki GitHub Wiki

상위 문서로 이동 : AI Wiki

서비스 아키텍처 모듈화

모듈화 적용 후 새롭게 설계된 서비스 아키텍처 다이어그램

AI_API_다이어그램 drawio



서비스 아키텍처 다이어그램

flowchart LR
  subgraph Client
    UI[Web/Mobile Client]
  end

  subgraph FastAPI_App
    AGW["API Gateway\n(app/main.py)"]
    subgraph Routers
      V1["/api/v1/..."]
      V2["/api/v2 (stub)"]
    end
    subgraph Services
      D3[DALL·E 3 Service]
      G4[GPT‑4o Service]
      CUST[Custom Inference Service]
      STG[S3 Storage Service]
    end
    subgraph DB
      TASKDB[(Task Repository)]
    end
    subgraph Worker
      BG[BackgroundTasks Worker]
    end

    UI --> AGW
    AGW --> V1
    AGW --> V2

    V1 --> BG
    V1 --> G4

    BG --> D3
    D3 --> STG
    BG --> TASKDB
    BG --> G4
    G4 --> TASKDB

    V2 -.-> CUST
    CUST --> STG

    TASKDB --> AGW
    STG --- UI
  end
Loading

모듈별 책임 및 기능


모듈명 책임(도메인) 주요 기능
API Gateway 진입점 - HTTP 요청 수신
- 인증/인가
- 요청을 각 Router로 라우팅
Routers (/api/v1) v1 엔드포인트 제공 - /generate, /prompt 등 v1 API 정의
- 요청 유효성 검사
Routers (/api/v2) v2 엔드포인트 준비(Stub) - 자체 모델 서빙을 위한 v2 API 스켈레톤
Services:DALL·E3 DALL·E 3 연동 - DALL·E 3 HTTP API 호출로 이미지 생성
Services:GPT‑4o GPT‑4o 연동 - GPT‑4o HTTP API 호출로 프롬프트 생성·후처리
Services:Custom 커스텀 모델 추론 - 자체 모델(추론 서버) 호출
Services:Storage S3 업로드/다운로드 - 입력/생성 이미지 S3 업로드
- Presigned URL 관리
Worker 비동기 처리 - BackgroundTasks 관리
- 추론·업로드·연계 API 호출 트리거
DB (Task Repo) 상태 관리 및 영속화 - SQLAlchemy ORM을 통한 Task 상태 저장/조회/갱신
Schemas 데이터 계약 - Pydantic 모델로 Request/Response 스펙 정의 및 유효성 검증
Core 공통 설정 및 유틸 - 환경변수 로드
- 로깅 설정
- 예외 정의
- IAM 정책 관리

폴더 구조


fastapi_project/                   # 프로젝트 루트
├── app/                           # FastAPI 애플리케이션
│   ├── main.py                    # 진입점: FastAPI() 인스턴스 생성 및 라우터 등록
│   ├── routers/                   # HTTP 엔드포인트 정의
│   │   ├── v1.py                  # v1: image2image 워크플로우 라우터
│   │   └── v2.py                  # v2: 커스텀 모델 서빙용 스텁
│   ├── services/                  # 비즈니스 로직 & 외부 API 통합
│   │   ├── vision2text.py         # GPT‑4o 기반 image→text 변환 함수
│   │   ├── dall_e3.py             # DALL·E 3 기반 text+image→image 생성 함수
│   │   ├── inference.py           # image2text→image2image 전체 Orchestration
│   │   └── storage.py             # S3 업로드/다운로드 및 Presigned URL 관리
│   ├── core/                      # 공통 설정 & 유틸리티
│   │   ├── config.py              # 환경변수 로드, 로깅 설정, IAM 정책
│   │   └── errors.py              # 공통 예외 클래스 정의
│   ├── db/                        # DB 연결 및 ORM 모델 정의
│   │   ├── base.py                # SQLAlchemy Base 선언
│   │   ├── session.py             # DB 세션/트랜잭션 관리
│   │   └── models.py              # Task 등 ORM 모델 클래스
│   ├── crud/                      # 데이터베이스 CRUD 레이어
│   │   └── task.py                # Task 생성/조회/갱신 함수
│   ├── schemas/                   # Pydantic 스키마 정의
│   │   └── task.py                # TaskCreate/TaskStatus 스키마
│   ├── worker/                    # 백그라운드 작업 정의
│   │   └── tasks.py               # BackgroundTasks/Celery 태스크 핸들러
│   └── ml_models/                 # ML 모델 파일 저장소
│       ├── dalle3/                # v1 DALL·E 3 가중치·설정 파일
│       └── custom/                # v2 자체 모델 가중치·설정 파일
├── tests/                         # 테스트 코드
│   ├── unit/                      # 단위 테스트
│   │   ├── test_services.py       # 서비스 로직 테스트
│   │   └── test_crud_task.py      # CRUD 기능 테스트
│   └── integration/               # 통합 테스트
│       └── test_api_v1.py         # /api/v1 end-to-end 테스트
├── .env                           # 환경 변수 파일
├── requirements.txt               # Python 패키지 의존성 목록
├── README.md                      # 프로젝트 개요 및 실행 가이드
└── alembic/                       # DB 마이그레이션 스크립트
    ├── env.py
    ├── script.py.mako
    └── versions/                  # 버전별 migration 파일

모듈 간 인터페이스 설계

1) API 명세

엔드포인트 Method 요청 본문 (Request) 응답 본문 (Response)
POST /api/v1/generate multipart/form-data file: UploadFile TaskStatus (id, status, input_url)
GET /api/v1/generate/{task_id} — — TaskStatus (id, status, input_url, output_url, product_url, error)
POST /api/v1/prompt application/json { "image_url": "string" } { "prompt": "string" }
POST /api/v2/generate (stub) application/json { /* v2 input spec */ } { /* v2 output spec */ }

2) 데이터 포맷

  • TaskStatus

    {
  "id": "uuid",
  "status": "pending | completed | failed",
  "input_url": "https://.../inputs/uuid.png",
  "output_url": "https://.../outputs/uuid.png",    // optional
  "product_url": "https://shopping.naver.com/...", // optional
  "error": "string"                                // optional
}

  • PromptRequest

    { "image_url": "https://.../outputs/uuid.png" }

  • PromptResponse

    { "prompt": "생성된 이미지에 대한 설명 혹은 태그" }

3) 통신 방식

  • 내부 모듈 호출: Python 함수 호출
    • ex) inference.background_generate(task_id)
  • 외부 서비스 호출: HTTP REST API
    • DALL·E 3, GPT‑4o, Naver Shopping API
  • 비동기 작업: FastAPI BackgroundTasks (추후 Celery 교체 가능)
  • DB 영속화: SQLAlchemy Session을 통한 트랜잭션 관리

모듈화 기대 효과 및 장점


  • 단일 책임 원칙(SRP) 적용
    • 모듈별 관심사 분리 → 코드 가독성·유지보수성 향상
  • 독립적 개발·테스트
    • 서비스, 스토리지, DB를 각자 Mock/Stubs로 분리 → 병렬 개발 가능
  • 확장성
    • v2 커스텀 모델 추가 시 services/custom.py + routers/v2.py만 구현 → 타 모듈 재사용
  • 배포 유연성
    • 모듈별 컨테이너화/스케일링 가능 (API 서버, 워커, DB, 스토리지)
  • 장애 격리
    • 한 모듈 장애 시 전체 서비스 영향 최소화
  • 변경 용이성
    • 예: DALL·E 3 → 다른 모델 전환 시 services/dall_e3.py만 수정

모듈화 설계가 서비스 시나리오에 부합함을 보여주는 근거


  1. 모델 교체 시나리오
    • DALL·E 3 API 버전 변경 혹은 중단 발생 → services/dall_e3.py 로직만 수정 후 배포
  2. 기능 확장 시나리오
    • 사용자 요청 시 이미지 태깅 + 감정 분석 추가 → services/gpt4o.py에 새로운 함수 추가 + routers/v1.py 엔드포인트 확장
  3. 성능 확장 시나리오
    • 추론 지연 증가 시 → Worker 컨테이너만 수평 확장, API 서버는 가볍게 유지
  4. 팀 협업 시나리오
    • Frontend 팀: API Gateway·Router 스펙 작업
    • Backend 팀: Service·DB 모듈 구현
    • DevOps 팀: 인프라(컨테이너·네트워크·IAM) 구성
      → 역할 구분 명확, 병목 없는 병렬 작업 가능
⚠️ **GitHub.com Fallback** ⚠️