---
title: 소방 복무관리 RAG 챗봇
emoji: 🚒
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: "5.0.0"
app_file: app.py
pinned: false
---

# 🚒 소방 복무관리 RAG 챗봇

소방공무원 복무관리 규정 및 절차에 대한 질문에 답변해 드리는 RAG(Retrieval-Augmented Generation) 기반 챗봇입니다.

## 📋 프로젝트 개요

- **목적**: 소방업무 복무관리 관련 문서들을 활용한 지능형 질의응답 시스템
- **기술**: RAG, OpenAI GPT, Supabase pgvector, Sentence-BERT, Gradio
- **문서 유형**: PDF, Word, TXT, Excel, CSV
- **특징**: 한국어 최적화, 실시간 검색, 클라우드 벡터 DB, 웹 인터페이스

## 🎯 주요 기능

### ✅ RAG 검색 시스템
- 문서 내용 자동 청킹
- 의미 기반 검색
- 유사도 측정
- 다중 문서 검색

### ✅ 인터페이스
- Gradio 기반 웹 채팅
- 실시간 응답
- 출처 정보 표시
- 신뢰도 점수 제공

### ✅ 문서 처리
- 다양한 파일 형식 지원 (PDF, DOCX, TXT, XLSX, CSV)
- 한국어 텍스트 전처리
- 소방 용어 최적화
- 동적 문서 추가

## 🏗️ 시스템 아키텍처

```
📂 문서 폴더
   ↓
📄 문서 처리기 (DocumentProcessor)
   ↓
🧠 임베딩 모델 (Sentence-BERT)
   ↓
🔍 벡터 DB (FAISS)
   ↓
💬 RAG 챗봇 (Chatbot)
   ↓
🌐 웹 인터페이스 (Gradio)
```

## 🚀 시작하기

### 1. 환경 설정

```bash
# 1. 저장소 복제
git clone <repository-url>
cd 119_chatbot

# 2. Python 가상환경 생성
python -m venv venv

# 3. 가상환경 활성화
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 4. 라이브러리 설치
pip install -r requirements.txt
```

### 2. OpenAI API 설정 (권장)

```bash
# OpenAI API Key 발급: https://platform.openai.com/api-keys
# .env 파일에 설정
echo "OPENAI_API_KEY=sk-your-api-key-here" >> .env
```

### 3. Supabase 설정 (권장 - 클라우드 벡터 DB)

```bash
# 1. Supabase 프로젝트 생성: https://supabase.com
# 2. SQL Editor에서 supabase_setup.sql 실행
# 3. Settings > API에서 URL과 Key 확인

# .env 파일에 Supabase 설정 추가
echo "SUPABASE_URL=https://your-project.supabase.co" >> .env
echo "SUPABASE_KEY=your-supabase-anon-key" >> .env
echo "VECTOR_DB_TYPE=supabase" >> .env
```

### 4. 문서 준비

```bash
# documents 폴더 생성
mkdir documents

# 복무관리 관련 문서 추가
# 지원 형식: .pdf, .docx, .txt, .xlsx, .csv
```

### 3. 로컬 실행

```bash
# 방법 1: 간단한 테스트
python document_processor.py

# 방법 2: 챗봇 테스트
python rag_chatbot.py

# 방법 3: 웹 인터페이스 실행
python gradio_interface.py

# 방법 4: 허깅페이스 배포용 실행
python app.py
```

## 📁 프로젝트 구조

```
119_chatbot/
├── app.py                     # 허깅페이스 배포용 메인 파일
├── config.py                 # 시스템 설정
├── requirements.txt          # 라이브러리 목록
├── README.md                # 프로젝트 설명서
├── .env.example             # 환경 변수 템플릿
├── supabase_setup.sql       # Supabase 설정 SQL
├── document_processor.py    # 문서 처리 모듈
├── vector_store.py          # FAISS 벡터 데이터베이스
├── supabase_vector_store.py # Supabase 벡터 데이터베이스
├── rag_chatbot.py           # 기존 RAG 챗봇
├── openai_chatbot.py        # OpenAI 기반 RAG 챗봇
├── gradio_interface.py      # Gradio 웹 인터페이스
├── documents/               # 문서 폴더
│   ├── 복무관리규정.txt
│   ├── 인사평가규정.txt
│   └── ...
└── faiss_index/             # 벡터 인덱스 캐시 (FAISS 사용시)
```

## ⚙️ 설정 옵션

### 환경 변수 설정 (.env 파일)

```bash
# OpenAI API (필수)
OPENAI_API_KEY=sk-your-openai-api-key
OPENAI_MODEL=gpt-4o-mini
OPENAI_EMBEDDING_MODEL=text-embedding-3-small

# Supabase (클라우드 벡터 DB 사용시 필수)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_KEY=your-supabase-anon-key

# 벡터 DB 타입 선택
VECTOR_DB_TYPE=supabase    # "supabase" 또는 "faiss"

# 관리자 보안 (필수)
ADMIN_PASSWORD=strong-password-here
```

### config.py 주요 설정

