RAG 기반 문서 검색 시스템 - 10(문서 메타데이터 및 버전 관리 기능 구현)

개요

이전 글에서는 사용자가 문서를 열람하거나 질문 응답 시 확인할 수 있는 근거 문장 UI를 구현했다. 해당 기능은 콜랩스/확장, 메타데이터 표시, 페이지 이동, 접근성을 모두 지원하도록 구현되었다. 이번 글에서는 문서 메타데이터 관리 및 버전 관리 시스템 구현 작업을 다룬다. 이는 RAG 시스템에서 문서의 추적성과 변경 이력을 관리하는 중요한 기반 기능으로, 향후 문서 분류, 권한 관리, 알림 시스템의 토대가 되는 구조다.

작업흐름

1. 데이터베이스 스키마 설계 및 마이그레이션

문서 업로드 이후 메타데이터 관리와 버전 추적을 위한 데이터베이스 구조를 설계했다. 기존 문서 테이블에 메타데이터 필드를 추가하고, 변경 이력과 알림을 위한 새로운 테이블을 생성했다.

주요 추가 필드:

• 메타데이터: description, tags, language, page_count, word_count, embedding_mode, embedding_dimension
• 버전 관리: version, s3_version_id, is_latest, parent_document_id

새로운 테이블:

• document_change_history: 문서 변경 이력 추적
• document_notifications: 알림 관리

2. 문서 모델 및 Pydantic 스키마 확장

SQLAlchemy 모델과 Pydantic 스키마를 확장하여 메타데이터와 버전 관리 기능을 지원하도록 구현했다. 카테고리 모델도 함께 추가하여 문서 분류 기능의 기반을 마련했다.

3. 문서 서비스 로직 구현

문서 생성, 버전 관리, 메타데이터 업데이트를 담당하는 서비스 로직을 구현했다. 새 버전 생성 시 기존 문서의 is_latest 상태를 관리하고, 부모-자식 관계를 통해 버전 트리를 구성한다.

4. 변경 이력 관리 서비스 구현

문서의 모든 변경사항을 자동으로 추적하고, LLM을 활용하여 변경점 요약을 생성하는 서비스를 구현했다. CREATE, UPDATE, DELETE, RESTORE 등 다양한 변경 타입을 지원한다.

5. API 엔드포인트 구현

메타데이터 조회/수정, 버전 관리, 변경 이력 조회, 알림 관리 등을 위한 RESTful API를 구현했다. 권한 검증, 페이징, 필터링 기능을 포함하여 완전한 CRUD 기능을 제공한다.

주요 엔드포인트:

• GET /{document_id}/metadata: 메타데이터 조회
• PUT /{document_id}/metadata: 메타데이터 업데이트
• GET /{document_id}/versions: 버전 목록 조회
• POST /{document_id}/versions/{version_id}/restore: 버전 복원
• GET /{document_id}/change-history: 변경 이력 조회

6. 알림 시스템 연동

문서 변경 시 자동으로 알림을 전송하는 시스템을 구현했다. 이메일, 슬랙 등 다양한 채널을 지원하며, 실패한 알림의 재시도 기능도 포함한다.

전체 작업 흐름

해당 작업은 총 6단계로 구성된다. FastAPI 백엔드에 문서 메타데이터 관리와 버전 관리 시스템을 완성하고, 변경 이력 추적, 알림 시스템, 권한 관리까지 모두 포함된다.

• 데이터베이스 스키마 설계 및 마이그레이션
• 문서 모델 및 Pydantic 스키마 확장
• 문서 서비스 로직 구현 (버전 관리 포함)
• 변경 이력 관리 서비스 구현
• API 엔드포인트 구현 (메타데이터, 버전, 이력, 알림)
• 알림 시스템 연동 및 테스트

파일 생성 및 수정

• backend/app/models/document.py: 문서, 카테고리, 변경 이력 모델 확장
• backend/migrations/versions/d0e95d166dfd_add_document_metadata_and_version_.py: DB 마이그레이션
• backend/app/services/document_service.py: 문서 생성 및 버전 관리 로직
• backend/app/services/change_history_service.py: 변경 이력 관리 서비스
• backend/api/documents.py: 메타데이터, 버전, 이력, 알림 API 통합 구현

결과 요약

• FastAPI 기반 문서 메타데이터 및 버전 관리 시스템 완성
• 변경 이력 자동 추적 및 LLM 기반 요약 생성 기능 구현
• 알림 시스템 연동으로 실시간 변경 알림 지원
• 권한 기반 접근 제어 및 카테고리 분류 기능 통합
• 다음 단계: 문서 분류 UI, 권한 관리, OCR 기능, Agent 태스크 등

용어 정리

용어	설명
메타데이터	문서의 속성 정보 (제목, 설명, 태그, 언어, 페이지 수 등)
버전 관리	문서의 변경 이력을 추적하고 특정 시점으로 복원하는 기능
변경 이력	문서의 생성, 수정, 삭제, 복원 등의 모든 변경사항 기록
부모-자식 관계	문서 버전 간의 계층 구조 (이전 버전 → 새 버전)
LLM 요약	GPT를 활용하여 문서 변경사항을 자동으로 요약하는 기능
알림 시스템	문서 변경 시 사용자에게 이메일, 슬랙 등으로 알림을 전송하는 기능
카테고리 분류	문서를 주제별로 분류하여 관리하는 기능
권한 기반 접근	사용자 역할에 따라 문서 접근 권한을 제어하는 기능

마무리

이번 글에서는 문서 메타데이터 관리 및 버전 관리 시스템 구현 작업을 정리했다. 각 단계의 설계와 구현, 변경 이력 추적, 알림 시스템 연동을 통하여 문서를 관리하였다. 다음 글에서는 업로드된 문서를 바탕으로 문서 분류 및 권한 기반 접근 제어 기능 구현에 대해 다룰 예정이다.