icey1287/SuperMew

SuperMew – 감사 가능한, RAG 우선 에이전트 플랫폼

개요 – SuperMew는 모든 사용자 상호작용을 일회성 HTTP 호출이 아닌, 지속적이고 재생 가능한 워크플로우로 취급하는 셀프호스팅 AI 에이전트 프레임워크입니다. 대화 스레드, 실행(Runs), 이벤트, 체크포인트를 연결하여 챗을 휴먼-인-더-루프(HITL) 검토를 위해 일시 중지하고, 나중에 재개하며, 완전히 감사할 수 있도록 합니다.

핵심 개념

영속화된 도메인 객체 – Thread, Message, Run, Event, Checkpoint, DocumentVersion은 PostgreSQL(메타데이터)과 Milvus(벡터 청크)에 저장됩니다. 이를 통해 과거의 모든 상호작용을 재생하거나 디버깅할 수 있습니다.
2단계 문서 게시 – 새로운 문서 버전은 격리된 후보 스코프에서 구축되고, 검증된 후 PostgreSQL CAS 작업을 통해 원자적으로 교체됩니다. 진행 중인 쿼리는 완성되지 않은 인덱스를 절대 보지 않습니다.
하이브리드 RAG 파이프라인 – 고밀도 벡터 검색(Milvus)과 네이티브 BM25가 Reciprocal Rank Fusion으로 융합되며, 선택적으로 재랭킹되고, 증거 품질이 판단되며, 단일 HyDE 또는 스텝백 재작성으로 폴백할 수 있습니다. 모든 중간 단계는 UI에서 시각화되는 rag_trace에 기록됩니다.
스킬/도구 레지스트리 – 고정 버전의 스킬(지식 베이스 조회, 날씨, 읽기 전용 SQL, 웹 리서치, 샌드박스 코드 실행, 제한된 HTTPS JSON)은 레지스트리에 선언됩니다. 각 도구의 스키마는 실행의 권한 확인 후에만 에이전트에 공개되며, 가드레일이 허용/거부/승인 정책을 강제합니다.
모델 제어 평면 – 관리자는 모델 프로필(비밀 정보 없음)을 정의하고 네 가지 역할에 할당합니다: Answer, Fast, Grader, Evaluator. Run 또는 평가 작업이 생성되면 정확한 모델 스냅샷이 동결되어 재현성이 보장됩니다.
RAG 평가 프레임워크 – 버전 관리된 데이터셋, 베이스라인 비교, CI-게이트 스타일 품질 체크, 영속적 평가 워커를 통해 정확성, 근거성, 관련성, 완전성, 미지원 주장, 충돌 공개를 자동으로 측정할 수 있습니다.
보안 및 인증 – 짧은 수명의 인메모리 액세스 토큰, HttpOnly 쿠키에 저장되는 로테이션 가능한 불투명 리프레시 토큰, RBAC, 엔드포인트별 레이트 리밋 HMAC, CSP/헤더, AST 및 RLS 체크를 갖춘 읽기 전용 SQL 샌드박스.

중요한 이유 – 모든 단계를 영속화함으로써, SuperMew는 다음을 가능하게 합니다:

감사 – 어떤 문서, 도구, 모델 출력이 응답을 생성했는지 정확히 추적합니다.
재개 – 인간 검토자가 명확화를 추가한 후 일시 중지된 대화를 재개합니다.
버전 관리 – 기존 실행을 깨뜨리지 않고 지식 베이스와 모델 구성을 버전 관리합니다.
벤치마킹 – 프로덕션과 유사한 환경에서 RAG 파이프라인을 끝에서 끝으로 벤치마킹합니다.

아키텍처 개요

구성 요소	기술	역할
API 서버	FastAPI (Python 3.12)	HTTP, SSE, 인증, 스레드/실행 오케스트레이션, 정적 프론트엔드 서빙
인덱싱 워커	Python 모듈 `backend.workers.indexing`	불변 문서 버전 구축, Milvus 벡터 작성, 후보 스코프 관리
RAG 평가 워커	Python 모듈 `backend.workers.evaluation`	오프라인 평가 작업 실행, 메트릭 계산, 결과 저장
벡터 스토어	Milvus (고밀도 + 네이티브 BM25)	빠른 근접 이웃 검색
메타데이터 스토어	PostgreSQL + SQLAlchemy + Alembic	스레드, 실행, 이벤트, 모델 스냅샷, 문서 카탈로그
캐시 / 저지연 알림	Redis	이벤트 푸시, 레이트 리밋 카운터
오브젝트 스토리지	MinIO (워커에서 사용)	업로드된 원본 문서
프론트엔드	Vite + Vue 3 + TypeScript + Pinia	챗, 스킬 센터, 관리 패널, 평가 워크벤치 UI

