Add application file

.env.example

@@ -0,0 +1,7 @@
+# API 서버 설정
+API_BASE_URL=http://localhost:8000
+PORT=5000
+
+# VITO STT API 키
+VITO_CLIENT_ID=your_vito_client_id
+VITO_CLIENT_SECRET=your_vito_client_secret

Dockerfile

@@ -0,0 +1,13 @@
+FROM python:3.9-slim
+
+WORKDIR /app
+
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+
+COPY . .
+
+ENV PORT=7860
+ENV API_BASE_URL=https://your-deployed-api-url.com
+
+CMD gunicorn app:app --bind 0.0.0.0:7860

README.md

@@ -11,3 +11,15 @@ license: mit
 ---
 
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+
+# RAG 챗봇 클라이언트
+
+RAG(Retrieval-Augmented Generation) 시스템을 위한 웹 클라이언트 애플리케이션입니다.
+RAG API와 연동되어 질의응답 서비스를 제공하며, VITO STT를 활용한 음성 인식 기능이 포함되어 있습니다.
+
+## 기능
+
+- 텍스트 기반 질의응답 대화
+- VITO STT를 활용한 음성 인식 질의
+- 지식베이스 문서 관리 (업로드 및 목록 조회)
+- 직관적인 웹 인터페이스

app.py

@@ -1,277 +1,188 @@
-"""
-RAG 챗봇 웹 클라이언트 애플리케이션
-
-Docker 기반 RAG API와 통신하는 웹 인터페이스를 제공합니다.
-VITO STT 기능을 통한 음성 질의도 지원합니다.
-"""
-
-import os
-import json
-import logging
-import tempfile
+import streamlit as st
 import requests
-from flask import Flask, request, jsonify, render_template, send_from_directory
-from werkzeug.utils import secure_filename
+import tempfile
+import os
 from dotenv import load_dotenv
+import json
 
+# VITO STT 클래스 임포트
 from utils.vito_stt import VitoSTT
 
-# 로거 설정
-logging.basicConfig(
-    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
-    level=logging.INFO
-)
-logger = logging.getLogger(__name__)
-
 # 환경 변수 로드
 load_dotenv()
 
-# Flask 앱 초기화
-app = Flask(__name__)
-
-# 최대 파일 크기 설정 (10MB)
-app.config['MAX_CONTENT_LENGTH'] = 10 * 1024 * 1024
-app.config['UPLOAD_FOLDER'] = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'uploads')
-
-# 업로드 폴더가 없으면 생성
-os.makedirs(app.config['UPLOAD_FOLDER'], exist_ok=True)
+# 페이지 구성
+st.set_page_config(
+    page_title="RAG 챗봇",
+    page_icon="🤖",
+    layout="wide"
+)
 
 # RAG API 설정
-API_BASE_URL = os.getenv('API_BASE_URL', 'http://localhost:8000')
-
-# 허용되는 오디오 파일 확장자
-ALLOWED_AUDIO_EXTENSIONS = {'mp3', 'wav', 'ogg', 'm4a'}
-
-# 허용되는 문서 파일 확장자
-ALLOWED_DOC_EXTENSIONS = {'txt', 'md', 'pdf', 'docx', 'csv'}
+API_BASE_URL = os.getenv('API_BASE_URL', 'https://your-deployed-api-url.com')
 
 # VITO STT 클라이언트 초기화
 stt_client = VitoSTT()
 
-def allowed_audio_file(filename):
-    """파일이 허용된 오디오 확장자를 가지는지 확인"""
-    return '.' in filename and filename.rsplit('.', 1)[1].lower() in ALLOWED_AUDIO_EXTENSIONS
+# 세션 상태 초기화
+if 'messages' not in st.session_state:
+    st.session_state.messages = []
+if 'sources' not in st.session_state:
+    st.session_state.sources = []
 
-def allowed_doc_file(filename):
-    """파일이 허용된 문서 확장자를 가지는지 확인"""
-    return '.' in filename and filename.rsplit('.', 1)[1].lower() in ALLOWED_DOC_EXTENSIONS
-
-@app.route('/')
-def index():
-    """메인 페이지"""
-    return render_template('index.html')
-
-@app.route('/chat')
-def chat():
-    """채팅 페이지"""
-    return render_template('chat.html')
-
-@app.route('/knowledge')
-def knowledge():
-    """지식베이스 관리 페이지"""
-    return render_template('knowledge.html')
-
-@app.route('/api/chat', methods=['POST'])
-def api_chat():
-    """텍스트 채팅 API"""
-    try:
-        data = request.get_json()
-        if not data or 'query' not in data:
-            return jsonify({"error": "쿼리가 제공되지 않았습니다."}), 400
-        
-        query = data['query']
-        logger.info(f"쿼리 처리 중: {query}")
-        
-        # RAG API 호출
-        response = requests.post(
-            f"{API_BASE_URL}/rag",
-            json={
-                "query": query,
-                "retriever_type": data.get("retriever_type", "reranker"),
-                "top_k": data.get("top_k", 3),
-                "temperature": data.get("temperature", 0.7)
-            }
-        )
-        
-        # API 응답 확인
-        if response.status_code != 200:
-            logger.error(f"API 오류: {response.status_code} - {response.text}")
-            return jsonify({"error": f"API 오류: {response.text}"}), response.status_code
-        
-        # API 응답 반환
-        result = response.json()
-        logger.info(f"API 응답 성공: {len(result['answer'])} 문자")
-        return jsonify(result)
-        
-    except requests.RequestException as e:
-        logger.error(f"API 통신 오류: {str(e)}")
-        return jsonify({"error": f"API 서버 연결 오류: {str(e)}"}), 503
-        
-    except Exception as e:
-        logger.error(f"채팅 처리 중 오류: {str(e)}", exc_info=True)
-        return jsonify({"error": f"처리 중 오류 발생: {str(e)}"}), 500
-
-@app.route('/api/voice', methods=['POST'])
-def api_voice():
-    """음성 채팅 API - 오디오 파일을 텍스트로 변환하고 RAG API에 질의"""
-    logger.info("음성 채팅 요청 처리 중...")
+# 사이드바 설정
+with st.sidebar:
+    st.title("🤖 RAG 챗봇")
+    st.write("Retrieval-Augmented Generation 기반 챗봇 서비스")
+    
+    st.subheader("⚙️ 설정")
+    retriever_type = st.selectbox(
+        "검색 엔진",
+        ["reranker", "vector"],
+        index=0
+    )
     
-    # 오디오 파일 확인
-    if 'audio' not in request.files:
-        logger.error("오디오 파일이 제공되지 않음")
-        return jsonify({"error": "오디오 파일이 제공되지 않았습니다."}), 400
+    top_k = st.slider(
+        "참고 문서 수 (Top-K)",
+        min_value=1,
+        max_value=10,
+        value=3
+    )
     
-    audio_file = request.files['audio']
+    temperature = st.slider(
+        "다양성 (Temperature)",
+        min_value=0.0,
+        max_value=1.0,
+        value=0.7,
+        step=0.1
+    )
     
-    if audio_file.filename == '':
-        logger.error("오디오 파일명이 비어있음")
-        return jsonify({"error": "오디오 파일이 선택되지 않았습니다."}), 400
+    st.divider()
     
-    if not allowed_audio_file(audio_file.filename):
-        logger.error(f"허용되지 않는 오디오 파일 형식: {audio_file.filename}")
-        return jsonify({"error": "허용되지 않는 오디오 파일 형식입니다."}), 400
+    st.subheader("📚 참고 문서")
+    if st.session_state.sources:
+        for i, source in enumerate(st.session_state.sources):
+            with st.expander(f"{i+1}. {source.get('metadata', {}).get('category', '일반')}"):
+                st.write(source.get('content', ''))
+    else:
+        st.info("참고 문서가 여기에 표시됩니다")
+
+# 메인 영역
+st.title("💬 RAG 챗봇")
+
+# 저장된 대화 표시
+for message in st.session_state.messages:
+    with st.chat_message(message["role"]):
+        st.write(message["content"])
+
+# 사용자 입력
+query = st.chat_input("질문을 입력하세요...")
+
+# 음성 입력 옵션
+audio_input = st.file_uploader("또는 음성으로 질문하기", type=["wav", "mp3", "ogg", "m4a"])
+
+if query:
+    # 사용자 메시지 추가
+    st.session_state.messages.append({"role": "user", "content": query})
+    with st.chat_message("user"):
+        st.write(query)
     
-    try:
-        # 오디오 파일 임시 저장
-        filename = secure_filename(audio_file.filename)
-        temp_dir = tempfile.mkdtemp()
-        temp_path = os.path.join(temp_dir, filename)
-        audio_file.save(temp_path)
-        
-        logger.info(f"오디오 파일 임시 저장: {temp_path}")
-        
-        # 파일을 바이트로 읽기
-        with open(temp_path, 'rb') as f:
-            audio_bytes = f.read()
-        
-        # VITO STT를 사용하여 음성 인식
-        stt_result = stt_client.transcribe_audio(audio_bytes)
-        
-        # 임시 파일 삭제
-        os.unlink(temp_path)
-        os.rmdir(temp_dir)
-        
-        if not stt_result["success"]:
-            logger.error(f"STT 오류: {stt_result.get('error', '알 수 없는 오류')}")
-            return jsonify({"error": f"음성 인식 오류: {stt_result.get('error', '알 수 없는 오류')}"}), 500
-        
-        transcription = stt_result["text"]
-        if not transcription:
-            logger.warning("STT 결과가 비어있음")
-            return jsonify({"error": "음성에서 텍스트를 인식하지 못했습니다."}), 400
-        
-        logger.info(f"음성 인식 결과: {transcription}")
-        
-        # RAG API 호출
+    # 챗봇 응답 영역
+    with st.chat_message("assistant"):
+        with st.spinner("답변 생성 중..."):
+            try:
+                # RAG API 요청
+                response = requests.post(
+                    f"{API_BASE_URL}/rag",
+                    json={
+                        "query": query,
+                        "retriever_type": retriever_type,
+                        "top_k": top_k,
+                        "temperature": temperature
+                    },
+                    timeout=30
+                )
+                
+                if response.status_code == 200:
+                    result = response.json()
+                    answer = result.get("answer", "")
+                    context_docs = result.get("context_docs", [])
+                    
+                    # 응답 표시
+                    st.markdown(answer)
+                    
+                    # 세션 상태 업데이트
+                    st.session_state.messages.append({"role": "assistant", "content": answer})
+                    st.session_state.sources = context_docs
+                else:
+                    st.error(f"API 오류: {response.status_code} - {response.text}")
+            except Exception as e:
+                st.error(f"오류 발생: {str(e)}")
+
+# 음성 입력 처리
+if audio_input:
+    with st.spinner("음성 처리 중..."):
         try:
