던전톡 MVP - AI 기반 TRPG 마스터 지원 시스템

프로젝트 개요

던전톡은 TRPG 게임 마스터를 위한 지능형 AI 어시스턴트입니다. 다양한 세계관의 게임 콘텐츠를 관리하고, 플레이어의 질문에 맞춤형 답변을 제공하는 RAG 기반 시스템입니다.

핵심 기능

1. 세계관별 콘텐츠 분류 시스템

• 자동 메타데이터 생성: 업로드된 문서를 AI가 자동으로 분석하여 FANTASY/ZOMBIE 세계관으로 분류
• 컨텍스트 기반 검색: 질문의 세계관에 맞는 콘텐츠만 선별적으로 검색
• 계층적 문서 구조: NPC, 장소, 아이템, 규칙, 시나리오별로 체계적 관리

2. 멀티 LLM 지원 아키텍처

• 통합 LLM 인터페이스: OpenAI GPT, Anthropic Claude, DeepSeek 모델을 하나의 인터페이스로 관리
• 동적 모델 전환: 환경변수를 통해 런타임에 AI 모델 변경 가능
• 폴백 메커니즘: 메인 모델 실패시 대체 모델로 자동 전환

3. 향상된 RAG 엔진

• 하이브리드 검색: 벡터 유사도 + 키워드 매칭 조합으로 정확도 향상
• 컨텍스트 윈도우 최적화: 토큰 한계에 맞춰 가장 관련성 높은 문서 선별
• 청킹 전략: 문서를 의미 단위로 분할하여 검색 정밀도 극대화

4. 캐싱 시스템

• Redis 기반 응답 캐싱: 동일 질문에 대한 즉시 응답으로 성능 최적화
• TTL 관리: 캐시 만료 시간 설정으로 최신성과 성능의 균형
• 해시 기반 캐시키: 질문과 세계관을 조합한 고유 캐시 식별

시스템 아키텍처

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend UI   │────│   FastAPI       │────│   RAG Engine    │
│  (Admin/Test)   │    │   Server        │    │   Enhanced      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                │                       │
                                │                       ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Redis Cache   │────│  Environment    │    │  Metadata       │
│   (Valkey)      │    │  Validator      │    │  Generator      │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
┌─────────────────┐    ┌─────────────────┐              │
│  PostgreSQL     │────│   PGVector      │──────────────┘
│  Database       │    │  Vectorstore    │
└─────────────────┘    └─────────────────┘

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   OpenAI API    │    │ Anthropic API   │    │  DeepSeek API   │
│    (GPT-4)      │    │   (Claude)      │    │    (Chat)       │
└─────────────────┘    └─────────────────┘    └─────────────────┘

구현 상세

RAG 파이프라인 처리 흐름

1. 문서 수집: documents/ 폴더의 모든 텍스트 파일 스캔
2. 메타데이터 추출: AI를 통해 각 문서의 세계관 타입 자동 분류
3. 텍스트 분할: RecursiveCharacterTextSplitter로 의미 단위 청킹
4. 벡터화: OpenAI Embeddings로 문서를 벡터 공간에 임베딩
5. 저장: PostgreSQL + pgvector에 벡터와 메타데이터 함께 저장

질의 응답 처리 흐름

1. 캐시 확인: Redis에서 기존 응답 검색
2. 벡터 검색: 질문을 벡터화하여 유사 문서 검색
3. 필터링: 세계관 타입으로 검색 결과 필터링
4. 컨텍스트 구성: 상위 K개 문서로 프롬프트 생성
5. LLM 호출: 선택된 모델로 답변 생성
6. 캐싱: 생성된 답변을 Redis에 저장

세계관 관리 시스템

• FANTASY 세계관: "잊혀진 별의 노래" 설정

  • 마법 시스템, 종족 설정, 지역 정보
  • NPC 프로필, 퀘스트 시나리오
  • 특수 아이템, 전투 규칙

• ZOMBIE 세계관: "황혼의 새벽" 설정

  • 아케론 바이러스 설정, 생존자 그룹
  • 폐허 지역 정보, 무기/도구 시스템
  • 생존 시나리오, 좀비 타입 분류

확장성 설계

• 모듈화 구조: 각 컴포넌트가 독립적으로 교체 가능
• 환경별 설정: Docker를 통한 배포 환경 표준화
• API 기반 설계: RESTful API로 프론트엔드와 분리
• 플러그인 아키텍처: 새로운 세계관이나 LLM 모델 쉽게 추가

성능 최적화

• uv 패키지 매니저: 기존 pip 대비 10배 빠른 의존성 설치
• Docker 레이어 캐싱: 의존성과 코드를 분리하여 빌드 시간 단축
• 벡터 인덱스: pgvector HNSW 인덱스로 대용량 검색 성능 보장
• 메모리 관리: 불필요한 캐시 정리 및 가비지 컬렉션 최적화

이 시스템은 TRPG 마스터가 게임 진행 중 실시간으로 필요한 정보를 AI를 통해 빠르게 얻을 수 있도록 설계되었습니다.