AI 기반 고객 서비스 RAG 시스템

RAG(Retrieval-Augmented Generation) 기반의 지능형 고객 서비스 챗봇 시스템입니다. 사용자 질문에 대한 답변, 관리자 답변 처리 및 자동 RAG 업데이트 기능을 제공합니다.

주요 기능

🤖 RAG 챗봇

• 사용자 질문에 대한 유사도 기반 답변 생성
• 신뢰도 수준에 따른 동적 응답
• 답변 품질 검증 시스템 (HIGH 신뢰도에서도 답변 실패 처리)
• 대화 기록 관리 및 컨텍스트 활용

🔄 관리자 워크플로우

• 관리자 답변 후 중복 검사
• 자동 RAG 업데이트
• 게시판 답변 → RAG 자동 연동

💾 지식 관리

• ChromaDB 기반 벡터 검색
• Redis 기반 대화 기록 관리
• Kafka 기반 비동기 처리

시스템 아키텍처

사용자 질문 → RAG 검색 → 신뢰도 계산 → 답변 생성 → 품질 검증
                ↓ (신뢰도 낮음 또는 품질 나쁨)
            게시물 초안 생성 → 게시판 등록 → 관리자 답변
                ↓
            중복 검사 → RAG 업데이트 → 향후 답변 개선

답변 품질 검증 시스템

• HIGH 신뢰도 + GOOD 품질: 직접 답변 제공
• HIGH 신뢰도 + POOR 품질: 게시글 생성 제안 (신뢰도 조정)
• MEDIUM/LOW 신뢰도: 기존 로직 유지

Initialize Setting

• Python 버전: v3.10.12
• venv 사용
• FastAPI 서버 사용

# (Mac/AI 패키지 호환을 위해 venv 대신 conda 환경 사용 권장)
conda create -n rag-env python=3.11
conda activate rag-env
conda install -c conda-forge faiss-cpu
pip install -r requirements.txt

python -m scripts.init_db_v2

환경 설정

1. env.example 파일을 .env로 복사하고 설정값을 입력하세요:

cp env.example .env