-            response = requests.post(
-                f"{API_BASE_URL}/rag",
-                json={
-                    "query": transcription,
-                    "retriever_type": "reranker",
-                    "top_k": 3
-                }
-            )
+            # 임시 파일로 저장
+            with tempfile.NamedTemporaryFile(delete=False, suffix='.wav') as tmp:
+                tmp.write(audio_input.getvalue())
+                tmp_path = tmp.name
             
-            if response.status_code != 200:
-                logger.error(f"RAG API 오류: {response.status_code} - {response.text}")
-                return jsonify({
-                    "transcription": transcription,
-                    "error": f"RAG API 오류: {response.text}"
-                }), response.status_code
+            # 파일 읽기
+            with open(tmp_path, 'rb') as f:
+                audio_bytes = f.read()
             
-            # API 결과에 음성 인식 결과 추가
-            result = response.json()
-            result["transcription"] = transcription
+            # 임시 파일 삭제
+            os.unlink(tmp_path)
             
-            logger.info("음성 처리 및 RAG 응답 성공")
-            return jsonify(result)
+            # VITO STT 처리
+            stt_result = stt_client.transcribe_audio(audio_bytes)
             
-        except requests.RequestException as e:
-            logger.error(f"RAG API 통신 오류: {str(e)}")
-            return jsonify({
-                "transcription": transcription,
-                "error": f"RAG API 서버 연결 오류: {str(e)}"
-            }), 503
-        
-    except Exception as e:
-        logger.error(f"음성 처리 중 오류: {str(e)}", exc_info=True)
-        return jsonify({"error": f"음성 처리 중 오류 발생: {str(e)}"}), 500
-
-@app.route('/api/documents', methods=['GET'])
-def api_get_documents():
-    """문서 목록 조회 API"""
-    try:
-        # RAG API 호출
-        response = requests.get(f"{API_BASE_URL}/cache/stats")
-        
-        if response.status_code != 200:
-            logger.error(f"문서 목록 조회 API 오류: {response.status_code} - {response.text}")
-            return jsonify({"error": f"문서 목록 조회 API 오류: {response.text}"}), response.status_code
-        
-        # 캐시 통계 정보 반환
-        return jsonify(response.json())
-        
-    except requests.RequestException as e:
-        logger.error(f"API 통신 오류: {str(e)}")
-        return jsonify({"error": f"API 서버 연결 오류: {str(e)}"}), 503
-        
-    except Exception as e:
-        logger.error(f"문서 목록 조회 중 오류: {str(e)}", exc_info=True)
-        return jsonify({"error": f"처리 중 오류 발생: {str(e)}"}), 500
-
-@app.route('/api/upload', methods=['POST'])
-def api_upload_document():
-    """문서 업로드 API"""
-    # 파일 확인
-    if 'document' not in request.files:
-        return jsonify({"error": "문서 파일이 제공되지 않았습니다."}), 400
-    
-    doc_file = request.files['document']
-    
-    if doc_file.filename == '':
-        return jsonify({"error": "문서 파일이 선택되지 않았습니다."}), 400
-    
-    if not allowed_doc_file(doc_file.filename):
-        return jsonify({"error": "허용되지 않는 문서 파일 형식입니다."}), 400
-    
-    try:
-        # 파일 임시 저장
-        filename = secure_filename(doc_file.filename)
-        temp_dir = tempfile.mkdtemp()
-        temp_path = os.path.join(temp_dir, filename)
-        doc_file.save(temp_path)
-        
-        logger.info(f"문서 파일 임시 저장: {temp_path}")
-        
-        # 파일을 멀티파트 폼으로 업로드
-        with open(temp_path, 'rb') as f:
-            files = {'document': (filename, f)}
-            response = requests.post(f"{API_BASE_URL}/documents/upload", files=files)
-        
-        # 임시 파일 삭제
-        os.unlink(temp_path)
-        os.rmdir(temp_dir)
-        
-        if response.status_code not in (200, 201):
-            logger.error(f"문서 업로드 API 오류: {response.status_code} - {response.text}")
-            return jsonify({"error": f"문서 업로드 API 오류: {response.text}"}), response.status_code
-        
-        return jsonify(response.json())
-        
-    except requests.RequestException as e:
-        logger.error(f"API 통신 오류: {str(e)}")
-        return jsonify({"error": f"API 서버 연결 오류: {str(e)}"}), 503
-        
-    except Exception as e:
-        logger.error(f"문서 업로드 중 오류: {str(e)}", exc_info=True)
-        return jsonify({"error": f"처리 중 오류 발생: {str(e)}"}), 500
-
-# 정적 파일 서빙
-@app.route('/static/<path:path>')
-def send_static(path):
-    return send_from_directory('static', path)
-
-if __name__ == '__main__':
-    port = int(os.getenv('PORT', 5000))
-    app.run(debug=True, host='0.0.0.0', port=port)
+            if stt_result["success"]:
+                transcription = stt_result["text"]
+                if transcription:
+                    st.success(f"인식된 텍스트: {transcription}")
+                    
+                    # 사용자 메시지 추가
+                    st.session_state.messages.append({"role": "user", "content": transcription})
+                    with st.chat_message("user"):
+                        st.write(transcription)
+                    
+                    # 챗봇 응답 영역
+                    with st.chat_message("assistant"):
+                        with st.spinner("답변 생성 중..."):
+                            try:
+                                # RAG API 요청
+                                response = requests.post(
+                                    f"{API_BASE_URL}/rag",
+                                    json={
+                                        "query": transcription,
+                                        "retriever_type": retriever_type,
+                                        "top_k": top_k,
+                                        "temperature": temperature
+                                    },
+                                    timeout=30
+                                )
+                                
+                                if response.status_code == 200:
+                                    result = response.json()
+                                    answer = result.get("answer", "")
+                                    context_docs = result.get("context_docs", [])
+                                    
+                                    # 응답 표시
+                                    st.markdown(answer)
+                                    
+                                    # 세션 상태 업데이트
+                                    st.session_state.messages.append({"role": "assistant", "content": answer})
+                                    st.session_state.sources = context_docs
+                                else:
+                                    st.error(f"API 오류: {response.status_code} - {response.text}")
+                            except Exception as e:
+                                st.error(f"오류 발생: {str(e)}")
+                else:
+                    st.warning("음성에서 텍스트를 인식하지 못했습니다.")
+            else:
+                st.error(f"음성 인식 오류: {stt_result.get('error', '알 수 없는 오류')}")
+                
+        except Exception as e:
+            st.error(f"음성 처리 중 오류: {str(e)}")

requirements.txt

@@ -0,0 +1,5 @@
+flask==2.2.3
+requests==2.28.2
+python-dotenv==1.0.0
+Werkzeug==2.2.3
+streamlit==1.29.0

static/css/style.css

@@ -0,0 +1,181 @@
+/* 공통 스타일 */
+body {
+    background-color: #f8f9fa;
+    min-height: 100vh;
+    display: flex;
+    flex-direction: column;
+}
+
+footer {
+    margin-top: auto;
+}
+
+/* 채팅 영역 스타일 */
+.chat-messages {
+    max-height: 500px;
+    overflow-y: auto;
+    padding-right: 5px;
+}
+
+/* 사용자 및 봇 메시지 공통 스타일 */
+.chat-message {
+    margin-bottom: 15px;
+}
+
+.message-avatar {
+    width: 40px;
+    height: 40px;
+    border-radius: 50%;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    margin-right: 15px;
+    flex-shrink: 0;
+}
+
+.message-content {
+    flex-grow: 1;
+    background-color: #ffffff;
+    border-radius: 12px;
+    padding: 12px 15px;
+    box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+    position: relative;
+}
+
+/* 사용자 메시지 스타일 */
+.user-message .message-content {
+    background-color: #e9f5ff;
+    border: 1px solid #cce5ff;
+}
+
+/* 봇 메시지 스타일 */
+.bot-message .message-content {
+    background-color: #ffffff;
+    border: 1px solid #e9ecef;
+}
+
+/* 메시지 텍스트 스타일 */
+.message-text {
+    white-space: pre-wrap;
+    word-break: break-word;
+}
+
+.message-text code {
+    background-color: #f5f5f5;
+    padding: 2px 4px;
+    border-radius: 4px;
+    font-family: 'Courier New', monospace;
+}
+
+.message-text pre {
+    background-color: #f5f5f5;
+    padding: 10px;
+    border-radius: 5px;
+    margin: 10px 0;
+    overflow-x: auto;
+}
+
+.message-text blockquote {
+    border-left: 4px solid #ced4da;
+    padding-left: 15px;
+    color: #6c757d;
+    margin: 10px 0;
+}
+
+.message-metadata {
+    font-size: 0.85rem;
+    color: #6c757d;
+}
+
+/* 음성 입력 버튼 스타일 */
+#micButton.recording {
+    background-color: #dc3545;
+    animation: pulse 1.5s infinite;
+}
+
+@keyframes pulse {
+    0% {
+        opacity: 1;
+    }
+    50% {
+        opacity: 0.7;
+    }
+    100% {
+        opacity: 1;
+    }
+}
+
+/* 드롭존 스타일 */
+.dropzone {
+    border: 2px dashed #ccc;
+    border-radius: 5px;
+    background-color: #f8f9fa;
+    min-height: 150px;
+}
+
+.dropzone:hover {
+    border-color: #198754;
+}
+
+.dropzone .dz-preview {
+    margin: 10px;
+}
+
+/* 소스 목록 스타일 */
+.source-item {
+    border-left: 3px solid #28a745;
+    background-color: #f8f9fa;
+}
+
+.source-score {
+    width: 40px;
+    height: 40px;
+    border-radius: 50%;
+    background-color: #28a745;
+    color: white;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-weight: bold;
+}
+
+/* 상자 애니메이션 효과 */
+.fade-in {
+    animation: fadeIn 0.5s;
+}
+
+@keyframes fadeIn {
+    from { opacity: 0; }
+    to { opacity: 1; }
+}
+
+/* 스크롤바 스타일 */
+::-webkit-scrollbar {
+    width: 8px;
+}
+
+::-webkit-scrollbar-track {
+    background: #f1f1f1;
+    border-radius: 10px;
+}
+
+::-webkit-scrollbar-thumb {
+    background: #c1c1c1;
+    border-radius: 10px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+    background: #a1a1a1;
+}
+
+/* 모바일 반응형 스타일 */
+@media (max-width: 768px) {
+    .message-avatar {
+        width: 35px;
+        height: 35px;
+    }
+    
+    .message-content {
+        padding: 10px;
+    }
+}

static/js/app.js

