README.md

metadata

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. 환경 설정

# 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 설정 (권장)

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

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

# 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. 문서 준비

# documents 폴더 생성
mkdir documents

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

3. 로컬 실행

# 방법 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 파일)

# 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 주요 설정

# 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%)

고급 기능

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

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

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

🌐 배포 방법

1. 허깅페이스 Spaces

# 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. 로컬 서버

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

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

📊 성능 최적화

🔍 검색 성능 향상

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

💾 메모리 관리

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

⚡ 응답 속도

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

🔧 개발 가이드

새로운 문서 추가

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)

커스텀 프롬프트

# 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: 간편한 웹 인터페이스 제공

---

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