Spaces:
Sleeping
Sleeping
| 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**: 간편한 웹 인터페이스 제공 | |
| --- | |
| **⚠️ 본 챗봇은 보조 도구입니다. 중요한 업무 결정 시 반드시 관련 규정 원본과 담당자의 확인을 받으세요!** | |