@@ -0,0 +1,59 @@
+/**
+ * RAG 챗봇 클라이언트 - 공통 기능
+ */
+
+document.addEventListener('DOMContentLoaded', function() {
+    // API 기본 URL
+    const API_BASE_URL = window.location.origin;
+    
+    // 상태 확인 함수
+    async function checkApiStatus() {
+        try {
+            const response = await fetch(`${API_BASE_URL}/api/status`);
+            const data = await response.json();
+            
+            if (data.ready) {
+                // API 서버 준비 완료
+                console.log('API 서버 준비 완료');
+                
+                // 로딩 페이지에서 왔다면 홈으로 리디렉션
+                if (window.location.pathname === '/loading') {
+                    window.location.href = '/';
+                }
+                
+                return true;
+            } else {
+                // API 서버 준비 중
+                console.log('API 서버 초기화 중...');
+                
+                // 로딩 페이지가 아니면 로딩 페이지로 리디렉션
+                if (window.location.pathname !== '/loading') {
+                    window.location.href = '/loading';
+                }
+                
+                return false;
+            }
+        } catch (err) {
+            console.error('API 서버 상태 확인 실패:', err);
+            
+            // 연결 오류 시 처리
+            const statusDisplay = document.getElementById('apiStatusDisplay');
+            if (statusDisplay) {
+                statusDisplay.innerHTML = `
+                    <div class="alert alert-danger">
+                        <i class="fas fa-exclamation-triangle me-2"></i>
+                        API 서버에 연결할 수 없습니다. 서버가 실행 중인지 확인하세요.
+                    </div>
+                `;
+            }
+            
+            return false;
+        }
+    }
+    
+    // 페이지 로드 시 API 상태 확인
+    checkApiStatus();
+    
+    // 주기적으로 API 상태 확인 (10초마다)
+    setInterval(checkApiStatus, 10000);
+});

static/js/chat.js

@@ -0,0 +1,407 @@
+/**
+ * RAG 챗봇 클라이언트 - 채팅 기능
+ * 텍스트 및 음성 대화 기능 구현
+ */
+
+document.addEventListener('DOMContentLoaded', function() {
+    // DOM 요소
+    const chatMessages = document.getElementById('chatMessages');
+    const userInput = document.getElementById('userInput');
+    const sendButton = document.getElementById('sendButton');
+    const micButton = document.getElementById('micButton');
+    const clearChat = document.getElementById('clearChat');
+    const recordingAlert = document.getElementById('recordingAlert');
+    const processingAlert = document.getElementById('processingAlert');
+    const typingAlert = document.getElementById('typingAlert');
+    const sourceList = document.getElementById('sourceList');
+    
+    // 설정 요소
+    const retrieverType = document.getElementById('retrieverType');
+    const topK = document.getElementById('topK');
+    const temperatureSlider = document.getElementById('temperature');
+    const temperatureValue = document.getElementById('temperatureValue');
+    
+    // 음성 녹음 관련 변수
+    let mediaRecorder;
+    let audioChunks = [];
+    let isRecording = false;
+    
+    // marked.js 설정 (마크다운 파서)
+    marked.setOptions({
+        renderer: new marked.Renderer(),
+        highlight: function(code, language) {
+            const validLang = hljs.getLanguage(language) ? language : 'plaintext';
+            return hljs.highlight(validLang, code).value;
+        },
+        gfm: true,
+        breaks: true
+    });
+    
+    // 채팅 기록 로드
+    loadChatHistory();
+    
+    // 이벤트 리스너 설정
+    
+    // 텍스트 입력 이벤트
+    userInput.addEventListener('keypress', function(e) {
+        if (e.key === 'Enter' && !e.shiftKey) {
+            e.preventDefault();
+            sendMessage();
+        }
+    });
+    
+    // 전송 버튼 클릭 이벤트
+    sendButton.addEventListener('click', sendMessage);
+    
+    // 마이크 버튼 클릭 이벤트
+    micButton.addEventListener('click', toggleRecording);
+    
+    // 녹음 알림 클릭 이벤트 (녹음 중지)
+    recordingAlert.addEventListener('click', stopRecording);
+    
+    // 대화 지우기 버튼 클릭 이벤트
+    clearChat.addEventListener('click', function() {
+        if (confirm('정말 대화 내용을 모두 지우시겠습니까?')) {
+            chatMessages.innerHTML = '';
+            sourceList.innerHTML = '<div class="list-group-item text-center text-muted"><i>참고 문서가 여기에 표시됩니다</i></div>';
+            localStorage.removeItem('chatHistory');
+        }
+    });
+    
+    // 온도 슬라이더 이벤트
+    temperatureSlider.addEventListener('input', function() {
+        temperatureValue.textContent = this.value;
+    });
+    
+    /**
+     * 텍스트 메시지 전송 함수
+     */
+    function sendMessage() {
+        const message = userInput.value.trim();
+        if (message === '') return;
+        
+        // 사용자 메시지 표시
+        addUserMessage(message);
+        userInput.value = '';
+        
+        // 설정 가져오기
+        const retriever = retrieverType.value;
+        const k = parseInt(topK.value);
+        const temperature = parseFloat(temperatureSlider.value);
+        
+        // 봇 응답 가져오기
+        getBotResponse(message, retriever, k, temperature);
+    }
+    
+    /**
+     * 음성 녹음 토글 함수
+     */
+    async function toggleRecording() {
+        if (!isRecording) {
+            startRecording();
+        } else {
+            stopRecording();
+        }
+    }
+    
+    /**
+     * 음성 녹음 시작 함수
+     */
+    async function startRecording() {
+        try {
+            const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+            mediaRecorder = new MediaRecorder(stream);
+            audioChunks = [];
+            
+            mediaRecorder.addEventListener('dataavailable', event => {
+                audioChunks.push(event.data);
+            });
+            
+            mediaRecorder.addEventListener('stop', async () => {
+                const audioBlob = new Blob(audioChunks, { type: 'audio/wav' });
+                await processAudio(audioBlob);
+            });
+            
+            mediaRecorder.start();
+            isRecording = true;
+            micButton.classList.add('recording');
+            recordingAlert.classList.remove('d-none');
+            
+        } catch (err) {
+            console.error('마이크 접근 오류:', err);
+            alert('마이크 접근에 실패했습니다. 마이크 권한을 확인해주세요.');
+        }
+    }
+    
+    /**
+     * 음성 녹음 중지 함수
+     */
+    function stopRecording() {
+        if (mediaRecorder && isRecording) {
+            mediaRecorder.stop();
+            isRecording = false;
+            micButton.classList.remove('recording');
+            recordingAlert.classList.add('d-none');
+            processingAlert.classList.remove('d-none');
+            
+            // 스트림 트랙 중지
+            mediaRecorder.stream.getTracks().forEach(track => track.stop());
+        }
+    }
+    
+    /**
+     * 녹음된 오디오 처리 함수
+     * @param {Blob} audioBlob - 녹음된 오디오 데이터
+     */
+    async function processAudio(audioBlob) {
+        try {
+            const formData = new FormData();
+            formData.append('audio', audioBlob, 'recording.wav');
+            
+            const response = await fetch('/api/voice', {
+                method: 'POST',
+                body: formData
+            });
+            
+            processingAlert.classList.add('d-none');
+            
+            if (!response.ok) {
+                const errorData = await response.json();
+                throw new Error(errorData.error || '음성 처리 중 오류가 발생했습니다.');
+            }
+            
+            const data = await response.json();
+            
+            // 인식된 텍스트가 있으면 사용자 메시지로 표시
+            if (data.transcription) {
+                addUserMessage(data.transcription);
+                
+                // 봇 응답이 있으면 표시
+                if (data.answer) {
+                    addBotMessage(data.answer, data.context_docs || []);
+                }
+            } else {
+                throw new Error('음성 인식에 실패했습니다.');
+            }
+            
+        } catch (err) {
+            console.error('음성 처리 오류:', err);
+            processingAlert.classList.add('d-none');
+            alert('음성 처리 중 오류가 발생했습니다: ' + err.message);
+        }
+    }
+    
+    /**
+     * API로부터 봇 응답 가져오기
+     * @param {string} message - 사용자 메시지
+     * @param {string} retriever - 검색기 유형
+     * @param {number} k - Top-K 문서 수
+     * @param {number} temperature - 생성 다양성
+     */
+    async function getBotResponse(message, retriever, k, temperature) {
+        try {
+            typingAlert.classList.remove('d-none');
+            sourceList.innerHTML = '<div class="list-group-item text-center"><div class="spinner-border spinner-border-sm text-primary" role="status"></div><span class="ms-2">참고 문서 로딩중...</span></div>';
+            
+            const response = await fetch('/api/chat', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json'
+                },
+                body: JSON.stringify({
+                    query: message,
+                    retriever_type: retriever,
+                    top_k: k,
+                    temperature: temperature
+                })
+            });
+            
+            typingAlert.classList.add('d-none');
+            
+            if (!response.ok) {
+                const errorData = await response.json();
+                throw new Error(errorData.error || '응답을 가져오는 중 오류가 발생했습니다.');
+            }
+            
+            const data = await response.json();
+            addBotMessage(data.answer, data.context_docs || []);
+            
+        } catch (err) {
+            console.error('API 요청 오류:', err);
+            typingAlert.classList.add('d-none');
+            alert('봇 응답을 가져오는 중 오류가 발생했습니다: ' + err.message);
+        }
+    }
+    
+    /**
+     * 사용자 메시지 추가 함수
+     * @param {string} message - 사용자 메시지
+     */
+    function addUserMessage(message) {
+        const template = document.getElementById('userMessageTemplate');
+        const messageNode = template.content.cloneNode(true);
+        
+        messageNode.querySelector('.message-text').textContent = message;
+        chatMessages.appendChild(messageNode);
+        
+        // 스크롤 하단으로 이동
+        chatMessages.scrollTop = chatMessages.scrollHeight;
+        
+        // 채팅 기록 저장
+        saveChatHistory();
+    }
+    
+    /**
+     * 봇 메시지 추가 함수
+     * @param {string} message - 봇 메시지
+     * @param {Array} sources - 참고 문서 목록
+     */
+    function addBotMessage(message, sources) {
+        const template = document.getElementById('botMessageTemplate');
+        const messageNode = template.content.cloneNode(true);
+        
+        // 마크다운 변환 및 코드 하이라이트 적용
+        const sanitizedHTML = DOMPurify.sanitize(marked.parse(message));
+        messageNode.querySelector('.message-text').innerHTML = sanitizedHTML;
+        
+        // 코드 하이라이팅 적용
+        messageNode.querySelectorAll('pre code').forEach((block) => {
+            hljs.highlightBlock(block);
+        });
+        
+        chatMessages.appendChild(messageNode);
+        
+        // 스크롤 하단으로 이동
+        chatMessages.scrollTop = chatMessages.scrollHeight;
+        
+        // 참고 문서 표시
+        updateSourceList(sources);
+        
+        // 채팅 기록 저장
+        saveChatHistory();
+    }
+    
+    /**
+     * 참고 문서 목록 업데이트 함수
+     * @param {Array} sources - 참고 문서 목록
+     */
+    function updateSourceList(sources) {
+        sourceList.innerHTML = '';
+        
+        if (!sources || sources.length === 0) {
+            sourceList.innerHTML = '<div class="list-group-item text-center text-muted"><i>참고 문서가 없습니다</i></div>';
+            return;
+        }
+        
+        sources.forEach((source, index) => {
+            const sourceItem = document.createElement('div');
+            sourceItem.className = 'list-group-item source-item';
+            
+            const score = source.score || 0;
+            const scoreValue = Math.round(score * 100) / 100;
+            const scoreColor = getScoreColor(score);
+            
+            sourceItem.innerHTML = `
+                <div class="d-flex align-items-center">
+                    <div class="source-score me-3" style="background-color: ${scoreColor}">
+                        ${scoreValue.toFixed(2)}
+                    </div>
+                    <div>
+                        <h6 class="mb-0">${source.source || '문서 #' + (index + 1)}</h6>
+                        <div class="small text-muted">관련성 점수: ${scoreValue.toFixed(2)}</div>
+                    </div>
+                </div>
+            `;
+            
+            sourceList.appendChild(sourceItem);
+        });
+    }
+    
+    /**
+     * 점수 색상 계산 함수
+     * @param {number} score - 관련성 점수 (0-1)
+     * @returns {string} - 색상 코드
+     */
+    function getScoreColor(score) {
+        if (score >= 0.8) return '#198754'; // 높은 관련성 (초록색)
+        if (score >= 0.6) return '#0d6efd'; // 중간 관련성 (파란색)
+        if (score >= 0.4) return '#fd7e14'; // 낮은 관련성 (주황색)
+        return '#6c757d'; // 매우 낮은 관련성 (회색)
+    }
+    
+    /**
+     * 채팅 기록 저장 함수
+     */
+    function saveChatHistory() {
+        const history = {
+            messages: [],
+            sources: []
+        };
+        
+        // 메시지 저장
+        document.querySelectorAll('.chat-message').forEach(msg => {
+            const isUser = msg.classList.contains('user-message');
+            const text = msg.querySelector('.message-text').textContent || msg.querySelector('.message-text').innerHTML;
+            
+            history.messages.push({
+                isUser: isUser,
+                content: text
+            });
+        });
+        
+        // 참고 문서 저장
+        const sourcesHtml = sourceList.innerHTML;
+        history.sources = sourcesHtml;
+        
+        // 로컬 스토리지에 저장
+        localStorage.setItem('chatHistory', JSON.stringify(history));
+    }
+    
+    /**
+     * 채팅 기록 로드 함수
+     */
+    function loadChatHistory() {
+        const history = localStorage.getItem('chatHistory');
+        if (!history) return;
+        
+        try {
+            const historyData = JSON.parse(history);
+            
+            // 메시지 로드
+            historyData.messages.forEach(msg => {
+                if (msg.isUser) {
+                    const template = document.getElementById('userMessageTemplate');
+                    const messageNode = template.content.cloneNode(true);
+                    messageNode.querySelector('.message-text').textContent = msg.content;
+                    chatMessages.appendChild(messageNode);
+                } else {
+                    const template = document.getElementById('botMessageTemplate');
+                    const messageNode = template.content.cloneNode(true);
+                    
+                    // 마크다운 변환 및 코드 하이라이트 적용
+                    const sanitizedHTML = DOMPurify.sanitize(marked.parse(msg.content));
+                    messageNode.querySelector('.message-text').innerHTML = sanitizedHTML;
+                    
+                    // 코드 하이라이팅 적용
+                    messageNode.querySelectorAll('pre code').forEach((block) => {
+                        hljs.highlightBlock(block);
+                    });
+                    
+                    chatMessages.appendChild(messageNode);
+                }
+            });
+            
+            // 참고 문서 로드
+            if (historyData.sources) {
+                sourceList.innerHTML = historyData.sources;
+            }
+            
+            // 스크롤 하단으로 이동
+            chatMessages.scrollTop = chatMessages.scrollHeight;
+            
+        } catch (err) {
+            console.error('채팅 기록 로드 실패:', err);
+            localStorage.removeItem('chatHistory');
+        }
+    }
+});

