OpenPaper 📄

논문 리딩 보조 시스템 — AI 기반 PDF 번역 + 표/그림/수식 해설

논문 PDF를 업로드하면 Docling AI가 문서 구조를 정밀 파싱하고, Gemini/OpenAI를 통해 번역과 시각적 요소(표·그림·수식) 해설을 제공합니다.

---

기술 스택

구분	기술
Backend	Python 3.10+, FastAPI, SQLAlchemy (async), PostgreSQL
Frontend	React 18, Vite, pdfjs-dist
AI 파싱	Docling (Heron AI 레이아웃 모델)
LLM	Google Gemini / OpenAI GPT
스토리지	AWS S3 / MinIO (S3 호환)
패키지 관리	uv (권장) / pip

---

빠른 시작 (Quick Start)

1. 저장소 클론

git clone https://github.com/<your-username>/openpaper.git
cd openpaper

2. 백엔드 의존성 설치

uv 를 사용하면 가상환경 생성 + 의존성 설치를 한 번에 처리할 수 있습니다.

# uv가 없다면 먼저 설치 (한 줄)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 가상환경 생성 + 의존성 동기화 (한 번에 완료!)
uv sync

# 개발 도구(ruff, pytest 등)까지 포함하려면:
uv sync --extra dev

pip을 사용하는 경우:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

3. 프론트엔드 의존성 설치

cd frontend
npm install
cd ..

4. 환경 변수 설정

cp .env.example .env

.env 파일을 열고 아래 필수 항목들을 실제 값으로 채워 넣습니다:

변수	설명	필수
OPENPAPER_DATABASE_URL	PostgreSQL 연결 URL	✅
OPENPAPER_S3_ACCESS_KEY	AWS/MinIO 액세스 키	✅
OPENPAPER_S3_SECRET_KEY	AWS/MinIO 시크릿 키	✅
OPENPAPER_GEMINI_API_KEY	Google AI Studio에서 발급	✅
OPENPAPER_S3_ENDPOINT_URL	MinIO 등 커스텀 엔드포인트 (AWS S3 기본이면 비워두기)	선택
OPENPAPER_PARSER_BACKEND	docling (AI 파서, 권장) 또는 pymupdf	선택
OPENPAPER_TRANSLATOR_BACKEND	huggingface (로컬 NLLB) 또는 llm (Gemini/OpenAI)	선택

5. 데이터베이스 준비

# PostgreSQL이 실행 중이어야 합니다.
# DB 생성 (이미 있다면 생략)
createdb openpaper

# 테이블 자동 생성 모드로 서버 시작 (처음 한 번만)
OPENPAPER_DEV_CREATE_TABLES=true uv run uvicorn app.main:app --reload

이후에는 OPENPAPER_DEV_CREATE_TABLES=false (기본값)로 두고, 스키마 변경 시 alembic upgrade head를 사용합니다.

6. 프론트엔드 빌드

cd frontend
npm run build
cd ..

7. 서버 실행

uv run uvicorn app.main:app --reload

브라우저에서 http://localhost:8000 으로 접속합니다.

---

프로젝트 구조

openpaper/
├── app/                          # 백엔드 (FastAPI)
│   ├── adapters/                 # 외부 서비스 어댑터 (Docling, Gemini, S3 등)
│   ├── api/                      # API 라우트 (command, query 분리)
│   ├── core/services/            # 비즈니스 로직
│   ├── db/                       # DB 세션 및 base 모델
│   ├── models/                   # SQLAlchemy ORM 모델
│   ├── ports/                    # 추상 포트 인터페이스 (헥사고날)
│   ├── schemas/                  # Pydantic 응답 스키마
│   ├── workers/                  # 비동기 Job 처리 워커
│   ├── config.py                 # 환경 변수 설정 (pydantic-settings)
│   └── main.py                   # FastAPI 엔트리포인트
├── frontend/                     # 프론트엔드 (React + Vite)
│   └── src/
│       ├── components/           # React 컴포넌트
│       ├── styles/               # CSS
│       └── api.js                # 백엔드 API 래퍼
├── tests/                        # 테스트
├── alembic/                      # DB 마이그레이션
├── pyproject.toml                # Python 의존성 정의
├── .env.example                  # 환경 변수 템플릿
└── README.md

---

주요 기능

📖 듀얼 패널 뷰어

좌측에 PDF 원문, 우측에 번역본을 나란히 표시합니다. 더블클릭으로 원문↔번역 간 위치를 동기화할 수 있습니다.

🌐 AI 번역

Gemini/OpenAI 또는 HuggingFace NLLB 로컬 모델로 논문을 번역합니다.

💡 AI 해설 (표/그림/수식)

PDF 위에 표시되는 색상별 오버레이(표=파랑, 그림=초록, 수식=주황)를 클릭하면 AI가 해당 요소를 분석하여 한국어로 상세 해설을 제공합니다.

---

📸 스크린샷 및 아키텍처

시스템 아키텍처 및 작업 흐름

1️⃣ 전체 시스템 아키텍처

FastAPI 기반의 모놀리식 백엔드, 비동기 큐(ARQ), 외부 AI 파서 및 LLM을 활용한 파이프라인 구성도입니다.

2️⃣ 비동기 작업(Job) 상태 전이도

대형 문서를 처리할 때 큐잉부터 결과 반환(RUNNING → DONE/FAILED)까지의 상태 변화를 나타냅니다.

실제 구동 화면

1️⃣ AI 해설 (시각적 요소 분석)

PDF에서 논문의 복잡한 그림이나 표를 클릭하면 우측 탭에서 AI가 문맥에 맞춰 한국어로 설명해줍니다.

2️⃣ 듀얼 패널 기반 AI 번역

원문과 번역본이 1:1로 매칭되며, 마우스 더블클릭으로 양쪽 스크롤 위치가 동기화됩니다.

---

개발 명령어 모음

# 서버 실행 (핫 리로드)
uv run uvicorn app.main:app --reload

# 프론트엔드 개발 서버
cd frontend && npm run dev

# 린트
uv run ruff check app/

# 테스트
uv run pytest tests/ -v

# DB 마이그레이션
uv run alembic upgrade head

---

환경 요구사항

• Python: 3.10 이상
• Node.js: 18 이상
• PostgreSQL: 14 이상
• GPU (선택): Docling AI 파서 사용 시 CUDA 지원 GPU 권장 (VRAM 6GB+)

---

라이선스

MIT License