boluo2077/deep-rag

전통적인 RAG (Retrieval-Augmented Generation) 시스템:

• ❌ 문서를 파편(fragments)으로 분할하여 구조를 상실함
• ❌ "유사한" 콘텐츠는 찾을 수 있지만, "반대되는" 콘텐츠는 찾을 수 없음
• ❌ 수치 비교 및 부정 논리(negation logic) 처리에 어려움이 있음
• ❌ 문서 간의 멀티홉 추론 (multi-hop reasoning) 수행이 불가능함
• ❌ 집계 쿼리 (aggregation queries)를 위한 전역적 이해도가 부족함

전통적인 RAG: 문서 분할 → 청크(chunks) 검색 → 모델에 입력
Deep RAG: 구조 보존 → 모델에 "지도" 제공 → 모델이 탐색하도록 허용

Deep RAG가 제공하는 기능:

• ✅ 지식 지도로서의 파일 요약 (File Summary as Knowledge Map): LLM이 전체 구조를 파악함 - ✅
• ✅ 능동적 탐색 (Active Navigation): 모델이 필요한 시점에 필요한 것을 검색함 - ✅
• ✅ 다회차 검색 (Multi-round Retrieval): 복잡한 멀티홉 추론 (multi-hop reasoning)을 지원함 - ✅
• ✅ 완전한 컨텍스트 (Complete Context): 파편이 아닌 전체 파일/디렉토리를 검색함

Deep RAG에 대해 더 알고 싶으신가요?

직관적이고 이해하기 쉬운 기사를 읽어보세요: 🔍 Deep RAG: AI에게 지식 베이스를 진정으로 "이해"하도록 가르치기

능력 (Capability)	전통적인 RAG	Deep RAG
부정 쿼리 ("제외하고", "외에도")	❌	✅
수치 비교 ("보다 큰", "보다 작은")	❌	✅
극단값 찾기 ("최대값", "최소값")	❌	✅
문서 간 비교	❌	✅
시간적 추론 ("작년", "이전")	❌	✅
다회차 메모리 (Multi-turn Memory)	❌	✅
멀티홉 추론 (Multi-hop Reasoning)	❌	✅
전역 집계 (Global Aggregation)	❌	✅

• 🔌 범용 LLM 지원: OpenAI, Anthropic, Google Gemini 또는 모든 OpenAI 호환 API - 🛠️
• 🔌 이중 도구 호출 모드 (Dual Tool Calling Modes): Function Calling + ReAct - 🎨
• 🔌 현대적인 웹 UI: React + TypeScript + Vite로 구축됨 - ⚡
• 🔌 스트리밍 응답 (Streaming Responses): 실시간 응답 스트리밍 - 🔧
• 🔌 쉬운 설정: 웹 기반 .env 에디터 - 📊
• 🔌 도구 호출 시각화 (Tool Call Visualization): AI가 무엇을 하고 있는지 확인 가능

**Python 3.8+****Node.js 16+**LLM API 키(OpenAI, Google Gemini, Anthropic 또는 호환 가능한 키)

저장소 복제 (Clone the repository)

git clone https://github.com/boluo2077/deep-rag.git
cd deep-rag

환경 변수 설정

cp .env.example .env
# API 키를 사용하여 .env 파일을 수정하세요

애플리케이션 시작

./start.sh

빠른 시작 (의존성 검사 건너뛰기):

./start.sh --fast

스크립트가 다음 작업을 수행합니다:

• ✅ Python 가상 환경 (virtual environment) 생성
• ✅ 백엔드 (backend) 의존성 설치
• ✅ 프론트엔드 (frontend) 의존성 설치
• ✅ 백엔드 서버 시작 (http://localhost:8000)
• ✅ 프론트엔드 개발 서버 시작 (http://localhost:5173)
• ✅ 브라우저 자동 실행

백엔드 (Backend):

python3 -m venv venv
source venv/bin/activate # Windows의 경우: venv\Scripts\activate
pip install -r requirements.txt
...

프론트엔드 (Frontend):

cd frontend
npm install
npm run dev

./stop.sh

./restart.sh

./restart.sh --full

Deep RAG는 문서를 청크 (chunks)로 나누는 대신, 파일 구조를 그대로 유지합니다:

Knowledge-Base/
├─ Product-Line-A-Smartwatch-Series/
│ ├─ SW-2100-Flagship.md
...

지식 베이스 (knowledge base)의 구조화된 요약을 생성합니다:

cd Knowledge-Base-File-Summary
python generate.py

이를 통해 다음과 같은 형태의 "지식 지도 (knowledge map)"가 생성됩니다:

Product-Line-A-Smartwatch-Series/
├─ SW-2100-Flagship.md: 2.1" AMOLED, 72h battery, IP68, $2999
├─ SW-1800-Business.md: 1.8" LCD, 48h battery, IP67, $1899
...

파일 요약은 시스템 프롬프트 (system prompt)에 주입되어, LLM에게 다음을 제공합니다:

• 📍 사용 가능한 모든 지식에 대한 개요 (Overview)
• 🗺️ 타겟팅된 검색 (retrieval)을 위한 파일 경로
• 🎯 다단계 쿼리 (multi-step queries)를 계획할 수 있는 능력

질문에 답변할 때, LLM은 다음과 같이 수행할 수 있습니다:

retrieve_files([
"Product-Line-A-Smartwatch-Series/SW-2100-Flagship.md", # 특정 파일
"2023-Market-Layout/", # 디렉토리 전체
...

┌─────────────────────────────────────────────────────────────┐
│ 프론트엔드 (React) │
│ • 채팅 인터페이스 • 설정 패널 • 시스템 프롬프트 뷰어 │
...

deep-rag/
├── backend/ # FastAPI 백엔드
│ ├── main.py # API 엔드포인트
...

.env를 수정하여 다음을 설정하세요:

# LLM 제공자 (openai, google, anthropic, custom)
API_PROVIDER=google
# 도구 호출 모드 (function, react)
...

코드 변경은 필요하지 않습니다! .env에 추가하기만 하면 됩니다:

PROVIDER_NAME_API_KEY=your_key
PROVIDER_NAME_BASE_URL=https://api.provider.com/v1
PROVIDER_NAME_MODEL=model-name
...

함수 호출 모드 (Function Calling Mode) (권장)

• 네이티브 함수 호출 (native function calling)을 지원하는 모델용
• 예시: GPT-4+, Gemini 1.5+, Claude 3.5+
• 더 신뢰할 수 있고 구조화된 방식

ReAct 모드

• 함수 호출 기능이 없는 모델용
• 프롬프트 기반의 추론 (reasoning) 및 행동 (action) 사용
• 모든 텍스트 완성 (text-completion) 모델과 호환 가능