static/js/knowledge.js

@@ -0,0 +1,272 @@
+/**
+ * RAG 챗봇 클라이언트 - 지식베이스 관리 기능
+ * 문서 업로드 및 지식베이스 상태 관리
+ */
+
+document.addEventListener('DOMContentLoaded', function() {
+    // DOM 요소
+    const uploadButton = document.getElementById('uploadButton');
+    const uploadSuccess = document.getElementById('uploadSuccess');
+    const uploadSuccessMessage = document.getElementById('uploadSuccessMessage');
+    const uploadError = document.getElementById('uploadError');
+    const uploadErrorMessage = document.getElementById('uploadErrorMessage');
+    const refreshStatus = document.getElementById('refreshStatus');
+    const databaseStats = document.getElementById('databaseStats');
+    const documentsContainer = document.getElementById('documentsContainer');
+    
+    // Dropzone 설정
+    Dropzone.autoDiscover = false;
+    
+    const documentUploadDropzone = new Dropzone("#documentUploadForm", {
+        url: "/api/upload",
+        maxFilesize: 10, // MB
+        acceptedFiles: ".txt,.md,.pdf,.docx,.csv",
+        addRemoveLinks: true,
+        dictDefaultMessage: "파일을 끌어다 놓거나 클릭하여 선택하세요",
+        dictRemoveFile: "제거",
+        dictCancelUpload: "업로드 취소",
+        dictUploadCanceled: "업로드 취소됨",
+        dictFileTooBig: "파일이 너무 큽니다 ({{filesize}}MB). 최대 파일 크기: {{maxFilesize}}MB.",
+        dictInvalidFileType: "이 형식의 파일은 업로드할 수 없습니다.",
+        autoProcessQueue: false,
+        maxFiles: 1
+    });
+    
+    // 파일이 추가되면 업로드 버튼 활성화
+    documentUploadDropzone.on("addedfile", function(file) {
+        uploadButton.disabled = false;
+        hideAlerts();
+    });
+    
+    // 파일이 제거되면 업로드 버튼 비활성화
+    documentUploadDropzone.on("removedfile", function(file) {
+        if (documentUploadDropzone.files.length === 0) {
+            uploadButton.disabled = true;
+        }
+    });
+    
+    // 업로드 버튼 클릭 이벤트
+    uploadButton.addEventListener('click', function() {
+        if (documentUploadDropzone.files.length > 0) {
+            uploadButton.disabled = true;
+            uploadButton.innerHTML = '<span class="spinner-border spinner-border-sm me-2" role="status"></span>업로드 중...';
+            documentUploadDropzone.processQueue();
+        }
+    });
+    
+    // 업로드 성공 이벤트
+    documentUploadDropzone.on("success", function(file, response) {
+        uploadButton.innerHTML = '<i class="fas fa-upload me-2"></i>업로드';
+        uploadButton.disabled = true;
+        
+        // 성공 메시지 표시
+        uploadSuccess.classList.remove('d-none');
+        uploadSuccessMessage.textContent = response.message || "문서가 성공적으로 업로드되었습니다.";
+        
+        // 파일 제거
+        documentUploadDropzone.removeFile(file);
+        
+        // 지식베이스 상태 새로고침
+        setTimeout(fetchDatabaseStats, 1000);
+        setTimeout(fetchDocuments, 1000);
+    });
+    
+    // 업로드 오류 이벤트
+    documentUploadDropzone.on("error", function(file, errorMessage, xhr) {
+        uploadButton.innerHTML = '<i class="fas fa-upload me-2"></i>업로드';
+        uploadButton.disabled = false;
+        
+        // 오류 메시지 표시
+        uploadError.classList.remove('d-none');
+        
+        if (typeof errorMessage === 'object' && errorMessage.error) {
+            uploadErrorMessage.textContent = errorMessage.error;
+        } else if (typeof errorMessage === 'string') {
+            uploadErrorMessage.textContent = errorMessage;
+        } else {
+            uploadErrorMessage.textContent = "업로드 중 오류가 발생했습니다.";
+        }
+    });
+    
+    // 새로고침 버튼 클릭 이벤트
+    refreshStatus.addEventListener('click', function() {
+        fetchDatabaseStats();
+        fetchDocuments();
+    });
+    
+    /**
+     * 알림창 숨기기
+     */
+    function hideAlerts() {
+        uploadSuccess.classList.add('d-none');
+        uploadError.classList.add('d-none');
+    }
+    
+    /**
+     * 지식베이스 상태 가져오기
+     */
+    async function fetchDatabaseStats() {
+        try {
+            databaseStats.innerHTML = `
+                <div class="d-flex justify-content-center align-items-center" style="height: 100px;">
+                    <div class="spinner-border text-primary" role="status">
+                        <span class="visually-hidden">Loading...</span>
+                    </div>
+                </div>
+            `;
+            
+            const response = await fetch('/api/documents');
+            
+            if (!response.ok) {
+                throw new Error('API 요청 실패');
+            }
+            
+            const data = await response.json();
+            
+            if (data.enabled === false) {
+                databaseStats.innerHTML = `
+                    <div class="alert alert-warning mb-0">
+                        <i class="fas fa-exclamation-triangle me-2"></i>캐시가 활성화되지 않았습니다.
+                    </div>
+                `;
+                return;
+            }
+            
+            const stats = data.stats || {};
+            
+            databaseStats.innerHTML = `
+                <div class="row text-center">
+                    <div class="col-6 border-end">
+                        <h3 class="mb-0">${stats.size || 0}</h3>
+                        <p class="text-muted mb-0">캐시 항목</p>
+                    </div>
+                    <div class="col-6">
+                        <h3 class="mb-0">${stats.max_size || 0}</h3>
+                        <p class="text-muted mb-0">최대 항목 수</p>
+                    </div>
+                </div>
+                <hr>
+                <div class="text-center">
+                    <p class="mb-0">캐시 TTL: ${stats.ttl || 0}초</p>
+                    <p class="mb-2">최대 항목 나이: ${(stats.oldest_item_age || 0).toFixed(1)}초</p>
+                </div>
+                <div class="d-grid">
+                    <button class="btn btn-sm btn-outline-primary" id="clearCache">캐시 비우기</button>
+                </div>
+            `;
+            
+            // 캐시 비우기 버튼 이벤트 리스너
+            document.getElementById('clearCache').addEventListener('click', clearCache);
+            
+        } catch (err) {
+            console.error('지식베이스 상태 가져오기 실패:', err);
+            databaseStats.innerHTML = `
+                <div class="alert alert-danger mb-0">
+                    <i class="fas fa-exclamation-circle me-2"></i>지식베이스 상태를 가져오는 중 오류가 발생했습니다.
+                </div>
+            `;
+        }
+    }
+    
+    /**
+     * 문서 목록 가져오기
+     */
+    async function fetchDocuments() {
+        try {
+            documentsContainer.innerHTML = `
+                <div class="text-center p-4">
+                    <div class="spinner-border text-primary" role="status">
+                        <span class="visually-hidden">Loading...</span>
+                    </div>
+                    <p class="mt-2">문서 목록을 불러오는 중...</p>
+                </div>
+            `;
+            
+            const response = await fetch('/api/documents');
+            
+            if (!response.ok) {
+                throw new Error('API 요청 실패');
+            }
+            
+            const data = await response.json();
+            const documents = data.documents || [];
+            
+            if (documents.length === 0) {
+                documentsContainer.innerHTML = `
+                    <div class="text-center p-4">
+                        <i class="fas fa-file-alt fa-3x mb-3 text-muted"></i>
+                        <p>지식베이스에 등록된 문서가 없습니다.</p>
+                        <p class="text-muted small">왼쪽 패널에서 문서를 업로드하세요.</p>
+                    </div>
+                `;
+                return;
+            }
+            
+            // 문서 목록 생성
+            const documentsList = document.createElement('div');
+            documentsList.className = 'list-group list-group-flush';
+            
+            documents.forEach(doc => {
+                const docItem = createDocumentItem(doc);
+                documentsList.appendChild(docItem);
+            });
+            
+            documentsContainer.innerHTML = '';
+            documentsContainer.appendChild(documentsList);
+            
+        } catch (err) {
+            console.error('문서 목록 가져오기 실패:', err);
+            documentsContainer.innerHTML = `
+                <div class="alert alert-danger m-3">
+                    <i class="fas fa-exclamation-circle me-2"></i>문서 목록을 가져오는 중 오류가 발생했습니다.
+                </div>
+            `;
+        }
+    }
+    
+    /**
+     * 문서 항목 생성
+     * @param {Object} doc - 문서 정보
+     * @returns {HTMLElement} - 문서 항목 요소
+     */
+    function createDocumentItem(doc) {
+        const template = document.getElementById('documentItemTemplate');
+        const docNode = template.content.cloneNode(true);
+        
+        docNode.querySelector('.document-name').textContent = doc.filename || doc.source || 'Unnamed Document';
+        docNode.querySelector('.document-chunks').textContent = doc.chunks || 0;
+        docNode.querySelector('.document-type').textContent = doc.filetype || 'UNKNOWN';
+        
+        return docNode.firstElementChild;
+    }
+    
+    /**
+     * 캐시 비우기
+     */
+    async function clearCache() {
+        try {
+            if (!confirm('정말 캐시를 비우시겠습니까?')) {
+                return;
+            }
+            
+            const response = await fetch('/api/cache/clear', {
+                method: 'POST'
+            });
+            
+            if (!response.ok) {
+                throw new Error('API 요청 실패');
+            }
+            
+            alert('캐시가 성공적으로 비워졌습니다.');
+            fetchDatabaseStats();
+            
+        } catch (err) {
+            console.error('캐시 비우기 실패:', err);
+            alert('캐시 비우기 실패: ' + err.message);
+        }
+    }
+    
+    // 초기 데이터 로드
+    fetchDatabaseStats();
+    fetchDocuments();
+});

