11 KiB
SmartBot KR 운영 가이드
코딩을 몰라도 설치·운영할 수 있도록 작성된 한글 가이드입니다. 지자체, 소상공인, 기업 모두 동일하게 사용할 수 있습니다.
목차
- 시스템 요구사항
- 설치 방법
- 초기 설정
- 대시보드 사용법
- FAQ 관리
- 문서 관리 (자료 학습)
- 문의 이력 조회
- 악성 감지 · 이용 제한
- 홈페이지 위젯 삽입
- LLM 연동 설정
- 백업 · 복구
- 문제 해결
- Windows 설치 가이드
- 조직 유형별 활용 팁
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 설치 가이드를 먼저 확인하세요.
2. 설치 방법
방법 A — 자동 설치 스크립트 (권장)
git clone https://github.com/sinmb79/Gov-chat-bot.git
cd Gov-chat-bot
chmod +x install.sh
./install.sh
스크립트가 자동으로 처리하는 항목:
- Docker 설치 확인
- 설정 파일(
.env) 생성 - 서비스 빌드 및 시작
- 데이터베이스 초기화
방법 B — 수동 설치
cp .env.example .env
# .env 파일을 편집하여 설정 입력
docker compose up -d
docker compose exec backend alembic upgrade head
3. 초기 설정
3-1. 관리자 계정 만들기
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 불가) |
|
| Word | .docx |
| 텍스트 | .txt |
| 마크다운 | .md |
업로드 절차
- 문서 관리 → + 문서 업로드 → 파일 선택
- 상태가
processed(처리 완료)로 바뀔 때까지 대기 - 승인 버튼 클릭 → AI가 학습 시작
승인하지 않으면 학습되지 않습니다. 반드시 승인 후 시뮬레이터로 테스트하세요.
어떤 자료를 올리면 좋을까요?
- 업무 매뉴얼, 안내 책자
- 상품 설명서, 이용약관
- 공지사항, 자주 묻는 질문 모음
- 가격표, 서비스 안내문
7. 문의 이력 조회
처리된 모든 문의를 조회할 수 있습니다.
- 고객 발화: 개인정보 자동 마스킹 처리 후 표시
- 사용자 식별: 해시값만 표시 (원본 저장 안 됨)
- Tier 필터로 분류별 조회 가능
8. 악성 감지 · 이용 제한
반복 욕설, 도배 등 악성 사용자를 단계적으로 제한합니다.
| 레벨 | 이름 | 의미 |
|---|---|---|
| 0 | 정상 | 제한 없음 |
| 1 | 경고 | 경고 메시지 표시 |
| 2 | 제한 | 응답 지연 |
| 3 | 일시 정지 | 관리자가 해제해야 함 |
| 4 | 차단 | 관리자만 해제 가능 |
| 5 | 영구 차단 | — |
9. 홈페이지 위젯 삽입
홈페이지 HTML에 아래 코드를 </body> 태그 바로 앞에 붙여넣으세요.
<script
src="http://내서버주소/widget/govbot-widget.js"
data-tenant="내조직ID"
data-api="http://내서버주소"
data-title="AI 도우미"
data-color="#2563eb"
></script>
| 속성 | 설명 | 예시 |
|---|---|---|
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) 사용:
LLM_PROVIDER=anthropic
ANTHROPIC_API_KEY=sk-ant-api03-...
ChatGPT (OpenAI) 사용:
LLM_PROVIDER=openai
OPENAI_API_KEY=sk-...
설정 후 재시작:
docker compose restart backend
비용 주의: LLM API는 질문 수에 따라 요금이 발생합니다. 처음에는 LLM 없이 시작하고, FAQ와 문서를 충분히 등록한 후 연결하세요.
11. 백업 · 복구
데이터베이스 백업
# 백업 (날짜 포함 파일명으로 저장)
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
정기 백업 자동화
# 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. 문제 해결
서비스가 안 켜질 때
docker compose logs backend # 오류 로그 확인
docker compose logs db # DB 오류 확인
docker compose restart # 재시작
포트 충돌 오류
# docker-compose.yml 파일에서 포트 변경
# "8000:8000" → "8080:8000"
# "3000:80" → "3001:80"
답변이 엉뚱할 때
- 시뮬레이터에서 테스트하며 FAQ를 추가하거나 수정
- 문서 내용이 명확한지 확인 (스캔 이미지 PDF는 인식 불가)
- FAQ에 더 다양한 표현으로 질문을 추가
AI 모델 로드 실패
처음 실행 시 한국어 AI 모델(약 400MB)이 자동 다운로드됩니다.
# 인터넷 연결 확인
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을 관리자 권한으로 실행 후:
wsl --install
컴퓨터를 재시작하면 Ubuntu 창이 뜹니다. 사용자 이름과 비밀번호를 설정하세요.
2단계 — Docker Desktop 설치
- Docker Desktop 다운로드 및 설치
- Settings → Resources → WSL Integration → Ubuntu 켜기
- Docker Desktop 재시작
3단계 — SmartBot KR 설치
Ubuntu 터미널에서:
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 · 오픈소스 무료 사용