430 lines
11 KiB
Markdown
430 lines
11 KiB
Markdown
# 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에 아래 코드를 `</body>` 태그 바로 앞에 붙여넣으세요.
|
|
|
|
```html
|
|
<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) 사용:**
|
|
```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 · 오픈소스 무료 사용*
|