templates/chat.html

@@ -0,0 +1,201 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>RAG 챗봇 - 채팅</title>
+    <link rel="stylesheet" href="/static/css/style.css">
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/css/bootstrap.min.css" rel="stylesheet">
+    <!-- Font Awesome -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">
+    <!-- Highlight.js for code styling -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/styles/github.min.css">
+    <!-- Markdown parser -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/marked/4.2.4/marked.min.js"></script>
+    <!-- DOMPurify for sanitizing HTML -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/dompurify/2.4.1/purify.min.js"></script>
+</head>
+<body>
+    <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
+        <div class="container">
+            <a class="navbar-brand" href="/">
+                <i class="fas fa-robot me-2"></i>RAG 챗봇
+            </a>
+            <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav">
+                <span class="navbar-toggler-icon"></span>
+            </button>
+            <div class="collapse navbar-collapse" id="navbarNav">
+                <ul class="navbar-nav ms-auto">
+                    <li class="nav-item">
+                        <a class="nav-link" href="/"><i class="fas fa-home me-1"></i>홈</a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link active" href="/chat"><i class="fas fa-comments me-1"></i>채팅</a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link" href="/knowledge"><i class="fas fa-database me-1"></i>지식베이스</a>
+                    </li>
+                </ul>
+            </div>
+        </div>
+    </nav>
+
+    <div class="container mt-4">
+        <div class="row">
+            <!-- 채팅 영역 -->
+            <div class="col-md-8">
+                <div class="card shadow-sm">
+                    <div class="card-header bg-primary text-white">
+                        <div class="d-flex justify-content-between align-items-center">
+                            <div>
+                                <i class="fas fa-comments me-2"></i>채팅
+                            </div>
+                            <div>
+                                <button id="clearChat" class="btn btn-sm btn-light">
+                                    <i class="fas fa-trash me-1"></i>대화 지우기
+                                </button>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="card-body">
+                        <div id="chatMessages" class="chat-messages mb-3"></div>
+                        
+                        <div class="alert alert-info d-none" id="recordingAlert">
+                            <i class="fas fa-microphone-alt me-2"></i>음성 녹음 중... 클릭하여 중지
+                        </div>
+                        
+                        <div class="alert alert-warning d-none" id="processingAlert">
+                            <div class="d-flex align-items-center">
+                                <div class="spinner-border spinner-border-sm me-2" role="status"></div>
+                                <div>음성을 처리 중입니다. 잠시만 기다려주세요...</div>
+                            </div>
+                        </div>
+                        
+                        <div class="alert alert-warning d-none" id="typingAlert">
+                            <div class="d-flex align-items-center">
+                                <div class="spinner-border spinner-border-sm me-2" role="status"></div>
+                                <div>답변을 생성하고 있습니다...</div>
+                            </div>
+                        </div>
+                        
+                        <div id="chatForm">
+                            <div class="input-group">
+                                <textarea id="userInput" class="form-control" placeholder="질문을 입력하세요..." rows="2"></textarea>
+                                <button type="button" id="micButton" class="btn btn-danger">
+                                    <i class="fas fa-microphone"></i>
+                                </button>
+                                <button type="button" id="sendButton" class="btn btn-primary">
+                                    <i class="fas fa-paper-plane"></i>
+                                </button>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+            
+            <!-- 설정 및 정보 영역 -->
+            <div class="col-md-4">
+                <div class="card shadow-sm mb-4">
+                    <div class="card-header bg-dark text-white">
+                        <i class="fas fa-cog me-2"></i>설정
+                    </div>
+                    <div class="card-body">
+                        <div class="mb-3">
+                            <label for="retrieverType" class="form-label">검색 엔진</label>
+                            <select id="retrieverType" class="form-select">
+                                <option value="reranker" selected>재순위화 검색</option>
+                                <option value="vector">벡터 검색</option>
+                            </select>
+                        </div>
+                        <div class="mb-3">
+                            <label for="topK" class="form-label">참고 문서 수 (Top-K)</label>
+                            <input type="number" class="form-control" id="topK" min="1" max="10" value="3">
+                        </div>
+                        <div class="mb-3">
+                            <label for="temperature" class="form-label">다양성 (Temperature)</label>
+                            <input type="range" class="form-range" id="temperature" min="0" max="1" step="0.1" value="0.7">
+                            <div class="d-flex justify-content-between">
+                                <small>정확</small>
+                                <small id="temperatureValue">0.7</small>
+                                <small>창의적</small>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+                
+                <div class="card shadow-sm mb-4">
+                    <div class="card-header bg-dark text-white">
+                        <i class="fas fa-info-circle me-2"></i>정보
+                    </div>
+                    <div class="card-body">
+                        <h5 class="card-title">사용 방법</h5>
+                        <ul class="mb-0">
+                            <li>텍스트를 입력하여 질문하거나</li>
+                            <li>마이크 버튼을 클릭하여 음성으로 질문할 수 있습니다.</li>
+                            <li>VITO STT로 음성이 텍스트로 변환됩니다.</li>
+                            <li>문서를 첨부하려면 지식베이스 메뉴를 이용하세요.</li>
+                        </ul>
+                    </div>
+                </div>
+                
+                <div class="card shadow-sm">
+                    <div class="card-header bg-success text-white">
+                        <i class="fas fa-book me-2"></i>참고 문서
+                    </div>
+                    <div class="card-body p-0">
+                        <div id="sourceList" class="list-group list-group-flush">
+                            <div class="list-group-item text-center text-muted">
+                                <i>참고 문서가 여기에 표시됩니다</i>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <footer class="bg-dark text-white text-center py-3 mt-5">
+        <div class="container">
+            <p class="mb-0">RAG 챗봇 클라이언트 &copy; 2025</p>
+        </div>
+    </footer>
+
+    <!-- 메시지 템플릿 -->
+    <template id="userMessageTemplate">
+        <div class="chat-message user-message mb-3">
+            <div class="d-flex">
+                <div class="message-avatar bg-primary text-white">
+                    <i class="fas fa-user"></i>
+                </div>
+                <div class="message-content">
+                    <div class="message-text"></div>
+                </div>
+            </div>
+        </div>
+    </template>
+
+    <template id="botMessageTemplate">
+        <div class="chat-message bot-message mb-3">
+            <div class="d-flex">
+                <div class="message-avatar bg-success text-white">
+                    <i class="fas fa-robot"></i>
+                </div>
+                <div class="message-content">
+                    <div class="message-text"></div>
+                    <div class="message-metadata mt-2 text-muted small">
+                        <span class="message-sources"></span>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </template>
+
+    <!-- Bootstrap JS Bundle with Popper -->
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/js/bootstrap.bundle.min.js"></script>
+    <!-- Highlight.js for code highlighting -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.7.0/highlight.min.js"></script>
+    <!-- 채팅 로직 -->
+    <script src="/static/js/chat.js"></script>
+</body>
+</html>

templates/index.html