2. 필요한 환경 변수:
   • OPENAI_API_KEY: OpenAI API 키
   • REDIS_URL: Redis 연결 URL (기본값: redis://localhost:6379/0)
   • KAFKA_BROKER: Kafka 브로커 주소 (기본값: kafka-svc:9092)
   • KAFKA_TOPIC: Kafka 토픽 이름 (기본값: customer-service-events)

사전 준비

• docker: v28.x ('25.7.7 기준 lts)
• docker compose: v2.x ('25.7.7 기준 lts)

Redis 서버 설정

Docker 환경

Dockerfile에 Redis 서버가 포함되어 있어 별도 설정이 필요하지 않습니다:

• Redis 서버가 컨테이너 내부에서 자동으로 시작됩니다
• 포트 6379에서 Redis 서버가 실행됩니다
• 애플리케이션은 redis://localhost:6379/0으로 연결됩니다

로컬 개발 환경

로컬에서 Redis 서버를 별도로 실행하려면:

# Ubuntu/Debian
sudo apt update
sudo apt install redis-server
sudo systemctl start redis-server
sudo systemctl enable redis-server

# macOS
brew install redis
brew services start redis

# Redis 연결 테스트
redis-cli ping

사용법 (도커, 개발환경)

실행

# Docker를 통한 실행
bash ./scripts/docker-run.sh <DOCKER HUB ID> <SERVICE NAME> <SERVICE PORT: 옵션>

• 위 명령어 사용시 docker 빌드 -> docker push -> docker run 순서로 진행됩니다.
• SERVICE PORT 는 외부에서 접근 가능한 포트입니다.

# 개발환경에서 실행
uvicorn src.app:app --host 0.0.0.0 --port 8000 --reload

• 위 명령어 사용시 개발환경에서 동작합니다.

테스트

# 기본 헬스 체크
curl -X GET "http://localhost:8000/health"

# Redis 연결 테스트
curl -X GET "http://localhost:8000/api/management/health/detailed"

• 초기 상태일 때 테스트 가능
• {"status": "OK", "message": "Service is running."} 응답 시 테스트 성공
• 상세 헬스 체크에서 Redis 연결 상태도 확인 가능

서비스 변경

• @app.route('/python/**') 경로를 수정해주세요.
• 수정 후 gateway 저장소의 서비스도 수정해야합니다.

API 엔드포인트

메인 API 서버 (src/app.py)

API 경로 구조

/api/management/ 경로는 혼합된 API 그룹입니다:

• 일반 사용자 API: 챗봇 질문, 대화 관리, 피드백 등
• 관리자 API: 시스템 관리, Q&A 검토, RAG 관리 등
• 시스템 API: 성능 모니터링, 통계 등

참고: /api/management/ 경로명이 "관리"를 의미하지만, 실제로는 일반 사용자 기능도 포함되어 있습니다.

헬스 체크

• GET / - API 서버 상태 확인
• GET /health - API 서버 상태 확인
• GET /api/management/health - 관리 시스템 헬스 체크 (상세 상태 포함)
• GET /api/management/health/detailed - 관리 시스템 상세 헬스 체크 (컴포넌트별 상태)

헬스 체크 응답 예시

기본 헬스 체크 (/health)

{
  "status": "OK",
  "message": "Service is running."
}

관리 시스템 헬스 체크 (/api/management/health)

{
  "status": "OK",
  "message": "Management system health check completed",
  "timestamp": "2025-08-07T06:40:24.742358",
  "components": {
    "service": "OK",
    "chromadb": {
      "status": "OK",
      "collections": 2
    },
    "langchain": {
      "status": "OK"
    },
    "conversation_manager": {
      "status": "OK"
    }
  }
}

상세 헬스 체크 (/api/management/health/detailed)

{
  "timestamp": "2025-08-07T06:40:43.037796",
  "overall_status": "OK",
  "components": {
    "chromadb": {
      "status": "OK",
      "collections": 2,
      "rag_documents_count": 0,
      "pending_qna_count": 0,
      "available_collections": ["pending_qna", "rag_documents"]
    },
    "langchain": {
      "status": "OK",
      "confidence_chain": "OK",
      "quality_chain": "OK",
      "rag_chain": "OK"
    },
    "conversation_manager": {
      "status": "OK",
      "memory": "MISSING"
    },
    "rag_manager": {
      "status": "OK"
    },
    "feedback_manager": {
      "status": "OK"
    }
  }
}

일반 사용자 API (User APIs)

• POST /api/management/chat/query - RAG 챗봇 답변 생성
• POST /api/management/chat/query-langchain - LangChain RAG 챗봇 답변 생성
• POST /api/management/conversations/create - 새로운 대화 세션 생성
• GET /api/management/conversations/{user_id}/{conversation_id} - 대화 기록 조회
• POST /api/management/feedback - 사용자 피드백 등록

개발/테스트 API (Development APIs)

• GET /api/management/chat/langchain-history - LangChain 대화 기록 조회
• POST /api/management/chat/langchain-clear - LangChain 대화 기록 초기화
• POST /api/management/chat/compare - 기존 시스템 vs LangChain 성능 비교

관리자 API (Admin APIs)

• POST /api/management/posts/summarize_and_submit - 게시글 요약 및 검수 대기 질문 등록
• GET /api/management/qna/pending - 검수 대기 질문 목록 조회
• POST /api/management/qna/review_and_register - 검수 대기 질문 처리

관리자 기능 API (Admin Functions)

• POST /api/management/admin/submit-answer - 관리자 답변 등록 (RAG 자동 저장)
• POST /api/management/admin/process-answer - 관리자 답변 처리 (중복 검사 포함)
• POST /api/management/admin/batch-process - 일괄 처리 (백엔드/프론트엔드에서 관리)
• GET /api/management/admin/suggest-related/{question} - 관련 Q&A 제안

피드백 관리 API (Feedback Management)

• GET /api/management/feedback/conversation/{conversation_id} - 대화별 피드백 목록 조회
• GET /api/management/feedback/negative-feedback-check/{conversation_id} - 부정적 피드백 확인

RAG 시스템 관리 API (RAG Management)

• GET /api/management/rag/qna - RAG Q&A 목록 조회
• GET /api/management/rag/qna/{qna_id} - RAG Q&A 상세 조회
• POST /api/management/rag/qna/search - RAG Q&A 검색
• PUT /api/management/rag/qna/{qna_id} - RAG Q&A 수정
• DELETE /api/management/rag/qna/{qna_id} - RAG Q&A 삭제
• GET /api/management/rag/qna/statistics - RAG Q&A 통계

시스템 모니터링 API (System Monitoring)

• GET /api/management/confidence/performance - 동적 신뢰도 시스템 성능 메트릭

테스트 및 관리 API (Testing & Management)

• POST /api/management/message - Kafka 메시지 전송 (테스트용)

API 사용 예시

헬스 체크 확인하기

# 기본 헬스 체크
curl -X GET "http://localhost:8000/health"

# 관리 시스템 헬스 체크
curl -X GET "http://localhost:8000/api/management/health"

# 상세 헬스 체크 (컴포넌트별 상태)
curl -X GET "http://localhost:8000/api/management/health/detailed"

RAG 챗봇 질문하기

curl -X POST "http://localhost:8000/api/management/chat/query" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "환불 정책은 어떻게 되나요?",
    "user_id": "user123",
    "conversation_id": "conv456"
  }'

관리자 답변 등록 (RAG 자동 저장)

curl -X POST "http://localhost:8000/api/management/admin/submit-answer" \
  -H "Content-Type: application/json" \
  -d '{
    "post_id": "post123",
    "admin_answer": "환불은 구매 후 7일 이내에 가능합니다.",
    "admin_user_id": "admin001",
    "tags": "환불,정책"
  }'

대화 세션 생성하기

curl -X POST "http://localhost:8000/api/management/conversations/create" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user123"
  }'

