README.md

---
title: Megumin RAG Chat
emoji: "💥"
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 6.10.0
app_file: app.py
pinned: false
---

# Megumin RAG Chat

메구밍과 직접 대화하는 체험형 캐릭터 챗봇입니다.  
메구밍의 말투와 감정선, 그리고 코노스바 설정 정보를 함께 참고해 답변합니다.

## 바로 써보기

이런 질문으로 시작해보세요.

- 메구밍, 카즈마 씨를 어떻게 생각하십니까?
- 폭렬마법을 가르쳐 준 사람은 누구인가요?
- 아쿠아의 세이크리드 브레이크 스펠이 무엇인지 설명해 주세요.
- 홍마족다운 자기소개를 한 번 들려주시겠습니까?

첫 접속 시 메구밍이 먼저 인삿말을 건네고, 답변은 ADK SSE 스트리밍으로 점진적으로 표시됩니다.

## 이 Space의 특징

- 메구밍 페르소나 기반 대화
- 설정 RAG + 스타일 RAG 동시 사용
- question 인덱스와 question+answer 인덱스를 함께 조회하는 FAISS 검색
- 첫 질문 시 lazy init
- `서비스 준비 중...`, `답변 생성 중...` 상태 표시
- 규칙 기반 작은 상태 배지
- `ssr_mode=False`로 초기 렌더 부담 완화
- 모바일에서는 제목, 최소 설명, 이미지, 채팅창만 보이는 단순화 레이아웃

## 실행

```bash
python app_gradio.py
```

메신저형 UI:

```bash
python app_gradio_messenger.py
```

Hugging Face Spaces 진입점:

```bash
python app.py
```

UI 선택:

```bash
MEGUMIN_UI=messenger
```

## 메신저 레이아웃 메모

`app_gradio_messenger.py`는 데스크톱 환경에서 Gradio 래퍼가 세로로 늘어나는 문제를 피하기 위해 고정 높이 메신저 레이아웃을 사용합니다.

- 좌측과 우측 섹터는 Gradio `Column(scale=3)`과 `Column(scale=7)`로 `3:7` 비율을 사용합니다.
- 메신저 패널 높이는 뷰포트 의존 flex 확장이 아니라 CSS 변수로 고정합니다.
- 우측 섹터는 세 개의 고정 역할을 갖는 3행 grid로 나뉩니다.
  `상단 헤더 = 96px`, `입력 영역 = 176px`, `메시지 표시 영역 = 나머지 높이`
- 메신저 UI에서는 `gr.Blocks(fill_height=True)`를 의도적으로 사용하지 않습니다. Gradio의 자동 stretch 래퍼가 고정 높이 동작을 다시 깨뜨릴 수 있기 때문입니다.
- 프로필 이미지는 외부 URL 대신 프로젝트 내부 `source_file` 폴더의 로컬 이미지를 사용합니다.
- 우선순위는 `megumin_profile.png`, `megumin_profile.jpg`, `megumin_profile.jpeg`, `megumin_profile.webp`이며, 없으면 같은 폴더의 첫 번째 이미지 파일을 사용합니다.
- 기본 SVG는 이미지 로드 실패 시에만 보이며, `source_file` 폴더는 메신저 단독 실행과 `app.py` 경유 실행 모두에서 `allowed_paths`로 명시적으로 서빙합니다.
- 이후 메신저 레이아웃을 변경하면 `app_gradio_messenger.py`와 `docs/agent-architecture.md`를 함께 수정합니다.

## Hugging Face 구성

앱 repo:

- `app.py`
- `app_gradio.py`
- `megumin_agent/`
- `scripts/`
- `docs/`
- `requirements.txt`
- `README.md`

dataset repo:

- `megumin_qa_dataset.json`
- `megumin_questions.faiss`
- `megumin_question_answer.faiss`
- `megumin_questions_meta.json`
- `namuwiki_qa.json`
- `namuwiki_questions.faiss`
- `namuwiki_question_answer.faiss`
- `namuwiki_questions_meta.json`

필수 Secret:

- `GOOGLE_API_KEY`
- `HF_TOKEN`

## 문서

- [ADK 정리](docs/Google-ADK.md)
- [데이터 수집 명세](docs/data-collection-spec.md)
- [Agent 구조 명세](docs/agent-architecture.md)