@@ -0,0 +1,103 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>RAG 챗봇 - 홈</title>
+    <link rel="stylesheet" href="/static/css/style.css">
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/css/bootstrap.min.css" rel="stylesheet">
+    <!-- Font Awesome -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">
+</head>
+<body>
+    <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
+        <div class="container">
+            <a class="navbar-brand" href="/">
+                <i class="fas fa-robot me-2"></i>RAG 챗봇
+            </a>
+            <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav">
+                <span class="navbar-toggler-icon"></span>
+            </button>
+            <div class="collapse navbar-collapse" id="navbarNav">
+                <ul class="navbar-nav ms-auto">
+                    <li class="nav-item">
+                        <a class="nav-link active" href="/"><i class="fas fa-home me-1"></i>홈</a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link" href="/chat"><i class="fas fa-comments me-1"></i>채팅</a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link" href="/knowledge"><i class="fas fa-database me-1"></i>지식베이스</a>
+                    </li>
+                </ul>
+            </div>
+        </div>
+    </nav>
+
+    <div class="container mt-5">
+        <div class="row justify-content-center">
+            <div class="col-md-8 text-center">
+                <h1 class="display-4 mb-4">RAG 챗봇</h1>
+                <p class="lead mb-5">Retrieval-Augmented Generation 기반 지능형 챗봇 서비스</p>
+                
+                <div class="row mt-5">
+                    <div class="col-md-4">
+                        <div class="card mb-4 shadow-sm h-100">
+                            <div class="card-body text-center py-4">
+                                <i class="fas fa-comments fa-4x mb-3 text-primary"></i>
+                                <h3 class="card-title">텍스트 채팅</h3>
+                                <p class="card-text">텍스트로 질문을 입력하고 지식 기반 답변을 받으세요.</p>
+                                <a href="/chat" class="btn btn-primary mt-2">채팅 시작</a>
+                            </div>
+                        </div>
+                    </div>
+                    
+                    <div class="col-md-4">
+                        <div class="card mb-4 shadow-sm h-100">
+                            <div class="card-body text-center py-4">
+                                <i class="fas fa-microphone fa-4x mb-3 text-danger"></i>
+                                <h3 class="card-title">음성 채팅</h3>
+                                <p class="card-text">VITO STT를 활용한 음성 질문으로 대화하세요.</p>
+                                <a href="/chat" class="btn btn-danger mt-2">음성 채팅</a>
+                            </div>
+                        </div>
+                    </div>
+                    
+                    <div class="col-md-4">
+                        <div class="card mb-4 shadow-sm h-100">
+                            <div class="card-body text-center py-4">
+                                <i class="fas fa-database fa-4x mb-3 text-success"></i>
+                                <h3 class="card-title">지식베이스</h3>
+                                <p class="card-text">문서를 업로드하여 챗봇의 지식을 확장하세요.</p>
+                                <a href="/knowledge" class="btn btn-success mt-2">지식베이스 관리</a>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+                
+                <div class="row mt-5">
+                    <div class="col-md-12">
+                        <div class="card shadow-sm">
+                            <div class="card-body">
+                                <h4 class="mb-3">RAG 기술에 대하여</h4>
+                                <p>RAG(Retrieval-Augmented Generation)는 대규모 언어 모델(LLM)에 외부 지식을 제공하여 더 정확하고 최신 정보를 바탕으로 응답을 생성하는 기술입니다.</p>
+                                <p>본 챗봇은 문서 검색과 LLM 생성을 결합하여 사용자 질문에 대한 맥락 기반 응답을 제공합니다.</p>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <footer class="bg-dark text-white text-center py-3 mt-5">
+        <div class="container">
+            <p class="mb-0">RAG 챗봇 클라이언�� &copy; 2025</p>
+        </div>
+    </footer>
+
+    <!-- Bootstrap JS Bundle with Popper -->
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/js/bootstrap.bundle.min.js"></script>
+</body>
+</html>

templates/knowledge.html

@@ -0,0 +1,170 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>RAG 챗봇 - 지식베이스</title>
+    <link rel="stylesheet" href="/static/css/style.css">
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/css/bootstrap.min.css" rel="stylesheet">
+    <!-- Font Awesome -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">
+    <!-- Dropzone.js -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/dropzone/5.9.3/min/dropzone.min.css">
+</head>
+<body>
+    <nav class="navbar navbar-expand-lg navbar-dark bg-dark">
+        <div class="container">
+            <a class="navbar-brand" href="/">
+                <i class="fas fa-robot me-2"></i>RAG 챗봇
+            </a>
+            <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbarNav">
+                <span class="navbar-toggler-icon"></span>
+            </button>
+            <div class="collapse navbar-collapse" id="navbarNav">
+                <ul class="navbar-nav ms-auto">
+                    <li class="nav-item">
+                        <a class="nav-link" href="/"><i class="fas fa-home me-1"></i>홈</a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link" href="/chat"><i class="fas fa-comments me-1"></i>채팅</a>
+                    </li>
+                    <li class="nav-item">
+                        <a class="nav-link active" href="/knowledge"><i class="fas fa-database me-1"></i>지식베이스</a>
+                    </li>
+                </ul>
+            </div>
+        </div>
+    </nav>
+
+    <div class="container mt-4">
+        <div class="row">
+            <!-- 문서 업로드 영역 -->
+            <div class="col-md-6">
+                <div class="card shadow-sm mb-4">
+                    <div class="card-header bg-success text-white">
+                        <i class="fas fa-upload me-2"></i>문서 업로드
+                    </div>
+                    <div class="card-body">
+                        <p class="card-text">챗봇에 지식을 제공할 문서를 업로드하세요. 텍스트 기반 문서(TXT, MD, PDF, DOCX, CSV)를 지원합니다.</p>
+                        
+                        <form id="documentUploadForm" class="dropzone mt-3">
+                            <div class="dz-message needsclick">
+                                <i class="fas fa-cloud-upload-alt fa-3x mb-3"></i>
+                                <h4>여기에 파일을 끌어다 놓거나 클릭하여 선택하세요</h4>
+                                <span class="text-muted">최대 10MB, 텍스트 기반 문서 파일만 허용</span>
+                            </div>
+                        </form>
+                        
+                        <div class="alert alert-success mt-3 d-none" id="uploadSuccess">
+                            <i class="fas fa-check-circle me-2"></i>
+                            <span id="uploadSuccessMessage">문서가 성공적으로 업로드되었습니다.</span>
+                        </div>
+                        
+                        <div class="alert alert-danger mt-3 d-none" id="uploadError">
+                            <i class="fas fa-exclamation-circle me-2"></i>
+                            <span id="uploadErrorMessage">업로드 중 오류가 발생했습니다.</span>
+                        </div>
+                        
+                        <button id="uploadButton" class="btn btn-success mt-3" disabled>
+                            <i class="fas fa-upload me-2"></i>업로드
+                        </button>
+                    </div>
+                </div>
+                
+                <div class="card shadow-sm">
+                    <div class="card-header bg-dark text-white">
+                        <i class="fas fa-info-circle me-2"></i>사용 안내
+                    </div>
+                    <div class="card-body">
+                        <h5>지원되는 파일 형식</h5>
+                        <ul>
+                            <li>텍스트 파일 (.txt)</li>
+                            <li>마크다운 파일 (.md)</li>
+                            <li>PDF 문서 (.pdf)</li>
+                            <li>MS Word 문서 (.docx)</li>
+                            <li>CSV 데이터 (.csv)</li>
+                        </ul>
+                        <h5>작동 방식</h5>
+                        <p>업로드된 문서는 적절한 크기로 분할되어 임베딩된 후 벡터 데이터베이스에 저장됩니다. 이 데이터는 사용자의 질문에 대한 관련 정보를 검색하는 데 사용됩니다.</p>
+                    </div>
+                </div>
+            </div>
+            
+            <!-- 현재 지식베이스 상태 -->
+            <div class="col-md-6">
+                <div class="card shadow-sm mb-4">
+                    <div class="card-header bg-primary text-white">
+                        <div class="d-flex justify-content-between align-items-center">
+                            <div>
+                                <i class="fas fa-database me-2"></i>지식베이스 상태
+                            </div>
+                            <div>
+                                <button id="refreshStatus" class="btn btn-sm btn-light">
+                                    <i class="fas fa-sync-alt me-1"></i>새로고침
+                                </button>
+                            </div>
+                        </div>
+                    </div>
+                    <div class="card-body">
+                        <div id="databaseStats">
+                            <div class="d-flex justify-content-center align-items-center" style="height: 100px;">
+                                <div class="spinner-border text-primary" role="status">
+                                    <span class="visually-hidden">Loading...</span>
+                                </div>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+                
+                <div class="card shadow-sm">
+                    <div class="card-header bg-primary text-white">
+                        <i class="fas fa-file-alt me-2"></i>문서 목록
+                    </div>
+                    <div class="card-body p-0">
+                        <div id="documentsContainer">
+                            <div class="text-center p-4">
+                                <div class="spinner-border text-primary" role="status">
+                                    <span class="visually-hidden">Loading...</span>
+                                </div>
+                                <p class="mt-2">문서 목록을 불러오는 중...</p>
+                            </div>
+                        </div>
+                    </div>
+                </div>
+            </div>
+        </div>
+    </div>
+
+    <footer class="bg-dark text-white text-center py-3 mt-5">
+        <div class="container">
+            <p class="mb-0">RAG 챗봇 클라이언트 &copy; 2025</p>
+        </div>
+    </footer>
+
+    <!-- 문서 항목 템플릿 -->
+    <template id="documentItemTemplate">
+        <div class="list-group-item">
+            <div class="d-flex justify-content-between align-items-center">
+                <div class="d-flex align-items-center">
+                    <i class="fas fa-file-alt me-3 text-primary"></i>
+                    <div>
+                        <h6 class="mb-0 document-name">문서명</h6>
+                        <div class="small text-muted">
+                            문서 청크: <span class="document-chunks">0</span> 개
+                        </div>
+                    </div>
+                </div>
+                <span class="badge bg-primary document-type">TXT</span>
+            </div>
+        </div>
+    </template>
+
+    <!-- Bootstrap JS Bundle with Popper -->
+    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/js/bootstrap.bundle.min.js"></script>
+    <!-- Dropzone.js -->
+    <script src="https://cdnjs.cloudflare.com/ajax/libs/dropzone/5.9.3/min/dropzone.min.js"></script>
+    <!-- 지식베이스 관리 스크립트 -->
+    <script src="/static/js/knowledge.js"></script>
+</body>
+</html>

templates/loading.html

@@ -0,0 +1,50 @@
+<!DOCTYPE html>
+<html lang="ko">
+<head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <title>RAG 챗봇 - 로딩 중</title>
+    <link rel="stylesheet" href="/static/css/style.css">
+    <!-- Bootstrap CSS -->
+    <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0-alpha1/dist/css/bootstrap.min.css" rel="stylesheet">
+    <!-- Font Awesome -->
+    <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.0.0/css/all.min.css">
+    <style>
+        .loading-container {
+            height: 100vh;
+            display: flex;
+            flex-direction: column;
+            justify-content: center;
+            align-items: center;
+        }
+        
+        .loader {
+            margin-bottom: 2rem;
+        }
+        
+        .progress {
+            width: 300px;
+        }
+    </style>
+    <meta http-equiv="refresh" content="3;url=/" />
+</head>
+<body class="bg-light">
+    <div class="loading-container">
+        <div class="loader">
+            <div class="spinner-border text-primary" style="width: 5rem; height: 5rem;" role="status">
+                <span class="visually-hidden">Loading...</span>
+            </div>
+        </div>
+        
+        <h3 class="mb-4 text-center">
+            <i class="fas fa-robot me-2"></i>RAG 챗봇을 초기화하는 중입니다
+        </h3>
+        
+        <div class="progress mb-3">
+            <div class="progress-bar progress-bar-striped progress-bar-animated" style="width: 100%"></div>
+        </div>
+        
+        <p class="text-muted">잠시만 기다려주세요. 곧 자동으로 리디렉션됩니다.</p>
+    </div>
+</body>
+</html>

uploads/README.md

@@ -0,0 +1,4 @@
+# 업로드 디렉토리
+
+이 디렉토리는 업로드된 파일을 임시로 저장하는 용도로 사용됩니다.
+업로드된 파일은 처리 후 삭제됩니다.

utils/__init__.py

@@ -0,0 +1 @@
+# Utils 패키지

utils/vito_stt.py

