Document Mini Project Backend

PDF, HWP/HWPX, DOCX, PPT/PPTX 문서를 업로드하면 텍스트를 추출하고, 벡터 DB를 구성한 뒤 로컬 LLM으로 요약과 카테고리 분류를 수행하는 FastAPI 백엔드입니다.

주요 기능

• PDF, HWP/HWPX, DOCX, PPT/PPTX 업로드
• 문서 형식별 텍스트 추출 및 OCR 폴백
• Sentence Transformer 기반 청킹 및 임베딩
• Chroma 기반 문서별 벡터 저장소 생성
• Ollama 기반 문서 요약 및 대분류·소분류
• PostgreSQL 문서·카테고리·처리 이력 저장
• 작업 ID를 이용한 비동기 처리 상태 조회

처리 흐름

문서 업로드
  -> 형식 및 확장자 검증
  -> 문서별 텍스트/OCR 추출
  -> 청킹 및 Chroma 저장
  -> Ollama 요약·카테고리 분류
  -> PostgreSQL 저장
  -> 처리 결과 반환

기술 스택

• Python 3.10+
• FastAPI, Uvicorn, Pydantic
• PostgreSQL, SQLAlchemy
• PaddleOCR, PyMuPDF, pdfplumber
• Sentence Transformers, Chroma
• Ollama

실행 준비

PostgreSQL과 Ollama가 먼저 실행되어 있어야 합니다. HWP 변환 기능은 실행 환경에 따라 LibreOffice 또는 별도 변환 도구가 필요할 수 있습니다.

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

cp .env.example .env

.env에서 데이터베이스 비밀번호와 사용할 모델을 현재 환경에 맞게 변경합니다.

DATABASE_URL=postgresql+psycopg2://postgres:YOUR_PASSWORD@localhost:5432/rag_db
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=qwen3:8b
EMBEDDING_MODEL_NAME=BAAI/bge-m3

Ollama 모델을 준비합니다.

ollama pull qwen3:8b
ollama serve

서버 실행

uvicorn main:app --reload --port 8000

• API 문서: http://localhost:8000/docs
• 상태 확인: http://localhost:8000/health

API

Method	Endpoint	설명
GET	/health	서버 상태 확인
POST	/api/process/start	문서 업로드 및 처리 시작
GET	/api/process/{job_id}	진행 상태와 처리 결과 조회

프로젝트 구조

.
├── main.py                 # FastAPI 진입점과 작업 상태 관리
├── document_pipeline.py    # 문서 형식별 추출 오케스트레이션
├── rag_pipeline.py         # 청킹·임베딩·Chroma 저장
├── llm_chain.py            # Ollama 요약·분류
├── database.py             # PostgreSQL 연결
├── models.py               # SQLAlchemy 모델
├── app/                    # 설정·스키마·서비스
├── extractors/             # 문서 형식별 추출기
└── utils/                  # 공통 유틸리티

주의사항

• .env는 저장소에 커밋하지 않습니다.
• 업로드 원본, OCR 결과, Chroma 데이터는 실행 중 생성되며 Git에서 제외됩니다.
• 현재 작업 상태는 메모리에 저장되므로 서버를 재시작하면 초기화됩니다.