Adaptive RAG: 모든 문서 + 웹검색 통합 (LangGraph + Ollama + E5)

한글 최적화 RAG 시스템으로 PDF, HWP를 포함한 다양한 문서 포맷을 읽고, 필요 시 웹 검색까지 수행하는 실전용 RAG 템플릿입니다.

• E5 다국어 임베딩으로 한글 검색 성능 최적화
• PDF, HWP 파일 지원 (hwp5txt 기반)
• Fast-then-Smart 하이브리드 라우팅 (Glossary → VectorStore → Web Search)
• Ollama + Qwen3:8b 기본, 다른 로컬 LLM도 교체 가능
• Windows 우선 친화 (PowerShell 스크립트 포함)

이 레포는 “모든 문서형태 + 웹검색”을 아우르는 RAG 툴킷입니다. 로컬 문서(PDF/HWP/TXT/CSV/JSON)에서 우선 검색하고, 필요 시 웹검색으로 보강합니다.

빠른 시작 (Windows PowerShell)

cd rag+web
python -m venv .venv
. .venv/Scripts/Activate.ps1

pip install --upgrade pip
pip install -r requirements.txt

# HWP 파일 처리를 위한 hwp5txt 설치 (선택사항)
# pip install hwp5

# Ollama 실행 (별도 터미널에서)
ollama serve

# 모델 설치 (필요시)
ollama pull qwen3:8b
ollama pull llama3.1:8b

# 실행
python app.py

중요: Ollama가 실행 중이어야 합니다: ollama serve
HWP 지원: hwp5txt 설치 시 HWP 파일 자동 처리

구조

rag+web/
├─ app.py                      # 엔트리포인트 (CLI/파이프라인)
├─ requirements.txt
├─ README.md
├─ src/adaptive_rag/
│  ├─ __init__.py
│  ├─ config.py                # 환경설정/모델 설정
│  ├─ embeddings.py            # E5 다국어 임베딩 모델
│  ├─ glossary.py              # 키워드 사전(빠른 경로)
│  ├─ vectorstore.py           # 로컬 문서 로딩/벡터스토어 초기화 (FAISS)
│  ├─ web_search.py            # Naver API + DuckDuckGo 웹 검색
│  ├─ nodes.py                 # LangGraph 노드들(라우팅/검색/생성/검증)
│  ├─ graph.py                 # 그래프 구성/컴파일
│  ├─ hwp5txt_loader.py        # HWP 파일 로더 (hwp5txt 기반)
│  ├─ improved_hwp_loader.py   # 개선된 HWP 로더 (olefile 기반)
│  ├─ cleaning.py              # 텍스트 정리 유틸
│  ├─ people.py                # people.json 처리
│  ├─ titanic.py               # titanic.csv 처리
│  ├─ retriever.py             # 하이브리드 검색
│  └─ utils.py                 # 공용 유틸
├─ data/
│  ├─ appendix-keywords-utf8.txt
│  ├─ people.json
│  ├─ titanic.csv
│  ├─ SPRI_AI_Brief_2023년12월호_F.pdf
│  ├─ 디지털 정부혁신 추진계획.hwp
│  └─ vectorstore_cache.pkl
└─ scripts/
   ├─ run.ps1                  # Windows 실행 스크립트
   ├─ run.bat                  # cmd 실행 스크립트
   └─ test_smoke.py            # 스모크 테스트

지원 문서 포맷 / 경로

• PDF: PyPDF 로딩, 한국어 페이지 아티팩트 정리
• HWP: hwp5txt 우선, olefile 기반 로더 폴백
• TXT: 일반 텍스트 파일 자동 인덱싱
• JSON: people.json 데모 스키마 지원
• CSV: titanic.csv 데모 스키마 지원

테스트 예시

• AI Brief 12월호에서 삼성 Gauss 요약해줘 → AI Brief PDF 검색
• 디지털 정부혁신 추진계획의 핵심 목표는? → HWP 파일 검색
• 삼성 가우스의 주요 특징은? → AI Brief PDF 검색
• 오늘 서울 날씨 어때? → Web Search 경로
• 홍길동 전화번호 알려줘 → people.json(데모) 경로

주요 특징

• E5 다국어 임베딩: 한글 검색 성능 최적화 (intfloat/multilingual-e5-small)
• HWP 파일 지원: hwp5txt 기반으로 한글 HWP 파일 자동 처리
• PDF 파일 지원: PyPDF 기반으로 PDF 문서 처리
• 한/영 동시 검색: "가우스"와 "Gauss" 동시 검색 지원
• 카테고리별 라우팅: AI Brief, 정부혁신, people, titanic 자동 분류
• 직접 답변 + 품질 게이트: 일반상식/계산 등은 직접답변 경로, 이후 환각/적합성 검사(자가치유 루프)
• MMR 재랭킹: 유사 문서 중 다양성을 반영하여 상위 문서 선별
• 품질 게이트: 재랭킹/문서평가 후 기준 미달 시 웹 검색 승격
• 캐시 시스템: 벡터스토어 캐시, 임베딩 캐시로 성능 최적화
• 모듈화: LLM/임베딩/검색엔진 교체가 쉽도록 의존성 분리

기술 스택

• LLM: Ollama (Qwen3:8b, Llama3.1:8b)
• 임베딩: E5 Multilingual (intfloat/multilingual-e5-small)
• 벡터스토어: FAISS
• 문서 처리: PyPDF, hwp5txt, olefile
• 웹 검색: Naver API, DuckDuckGo
• 프레임워크: LangGraph, LangChain

설치 및 실행

1. 환경 설정

# 가상환경 생성 및 활성화
python -m venv .venv
. .venv/Scripts/Activate.ps1  # Windows PowerShell
# source .venv/bin/activate    # Linux/Mac

# 의존성 설치
pip install -r requirements.txt

2. HWP 파일 지원 (선택사항)

# HWP 파일 처리를 위한 hwp5txt 설치
pip install hwp5

3. Ollama 설정

# Ollama 서버 실행 (별도 터미널)
ollama serve

# 모델 설치
ollama pull qwen3:8b
ollama pull llama3.1:8b

4. 실행

python app.py

5. 통합 테스트 (선택)

python -m pytest -q
python scripts/run_pipeline.py

테스트

# 스모크 테스트 실행
python scripts/test_smoke.py

배포/주의사항

• .env 파일은 절대 커밋하지 마세요 (API 키, 비밀 설정 포함)
• 대용량 바이너리(모델, 개인 문서)는 원격 저장소에 올리지 않는 것을 권장합니다
• data/vectorstore_cache.pkl은 자동 생성 캐시로 커밋 대상이 아닙니다

라이선스

MIT