Introduce.md

Ragnaforge - 기업용 하이브리드 RAG 시스템

🎯 프로젝트 개요

Ragnaforge는 한국어에 특화된 차세대 하이브리드 RAG(Retrieval-Augmented Generation) 시스템으로, 기업의 문서 지능화 및 지식 관리 혁신을 위해 설계된 엔터프라이즈급 솔루션입니다.

핵심 가치 제안

• 한국어 최적화: KURE-v1, KoE5 등 한국어 특화 임베딩 모델 지원
• 하이브리드 검색: Vector 검색과 Text 검색의 지능적 결합으로 검색 정확도 극대화
• OpenAI 호환성: 기존 OpenAI API 기반 시스템과 완벽 호환
• 엔터프라이즈 준비: 확장성, 보안성, 안정성을 고려한 기업용 아키텍처

🏢 기업용 시장 적합성

타겟 시장

1. 대기업 및 공공기관

   • 대용량 문서 처리 및 지식 관리 시스템 구축
   • 내부 문서 검색 및 질의응답 시스템
   • 규정 및 매뉴얼 자동화 시스템

2. 금융 및 법무 기관

   • 계약서, 법령, 판례 등 전문 문서 분석
   • 컴플라이언스 및 리스크 관리
   • 고객 상담 자동화

3. 연구개발 기관

   • 연구 논문 및 기술 문서 분석
   • 특허 검색 및 분석
   • 지식 베이스 구축

4. IT 서비스 기업

   • 고객사 맞춤형 RAG 솔루션 제공
   • SaaS 형태의 문서 지능화 서비스
   • AI 기반 검색 엔진 구축

시장 니즈 부합도

✅ 강점

• 한국어 처리 우위: 기존 글로벌 솔루션 대비 한국어 문서 처리 성능 우수
• 비용 효율성: 로컬 모델 사용으로 API 비용 절감 (OpenAI 대비 90% 절약)
• 데이터 보안: 온프레미스 배포로 민감한 기업 데이터 보호
• 커스터마이징: 기업별 요구사항에 맞춘 유연한 설정 및 확장

🎯 시장 기회

• AI 도입 가속화: 기업의 디지털 전환 및 AI 도입 확산
• 데이터 주권 강화: 국내 데이터 처리에 대한 규제 강화 트렌드
• 비용 최적화: 클라우드 API 비용 부담으로 인한 온프레미스 솔루션 선호
• 한국어 특화 니즈: 글로벌 솔루션의 한국어 처리 한계

🏗️ 시스템 아키텍처

전체 구조

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Client Apps   │    │   Web UI        │    │   API Clients   │
│   (OpenAI SDK)  │    │   (Streamlit)   │    │   (REST API)    │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │      FastAPI Gateway      │
                    │   (OpenAI Compatible)     │
                    └─────────────┬─────────────┘
                                  │
        ┌─────────────────────────┼─────────────────────────┐
        │                         │                         │
┌───────▼────────┐    ┌──────────▼──────────┐    ┌─────────▼────────┐
│  Document      │    │   Embedding &       │    │   Search &       │
│  Processing    │    │   Vector Store      │    │   Retrieval      │
│                │    │                     │    │                  │
│ • Marker       │    │ • KURE-v1/KoE5     │    │ • Vector Search  │
│ • Docling      │    │ • Qdrant/Milvus    │    │ • Text Search    │
│ • Chunking     │    │ • Batch Processing  │    │ • Hybrid Search  │
│ • Storage      │    │ • GPU Acceleration  │    │ • Reranking      │
└────────────────┘    └─────────────────────┘    └──────────────────┘

레이어별 아키텍처

🌐 프레젠테이션 레이어

