README.md

metadata

title: SmartEyeSsen Backend
emoji: 🔍
colorFrom: blue
colorTo: green
sdk: docker
app_port: 7860
pinned: false

SmartEyeSsen Backend

FastAPI · MySQL · DocLayout-YOLO 기반 AI 문서 분석 백엔드

📚 목차

• 프로젝트 개요
• 디렉터리 구조
• 실행 모드
• 환경 변수
• 데이터베이스 & Docker 구성
• FastAPI 모듈 구성
• 테스트 & 스크립트
• 자주 묻는 문제
• 참고 자료

---

🎯 프로젝트 개요

• PDF/이미지 업로드 → DocLayout-YOLO + Tesseract로 레이아웃과 텍스트를 추출하고, OpenAI Vision으로 도표·표 설명을 생성합니다.
• 결과물은 SmartEye 정렬 규칙을 거쳐 프로젝트/페이지/요소 단위로 저장되며, DOCX 다운로드까지 제공됩니다.
• 운영 환경은 DigitalOcean Droplet에서 docker-compose.prod.yml을 통해 MySQL + Backend + Frontend + Certbot 컨테이너로 배포됩니다.

---

🗂 디렉터리 구조

Backend/
├── app/
│   ├── main.py            # FastAPI 엔트리포인트
│   ├── database.py        # 세션/엔진, MySQL 연결
│   ├── models.py          # SQLAlchemy ORM
│   ├── schemas.py         # Pydantic v2 스키마
│   ├── crud.py            # DB 접근 헬퍼
│   ├── routers/           # 프로젝트/페이지/분석/다운로드 라우터
│   └── services/          # OCR·레이아웃·정렬·AI 설명 모듈
├── scripts/
│   ├── init_db_complete.sql   # 12개 테이블 + 초기 데이터
│   └── reset_db.sh (옵션)     # 개발용 초기화 스크립트
├── uploads/, static/          # 업로드/정적 결과 (컨테이너 볼륨 연결)
├── Dockerfile                 # 멀티 스테이지 프로덕션 이미지
├── docker-compose.yml         # 백엔드 단독 MySQL 컨테이너
├── requirements.txt           # Python 의존성
└── README.md                  # 본 문서

---

⚙ 실행 모드

1. 로컬 개발 (venv + Uvicorn)

cd Backend
python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

필요 시 OPENAI_API_KEY를 .env에 설정하면 AI 설명 기능이 활성화됩니다.

2. 백엔드 전용 Docker Compose (MySQL 포함)

Backend/docker-compose.yml은 MySQL 8.0 컨테이너만 띄워 FastAPI를 로컬에서 실행할 때 사용합니다.

cd Backend
docker compose up -d                      # smart_mysql 컨테이너 시작 (기본 포트 3308→3306)
uvicorn app.main:app --reload

종료 또는 초기화:

docker compose down                       # 컨테이너만 종료
docker compose down -v                    # smart_mysql_data 볼륨까지 삭제 (⚠ 전체 데이터 삭제)

3. 프로덕션 Docker Compose (전체 스택)

루트 docker-compose.prod.yml의 backend 서비스는 다음과 같이 구성됩니다.

backend:
  build:
    context: ./Backend
    dockerfile: Dockerfile
  env_file:
    - Backend/.env
  environment:
    DB_HOST: mysql
    DB_PORT: 3306
    ENVIRONMENT: production
  volumes:
    - ./Backend/uploads:/app/uploads
    - ./Backend/static:/app/static
  depends_on:
    mysql:
      condition: service_healthy

배포 시 서버에서:

git checkout main && git pull --ff-only origin main
docker compose -f docker-compose.prod.yml build backend
docker compose -f docker-compose.prod.yml up -d --force-recreate backend

---

🔐 환경 변수

.env.example을 기반으로 .env를 생성합니다.

변수	설명	비고
DB_HOST, DB_PORT	MySQL 접속 정보	Docker 사용 시 mysql/3306으로 자동 override
DB_USER, DB_PASSWORD, DB_NAME	DB 계정	초기 스크립트 기본값: root / change_this_password / smarteyessen_db
DATABASE_URL	SQLAlchemy 접속 URL	변경 불필요 (템플릿 자동 조합)
API_HOST, API_PORT	FastAPI 서버 호스트/포트	기본 0.0.0.0:8000
ENVIRONMENT	development / production	Compose에서 production으로 강제
OPENAI_API_KEY	선택 항목	없으면 AI 설명 비활성화
UPLOAD_DIR, MAX_FILE_SIZE, ALLOWED_EXTENSIONS	업로드 설정	기본 100 MB, jpg/jpeg/png/pdf
SECRET_KEY, ALGORITHM	JWT/보안 옵션	필요 시 업데이트
USE_ADAPTIVE_SORTER, PDF_PROCESSOR_DPI 등	파이프라인 동작 제어	.env.example 참고

