RAG 기반 문서 검색 시스템 - 6(문서 파싱/임베딩/벡터DB 저장 및 문서화)

개요

이전 글에서는 FastAPI 기반 백엔드에 문서 업로드 기능을 안전하고 확장 가능하게 구성하기 위한 전 과정을 정리했다. 파일 업로드, S3 저장, 실시간 전송, 성능 최적화까지 모든 단계를 모듈화하고 테스트 및 문서화까지 일관성 있게 마무리했다.
이번 글에서는 문서 업로드 이후의 흐름인 문서 파싱, 임베딩, 벡터DB(Milvus) 저장 및 문서화 작업을 다룬다. 이 과정은 RAG 파이프라인의 핵심을 구성하는 백엔드 처리 흐름으로, 향후 자연어 질문 검색 및 LLM 응답의 기반이 되는 구조다.

 

문서 파싱, 임베딩, 벡터DB(Milvus) 저장 및 문서화 작업흐름

1. 파이프라인 설계 및 구현

문서 업로드 이후 파싱 → 임베딩 → 벡터DB 저장 → 검색까지 전체 흐름을 FastAPI 기반으로 구현했다. 초기 구현은 정상 작동했으나, 인증 오류, S3 버킷 인증 실패, Milvus 컬렉션 미로드 이슈 등이 발견됐다.

2. 인증 구조 수정

roles.py의 get_current_user()가 User 객체를 반환하면서 JSON 직렬화 오류가 발생했다. 이를 dict로 변환하도록 수정하여 JWT 인증 흐름을 안정화했다.

3. S3(MinIO) 연동 디버깅

MinIO 인증 실패 이슈를 해결하기 위해 환경변수, endpoint, 버킷 존재 여부를 점검하고, 자동 버킷 생성 로직을 추가했다.

4. Milvus 연동 개선

벡터 검색 시 collection not loaded 오류가 반복되었으며, 이를 해결하기 위해 검색 전에 load() 호출을 명시적으로 추가했다.

5. JSON 직렬화 및 테스트

vector_ids, chunks 같은 복잡한 객체를 JSON으로 반환하는 데 문제가 있어, Pydantic 모델과 변환 로직을 추가했다. 테스트 코드를 통해 전체 흐름 검증을 수행했다.

* SSE 및 기타 이슈 발생 : SSE(bytes ↔ str 분기), extract_text 누락, 손상된 테스트 파일 복구 등 디테일한 이슈들을 반복적으로 점검하며 23개 중 20개 테스트를 통과했다.

6. 전체 흐름 문서화(README.MD작성)

전체 작업 흐름

해당 작업은 총 6단계로 구성된다. FastAPI 백엔드에 문서 업로드 이후의 흐름을 완성하고, S3와 Milvus 연동, 인증 처리, 예외 처리, 테스트 및 문서화까지 모두 포함된다.

1. 문서 업로드~검색 전체 파이프라인 설계 및 구현
2. JWT 인증, S3(MinIO), Milvus 벡터DB 연동
3. 서비스/유틸 예외처리 및 권한 로직 강화
4. 업로드 및 검색 관련 테스트 코드 작성 및 실행
5. JSON 직렬화 오류 및 컬렉션 미로드 등 반복 이슈 해결
6. 전체 흐름 문서화 

 파일 생성 및 수정

• backend/api/documents.py: 업로드, 파싱, 임베딩, 검색 API 통합 구현
• backend/app/services/document_parser.py: 문서 파싱 로직
• backend/app/services/document_chunker.py: 청킹 및 벡터화 로직
• backend/app/services/embedding_service.py: 임베딩 생성 및 오류 처리
• backend/app/services/milvus_service.py: 컬렉션 로드 포함한 벡터 저장/검색 기능
• backend/api/search.py: 검색 API 및 mock 응답
• backend/tests/test_upload.py, test_search.py: 테스트 코드 작성
• README.md: 파이프라인 구조, 테스트 결과, 기여 가이드 등 문서화

결과 요약

• FastAPI 기반 문서 파싱~검색 파이프라인 완성
• JWT 인증, S3, Milvus 연동 안정화 및 예외처리 구현
• 전체 테스트 87% 통과, SSE 일부 실패(기능 영향 없음)
• 다음 단계: LLM 연동, 프론트 UI, 샘플 문서, 모니터링 등

용어 정리

용어	설명
FastAPI	비동기 Python 기반의 고성능 웹 프레임워크
Milvus	대규모 벡터 검색을 위한 오픈소스 벡터 데이터베이스
MinIO	Amazon S3 호환 오브젝트 스토리지
RAG	Retrieval-Augmented Generation, 벡터 검색을 통해 LLM 성능을 향상시키는 기법
Vooster	태스크 기반 프로젝트 관리 도구
SSE	Server-Sent Events, 서버에서 클라이언트로 실시간 메시지를 전송하는 방식

마무리

이번 글에서는 FastAPI 기반 백엔드에 문서 파싱/임베딩/벡터DB 저장 및 문서화 작업을 정리했다. 각 단계의 이슈를 반복 점검하며 설계와 구현, 예외처리, 테스트, 문서화를 체계적으로 수행하였다.
다음 글에서는 업로드된 문서를 바탕으로 자연어 질문 기반의 RAG 검색 및 LLM 응답 기능 구현에 대해 다룰 예정이다.