배포 (쿠버네티스)

배포 방법

1. 수동 배포 (로컬)

# Kafka 및 Customer Service 함께 배포
bash ./scripts/kube-run.sh <DOCKER_HUB_ID> <SERVICE_NAME>

# 서비스 상태 확인
kubectl get pods -n sangsangplus-backend
kubectl get services -n sangsangplus-backend

2. 자동 배포 (CI/CD)

GitHub Actions를 통한 자동 배포:

• 트리거: main 브랜치에 push 또는 pull request
• 배포 순서: Kafka → Zookeeper → Customer Service
• 헬스 체크: 자동으로 서비스 상태 확인

# main 브랜치에 push하면 자동 배포
git push origin main

포트 설정

포트	용도	설명
8000	메인 애플리케이션 포트	FastAPI 서버 기본 포트
6379	Redis 서버 포트	대화 기록 및 피드백 관리
9092	Kafka 브로커 포트	비동기 메시징
2181	Zookeeper 포트	Kafka 클러스터 관리
80	Kubernetes 서비스 포트	외부 접근용 (HTTP)
8080	CI/CD 헬스 체크용 (임시)	포트 포워딩용

헬스 체크 설정

Kubernetes에서 헬스 체크를 위해 다음 엔드포인트를 사용할 수 있습니다:

Liveness Probe (활성 상태 확인)

livenessProbe:
  httpGet:
    path: '/api/management/health'
    port: 8000
  initialDelaySeconds: 120
  timeoutSeconds: 2
  periodSeconds: 5
  failureThreshold: 5

Readiness Probe (준비 상태 확인)

readinessProbe:
  httpGet:
    path: '/api/management/health'
    port: 8000
  initialDelaySeconds: 10
  timeoutSeconds: 2
  periodSeconds: 5
  failureThreshold: 10

상세 모니터링 (선택사항)

• /api/management/health/detailed 엔드포인트를 사용하여 각 컴포넌트별 상태를 모니터링할 수 있습니다.
• Prometheus나 다른 모니터링 도구에서 활용 가능합니다.

사전 설정

azure 설치

curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

azure 로그인

az login --use-device-code

쿠버네티스 클러스터 연결

az aks get-credentials --resource-group <마이크로소프트 리소스 그룹> --name <마이크로소프트 쿠버네티스 클러스터>

쿠버네티스 CLI 도구 설치

• 링크 참조: https://kubernetes.io/ko/docs/tasks/tools/install-kubectl-linux/

쿠버네티스 설정 실행

bash scripts/kube-run.sh <DOCKER HUB ID>

• 각 설정에 따라 kubernetes/deploy.yml 을 수정해주세요.
• image 는 docker hub에 올린 이미지 사용 (기본: chldlsrb1000/python-service:latest)

추가 명령어

# 제거하기
kubectl delete -f kubernetes/deploy.yml

# 확인하기 (pods, services, deployments..)
kubectl get all

# 로그확인(-f: 실시간 옵션)
kubectl logs <POD NAME>

# 바로 재반영
kubectl get deployment  # 확인
kubectl rollout restart deployment/gateway  # 재반영

주요 변경사항

🗑️ 제거된 기능

• 게시판 API 서버: board_api_server.py 완전 삭제
• 게시판 관련 API 엔드포인트: /api/management/board/* 경로의 모든 API 제거
• 게시판 연동 모듈: src/board_integration.py 단순화 (외부 백엔드/프론트엔드에서 관리)
• 게시판 설정: BOARD_API_BASE_URL, BOARD_API_TOKEN 환경변수 제거

🔄 단순화된 기능

• 일괄 처리: batch_process_pending_answers 단순화 (외부에서 관리)
• 게시판 연동: 외부 백엔드/프론트엔드에서 직접 관리
• 포트 정리: 8083 포트 (게시판 API) 제거

✅ 유지된 핵심 기능

• RAG 자동 연동: 관리자 답변 → RAG 자동 저장 기능 유지
• 대화 기록 관리: Redis 기반 대화 기록 관리
• 피드백 시스템: 사용자 피드백 관리
• 신뢰도 시스템: 동적 신뢰도 계산 및 품질 검증

🐳 Docker 개선사항

• Redis 서버 통합: Dockerfile에 Redis 서버 설치 및 실행 스크립트 추가
• 멀티 포트 지원: 8000 (FastAPI) + 6379 (Redis) 포트 노출
• 자동 시작 스크립트: Redis 서버와 FastAPI 애플리케이션 순차 시작

📦 Kubernetes 서비스 추가

• Kafka 서버: kafka-deploy.yml로 Kafka 및 Zookeeper 서비스 배포
• 서비스 연결: kafka-svc:9092로 Kafka 브로커 연결
• 배포 스크립트: Kafka 서비스와 Customer Service 순차 배포