airkjw/Gov-chat-bot
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: import from sinmb79/Gov-chat-bot

Browse Source 
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
airkjw
2026-03-26 12:49:43 +09:00
commit a16c972dbb
104 changed files with 8063 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
docs/WSL2_가이드.md Normal file
View File

@@ -0,0 +1,28 @@
# Windows 설치 빠른 시작 가이드
SmartBot KR을 Windows에서 실행하는 가장 빠른 방법입니다.
## 5분 설치 순서
**1. PowerShell(관리자)** 열기 → `wsl --install` 실행 → 컴퓨터 재시작
**2. Ubuntu** 실행 → 사용자 이름·비밀번호 설정
**3. [Docker Desktop](https://www.docker.com/products/docker-desktop/) 설치**
- 설치 후: Settings → Resources → WSL Integration → Ubuntu 켜기 → Apply
**4. Ubuntu 터미널에서:**
```bash
git clone https://github.com/sinmb79/Gov-chat-bot.git
cd Gov-chat-bot
chmod +x install.sh && ./install.sh
```
**5. 브라우저에서 접속:**
- 관리자 화면: http://localhost:3000
- API 문서: http://localhost:8000/docs
---
자세한 내용은 [운영가이드.md](./운영가이드.md) 13장을 참고하세요.

429
docs/운영가이드.md Normal file
View File

@@ -0,0 +1,429 @@
# 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 · 오픈소스 무료 사용*