# SmartBot KR 운영 가이드 > 코딩을 몰라도 설치·운영할 수 있도록 작성된 한글 가이드입니다. > 지자체, 소상공인, 기업 모두 동일하게 사용할 수 있습니다. --- ## 목차 1. [시스템 요구사항](#1-시스템-요구사항) 2. [설치 방법](#2-설치-방법) 3. [초기 설정](#3-초기-설정) 4. [대시보드 사용법](#4-대시보드-사용법) 5. [FAQ 관리](#5-faq-관리) 6. [문서 관리 (자료 학습)](#6-문서-관리-자료-학습) 7. [문의 이력 조회](#7-문의-이력-조회) 8. [악성 감지 · 이용 제한](#8-악성-감지--이용-제한) 9. [홈페이지 위젯 삽입](#9-홈페이지-위젯-삽입) 10. [LLM 연동 설정](#10-llm-연동-설정) 11. [백업 · 복구](#11-백업--복구) 12. [문제 해결](#12-문제-해결) 13. [Windows 설치 가이드](#13-windows-설치-가이드) 14. [조직 유형별 활용 팁](#14-조직-유형별-활용-팁) --- ## 1. 시스템 요구사항 | 항목 | 최소 | 권장 | |------|------|------| | OS | Ubuntu 20.04 / macOS 13 | Ubuntu 22.04 LTS | | CPU | 2코어 | 4코어 이상 | | RAM | 4GB | 8GB 이상 | | 디스크 | 20GB | 50GB 이상 | | Docker | 24.x 이상 | 최신 버전 | > **Windows 사용자**: [13장 Windows 설치 가이드](#13-windows-설치-가이드)를 먼저 확인하세요. --- ## 2. 설치 방법 ### 방법 A — 자동 설치 스크립트 (권장) ```bash git clone https://github.com/sinmb79/Gov-chat-bot.git cd Gov-chat-bot chmod +x install.sh ./install.sh ``` 스크립트가 자동으로 처리하는 항목: - Docker 설치 확인 - 설정 파일(`.env`) 생성 - 서비스 빌드 및 시작 - 데이터베이스 초기화 ### 방법 B — 수동 설치 ```bash cp .env.example .env # .env 파일을 편집하여 설정 입력 docker compose up -d docker compose exec backend alembic upgrade head ``` --- ## 3. 초기 설정 ### 3-1. 관리자 계정 만들기 ```bash docker compose exec backend python -m app.scripts.create_admin ``` 입력 항목: - **조직 ID**: 영문 소문자 (예: `my-cafe`, `city-hall`, `my-shop`) - **이메일**: 로그인에 사용할 이메일 - **비밀번호**: 8자 이상 ### 3-2. 조직 기본 정보 설정 (폴백 메시지용) AI가 답을 못 찾을 때 표시할 안내 메시지를 설정합니다. API를 통해 TenantConfig에 다음 값을 등록하세요: | 키 | 설명 | 예시 | |----|------|------| | `tenant_name` | 조직 이름 | 맛있는 식당, 동두천시 | | `phone_number` | 대표 전화번호 | 031-000-0000 | | `fallback_dept` | 문의 담당 (선택) | 고객센터, 민원과 | --- ## 4. 대시보드 사용법 브라우저에서 `http://서버주소:3000` 접속 후 로그인. | 메뉴 | 설명 | |------|------| | 📊 대시보드 | 문의 통계, 자동응답률 현황 | | ❓ FAQ 관리 | 자주 묻는 질문 등록·수정·삭제 | | 📄 문서 관리 | 자료 파일 업로드·승인·삭제 | | 📋 문의 이력 | 처리된 문의 조회 (개인정보 마스킹) | | 🚫 악성 감지 | 도배·욕설 사용자 관리 | | 💬 시뮬레이터 | AI 응답 미리 테스트 | --- ## 5. FAQ 관리 FAQ는 가장 빠르고 정확한 답변 방식입니다. 유사도가 높은 질문이 들어오면 즉시 답변합니다. ### 효과적인 FAQ 작성 방법 **같은 의미를 여러 표현으로 등록**하면 인식률이 크게 올라갑니다. ``` 질문: "영업시간이 어떻게 되나요?" 질문: "몇 시에 열어요?" ← 별도 FAQ로 추가 질문: "오늘 언제까지 하나요?" ← 별도 FAQ로 추가 → 세 개 모두 같은 답변으로 연결 ``` **답변 작성 팁:** - 짧고 명확하게 (200자 이내 권장) - 전화번호, 주소 등 실용 정보 포함 - 줄바꿈으로 읽기 쉽게 ### 카테고리 예시 | 업종 | 카테고리 예시 | |------|---------------| | 음식점 | 메뉴, 예약, 위치, 영업시간 | | 쇼핑몰 | 배송, 교환환불, 결제, 회원 | | 병원 | 진료, 예약, 보험, 주차 | | 지자체 | 민원, 복지, 세금, 교통 | | 학원 | 수강, 수업, 환불, 일정 | --- ## 6. 문서 관리 (자료 학습) PDF, Word 파일을 올리면 AI가 내용을 자동으로 학습하여 질문에 활용합니다. ### 지원 파일 형식 | 형식 | 확장자 | |------|--------| | PDF | `.pdf` (이미지 스캔 PDF 불가) | | Word | `.docx` | | 텍스트 | `.txt` | | 마크다운 | `.md` | ### 업로드 절차 1. **문서 관리** → **+ 문서 업로드** → 파일 선택 2. 상태가 `processed`(처리 완료)로 바뀔 때까지 대기 3. **승인** 버튼 클릭 → AI가 학습 시작 > **승인하지 않으면 학습되지 않습니다.** 반드시 승인 후 시뮬레이터로 테스트하세요. ### 어떤 자료를 올리면 좋을까요? - 업무 매뉴얼, 안내 책자 - 상품 설명서, 이용약관 - 공지사항, 자주 묻는 질문 모음 - 가격표, 서비스 안내문 --- ## 7. 문의 이력 조회 처리된 모든 문의를 조회할 수 있습니다. - 고객 발화: **개인정보 자동 마스킹** 처리 후 표시 - 사용자 식별: 해시값만 표시 (원본 저장 안 됨) - Tier 필터로 분류별 조회 가능 --- ## 8. 악성 감지 · 이용 제한 반복 욕설, 도배 등 악성 사용자를 단계적으로 제한합니다. | 레벨 | 이름 | 의미 | |------|------|------| | 0 | 정상 | 제한 없음 | | 1 | 경고 | 경고 메시지 표시 | | 2 | 제한 | 응답 지연 | | 3 | 일시 정지 | 관리자가 해제해야 함 | | 4 | 차단 | 관리자만 해제 가능 | | 5 | 영구 차단 | — | --- ## 9. 홈페이지 위젯 삽입 홈페이지 HTML에 아래 코드를 `` 태그 바로 앞에 붙여넣으세요. ```html ``` | 속성 | 설명 | 예시 | |------|------|------| | `data-tenant` | 조직 ID | `my-cafe` | | `data-api` | 서버 주소 | `https://bot.myshop.com` | | `data-title` | 위젯 제목 | `주문 도우미` | | `data-color` | 버튼 색상 | `#e53e3e` (빨강) | --- ## 10. LLM 연동 설정 기본값은 LLM 없이 FAQ + 문서 기반 응답만 사용합니다. 더 자연스러운 답변을 원하면 AI API를 연결할 수 있습니다. `.env` 파일을 열어 아래 내용을 수정합니다: **Claude (Anthropic) 사용:** ```env LLM_PROVIDER=anthropic ANTHROPIC_API_KEY=sk-ant-api03-... ``` **ChatGPT (OpenAI) 사용:** ```env LLM_PROVIDER=openai OPENAI_API_KEY=sk-... ``` 설정 후 재시작: ```bash docker compose restart backend ``` > **비용 주의**: LLM API는 질문 수에 따라 요금이 발생합니다. > 처음에는 LLM 없이 시작하고, FAQ와 문서를 충분히 등록한 후 연결하세요. --- ## 11. 백업 · 복구 ### 데이터베이스 백업 ```bash # 백업 (날짜 포함 파일명으로 저장) docker compose exec db pg_dump -U botuser smartbot > backup_$(date +%Y%m%d).sql # 복구 docker compose exec -T db psql -U botuser smartbot < backup_20260101.sql ``` ### 정기 백업 자동화 ```bash # crontab -e 에 추가 (매일 새벽 2시) 0 2 * * * cd /경로/Gov-chat-bot && docker compose exec db pg_dump -U botuser smartbot > /백업경로/backup_$(date +\%Y\%m\%d).sql ``` --- ## 12. 문제 해결 ### 서비스가 안 켜질 때 ```bash docker compose logs backend # 오류 로그 확인 docker compose logs db # DB 오류 확인 docker compose restart # 재시작 ``` ### 포트 충돌 오류 ```bash # docker-compose.yml 파일에서 포트 변경 # "8000:8000" → "8080:8000" # "3000:80" → "3001:80" ``` ### 답변이 엉뚱할 때 - **시뮬레이터**에서 테스트하며 FAQ를 추가하거나 수정 - 문서 내용이 명확한지 확인 (스캔 이미지 PDF는 인식 불가) - FAQ에 더 다양한 표현으로 질문을 추가 ### AI 모델 로드 실패 처음 실행 시 한국어 AI 모델(약 400MB)이 자동 다운로드됩니다. ```bash # 인터넷 연결 확인 docker compose exec backend curl -I https://huggingface.co # 모델 캐시 초기화 후 재시작 docker compose exec backend rm -rf /root/.cache/huggingface docker compose restart backend ``` --- ## 13. Windows 설치 가이드 Windows에서는 WSL2(리눅스 가상환경)를 통해 설치합니다. ### 1단계 — WSL2 설치 PowerShell을 **관리자 권한**으로 실행 후: ```powershell wsl --install ``` 컴퓨터를 재시작하면 Ubuntu 창이 뜹니다. 사용자 이름과 비밀번호를 설정하세요. ### 2단계 — Docker Desktop 설치 1. [Docker Desktop](https://www.docker.com/products/docker-desktop/) 다운로드 및 설치 2. Settings → Resources → WSL Integration → Ubuntu 켜기 3. Docker Desktop 재시작 ### 3단계 — SmartBot KR 설치 Ubuntu 터미널에서: ```bash git clone https://github.com/sinmb79/Gov-chat-bot.git cd Gov-chat-bot chmod +x install.sh && ./install.sh ``` ### 4단계 — 브라우저 접속 Windows 브라우저에서 바로 접속 가능합니다: - 관리자 화면: http://localhost:3000 - API 문서: http://localhost:8000/docs --- ## 14. 조직 유형별 활용 팁 ### 🍽️ 음식점 · 카페 **FAQ 등록 우선 항목:** - 영업시간 (요일별, 공휴일 포함) - 메뉴 안내 (가격 포함) - 예약 방법 및 연락처 - 주차 가능 여부, 위치 - 포장·배달 가능 여부 **문서 업로드 추천:** - 메뉴판 (텍스트 PDF) - 이벤트·프로모션 안내문 --- ### 🛍️ 쇼핑몰 · 온라인 판매 **FAQ 등록 우선 항목:** - 배송 기간 및 방법 - 교환·환불 정책 (기간, 조건) - 결제 수단 - 회원가입·포인트 안내 - AS 문의 방법 **문서 업로드 추천:** - 이용약관 - 배송·환불 정책 전문 --- ### 🏥 병원 · 의원 · 약국 **FAQ 등록 우선 항목:** - 진료 시간 (요일별) - 진료 과목 - 예약 방법 - 주차, 대중교통 - 건강보험 적용 여부 > **주의**: 구체적인 의학 상담 답변은 등록하지 마세요. 진료 예약 안내만 다루는 것이 안전합니다. --- ### 🎓 학원 · 교육기관 **FAQ 등록 우선 항목:** - 수업 시간표 - 수강료 및 납부 방법 - 등록·상담 방법 - 환불 규정 - 교재·준비물 안내 --- ### 🏛️ 지자체 · 공공기관 **FAQ 등록 우선 항목:** - 주요 민원 처리 방법 - 서류 발급 절차 - 담당 부서 연락처 - 이용 시간 및 휴관일 **문서 업로드 추천:** - 민원 안내 책자 - 주요 사업 안내문 --- ## 부록: 주요 API 엔드포인트 | 주소 | 설명 | |------|------| | `GET /health` | 서비스 정상 여부 확인 | | `POST /skill/{조직ID}` | 카카오톡 스킬 연결 주소 | | `POST /api/admin/auth/login` | 관리자 로그인 | | `GET /docs` | API 전체 문서 | --- *SmartBot KR · MIT License · 오픈소스 무료 사용*