AI 문서 어시스턴트를 위한 RAG 대체 가상 파일시스템 구축

• 기존 RAG 기반 검색의 한계를 극복하기 위해, 문서를 파일과 디렉터리로 구성한 가상 파일시스템 구조로 전환
• 실제 파일 복제 없이 Chroma 데이터베이스를 기반으로 grep, cat, ls, find 명령을 수행할 수 있는 ChromaFs를 구현
• 이 방식으로 세션 생성 시간이 46초에서 100밀리초로 단축, 추가 연산 비용은 0달러 수준으로 감소
• 접근 제어는 파일 경로 메타데이터의 RBAC 필터링으로 처리되어, 별도 컨테이너나 사용자 그룹 관리가 불필요
• 결과적으로 Mintlify 문서 어시스턴트는 즉시 응답, 저비용, 무상태 구조를 갖춘 대규모 서비스로 운영 가능

RAG의 한계를 넘어선 가상 파일시스템 접근

• 기존 RAG 기반 문서 검색은 쿼리와 일치하는 텍스트 조각만 반환해, 여러 페이지에 걸친 답변이나 정확한 구문 검색이 어려웠음
• 이를 해결하기 위해 문서 구조를 파일시스템처럼 탐색 가능한 형태로 전환, 각 문서 페이지를 파일로, 섹션을 디렉터리로 매핑함
• 에이전트는 grep, cat, ls, find 명령을 통해 문서를 직접 탐색할 수 있어, 개발자가 코드베이스를 다루듯 문서를 검색할 수 있는 구조로 설계됨

컨테이너 병목 문제

• 일반적인 접근은 에이전트에 실제 파일시스템을 제공하기 위해 격리된 샌드박스 환경을 생성하고 저장소를 복제하는 방식
• 그러나 프런트엔드 어시스턴트에서는 세션 생성 지연이 심각하게 나타나며, p90 세션 생성 시간은 약 46초에 달함
• 월 85만 회 대화 기준, 최소 구성(1 vCPU, 2GiB RAM, 5분 세션 유지)에서도 연간 7만 달러 이상 인프라 비용이 발생
• 이러한 병목을 제거하기 위해 즉시 반응하고 저비용으로 동작하는 가상 파일시스템이 필요했음

가상 셸 구현 — ChromaFs

• 실제 파일시스템 대신 가상의 파일시스템 환상(illusion) 만 제공
• 기존 문서 데이터는 이미 Chroma 데이터베이스에 색인되어 있었기 때문에, 이를 기반으로 ChromaFs를 구축
• ChromaFs는 UNIX 명령을 가로채어 Chroma 쿼리로 변환함
• 결과적으로 세션 생성 시간이 46초에서 100밀리초로 단축, 추가 연산 비용은 0달러 수준으로 감소

• just-bash (Vercel Labs) 기반으로 구현되어, grep, cat, ls, find, cd 명령을 지원
• just-bash의 IFileSystem 인터페이스를 활용해, 파이프 처리 및 플래그 로직은 그대로 유지하면서 파일 접근 호출을 Chroma 쿼리로 변환

디렉터리 트리 부트스트래핑

• ChromaFs는 실행 전 어떤 파일이 존재하는지 알아야 하므로, 전체 파일 트리를 압축된 JSON(__path_tree__) 형태로 Chroma 컬렉션에 저장
• 서버 초기화 시 이를 가져와 두 가지 메모리 구조로 복원
  • 파일 경로의 Set<string>
  • 디렉터리별 자식 목록의 Map<string, string[]>
• 이후 ls, cd, find 명령은 네트워크 호출 없이 로컬 메모리에서 즉시 처리, 동일 사이트의 후속 세션은 캐시된 트리를 재사용

접근 제어

• 경로 트리에는 isPublic 및 groups 필드가 포함되어 있으며, 사용자 세션 토큰을 기준으로 접근 가능한 파일만 남김
• 접근 권한이 없는 파일은 트리에서 완전히 제거되어, 에이전트가 해당 경로를 인식하지 못함
• 기존 샌드박스에서는 이를 위해 리눅스 사용자 그룹, chmod, 컨테이너 분리 등을 관리해야 했으나, ChromaFs에서는 간단한 필터링 로직만으로 RBAC 구현

문서 조각 재조립

• Chroma에 저장된 문서는 임베딩을 위해 여러 조각으로 분할되어 있음
• cat /auth/oauth.mdx 실행 시, 동일한 page 슬러그를 가진 모든 조각을 가져와 chunk_index 순서로 정렬 후 병합
• 결과는 캐시되어, 반복된 grep 워크플로에서도 DB 재조회가 발생하지 않음
• 대형 OpenAPI 스펙 등은 지연 로딩 포인터(lazy file pointer) 로 등록되어, 접근 시에만 S3에서 가져옴
• 모든 쓰기 연산은 EROFS(읽기 전용 파일시스템) 오류를 반환해, 세션 상태가 없는(stateless) 안전한 구조 유지

Grep 최적화

• grep -r 명령은 단순 네트워크 스캔 시 매우 느리므로, 두 단계 필터링 구조로 최적화
  • 1단계: Chroma 쿼리($contains, $regex)를 이용해 후보 파일을 선별
  • 2단계: Redis 캐시에 미리 가져온 후, just-bash에서 메모리 내 정밀 필터링 수행
• 이를 통해 대규모 재귀 검색도 밀리초 단위로 완료 가능

결론

• ChromaFs는 하루 3만 건 이상, 수십만 명의 사용자가 이용하는 Mintlify 문서 어시스턴트를 구동
• 샌드박스를 대체함으로써 즉시 세션 생성, 0에 가까운 추가 비용, 내장 RBAC, 무상태 구조를 달성
• Mintlify의 모든 문서 사이트에서 직접 사용 가능 (mintlify.com/docs)