• FastAPI Gateway: OpenAI 호환 REST API 제공
• Streamlit UI: 직관적인 웹 인터페이스
• Router 모듈: 기능별 엔드포인트 분리
  • /embeddings - 임베딩 생성 API
  • /v1/upload - 파일 업로드
  • /v1/process - 문서 처리
  • /v1/search/* - 검색 API
  • /v1/rerank - 재순위화 API
  • /admin/* - 관리 기능

🔧 비즈니스 로직 레이어

• Document Processing Service: 문서 변환 및 처리 오케스트레이션
• Embedding Service: 임베딩 모델 관리 및 벡터 생성
• Unified Search Service: 하이브리드 검색 엔진
• Rerank Service: Cross-encoder 기반 재순위화
• File Upload Service: 파일 업로드 및 중복 검사
• Storage Service: 파일 시스템 관리

💾 데이터 레이어

• Vector Backends: Qdrant, Milvus, Chroma, Weaviate
• Text Backends: MeiliSearch, OpenSearch, Elasticsearch
• Database Service: 메타데이터 및 파일 정보 관리
• Storage System: 계층화된 파일 저장 구조

핵심 컴포넌트

1. 문서 처리 파이프라인

• 다중 변환 엔진: Marker(고속), Docling(고품질) 지원
• 지능형 청킹: 문서 구조 인식 기반 최적 분할
• 메타데이터 관리: 파일 정보, 해시, 중복 검사
• 이미지 처리: 문서 내 이미지 추출 및 OCR

2. 임베딩 & 벡터 스토어

• 한국어 특화 모델: KURE-v1, KoE5, Arctic-embed-ko
• 배치 최적화: GPU 메모리 효율적 활용 (배치 크기 128)
• 다중 백엔드: Qdrant, Milvus, Chroma, Weaviate 지원
• 실시간 인덱싱: 문서 업로드 즉시 검색 가능

3. 하이브리드 검색 엔진

• 벡터 검색: 의미적 유사도 기반 검색
• 텍스트 검색: 키워드 기반 정확 매칭 (MeiliSearch)
• 지능형 결합: 가중치 기반 스코어 융합
• 재순위화: Cross-encoder 모델을 통한 결과 품질 향상

4. API 게이트웨이

• OpenAI 호환: 기존 OpenAI SDK 그대로 사용 가능
• RESTful API: 표준 HTTP API 제공
• 인증 & 권한: Bearer 토큰 기반 보안
• 모니터링: 성능 메트릭 및 사용량 추적

� 문서 처리 흐름

전체 파이프라인

📄 파일 업로드 → 🔍 중복 검사 → 🔄 문서 변환 → ✂️ 청킹 → 🧠 임베딩 → 💾 저장 → 🔍 검색 가능

상세 처리 단계

1️⃣ 파일 업로드 및 검증

클라이언트 요청 (POST /v1/upload)
    ↓
파일 크기 검증 (최대 50MB)
    ↓
파일 형식 검증 (PDF, DOCX, PPTX, MD, TXT)
    ↓
임시 저장소에 파일 저장
    ↓
SHA-256 해시 계산
    ↓
중복 파일 검사 (데이터베이스)
    ↓
고유 파일 ID 생성 및 메타데이터 저장

2️⃣ 문서 변환 (Document Processing Service)

파일 타입 분석
    ↓
변환 방법 선택:
├── PDF → Marker (고속) 또는 Docling (고품질)
├── DOCX/PPTX → Docling
├── MD/TXT → 직접 읽기
    ↓
마크다운 변환 실행
    ↓
이미지 추출 (선택사항)
    ↓
변환 결과 검증 및 저장

3️⃣ 텍스트 청킹 (Chunking Service)

마크다운 텍스트 입력
    ↓
청킹 전략 선택:
├── recursive: 재귀적 분할 (기본값)
├── semantic: 의미 단위 분할
├── fixed: 고정 크기 분할
    ↓
청크 크기 설정 (기본 380자)
    ↓
오버랩 설정 (기본 70자)
    ↓
청크 생성 및 메타데이터 추가

4️⃣ 임베딩 생성 (Embedding Service)

청크 텍스트 배치 처리
    ↓
임베딩 모델 로드:
├── KURE-v1 (기본값)
├── KoE5
├── Arctic-embed-ko
    ↓
GPU 메모리 최적화 (배치 크기 128)
    ↓
벡터 임베딩 생성
    ↓
정규화 및 품질 검증

5️⃣ 인덱싱 및 저장

벡터 데이터베이스 저장:
├── Qdrant (기본값)
├── Milvus
├── Chroma
├── Weaviate
    ↓
텍스트 검색 엔진 저장:
├── MeiliSearch (기본값)
├── OpenSearch
├── Elasticsearch
    ↓
메타데이터 데이터베이스 업데이트
    ↓
파일 시스템 정리

검색 처리 흐름

🔍 벡터 검색 프로세스

검색 쿼리 입력 (POST /v1/search/vector)
    ↓
쿼리 임베딩 생성
    ↓
벡터 검색 실행 (의미적 유사도)
    ↓
재순위화 (Cross-encoder, 선택사항)
    ↓
최종 결과 반환

📝 텍스트 검색 프로세스

검색 쿼리 입력 (POST /v1/search/text)
    ↓
텍스트 검색 실행 (키워드 매칭)
    ↓
하이라이팅 처리 (선택사항)
    ↓
최종 결과 반환

🎯 재순위화 프로세스

초기 검색 결과 (상위 100개)
    ↓
Cross-encoder 모델 로드:
└── dragonkue/bge-reranker-v2-m3-ko
    ↓
쿼리-문서 쌍 점수 계산
    ↓
배치 처리 (32개씩)
    ↓
점수 기반 재정렬
    ↓
최종 상위 결과 반환

�🚀 주요 기능 및 특장점

문서 처리 능력

• 50MB 대용량 파일 지원
• PDF, DOCX, PPTX, MD, TXT 등 다양한 형식
• 이미지 추출 및 메타데이터 보존
• 중복 문서 자동 감지 (SHA-256 해시 기반)
• 스트리밍 처리: 메모리 효율적 대용량 파일 처리

검색 성능

• 200ms 이하 평균 응답 시간
• 하이브리드 검색으로 정확도 향상
• 재순위화를 통한 결과 품질 최적화
• 동시 요청 처리 (스로틀링 지원)
• 캐싱 시스템: 임베딩 및 재순위화 결과 캐싱

개발자 친화성

• OpenAI SDK 완전 호환
• Swagger/ReDoc 자동 문서화
• Docker 컨테이너화 지원
• 환경별 설정 분리 (dev/staging/prod)
• 모듈형 아키텍처: 플러그인 방식 백엔드 확장

운영 안정성

• GPU 메모리 최적화
• 자동 파일 정리
• 헬스 체크 및 모니터링
• 에러 처리 및 로깅
• 백업 및 복구: 데이터 무결성 보장

💼 비즈니스 모델 및 수익화

라이선스 모델

1. 오픈소스 (MIT): 기본 기능 무료 제공
2. 엔터프라이즈: 고급 기능 및 기술 지원
3. 클라우드 SaaS: 관리형 서비스 제공
4. 컨설팅: 구축 및 커스터마이징 서비스

경쟁 우위

• 한국어 특화: 글로벌 솔루션 대비 한국어 처리 우수
• 비용 효율성: OpenAI API 대비 90% 비용 절감
• 온프레미스: 데이터 보안 및 규제 준수
• 확장성: 모듈형 아키텍처로 유연한 확장

🛣️ 로드맵 및 발전 방향

단기 목표 (3-6개월)

• URL 크롤링 시스템 구축
• 고급 데이터 관리 API 확장
• 모니터링 & 분석 대시보드
• 새로운 백엔드 추가 (OpenSearch, Elasticsearch)

중기 목표 (6-12개월)

• MCP(Model Context Protocol) 지원
• AI 에이전트 기능 (질의응답, 요약)
• 외부 데이터 소스 연계
• Kubernetes 배포 최적화

장기 목표 (1-2년)

• 멀티모달 지원 (이미지, 음성)
• 실시간 스트리밍 검색
• 연합 학습 지원
• 글로벌 시장 진출

� 기술 스택 상세

백엔드 프레임워크

• FastAPI: 고성능 비동기 웹 프레임워크
• Pydantic: 데이터 검증 및 설정 관리
• Uvicorn: ASGI 서버
• Python 3.11: 최신 언어 기능 활용

문서 처리 엔진

• Marker: 고속 PDF 변환 (GPU 가속)
• Docling: 다중 형식 지원 (IBM Research)
• LangChain: 텍스트 청킹 및 분할
• Pillow: 이미지 처리 및 추출

임베딩 모델

• KURE-v1: 한국어 특화 임베딩 (NLPAI Lab)
• KoE5: 한국어 E5 모델
• Arctic-embed-ko: 다국어 임베딩
• Sentence-Transformers: 모델 로딩 및 추론

벡터 데이터베이스

• Qdrant: 고성능 벡터 검색 (Rust 기반)
• Milvus: 확장 가능한 벡터 DB
• Chroma: 경량 벡터 스토어
• Weaviate: 그래프 기반 벡터 DB

텍스트 검색 엔진

• MeiliSearch: 빠른 전문 검색 (Rust 기반)
• OpenSearch: 분산 검색 엔진
• Elasticsearch: 엔터프라이즈 검색
• Solr: Apache 검색 플랫폼

재순위화 모델

• BGE-Reranker-v2-m3-ko: 한국어 특화 Cross-encoder
• BGE-M3: 다국어 재순위화 모델
• Custom Rerankers: 도메인 특화 모델 지원

모니터링 & 로깅

• Python Logging: 구조화된 로그 관리
• Performance Metrics: 응답 시간 및 처리량 추적
• Health Checks: 서비스 상태 모니터링
• Error Tracking: 예외 및 오류 추적

저장 시스템

• 계층화 파일 시스템: 타입별 자동 분류
• 메타데이터 DB: SQLite/PostgreSQL 지원
• 캐시 시스템: 메모리 기반 결과 캐싱
• 백업 전략: 자동 데이터 백업

🔄 데이터 플로우 및 시스템 통합

전체 데이터 플로우

📱 클라이언트 → 🌐 API Gateway → 🔧 비즈니스 로직 → 💾 데이터 레이어
    ↑                    ↓                    ↓                ↓
📊 응답 결과 ← 🔍 검색 결과 ← ⚡ 처리 완료 ← 💿 데이터 저장

서비스 간 통신 패턴

🔗 동기 통신

• API 요청/응답: FastAPI 라우터 → 서비스 레이어
• 데이터베이스 쿼리: 서비스 → 데이터베이스
• 모델 추론: 임베딩/재순위화 서비스

⚡ 비동기 처리

• 문서 변환: 백그라운드 태스크
• 배치 임베딩: GPU 메모리 최적화
• 병렬 검색: 벡터 + 텍스트 동시 실행

메모리 관리 전략

🧠 GPU 메모리 최적화

모델 로딩 → 메모리 풀 관리 → 배치 처리 → 자동 정리
    ↓              ↓              ↓           ↓
VRAM 할당 → 배치 크기 조정 → 추론 실행 → 메모리 해제

💾 시스템 메모리 관리

• 스트리밍 파일 처리: 대용량 파일 청크 단위 처리
• 캐시 관리: LRU 기반 자동 캐시 정리
• 가비지 컬렉션: 대용량 객체 즉시 해제

확장성 설계

🔄 수평 확장

• 로드 밸런싱: 다중 인스턴스 지원
• 상태 비저장: 세션 독립적 설계
• 데이터베이스 샤딩: 대용량 데이터 분산

📈 수직 확장

• GPU 클러스터: 다중 GPU 활용
• 메모리 확장: 대용량 RAM 지원
• 스토리지 확장: 분산 파일 시스템

보안 및 인증

🔐 API 보안

• Bearer 토큰: JWT 기반 인증
• CORS 정책: 도메인 기반 접근 제어
• Rate Limiting: 요청 빈도 제한
• Input Validation: 입력 데이터 검증

🛡️ 데이터 보안

• 파일 해시 검증: 무결성 보장
• 암호화 저장: 민감 데이터 보호
• 접근 로그: 감사 추적
• 백업 암호화: 데이터 유출 방지

모니터링 및 관찰성

📊 메트릭 수집

요청 수신 → 처리 시간 측정 → 성능 지표 수집 → 대시보드 표시
    ↓              ↓                ↓              ↓
로그 기록 → 에러 추적 → 알림 발송 → 자동 복구

🔍 로그 관리

• 구조화 로깅: JSON 형태 로그
• 레벨별 분류: DEBUG, INFO, WARNING, ERROR
• 컨텍스트 추적: 요청 ID 기반 추적
• 로그 집계: 중앙화된 로그 관리

�📊 기술적 성과

성능 지표

• 82개 테스트 케이스 100% 통과
• 200ms 이하 평균 응답 시간
• GPU 메모리 효율성 80% 활용률
• 동시 처리 최대 8개 요청
• 처리량: 초당 5-10개 문서 처리
• 정확도: 하이브리드 검색 90%+ 정확도

품질 보증

• 종합 테스트 스위트 구축
• 보안 테스트 (SQL 인젝션, XSS 방어)
• 성능 테스트 자동화
• 코드 품질 관리
• CI/CD 파이프라인 준비
• 문서화 자동 생성

🎯 결론

Ragnaforge는 한국 기업의 문서 지능화 니즈를 정확히 파악하고, 기술적 우수성과 비즈니스 실용성을 모두 갖춘 차세대 RAG 솔루션입니다.

핵심 경쟁력:

• 한국어 특화 처리 능력
• 엔터프라이즈급 안정성
• OpenAI 호환성
• 비용 효율성

시장 기회:

• 급성장하는 기업 AI 도입 시장
• 데이터 주권 및 보안 강화 트렌드
• 한국어 특화 솔루션 부족

Ragnaforge는 기업의 디지털 전환을 가속화하고, 지식 관리의 패러다임을 혁신할 수 있는 강력한 플랫폼으로 자리잡을 것입니다.