RAG 기반 문서 검색 시스템 - 5(문서 업로드 및 S3 저장/바이러스 검사 구현)

개요

앞선 글에서는 FastAPI 기반 백엔드의 인증 및 사용자 관리의 기반을 구축했다.  이번 글에서는 문서 업로드 기능의 전반적인 구현 흐름을 다룬다. 파일 업로드부터 바이러스 검사, S3 저장, 업로드 진행률 전송, 대용량 예외처리까지 다섯 개의 세부 작업을 통해 안전하고 확장 가능한 업로드 기능을 구축하였다.

 

문서 업로드 기능 구현 흐름

1. 파일 업로드 엔드포인트 구현 

문서 업로드용 FastAPI 엔드포인트(/api/documents/upload)를 구축하였다. 최대 200MB까지 PDF, TXT, DOCX 파일을 지원하며, 파일 확장자 및 크기 검증, 예외처리, 응답 구조를 포함한다.

• 파일 확장자 및 크기 제한 검증
• 에러 발생 시 HTTP 400/422 응답, 정상 시 presigned URL 포함 응답
• 정상/오류/미첨부 등 다양한 테스트 시나리오 적용

async def upload_document(file: UploadFile = File(...)):
    # 확장자 및 크기 검사 후 처리
    return {"file_id": ..., "filename": ..., "presigned_url": ...}

2. 바이러스 검사 로직 설계

ClamAV 연동을 고려한 바이러스 검사 로직(scan_virus)을 설계하였다. 현재는 실제 연동 대신 모킹 기반 구현이며, 추후 환경 구성 후 실제 연동 적용 예정이다.

• 감염/실패/정상 시나리오 분기 및 예외처리 적용
• 검사 실패 시 HTTP 500, 감염 파일 시 HTTP 400 응답

def scan_virus(contents: bytes) -> bool:
    return False  # 현재는 항상 정상 처리

3. AWS S3 저장 및 presigned URL 반환 

바이러스 검사를 통과한 파일만 AWS S3에 저장되며, 저장된 파일에 대한 presigned URL을 응답으로 반환한다. 저장 실패에 대한 예외처리 및 테스트까지 포함한 구조를 구현하였다.

• 저장 실패 시 HTTP 500 예외처리
• 정상 저장 시 presigned URL 반환

def save_to_s3(file_id: str, filename: str, contents: bytes) -> str:
    return "https://s3-url"  # presigned URL mock 반환

4. SSE 진행률 전송 기능 구현

파일 업로드 과정의 각 단계를 실시간으로 전송하는 SSE(Server-Sent Events) 기반 API(/api/documents/upload/progress)를 구현하였다. 사용자 입장에서 업로드, 검사, 저장 상태를 직관적으로 확인할 수 있도록 설계했다.

• 단계별 진행률 및 오류 상태 실시간 전송
• 비동기 yield로 SSE 전송 흐름 구성

async def upload_document_progress(file: UploadFile = File(...)):
    async def event_stream():
        yield ...  # 진행률 단계 이벤트
    return StreamingResponse(event_stream(), media_type="text/event-stream")

5. 대용량 업로드 성능 및 예외 처리 최적화 

최대 200MB까지의 대용량 파일 업로드를 테스트하고, 다중 동시 업로드 시 서버 부하 및 예외 상황을 안정적으로 처리할 수 있도록 최적화하였다.

• 대용량 및 동시 업로드 테스트 시나리오 적용
• 성능 저하 및 서버 오류 방지를 위한 로직 설계

 

관련 용어 정리

용어	설명
UploadFile	FastAPI에서 파일을 업로드할 때 사용하는 비동기 파일 객체
ClamAV	오픈소스 바이러스 검사 도구
Presigned URL	인증된 사용자가 S3 파일에 일시적으로 접근할 수 있도록 하는 URL
SSE (Server-Sent Events)	서버에서 클라이언트로 실시간 이벤트를 전송하는 HTTP 기반 기술

 

마무리

이번 글에서는 FastAPI 기반 백엔드에 문서 업로드 기능을 안전하고 확장 가능하게 구성하기 위한 전 과정을 정리하였다. 파일 업로드에서 시작해 바이러스 검사, S3 저장, 실시간 진행률 전송, 성능 최적화까지 각 단계를 세분화하여 모듈화하였고, 테스트 및 문서화까지 일관성 있게 유지하였다.

다음 글에서는 업로드된 문서를 바탕으로 문서 파싱/임베딩/벡터DB 저장 및 문서화에 대해 다룰 예정이다.