DataProc 주간 릴리즈 노트

문서인식 UX 개선 및 이미지 추출 기능 - 2025년 11월 2일 ~ 11월 8일

주요 개발 내용 요약

DataProc 프로젝트는 문서인식(Document Recognition) 기능의 사용자 경험 개선 및 이미지 추출 기능 강화에 집중하였습니다. 11월 2일부터 11월 8일까지 총 10개의 커밋이 진행되었으며, 2개의 주요 PR이 병합되어 페이지별 이미지 추출 기능, 문서인식 화면 레이아웃 최적화, 문서 레이아웃 분석 가이드 문서화가 완성되었습니다.

새로운 기능 (New Features)

1. 페이지별 이미지 추출 기능 (#59, #58)

• 구현 완료: 문서인식 페이지에서 PDF 페이지별 이미지 추출 및 표시
• Backend 구현:
  • PageExtractionRequest API 모델에 “image” 형식 추가
  • extract_images_from_page() 메서드 구현 (PyMuPDF 사용)
  • Base64 인코딩 방식 도입으로 인증 문제 해결
  • 50x50px 미만 작은 이미지 자동 필터링
  • 임시 디렉토리 백업 저장: temp_images/{file_id}/
  • GET /files/{file_id}/images/{image_filename} 엔드포인트 추가 (인증 포함)
• Frontend 구현:
  • 추출 형식에 ‘Image’ 라디오 버튼 추가
  • extractedImages 상태 변수 및 hasExtractedImage 상태 추가
  • 반응형 이미지 그리드 UI (2-3열 레이아웃)
  • 각 이미지의 메타데이터 표시 (크기, 형식, 용량)
  • 이미지 없는 페이지 안내 메시지 및 아이콘 표시
• 성능 최적화:
  • useMemo로 PDF URL 메모이제이션
  • useCallback으로 콜백 함수 최적화
  • PdfViewer 불필요한 리렌더링 방지
• 기술적 고려사항:
  • Base64 Data URL 방식 선택: <img> 태그의 HTTP 헤더 제약으로 인증 토큰 전달 불가 문제 해결
  • 디스크 백업 저장으로 감사 및 디버깅 지원
  • Lazy loading 지원
• 이미지 응답 형식:

  [
    {
      "filename": "page_3_img_0_4de12abc.png",
      "data_url": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAA...",
      "width": 1520,
      "height": 2233,
      "format": "png",
      "size_bytes": 118400
    }
  ]
  

• 주요 커밋: 524cd11, a354a31, 37251ed

주요 개선사항 (Improvements)

1. 문서인식 화면 레이아웃 최적화 (#57, #56)

• 문제: 파일 업로드/목록 영역이 과도하게 넓고, 페이지 추출 결과 영역이 상대적으로 좁아 사용성 저하
• 해결책: 화면 비율 재조정으로 사용자 경험 개선
  • 파일 업로드/목록 영역: 33% → 17% (col-span-2/12)
  • 페이지 추출 결과 영역: 33% → 50% (col-span-6/12)
  • PDF 뷰어 영역: 33% 유지 (col-span-4/12)
• 추가 개선:
  • 파일명 툴팁 기능 추가: 파일명이 잘려도 마우스 오버 시 전체 파일명 확인 가능
  • Tailwind CSS grid 시스템 grid-cols-3 → grid-cols-12로 세밀한 비율 조정
  • title 속성을 클릭 가능한 부모 div로 이동하여 접근성 향상
• 효과:
  • 페이지 추출 결과 영역이 화면의 절반(50%)을 차지하여 문서 내용 가독성 대폭 향상
  • 파일 관리 영역을 최소화(17%)하여 공간 효율성 극대화
  • 사용자가 가장 중요하게 확인해야 하는 추출 결과에 집중 가능
• 주요 커밋: c625306, 4c03dbe, d729070

2. 문서 레이아웃 분석 가이드 문서화

• 구현 완료: 종합적인 문서 레이아웃 분석 방법론 가이드 작성
• 주요 내용:
  • 문서 레이아웃 분석 방법론 상세 설명
  • Docling 레이아웃 시각화 가이드 및 실전 예제
  • 테이블 추출, OCR 통합 기법 포함
  • 실용적인 예제 코드 및 Best Practice
• 효과:
  • 개발자 온보딩 시간 단축
  • Docling 활용 표준화
  • 문서 처리 품질 향상
• 주요 커밋: 68147a4

3. UI/UX 및 상태 관리 개선

• 이미지 추출 조건부 렌더링 개선:
  • hasExtractedImage 상태로 추출 완료 추적
  • 중첩 삼항 연산자 로직 명확화
  • 이미지 없는 페이지 시각적 피드백 (아이콘 + 메시지)
  • TypeError 방지 (이미지 없는 페이지 처리)
• Base64 Data URL 방식 도입:
  • URL 기반 → Base64 Data URL 방식 전환
  • <img> 태그 인증 이슈 해결
  • 별도 이미지 로딩 로직 불필요
• PdfViewer 리렌더링 오류 수정:
  • useMemo 및 useCallback 최적화 적용
  • 불필요한 재생성 방지
  • PDF 로드 핸들러 최적화

버그 수정 (Bug Fixes)

1. 이미지 미표시 문제 해결

• 문제: 이미지 추출 후 화면에 표시되지 않음 (인증 토큰 이슈)
• 해결: Base64 data URL 방식으로 전환하여 <img> 태그의 HTTP 헤더 제약 우회
• 주요 커밋: 37251ed

2. PdfViewer 리렌더링 오류 수정

• 문제: PDF 전환 시 ArrayBuffer detached 오류 및 불필요한 리렌더링
• 해결: React 메모이제이션 패턴 적용 (useMemo, useCallback)
• 주요 커밋: 37251ed

3. 이미지 없는 페이지 TypeError 수정

• 문제: 이미지 없는 페이지 추출 시 조건부 렌더링 오류
• 해결: hasExtractedImage 상태 추가 및 명확한 상태 관리
• 주요 커밋: a354a31

성과 지표 (Metrics)

• 총 커밋 수: 10개 커밋 (11/2 ~ 11/9)
• 병합된 PR: 2개 주요 풀 리퀘스트 (#59, #57)
• 새로운 기능: 1개 주요 기능 (페이지별 이미지 추출)
• 주요 개선사항: 3개 시스템 최적화 (레이아웃 최적화, 문서화, UI/UX 개선)
• 버그 수정: 3개 주요 버그 수정
• 문서화: 1개 주요 문서 작성 (문서 레이아웃 분석 가이드)

주요 PR 목록

• #59: 페이지 추출 기능에 이미지 형식 추가
• #57: 문서인식 화면 레이아웃 개선: 파일 업로드 영역과 페이지 추출 영역 비율 조정

핵심 개선 영역

• 문서인식 강화: 페이지별 이미지 추출, Base64 인코딩, 메타데이터 표시
• 사용자 경험: 레이아웃 최적화 (50% 추출 영역), 툴팁, 시각적 피드백
• 성능 최적화: React 메모이제이션, 불필요한 리렌더링 방지, Lazy loading
• 문서화: 문서 레이아웃 분석 방법론 및 Docling 활용 가이드

수정 파일 통계

• Backend: 2개 파일 (document_recognition.py, document_processing_service.py)
• Frontend: 1개 파일 (workspace/page.tsx)
• Docs: 1개 문서 (문서 레이아웃 분석 가이드)

향후 계획 (Future Plans)

1. 이미지 추출 기능 고도화

• 이미지 다운로드 기능 (개별 및 일괄)
• 이미지 확대 보기 모달 (Lightbox)
• 이미지 선택 및 일괄 관리
• 이미지 캐싱 전략 구현

2. 문서인식 성능 최적화

• 대용량 PDF 처리 성능 개선
• 이미지 추출 병렬 처리
• Progressive loading 구현
• 메모리 사용량 최적화

3. 멀티모달 검색 통합

• 추출된 이미지를 RAG 시스템에 통합
• 이미지 기반 검색 및 유사도 비교
• Vision Search와 Docling 통합

4. 문서 처리 확장

• 다양한 문서 형식 지원 확대 (DOCX, PPTX, XLSX)
• 테이블 추출 고도화
• OCR 정확도 향상
• 레이아웃 분석 자동화

5. 사용자 경험 개선

• 실시간 추출 진행 상황 표시
• 이미지 미리보기 썸네일
• 드래그 앤 드롭 업로드
• 키보드 단축키 지원

결론

DataProc 프로젝트는 이번 주 문서인식 기능의 UX 개선 및 이미지 추출 기능 강화를 통해 사용자 경험을 크게 향상시켰습니다. 페이지별 이미지 추출 기능은 Base64 인코딩 방식을 통해 인증 문제를 해결하고, 반응형 그리드 UI로 직관적인 이미지 확인을 제공합니다. 문서인식 화면 레이아웃 최적화는 페이지 추출 결과 영역을 50%로 확대하여 문서 내용 가독성을 대폭 향상시켰습니다.

특히 React 메모이제이션 패턴 적용으로 PdfViewer의 불필요한 리렌더링을 방지하고, 파일명 툴팁 기능 추가로 접근성을 개선하였습니다. 또한 문서 레이아웃 분석 가이드 작성을 통해 Docling 활용 표준화 및 개발자 온보딩 시간 단축에 기여하였습니다.

이번 개선사항은 문서인식 워크플로우의 효율성을 크게 높였으며, 향후 이미지 다운로드, 멀티모달 검색 통합, 문서 형식 확장을 통해 더욱 강력한 문서 분석 플랫폼으로 발전할 예정입니다.

문서 작성일: 2025년 11월 9일 버전: v0.5.1 - Document Recognition UX Improvements & Image Extraction