AI Healthcare Project Template

이 프로젝트는 AI 모델 추론(Inference) 워커와 FastAPI API 서버를 통합한 서비스 템플릿입니다. 현대적인 Python 패키지 관리 도구인 uv와 컨테이너화 도구인 Docker를 활용하여 일관된 개발 및 배포 환경을 제공합니다.

---

🚀 주요 특징

• FastAPI Framework: 고성능 비동기 API 서버 구현.
• AI Worker: 모델 추론 및 학습 작업을 API 서버와 분리하여 처리.
• UV Package Manager: 매우 빠른 의존성 설치 및 가상환경 관리.
• Tortoise ORM: 비동기 방식의 데이터베이스 모델링 및 쿼리 관리.
• Docker-Compose: MySQL, Redis, Nginx를 포함한 전체 서비스 스택을 한 번에 실행.
• CI/CD Scripts: 코드 포맷팅(Ruff), 타입 체크(Mypy), 테스트(Pytest)를 위한 자동화 스크립트 제공.

---

📂 프로젝트 구조

.
├── ai_worker/          # AI 모델 추론 및 학습 관련 코드 (Worker)
│   ├── core/           # 워커 설정 및 로거
│   ├── models/         # AI 모델 파일 보관 (PyTorch 등)
│   ├── tasks/          # 실제 처리할 작업 정의
│   └── main.py         # 워커 진입점
├── app/                # FastAPI 서버 코드
│   ├── apis/           # API 라우터 (v1 버전 관리)
│   ├── core/           # 서버 설정 (pydantic-settings), DB 설정, JWT, Validator 등 핵심 기능
│   ├── dtos/           # 데이터 전송 객체 (Pydantic models)
│   ├── models/         # DB 테이블 정의
│   ├── services/       # 비즈니스 로직
│   └── main.py         # FastAPI 애플리케이션 진입점
├── envs/               # 환경 변수 설정 파일 (.env)
├── infra/              # 인프라 설정 관련 디렉터리
│   ├── docker/         # Docker Compose 설정 (운영용)
│   └── nginx/          # Nginx 설정 파일 (리버스 프록시)
├── scripts/            # 배포 및 CI용 쉘 스크립트
├── docker-compose.yml  # 로컬 개발용 서비스 실행 설정
└── pyproject.toml      # uv 기반 의존성 관리 설정

---

⚙️ 사전 준비 사항

• Python: 3.13 이상 (로컬 개발 환경용)
• UV: Python 패키지 매니저 (설치 가이드)
• Docker & Docker-Compose: 전체 서비스 실행용

---

🛠️ 설치 및 설정

1. 가상환경 구축 및 의존성 설치

uv를 사용하여 프로젝트에 필요한 패키지를 설치합니다.

# 의존성 설치 (가상환경 자동 생성)
uv sync

# 특정 그룹의 의존성만 설치하려는 경우
uv sync --group app  # API 서버용
uv sync --group ai   # AI 워커용

2. 환경 변수 설정

envs/ 디렉토리에 있는 예시 파일을 복사하여 .env 파일을 생성합니다.

• 로컬용

  cp envs/example.local.env envs/.local.env

• 배포용

  cp envs/example.prod.env envs/.prod.env

생성된 env 파일 내의 환경변수들은 프로젝트 상황에 맞게 수정하세요.

---

🏃 실행 방법

1. 로컬 및 개발 환경

Docker Compose로 전체 스택 실행

모든 서비스(API, Worker, DB, Redis, Nginx)를 한 번에 실행합니다.

docker-compose up -d --build

실행 후 다음 주소로 접속 가능합니다:

• API 서버: http://localhost/api/docs (Swagger UI)
• Nginx: 80 포트를 통해 API 서버로 요청을 전달합니다.

로컬에서 개별 실행 (개발용)

FastAPI 서버 실행:

uv run uvicorn app.main:app --reload
# or
docker compose up -d --build app

AI Worker 실행:

uv run python -m ai_worker.main
# or
docker compose up -d --build ai_worker

2. EC2 배포 환경 (Production)

제공된 쉘 스크립트를 사용하여 AWS EC2 환경에 이미지를 빌드, 푸시 및 배포할 수 있습니다.

사전 준비

• EC2 인스턴스 (Ubuntu 권장)
• SSH 키 페어 (~/.ssh/ 경로에 위치)
• 도커 허브(Docker Hub) 계정 및 Personal Access Token
• 배포용 환경 변수 설정 (envs/.prod.env)
• 도메인 구매 (Gabia, GoDaddy, AWS Route53 등)

자동 배포 스크립트 실행

scripts/deployment.sh는 도커 이미지 빌드, 레포지토리 푸시, EC2 접속 및 컨테이너 실행 과정을 자동화합니다.

chmod +x scripts/deployment.sh
./scripts/deployment.sh

스크립트 실행 시 다음 정보를 입력해야 합니다:

1. 도커 허브 계정 정보 (Username, PAT)
2. 이미지를 업로드할 레포지토리 이름
3. 배포할 서비스 선택 (FastAPI, AI-Worker) 및 버전(Tag)
4. SSH 키 파일명 및 EC2 IP 주소
5. https 사용여부
   • 5-1. https인 경우 도메인 추가 입력

SSL(HTTPS) 설정 (Certbot)

도메인을 연결하고 HTTPS를 적용하려면 scripts/certbot.sh를 사용합니다.

chmod +x scripts/certbot.sh
./scripts/certbot.sh

1. 도메인 주소 및 이메일 입력
2. SSH 키 파일명 및 EC2 IP 주소 입력
3. Let's Encrypt를 통한 인증서 발급 및 Nginx 설정 자동 갱신 적용

---

🧪 테스트 및 품질 관리

제공된 스크립트를 사용하여 코드의 품질을 검증할 수 있습니다.

# 테스트 실행
./scripts/ci/run_test.sh

# 코드 포맷팅 확인 (Ruff)
./scripts/ci/code_fommatting.sh

# 정적 타입 검사 (Mypy)
./scripts/ci/check_mypy.sh

---

📝 개발 가이드

• API 추가: app/apis/v1/ 아래에 새로운 라우터 파일을 생성하고 app/apis/v1/__init__.py에 등록하세요.
• DB 모델 추가: app/models/에 Tortoise 모델을 정의하고 app/db/databases.py의 MODELS 리스트에 추가하세요.
• AI 로직 추가: ai_worker/tasks/에 새로운 처리 로직을 작성하고 ai_worker/main.py에서 호출하도록 구성하세요.