@@ -0,0 +1,245 @@
+# -*- coding: utf-8 -*-
+"""
+VITO API를 사용한 음성 인식(STT) 모듈
+"""
+
+import os
+import logging
+import requests
+import json
+import time
+from dotenv import load_dotenv
+
+# 환경 변수 로드
+load_dotenv()
+
+# 로거 설정
+logger = logging.getLogger("VitoSTT")
+# 기본 로깅 레벨 설정 (핸들러가 없으면 출력이 안될 수 있으므로 기본 핸들러 추가 고려)
+if not logger.hasHandlers():
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO) # 기본 레벨 INFO로 설정
+
+class VitoSTT:
+    """VITO STT API 래퍼 클래스"""
+
+    def __init__(self):
+        """VITO STT 클래스 초기화"""
+        self.client_id = os.getenv("VITO_CLIENT_ID")
+        self.client_secret = os.getenv("VITO_CLIENT_SECRET")
+
+        if not self.client_id or not self.client_secret:
+            logger.warning("VITO API 인증 정보가 .env 파일에 설정되지 않았습니다.")
+            logger.warning("VITO_CLIENT_ID와 VITO_CLIENT_SECRET를 확인하세요.")
+            # 에러를 발생시키거나, 기능 사용 시점에 체크하도록 둘 수 있습니다.
+            # 여기서는 경고만 하고 넘어갑니다.
+        else:
+            logger.info("VITO STT API 클라이언트 ID/Secret 로드 완료.")
+
+        # API 엔드포인트
+        self.token_url = "https://openapi.vito.ai/v1/authenticate"
+        self.stt_url = "https://openapi.vito.ai/v1/transcribe"
+
+        # 액세스 토큰
+        self.access_token = None
+        self._token_expires_at = 0 # 토큰 만료 시간 추적 (선택적 개선)
+
+    def get_access_token(self):
+        """VITO API 액세스 토큰 획득"""
+        # 현재 시간을 가져와 토큰 만료 여부 확인 (선택적 개선)
+        now = time.time()
+        if self.access_token and now < self._token_expires_at:
+            logger.debug("기존 VITO API 토큰 사용")
+            return self.access_token
+
+        if not self.client_id or not self.client_secret:
+            logger.error("API 키가 설정되지 않아 토큰을 획득할 수 없습니다.")
+            raise ValueError("VITO API 인증 정보가 설정되지 않았습니다.")
+
+        logger.info("VITO API 액세스 토큰 요청 중...")
+        try:
+            response = requests.post(
+                self.token_url,
+                data={"client_id": self.client_id, "client_secret": self.client_secret},
+                timeout=10 # 타임아웃 설정
+            )
+            response.raise_for_status() # HTTP 오류 발생 시 예외 발생
+
+            result = response.json()
+            self.access_token = result.get("access_token")
+            expires_in = result.get("expires_in", 3600) # 만료 시간 (초), 기본값 1시간
+            self._token_expires_at = time.time() + expires_in - 60 # 60초 여유
+
+            if not self.access_token:
+                logger.error("VITO API 응답에서 토큰을 찾을 수 없습니다.")
+                raise ValueError("VITO API 토큰을 받아오지 못했습니다.")
+
+            logger.info("VITO API 액세스 토큰 획득 성공")
+            return self.access_token
+        except requests.exceptions.Timeout:
+            logger.error(f"VITO API 토큰 획득 시간 초과: {self.token_url}")
+            raise TimeoutError("VITO API 토큰 획득 시간 초과")
+        except requests.exceptions.RequestException as e:
+            logger.error(f"VITO API 토큰 획득 실패: {e}")
+            if hasattr(e, 'response') and e.response is not None:
+                 logger.error(f"응답 코드: {e.response.status_code}, 내용: {e.response.text}")
+            raise ConnectionError(f"VITO API 토큰 획득 실패: {e}")
+
+
+    def transcribe_audio(self, audio_bytes, language="ko"):
+        """
+        오디오 바이트 데이터를 텍스트로 변환
+
+        Args:
+            audio_bytes: 오디오 파일 바이트 데이터
+            language: 언어 코드 (기본값: 'ko')
+
+        Returns:
+            인식된 텍스트 또는 오류 메시지를 포함한 딕셔너리
+            {'success': True, 'text': '인식된 텍스트'}
+            {'success': False, 'error': '오류 메시지', 'details': '상세 내용'}
+        """
+        if not self.client_id or not self.client_secret:
+            logger.error("API 키가 설정되지 않았습니다.")
+            return {"success": False, "error": "API 키가 설정되지 않았습니다."}
+
+        try:
+            # 토큰 획득 또는 갱신
+            # (선택적 개선: 만료 시간 체크 로직 추가 시 self._token_expires_at 사용)
+            if not self.access_token or time.time() >= self._token_expires_at:
+                logger.info("VITO API 토큰 획득/갱신 시도...")
+                self.get_access_token()
+
+            headers = {
+                "Authorization": f"Bearer {self.access_token}"
+            }
+
+            files = {
+                "file": ("audio_file", audio_bytes) # 파일명 튜플로 전달
+            }
+
+            # API 설정값 (필요에 따라 수정)
+            config = {
+                "use_multi_channel": False,
+                "use_itn": True, # Inverse Text Normalization (숫자, 날짜 등 변환)
+                "use_disfluency_filter": True, # 필러 (음, 아...) 제거
+                "use_profanity_filter": False, # 비속어 필터링
+                "language": language,
+                # "type": "audio" # type 파라미터는 VITO 문서상 필수 아님 (자동 감지)
+            }
+            data = {"config": json.dumps(config)}
+
+            logger.info(f"VITO STT API ({self.stt_url}) 요청 전송 중...")
+            response = requests.post(
+                self.stt_url,
+                headers=headers,
+                files=files,
+                data=data,
+                timeout=20 # 업로드 타임아웃
+            )
+            response.raise_for_status()
+
+            result = response.json()
+            job_id = result.get("id")
+
+            if not job_id:
+                logger.error("VITO API 작업 ID를 받아오지 못했습니다.")
+                return {"success": False, "error": "VITO API 작업 ID를 받아오지 못했습니다."}
+
+            logger.info(f"VITO STT 작업 ID: {job_id}, 결과 확인 시작...")
+
+            # 결과 확인 URL
+            transcript_url = f"{self.stt_url}/{job_id}"
+            max_tries = 15 # 최대 시도 횟수 증가
+            wait_time = 2 # 대기 시간 증가 (초)
+
+            for try_count in range(max_tries):
+                time.sleep(wait_time) # API 부하 감소 위해 대기
+                logger.debug(f"결과 확인 시도 ({try_count + 1}/{max_tries}) - URL: {transcript_url}")
+                get_response = requests.get(
+                    transcript_url,
+                    headers=headers,
+                    timeout=10 # 결과 확인 타임아웃
+                )
+                get_response.raise_for_status()
+
+                result = get_response.json()
+                status = result.get("status")
+                logger.debug(f"현재 상태: {status}")
+
+                if status == "completed":
+                    # 결과 추출 (utterances 구조 확인 필요)
+                    utterances = result.get("results", {}).get("utterances", [])
+                    if utterances:
+                         # 전체 텍스트를 하나로 합침
+                        transcript = " ".join([seg.get("msg", "") for seg in utterances if seg.get("msg")]).strip()
+                        logger.info(f"VITO STT 인식 성공 (일부): {transcript[:50]}...")
+                        return {
+                            "success": True,
+                            "text": transcript
+                            # "raw_result": result # 필요시 전체 결과 반환
+                        }
+                    else:
+                         logger.warning("VITO STT 완료되었으나 결과 utterances가 비어있습니다.")
+                         return {"success": True, "text": ""} # 성공이지만 텍스트 없음
+
+                elif status == "failed":
+                    error_msg = f"VITO API 변환 실패: {result.get('message', '알 수 없는 오류')}"
+                    logger.error(error_msg)
+                    return {"success": False, "error": error_msg, "details": result}
+
+                elif status == "transcribing":
+                    logger.info(f"VITO API 처리 중... ({try_count + 1}/{max_tries})")
+                else: # registered, waiting 등 다른 상태
+                    logger.info(f"VITO API 상태 '{status}', 대기 중... ({try_count + 1}/{max_tries})")
+
+
+            logger.error(f"VITO API 응답 타임아웃 ({max_tries * wait_time}초 초과)")
+            return {"success": False, "error": "VITO API 응답 타임아웃"}
+
+        except requests.exceptions.HTTPError as e:
+            # 토큰 만료 오류 처리 (401 Unauthorized)
+            if e.response.status_code == 401:
+                logger.warning("VITO API 토큰이 만료되었거나 유효하지 않습니다. 토큰 재발급 시도...")
+                self.access_token = None # 기존 토큰 무효화
+                try:
+                    # 재귀 호출 대신, 토큰 재발급 후 다시 시도하는 로직 구성
+                    self.get_access_token()
+                    logger.info("새 토큰으로 재시도합니다.")
+                    # 재시도는 이 함수를 다시 호출하는 대신, 호출하는 쪽에서 처리하는 것이 더 안전할 수 있음
+                    return self.transcribe_audio(audio_bytes, language) # 재귀 호출 방식
+
+                except Exception as token_e:
+                    logger.error(f"토큰 재획득 실패: {token_e}")
+                    return {"success": False, "error": f"토큰 재획득 실패: {str(token_e)}"}
+
+            else:
+                # 401 외 다른 HTTP 오류
+                error_body = ""
+                try:
+                    error_body = e.response.text
+                except Exception:
+                    pass
+                logger.error(f"VITO API HTTP 오류: {e.response.status_code}, 응답: {error_body}")
+                return {
+                    "success": False,
+                    "error": f"API HTTP 오류: {e.response.status_code}",
+                    "details": error_body
+                }
+
+        except requests.exceptions.Timeout:
+            logger.error("VITO API 요청 시간 초과")
+            return {"success": False, "error": "API 요청 시간 초과"}
+        except requests.exceptions.RequestException as e:
+            logger.error(f"VITO API 요청 중 네트워크 오류 발생: {str(e)}")
+            return {"success": False, "error": "API 요청 네트워크 오류", "details": str(e)}
+        except Exception as e:
+            logger.error(f"음성인식 처리 중 예상치 못한 오류 발생: {str(e)}", exc_info=True)
+            return {
+                "success": False,
+                "error": "음성인식 내부 처리 실패",
+                "details": str(e)
+            }

vito_stt.py

