🤖 RAG chatbot for Python 3.13 document

이 프로젝트는 파이썬 공식 문서를 기반으로 정확한 답변을 제공하는 RAG(Retrieval-Augmented Generation) 시스템입니다.

ChromaDB(Vector)와 BM25(Keyword)를 결합한 하이브리드 검색을 지원하며, 문서의 구조를 고려한 헤더(Header) 기반 청킹과 문단(Paragraph) 기반 청킹 전략을 비교/선택하여 사용할 수 있습니다.

✨ 주요 기능

• 하이브리드 검색 (Hybrid Search): 의미 기반의 Vector 검색(ChromaDB)과 키워드 기반의 BM25 검색을 결합하여 검색 정확도를 극대화했습니다. (Ensemble Retriever)
• 다양한 청킹 전략 (Chunking Strategies):
  • header: 문서의 헤더(****, ====, ----) 구조를 인식하여 의미 단위로 문서를 분할합니다.
  • paragraph: 문단 단위로 문서를 분할합니다.
• RAGAS 평가 시스템: Faithfulness, Answer Relevancy, Context Recall 등 전문 지표를 통해 RAG 성능을 정량적으로 평가합니다.
• 직관적인 Web UI: Streamlit을 활용한 깔끔한 채팅 인터페이스를 제공하며, 참고한 문서(Source)를 시각적으로 확인할 수 있습니다.

📂 폴더 구조

rag-for-programming-document
├── src/                    # 핵심 로직 (Backend)
│   ├── config/             # 설정 관리
│   ├── data_preprocessing/ # 문서 로드, 전처리, 청킹
│   ├── embeddings/         # 임베딩 및 벡터 스토어 관리
│   ├── retrieval/          # 검색기 (Hybrid Retriever)
│   ├── generation/         # LLM 및 RAG 체인
│   ├── evaluation/         # RAGAS 평가 로직
│   └── utils/              # 로거 등 유틸리티
├── ui/                     # Streamlit UI (Frontend)
│   ├── components/         # 사이드바, 채팅창 컴포넌트
│   └── styles/             # Custom CSS
├── data/                   # 데이터 저장소
│   ├── raw/                # RAG에 학습시킬 파이썬 공식 문서
│   └── vector_db_*/        # [자동 생성] 벡터 DB 및 BM25 인덱스
├── main.py                 # CLI 실행 엔트리 포인트
└── requirements.txt        # 의존성 패키지 목록

🚀 설치 및 설정

1. 환경 설정

Python 3.10 이상을 권장합니다.

# 저장소 클론
git clone "https://github.com/ApplesHUFS/rag-for-python-document.git"

# 가상환경 생성
python -m venv venv

# 가상환경 활성화 (Windows)
.\venv\Scripts\activate

# 가상환경 활성화 (Mac/Linux)
source venv/bin/activate

2. 패키지 설치

pip install -r requirements.txt

3. 환경 변수 설정 (.env)

프로젝트 루트에 .env 파일을 생성하고 OpenAI API 키를 입력하세요.

cp .env.example .env
OPENAI_API_KEY=sk-your-openai-api-key-here

---

💻 사용 방법 (Usage)

이 프로젝트는 터미널(CLI)과 웹 인터페이스(UI) 두 가지 방식으로 사용할 수 있습니다.

1단계: 데이터 준비

data/raw/ 폴더에 파이썬 공식 문서(.txt) 파일이 들어있는 폴더를 넣어주세요.

파이썬 공식 홈페이지 바로가기: https://docs.python.org/ko/3/download.html

2단계: 데이터베이스 구축

RAG를 실행하기 전에 문서를 청킹하고 DB를 전략별로 구축해야 합니다.

# 헤더 기반 전략으로 DB 구축
python main.py --mode build --chunk_strategy header

# 문단 기반 전략으로 DB 구축
python main.py --mode build --chunk_strategy paragraph

빌드가 완료되면 data/vector_db_header 폴더 내에 chroma.sqlite3와 bm25_index.pkl 파일이 생성됩니다.

3단계: 웹 UI 실행

브라우저에서 채팅을 나눌 수 있습니다.

streamlit run ui/app.py

• 브라우저가 열리면 사이드바에서 청킹 전략을 선택할 수 있습니다.
• 만약 "DB가 없습니다"라는 에러가 뜨면 **2단계(빌드)**를 먼저 수행해주세요.

4단계: CLI에서 바로 질문하기 (Optional)

python main.py --mode query --query "파이썬의 GIL이 뭐야?" --chunk_strategy header

---

📊 분석 및 평가

RAGAS 성능 평가 (Evaluate)

data/test_samples.json 파일에 질문(question)과 모범 답안(Ground Truth) 쌍을 미리 준비해야 합니다.

data/test_samples.json 예시:

[
  {
    "question": "파이썬의 창시자는?",
    "ground_truth": "귀도 반 로섬입니다."
  }
]

평가 실행:

python main.py --mode evaluate

• header와 paragraph 전략을 비교 평가하여 evaluation_report.csv를 생성합니다.

---

📄 라이선스 (License)

이 프로젝트는 MIT 라이선스에 따라 배포됩니다.

자유롭게 수정 및 배포가 가능하며, 자세한 내용은 LICENSE 파일을 참조해 주세요.