https://github.com/urstory/urstory-rag

에 다음과 같은 기능이 추가되거나 변경되었습니다. RAG에 관심있는 분의 참여 부탁드려요.

UrstoryRAG 개발 이력 요약

12개 이슈 처리 및 IBM Docling PDF 파싱 도입까지의 개발 과정을 정리한다.

---

처리된 이슈 (12건)

Phase 12: 보안 강화 — 이슈 #1, #2, #3, #4

커밋: ce9e541, PR #22로 머지

---

Phase 13: 프로덕션 운영 기반 — 이슈 #5, #6, #8, #9

커밋: fcfd6a3, PR #23으로 머지

---

Langfuse v3 모니터링 — 이슈 #7

커밋: 0253eca

---

Phase 14: Redis 응답 캐싱 레이어 — 이슈 #10

커밋: 76993c4, PR #24로 머지

---

Circuit Breaker — 이슈 #12

커밋: 0500185, PR #25로 머지

---

공개 테스트 데이터셋 — 이슈 #21

커밋: c191907

---

Phase 15: IBM Docling PDF 레이아웃 인식 파싱

도입 배경

기존 pypdf는 PDF에서 텍스트만 추출하여 다음 문제가 있었다:

• 테이블 구조 붕괴 (숫자가 뒤섞여 검색 불가)
• 헤더 감지가 줄 길이 휴리스틱에 의존 (오탐/미탐)
• 다단 컬럼이 하나의 텍스트 스트림으로 병합
• 스캔 PDF 미지원

Open-Parse (GitHub 3.2K stars)를 검토했으나 16개월간 업데이트 없이 방치 상태. IBM Docling (55K stars, MIT, 주간 릴리즈)을 선택했다.

Docling이 해결하는 것

아키텍처

복사
[ Before ] PDF → PyPDFToDocument (텍스트) → SectionHeaderChunking (휴리스틱 헤더)
[ After  ] PDF → Docling (마크다운)        → SectionHeaderChunking (정확한 # 헤더)

기존 청킹 파이프라인(SectionHeaderChunking, ContextualChunking)은 수정 없이 재사용한다. Docling의 마크다운 출력에 # 헤더가 포함되므로 오히려 더 정확한 breadcrumb 계층이 생성된다.

핵심 구현

DoclingPDFConverter (backend/app/services/document/docling_converter.py)

• Docling DocumentConverter를 래핑
• 지연 초기화: _get_converter() 호출 시에만 import (앱 시작 속도 보존)
• 자동 폴백: Docling 실패 시 pypdf로 전환, 서비스 중단 없음
• 메타데이터에 converter: "docling" | "pypdf_fallback" 기록

설정 제어 (RAGSettings)

복사
pdf_parser: str = "docling"         # docling | pypdf
ocr_enabled: bool = False
ocr_languages: list[str] = ["ko", "en"]
table_extraction_enabled: bool = True

관리자 UI에서 실시간 변경 가능. GPU가 없는 서버에서는 pdf_parser=pypdf로 전환하면 된다.

GPU/CPU 호환성

Docling은 GPU 없이도 동작한다. PyTorch가 하드웨어를 자동 감지한다.

macOS 주의사항: Celery의 기본 fork 기반 워커는 Metal/MPS와 호환되지 않는다 (SIGABRT 발생). --pool=solo 옵션으로 실행해야 MPS GPU를 사용할 수 있다.

복사
celery -A app.worker:celery_app worker --pool=solo --loglevel=info

Docling 모델 (첫 실행 시 자동 다운로드)

총 ~450MB, ~/.cache/docling/models/에 캐시된다.

성능

변환 속도가 느려지지만 Celery 비동기 처리이므로 사용자 대기에 영향 없다.

품질 측정 결과

공개 데이터셋 68개 Q&A, 12개 문서 기준:

PDF 테이블이 포함된 문서에서 숫자/통계 검색 정확도가 크게 개선되었다.

TDD 구현 순서

복사
Step 0: docling >= 2.78 의존성 추가 + 환경 검증
Step 1: RAGSettings에 pdf_parser, ocr_enabled 등 설정 추가 (RED → GREEN)
Step 2: DoclingPDFConverter 구현 + pypdf 폴백 (RED → GREEN)
Step 3: DocumentConverter에 Docling 통합 (RED → GREEN)
Step 4: Processor/Task에서 RAGSettings → DocumentConverter 설정 전달 (RED → GREEN)
Step 5: 실제 PDF 통합 테스트 + 품질 검증
Step 6: 전체 테스트 회귀 확인 (517 단위 + 8 통합 테스트 통과)

테스트

• 단위 테스트: 11개 (DoclingPDFConverter) + 8개 (DocumentConverter 통합) + RAGSettings + Processor
• 통합 테스트: 8개 (실제 PDF 변환, 폴백, 설정 토글, 청킹 파이프라인)
• 품질 테스트: 68개 Q&A LLM-as-Judge 자동 평가

---

전체 시스템 계층

12개 이슈 처리 후의 시스템 아키텍처:

복사
사용자 → 프론트엔드 (Next.js 15)
  ↓
보안 헤더 미들웨어 (X-Content-Type-Options, X-Frame-Options, CSP)
  ↓
Rate Limiter (slowapi + Redis, 엔드포인트별 제한)
  ↓
JWT 인증 (access/refresh, RBAC)
  ↓
구조화된 로깅 (structlog, request_id 추적)
  ↓
Redis 응답 캐시 (SHA-256 키, 자동 무효화)
  ↓
Circuit Breaker (연속 실패 감지, 자동 차단/복구)
  ↓
문서 변환 (Docling PDF → 마크다운, pypdf 폴백)
  ↓
RAG 파이프라인 (Haystack, 하이브리드 검색, 리랭킹, HyDE)
  ↓
데이터베이스 (PostgreSQL+PGVector, Elasticsearch+Nori, Redis)
  ↓
모니터링 (Langfuse v3, Sentry)

---

남은 오픈 이슈