@@ -0,0 +1,253 @@
+# -*- coding: utf-8 -*-
+"""
+VITO API를 사용한 음성 인식(STT) 모듈
+"""
+
+import os
+import logging
+import requests
+import json
+import time # time import 추가
+from dotenv import load_dotenv
+
+# 환경 변수 로드
+load_dotenv()
+
+# 로거 설정 (app.py와 공유하거나 독립적으로 설정 가능)
+# 여기서는 독립적인 로거를 사용합니다. 필요시 app.py의 로거를 사용하도록 수정할 수 있습니다.
+logger = logging.getLogger("VitoSTT")
+# 기본 로깅 레벨 설정 (핸들러가 없으면 출력이 안될 수 있으므로 기본 핸들러 추가 고려)
+if not logger.hasHandlers():
+    handler = logging.StreamHandler()
+    formatter = logging.Formatter('%(asctime)s - %(name)s - %(levelname)s - %(message)s')
+    handler.setFormatter(formatter)
+    logger.addHandler(handler)
+    logger.setLevel(logging.INFO) # 기본 레벨 INFO로 설정
+
+class VitoSTT:
+    """VITO STT API 래퍼 클래스"""
+
+    def __init__(self):
+        """VITO STT 클래스 초기화"""
+        self.client_id = os.getenv("VITO_CLIENT_ID")
+        self.client_secret = os.getenv("VITO_CLIENT_SECRET")
+
+        if not self.client_id or not self.client_secret:
+            logger.warning("VITO API 인증 정보가 .env 파일에 설정되지 않았습니다.")
+            logger.warning("VITO_CLIENT_ID와 VITO_CLIENT_SECRET를 확인하세요.")
+            # 에러를 발생시키거나, 기능 사용 시점에 체크하도록 둘 수 있습니다.
+            # 여기서는 경고만 하고 넘어갑니다.
+        else:
+            logger.info("VITO STT API 클라이언트 ID/Secret 로드 완료.")
+
+        # API 엔드포인트
+        self.token_url = "https://openapi.vito.ai/v1/authenticate"
+        self.stt_url = "https://openapi.vito.ai/v1/transcribe"
+
+        # 액세스 토큰
+        self.access_token = None
+        self._token_expires_at = 0 # 토큰 만료 시간 추적 (선택적 개선)
+
+    def get_access_token(self):
+        """VITO API 액세스 토큰 획득"""
+        # 현재 시간을 가져와 토큰 만료 여부 확인 (선택적 개선)
+        # now = time.time()
+        # if self.access_token and now < self._token_expires_at:
+        #     logger.debug("기존 VITO API 토큰 사용")
+        #     return self.access_token
+
+        if not self.client_id or not self.client_secret:
+            logger.error("API 키가 설정되지 않아 토큰을 획득할 수 없습니다.")
+            raise ValueError("VITO API 인증 정보가 설정되지 않았습니다.")
+
+        logger.info("VITO API 액세스 토큰 요청 중...")
+        try:
+            response = requests.post(
+                self.token_url,
+                data={"client_id": self.client_id, "client_secret": self.client_secret},
+                timeout=10 # 타임아웃 설정
+            )
+            response.raise_for_status() # HTTP 오류 발생 시 예외 발생
+
+            result = response.json()
+            self.access_token = result.get("access_token")
+            expires_in = result.get("expires_in", 3600) # 만료 시간 (초), 기본값 1시간
+            self._token_expires_at = time.time() + expires_in - 60 # 60초 여유
+
+            if not self.access_token:
+                logger.error("VITO API 응답에서 토큰을 찾을 수 없습니다.")
+                raise ValueError("VITO API 토큰을 받아오지 못했습니다.")
+
+            logger.info("VITO API 액세스 토큰 획득 성공")
+            return self.access_token
+        except requests.exceptions.Timeout:
+            logger.error(f"VITO API 토큰 획득 시간 초과: {self.token_url}")
+            raise TimeoutError("VITO API 토큰 획득 시간 초과")
+        except requests.exceptions.RequestException as e:
+            logger.error(f"VITO API 토큰 획득 실패: {e}")
+            if hasattr(e, 'response') and e.response is not None:
+                 logger.error(f"응답 코드: {e.response.status_code}, 내용: {e.response.text}")
+            raise ConnectionError(f"VITO API 토큰 획득 실패: {e}")
+
+
+    def transcribe_audio(self, audio_bytes, language="ko"):
+        """
+        오디오 바이트 데이터를 텍스트로 변환
+
+        Args:
+            audio_bytes: 오디오 파일 바이트 데이터
+            language: 언어 코드 (기본값: 'ko')
+
+        Returns:
+            인식된 텍스트 또는 오류 메시지를 포함한 딕셔너리
+            {'success': True, 'text': '인식된 텍스트'}
+            {'success': False, 'error': '오류 메시지', 'details': '상세 내용'}
+        """
+        if not self.client_id or not self.client_secret:
+            logger.error("API 키가 설정되지 않았습니다.")
+            return {"success": False, "error": "API 키가 설정되지 않았습니다."}
+
+        try:
+            # 토큰 획득 또는 갱신
+            # (선택적 개선: 만료 시간 체크 로직 추가 시 self._token_expires_at 사용)
+            if not self.access_token: # or time.time() >= self._token_expires_at:
+                logger.info("VITO API 토큰 획득/갱신 시도...")
+                self.get_access_token()
+
+            headers = {
+                "Authorization": f"Bearer {self.access_token}"
+            }
+
+            files = {
+                "file": ("audio_file", audio_bytes) # 파일명 튜플로 전달
+            }
+
+            # API 설정값 (필요에 따라 수정)
+            config = {
+                "use_multi_channel": False,
+                "use_itn": True, # Inverse Text Normalization (숫자, 날짜 등 변환)
+                "use_disfluency_filter": True, # 필러 (음, 아...) 제거
+                "use_profanity_filter": False, # 비속어 필터링
+                "language": language,
+                # "type": "audio" # type 파라미터는 VITO 문서상 필수 아님 (자동 감지)
+            }
+            data = {"config": json.dumps(config)}
+
+            logger.info(f"VITO STT API ({self.stt_url}) 요청 전송 중...")
+            response = requests.post(
+                self.stt_url,
+                headers=headers,
+                files=files,
+                data=data,
+                timeout=20 # 업로드 타임아웃
+            )
+            response.raise_for_status()
+
+            result = response.json()
+            job_id = result.get("id")
+
+            if not job_id:
+                logger.error("VITO API 작업 ID를 받아오지 못했습니다.")
+                return {"success": False, "error": "VITO API 작업 ID를 받아오지 못했습니다."}
+
+            logger.info(f"VITO STT 작업 ID: {job_id}, 결과 확인 시작...")
+
+            # 결과 확인 URL
+            transcript_url = f"{self.stt_url}/{job_id}"
+            max_tries = 15 # 최대 시도 횟수 증가
+            wait_time = 2 # 대기 시간 증가 (초)
+
+            for try_count in range(max_tries):
+                time.sleep(wait_time) # API 부하 감소 위해 대기
+                logger.debug(f"결과 확인 시도 ({try_count + 1}/{max_tries}) - URL: {transcript_url}")
+                get_response = requests.get(
+                    transcript_url,
+                    headers=headers,
+                    timeout=10 # 결과 확인 타임아웃
+                )
+                get_response.raise_for_status()
+
+                result = get_response.json()
+                status = result.get("status")
+                logger.debug(f"현재 상태: {status}")
+
+                if status == "completed":
+                    # 결과 추출 (utterances 구조 확인 필요)
+                    utterances = result.get("results", {}).get("utterances", [])
+                    if utterances:
+                         # 전체 텍스트를 하나로 합침
+                        transcript = " ".join([seg.get("msg", "") for seg in utterances if seg.get("msg")]).strip()
+                        logger.info(f"VITO STT 인식 성공 (일부): {transcript[:50]}...")
+                        return {
+                            "success": True,
+                            "text": transcript
+                            # "raw_result": result # 필요시 전체 결과 반환
+                        }
+                    else:
+                         logger.warning("VITO STT 완료되었으나 결과 utterances가 비어있습니다.")
+                         return {"success": True, "text": ""} # 성공이지만 텍스트 없음
+
+                elif status == "failed":
+                    error_msg = f"VITO API 변환 실패: {result.get('message', '알 수 없는 오류')}"
+                    logger.error(error_msg)
+                    return {"success": False, "error": error_msg, "details": result}
+
+                elif status == "transcribing":
+                    logger.info(f"VITO API 처리 중... ({try_count + 1}/{max_tries})")
+                else: # registered, waiting 등 다른 상태
+                    logger.info(f"VITO API 상태 '{status}', 대기 중... ({try_count + 1}/{max_tries})")
+
+
+            logger.error(f"VITO API 응답 타임아웃 ({max_tries * wait_time}초 초과)")
+            return {"success": False, "error": "VITO API 응답 타임아웃"}
+
+        except requests.exceptions.HTTPError as e:
+            # 토큰 만료 오류 처리 (401 Unauthorized)
+            if e.response.status_code == 401:
+                logger.warning("VITO API 토큰이 만료되었거나 유효하지 않습니다. 토큰 재발급 시도...")
+                self.access_token = None # 기존 토큰 무효화
+                try:
+                    # 재귀 호출 대신, 토큰 재발급 후 다시 시도하는 로직 구성
+                    self.get_access_token()
+                    logger.info("새 토큰으로 재시도합니다.")
+                    # 재시도는 이 함수를 다시 호출하는 대신, 호출하는 쪽에서 처리하는 것이 더 안전할 수 있음
+                    # 여기서는 한 번 더 시도하는 로직 추가 (무한 루프 방지 필요)
+                    # return self.transcribe_audio(audio_bytes, language) # 재귀 호출 방식
+                    # --- 비재귀 방식 ---
+                    headers["Authorization"] = f"Bearer {self.access_token}" # 헤더 업데이트
+                    # POST 요청부터 다시 시작 (코드 중복 발생 가능성 있음)
+                    # ... (POST 요청 및 결과 폴링 로직 반복) ...
+                    # 간단하게는 그냥 실패 처리하고 상위에서 재시도 유도
+                    return {"success": False, "error": "토큰 만료 후 재시도 필요", "details": "토큰 재발급 성공"}
+
+                except Exception as token_e:
+                    logger.error(f"토큰 재획득 실패: {token_e}")
+                    return {"success": False, "error": f"토큰 재획득 실패: {str(token_e)}"}
+
+            else:
+                # 401 외 다른 HTTP 오류
+                error_body = ""
+                try:
+                    error_body = e.response.text
+                except Exception:
+                    pass
+                logger.error(f"VITO API HTTP 오류: {e.response.status_code}, 응답: {error_body}")
+                return {
+                    "success": False,
+                    "error": f"API HTTP 오류: {e.response.status_code}",
+                    "details": error_body
+                }
+
+        except requests.exceptions.Timeout:
+            logger.error("VITO API 요청 시간 초과")
+            return {"success": False, "error": "API 요청 시간 초과"}
+        except requests.exceptions.RequestException as e:
+            logger.error(f"VITO API 요청 중 네트워크 오류 발생: {str(e)}")
+            return {"success": False, "error": "API 요청 네트워크 오류", "details": str(e)}
+        except Exception as e:
+            logger.error(f"음성인식 처리 중 예상치 못한 오류 발생: {str(e)}", exc_info=True)
+            return {
+                "success": False,
+                "error": "음성인식 내부 처리 실패",
+                "details": str(e)
+            }