Hailo-RAG-Engine

Hailo H10 NPU 탑재 소형 LLM(1~2B)을 위한 RAG 추론 엔진과, 이를 서빙하는 FastAPI 백엔드 + React 대시보드.

헬기 정비 도메인 문서를 기반으로 하이브리드 RAG 파이프라인을 구성하고, 대시보드를 통해 실시간 RAG 챗봇 시연 및 모델별 답변 품질 비교를 지원한다.

---

산출물 구성

---

mrod_engine 패키지

백엔드와 평가 스크립트가 공통으로 사용하는 추론 엔진 코어. FastAPI 의존 없음.

engine.py — 추론 엔진

rag_pipeline.py — HybridRagPipeline

BM25 (ko_kiwi, top10)    ─┐
KURE-v1 semantic (top10) ─┤ HybridCC (mm 정규화, 0.7/0.3) → top3
                           │
                           ▼
                  child ID → parent 원문 교환 → 컨텍스트 주입

• HybridCC: min-max 정규화 후 semantic 0.7 : lexical 0.3 가중 합산
• Parent Document: child(300자 내외)로 검색 → parent(원문 단위)로 컨텍스트 확보
• 리랭커 없음 — 실험 결과 HybridCC top3이 최적 구성으로 확정

---

FastAPI 백엔드

GET  /api/health              GPU 상태·로드 모델·RAG 준비 여부
GET  /api/backend             현재 backend(gpu/cpu) 조회
POST /api/backend/select      backend 전환
GET  /api/models              후보 모델 목록
POST /api/models/select       모델 로드 (이전 모델 자동 언로드)
POST /api/chat                질문 → 답변 + RAG 참고 문서 (단건 JSON)
POST /api/chat/stream         질문 → 답변 토큰 SSE 스트리밍
GET  /api/sessions            전체 세션 이력
GET  /api/judge/analyze       Judge 채점 결과 집계

---

React 대시보드

---

탑재 대상 LLM

---

프로젝트 구조

Hailo-RAG-Engine/
├── mrod_engine/
│   ├── engine.py          # 추론 엔진 코어 (라우팅·생성·스트리밍·RAG)
│   ├── rag_pipeline.py    # HybridRagPipeline (KURE + BM25 + HybridCC)
│   ├── llama_runner.py    # CPU(GGUF) 경로
│   ├── prompts.py         # 시스템 프롬프트
│   ├── schemas.py         # ROUTER_SCHEMA (JSON 강제 디코딩용)
│   └── config.py
├── dashboard/
│   ├── backend/
│   │   ├── main.py              # FastAPI 진입점 (REST + SSE)
│   │   ├── build_kure_index.py  # ChromaDB + BM25 인덱스 빌드 (1회)
│   │   └── results.py           # Judge 결과 조회
│   ├── frontend/                # Vite + React + TypeScript + Tailwind
│   ├── README.md
│   └── RAGCHAT_API.md
├── data/
│   ├── parent_store.json        # parent 청크 원문 + 메타
│   ├── child_store.json         # child 청크 (인덱스 재빌드 입력)
│   ├── chroma_kure_v1/          # KURE-v1 ChromaDB (child) — git 제외
│   └── bm25_kiwi_store/         # BM25 ko_kiwi 인덱스 — git 제외
├── docs/
│   ├── API_SPEC.md
│   ├── BACKEND.md
│   └── screenshot_dashboard.png
├── results_qa/                  # 모델별 평가 결과 JSON
├── test_qa_rag.py               # 모델 선정용 QA 생성
├── judge_qa.py                  # LLM Judge 채점
├── EXPO_PLAN_D7.md
├── requirements.txt
└── .env.example

---

설치 및 실행

1. 환경 설치

python -m venv venv

# GPU (CUDA 12.1)
venv/Scripts/pip install torch==2.5.1 --index-url https://download.pytorch.org/whl/cu121
venv/Scripts/pip install -r requirements.txt

2. 환경변수

cp .env.example .env
# HF_TOKEN=hf_...   (Llama-3.2-1B 사용 시)

3. 인덱스 빌드 (최초 1회)

venv/Scripts/python dashboard/backend/build_kure_index.py

4. 대시보드 실행

# 백엔드
cd dashboard/backend && ../../venv/Scripts/python main.py

# 프론트엔드 (별도 터미널)
cd dashboard/frontend && npm install && npm run dev

---

기술 스택