시작하기 (로컬 개발)

요구 사항 – Python 3.12+, uv 패키지 매니저, Node 20+, Docker Compose.
구성 – .env.example을 .env로 복사하고 다음을 입력합니다:
- 모델 식별자 (MODEL, FAST_MODEL, …)
- JWT_SECRET_KEY (32자 이상의 랜덤 문자열)
- 선택적 관리자 초대 코드.
의존성 시작 – docker compose up -d (Postgres, Redis, etcd, MinIO, Milvus, Attu).
Python 의존성 설치 – uv sync --frozen.
프론트엔드 빌드 – cd frontend && npm ci && npm run build && cd ...

마이그레이션 및健全성 체크 실행 –

uv run --frozen alembic upgrade head
uv run --frozen python -m backend.tools.registry_cli validate

세 가지 프로세스 시작 – ./scripts/start.sh (API, 인덱싱 워커, 평가 워커). 핫리로드를 비활성화하려면 --no-reload를 사용합니다.
UI는 http://127.0.0.1:8000/, OpenAPI는 http://127.0.0.1:8000/docs, Milvus Attu는 http://127.0.0.1:8080/ 을 엽니다.

프로덕션 체크리스트 (요약)

동일한 세 가지 서비스(API, 인덱싱 워커, 평가 워커)를 슈퍼바이저(systemd, k8s 등) 아래에 배포하여 동일한 코드 버전과 UPLOAD_DIR을 공유하도록 합니다.
APP_ENV=production을 설정하고 JWT, 레이트 리밋 HMAC, DB 비밀번호, 모델 제공자 키에 대한 실제 비밀 정보를 제공합니다.
보안 쿠키를 활성화합니다 (AUTH_REFRESH_COOKIE_SECURE=true).
워커를 API 보다 먼저 시작하고, 헬스 체크를 실행한 후, 공개 엔드포인트를 열기 전에 최소한의 끝에서 끝 테스트(스레드 생성, 문서 업로드, RAG 쿼리 실행, 작은 평가 작업 시작)를 수행합니다.
만료된 리프레시 토큰 장부를 정리하기 위해 클린업 작업 python -m backend.auth.cleanup 을 주기적으로 실행합니다.

일반적인 사용 사례

사용 사례	SuperMew의 도움
엔터프라이즈 지식 베이스 Q&A	PDF/문서를 업로드하고 버전 관리하며, 감사 추적을 유지하면서 하이브리드 검색으로 에이전트가 검색하도록 합니다.
휴먼-인-더-루프 지원	`Checkpoint`에서 실행을 일시 중지하고, 검토자가 도구 호출을 편집하거나 승인한 후, 컨텍스트를 잃지 않고 재개합니다.
규제 환경	엄격한 허용 목록, 샌드박스 코드 실행, 정책 기반 도구 가드레일을 갖춘 읽기 전용 SQL 어시스턴트가 컴플라이언스 요구 사항을 충족합니다.
모델/RAG 벤치마킹	데이터셋을 정의하고, 평가 워커를 실행하고, 베이스라인과 비교하며, 품질 메트릭에 기반하여 릴리스를 게이트합니다.
커스텀 스킬 통합	레지스트리를 통해 새로운 HTTP-JSON 도구 또는 도메인별 스킬을 추가합니다. 플랫폼은 버전 관리, 권한 확인, UI 노출을 자동으로 처리합니다.

TL;DR

SuperMew는 검색 증강 생성(RAG)에 의존하는 프로덕션 등급 AI 에이전트를 구축하기 위한 풀스택 오픈소스 플랫폼입니다. 지속성, 감사 가능성, 휴먼-인-더-루프 제어, 안전한 버전 관리 도구를 강조합니다. 모든 단계를 검사, 재생 또는 게이트할 수 있는 셀프호스팅 RAG 시스템이 필요하면, SuperMew는 PostgreSQL 기반 이벤트 소싱부터 Vue 기반 UI 및 견고한 평가 프레임워크까지 완전한 스택을 제공합니다.