---

🐳 데이터베이스 & Docker 구성

Backend/docker-compose.yml (로컬 MySQL)

항목	값
이미지	mysql:8.0
컨테이너 이름	smart_mysql
포트	호스트 ${MYSQL_PORT:-3308} → 3306
볼륨	smart_mysql_data:/var/lib/mysql (Named Volume)
초기화	./scripts/init_db_complete.sql → /docker-entrypoint-initdb.d/01_init.sql
문자셋	utf8mb4 / utf8mb4_unicode_ci
헬스체크	mysqladmin ping (10초 간격, 5회 재시도)

Backend/Dockerfile (프로덕션 이미지)

1. Builder 단계 (python:3.9-slim)
   • Tesseract(ko/en), OpenCV 의존 패키지 설치
   • pip install -r requirements.txt + doclayout-yolo
2. Runtime 단계 (python:3.9-slim)
   • 런타임 패키지 설치 후 Builder에서 site-packages 복사
   • ko_KR.UTF-8 로케일 생성
   • /app/uploads, /app/static, /app/test_pipeline_outputs 생성 및 권한 부여
   • Healthcheck: requests.get('http://localhost:8000/health')
   • CMD: Gunicorn + UvicornWorker (1 worker, timeout 300초)

DB 초기 스키마

• scripts/init_db_complete.sql이 12개 테이블(users, projects, pages, … combined_results)과 시드 데이터(document_types 2건, formatting_rules 25건)를 생성합니다.
• combined_results.combined_text 타입은 LONGTEXT로 4GB까지 저장할 수 있습니다.

---

🧠 FastAPI 모듈 구성

영역	설명
routers/projects.py	프로젝트 CRUD, 분석 트리거
routers/pages.py	페이지 업로드, 텍스트 버전 API
routers/analyze.py	DocLayout-YOLO 실행, Tesseract OCR, AI 설명
routers/download.py	통합 텍스트/WORD 생성
services/layout_service.py	모델 로딩, 레이아웃 후처리
services/ocr_service.py	PDF 분리, 이미지 전처리, Tesseract 호출
services/sorter_service.py	문제지/일반 문서별 정렬 로직
services/ai_description_service.py	OpenAI Vision 호출 및 캐싱

모든 라우터는 app/main.py에서 FastAPI 인스턴스에 등록되며, database.SessionLocal 의존성을 주입해 트랜잭션을 관리합니다.

---

🧪 테스트 & 스크립트

• Pytest: 루트에서 pytest -c Project/pytest.ini 실행 (회귀/통합 시 -m regression 사용)
• start_backend.sh: 의존성 체크 후 Uvicorn 실행 (루트 스크립트)
• scripts/reset_db.sh: 개발 DB 초기화 (데이터 전체 삭제)
• api_server.py: 레거시 단일 스크립트 실행(필요 시만 사용)

---

🚨 자주 묻는 문제

증상	해결 방법
MySQL 컨테이너 헬스체크 실패	docker compose logs mysql 확인, 포트 충돌 시 MYSQL_PORT 변경, docker compose down -v로 재생성
DataError: ... combined_text	scripts/init_db_complete.sql 최신 버전 적용 후 reset_db.sh 실행
Tesseract 언어 미탑재	Dockerfile 이미지는 tesseract-ocr-kor/eng를 포함함. 로컬 수동 설치 시 sudo apt install tesseract-ocr-kor
OpenAI 오류	.env의 OPENAI_API_KEY 확인, 요청 수 제한 시 OPENAI_MAX_CONCURRENCY 값 조정
업로드 파일 미저장	컨테이너 볼륨이 올바르게 마운트되었는지 (./Backend/uploads:/app/uploads) 확인

---

📎 참고 자료

• ../README.md – 전체 시스템 개요 및 배포 전략
• Backend/docs/Backend API 문서/ – 세부 API 스펙