```python
# RAG 파라미터
CHUNK_SIZE = 500                            # 문서 청크 크기
CHUNK_OVERLAP = 50                          # 청크 중복 크기
MAX_RETRIEVE_DOCS = 3                       # 검색할 문서 수

# 기존 로컬 모델 설정 (FAISS 사용시)
EMBEDDING_MODEL = "jhgan/ko-sbert-nli"      # 한국어 임베딩 모델
LLM_MODEL = "beomi/Llama-3-Open-Ko-8B"      # 한국어 LLM

# 경로 설정
DOCS_FOLDER = "documents"                   # 문서 폴더
VECTOR_DB_PATH = "faiss_index"             # 벡터 DB 경로
```

### 🔄 벡터 DB 옵션

#### 1. Supabase (권장) - 클라우드 벡터 DB
- **장점**: 클라우드 저장, 확장성, 동시성, 실시간 동기화
- **필요사항**: OpenAI API Key, Supabase 프로젝트
- **설정**: `VECTOR_DB_TYPE=supabase`

#### 2. FAISS (로컬) - 오프라인 벡터 DB
- **장점**: 로컬 실행, 무료, 빠른 초기 설정
- **단점**: 로컬 저장 공간 필요, 확장성 제한
- **설정**: `VECTOR_DB_TYPE=faiss`

## 🧪 사용 예시

### 기본 질문

```
Q: 연차휴가 사용 방법을 알려주세요
A: 연차휴가는 1년간 정상 근무한 자에게 15일을 부여합니다.
   사용 시 3일 전까지 신청서를 제출하고 부서장의 승인을 받아야 합니다.

   📚 출처: 복무관리규정.txt (신뢰도: 92%)
```

### 고급 기능

```python
# 직접 코드로 사용
from rag_chatbot import RAGChatbot

# 챗봇 초기화
chatbot = RAGChatbot()
chatbot.initialize()

# 질문하고 답변 받기
response = chatbot.generate_answer("연차휴가 절차를 알려주세요")
print(response.answer)
```

## 🌐 배포 방법

### 1. 허깅페이스 Spaces

```bash
# 1. 허깅페이스 계정으로 로그인
huggingface-cli login

# 2. 새로운 Space 생성
# - Space 이름: fire-service-rag-chatbot
# - SDK: Gradio
# - Hardware: CPU Basic (무료)

# 3. 파일 업로드
git add .
git commit -m "초기 버전 배포"
git push origin main
```

### 2. 로컬 서버

```bash
# 포트 7860으로 실행
python app.py --port 7860

# 공유 링크 생성
python app.py --share
```

## 📊 성능 최적화

### 🔍 검색 성능 향상
- **Chunk 크기**: 500-1000 토큰으로 최적화
- **검색 문서 수**: 3-5개로 설정하여 속도와 정확도 균형
- **임베딩 모델**: 한국어 전용 모델 사용

### 💾 메모리 관리
- **캐싱**: 벡터 인덱스 로컬 저장
- **동적 로드**: 필요 시에만 LLM 모델 로드
- **청크 최적화**: 너무 긴 문서 분리

### ⚡ 응답 속도
- **템플릿 모드**: LLM 없이 빠른 응답
- **캐싱**: 자주 묻는 질문 응답 저장
- **비동기 처리**: 대용량 문서 처리 시 배치 작업

## 🔧 개발 가이드

### 새로운 문서 추가

```python
from document_processor import DocumentProcessor

# 문서 처리기 생성
processor = DocumentProcessor()

# 새 문서 로드
new_docs = processor.load_documents_from_folder("new_documents")

# 기존 문서에 추가
from vector_store import VectorStore
vector_store = VectorStore()
vector_store.add_documents(new_docs)
```

### 커스텀 프롬프트

```python
# config.py에서 시스템 프롬프트 수정
SYSTEM_PROMPT = """
당신은 소방 복무관리 전문가입니다...
[원하는 프롬프트 내용]
"""
```

## 🚨 주의사항

### 보안
- 민감한 개인정보가 포함된 문서는 업로드하지 마세요
- 법적 효력이 있는 최신 규정만 사용하세요
- 정기적으로 문서를 업데이트해야 합니다

### 성능
- 대용량 문서 처리 시 시간이 오래 걸릴 수 있습니다
- LLM 모델 로드 시 충분한 메모리가 필요합니다
- 무료 플랜의 경우 리소스 제한이 있을 수 있습니다

### 정확성
- 생성된 답변은 반드시 실제 규정과 교차 확인하세요
- 중요한 결정 시 반드시 담당자와 상담하세요
- 챗봇 답변을 법적 효력으로 사용하지 마세요

## 🤝 기여 방법

1. 이슈 등록: 버그나 개선사항 등록
2. 코드 제출: Pull Request를 통한 기여
3. 문서 개선: README나 코드 주석 개선
4. 테스트: 다양한 문서로 테스트 및 피드백

## 📞 문의

- 개발자: Claude (AI Assistant)
- 이메일: [개발자 이메일]
- 라이선스: MIT License

## 🙏 감사

- **Hugging Face**: 오픈소스 모델 및 플랫폼 제공
- **LangChain**: RAG 프레임워크 제공
- **Sentence-Transformers**: 한국어 임베딩 모델 제공
- **FAISS**: 고성능 벡터 검색 라이브러리 제공
- **Gradio**: 간편한 웹 인터페이스 제공

---

**⚠️ 본 챗봇은 보조 도구입니다. 중요한 업무 결정 시 반드시 관련 규정 원본과 담당자의 확인을 받으세요!**