shared-dg04-hi/ai-review

Fork 0

History

ondal a2a7daf6f6 release

2025-06-16 13:36:14 +09:00

app

release

2025-06-15 13:52:26 +00:00

deployment/container

release

2025-06-16 13:36:14 +09:00

build-base.sh

release

2025-06-15 13:52:26 +00:00

build.sh

release

2025-06-15 13:52:26 +00:00

create-imagepullsecret.sh

release

2025-06-15 13:52:26 +00:00

README.md

release

2025-06-15 13:52:26 +00:00

setup.sh

release

2025-06-15 13:52:26 +00:00

README.md

카카오맵 리뷰 분석 서비스 (교육용)

AI 기반 리뷰 분석을 통해 소상공인의 고객 피드백 관리를 지원하는 RESTful API 서비스입니다.

⚠️ 중요 법적 경고사항

이 서비스는 교육 목적으로만 제작되었습니다.

법적 위험

카카오 이용약관 위반 → 계정 정지, 법적 조치
개인정보보호법(PIPA) 위반 → 과태료 최대 3억원
저작권 및 데이터베이스권 침해 → 손해배상
업무방해죄 → 5년 이하 징역 또는 1천500만원 이하 벌금

합법적 대안

카카오 공식 API 활용 (developers.kakao.com)
점주 대상 자체 가게 관리 서비스 개발
사용자 동의 기반 데이터 수집 앱
카카오와 정식 파트너십 체결

실제 서비스 사용을 금지합니다!

📋 프로젝트 개요

주요 기능

🔍 카카오맵 리뷰 분석: HTML 파싱 및 Selenium 기반 동적 수집
🤖 AI 기반 피드백: Claude API 연동을 통한 맞춤형 개선 방안 제시
📊 감정 분석: 긍정/부정/중립 감정 분류 및 통계
💾 Vector DB 연동: 유사 케이스 검색 및 템플릿 활용
🚀 RESTful API 제공: FastAPI 기반의 완전한 API 서비스
📚 Swagger UI 지원: 자동 생성되는 API 문서
☸️ Kubernetes 배포: 완전한 컨테이너 오케스트레이션 지원
🔧 환경변수 설정: ConfigMap과 Secret을 통한 유연한 설정 관리

기술 스택

Backend: Python 3.11, FastAPI, aiohttp
Web Scraping: Selenium, BeautifulSoup4, Chrome WebDriver
AI/ML: Claude AI API, Vector DB (Chroma)
Database: PostgreSQL (향후), Vector DB
Container: Docker, Multi-stage build
Orchestration: Kubernetes (AKS)
Registry: Azure Container Registry (ACR)
Documentation: Swagger UI, ReDoc

🏗️ 프로젝트 구조

review-api/review/
├── app/                           # 애플리케이션 소스
│   ├── main.py                   # 메인 애플리케이션
│   └── requirements.txt          # Python 의존성
├── deployment/                    # 배포 관련 파일
│   ├── container/                # 컨테이너 이미지 빌드
│   │   ├── Dockerfile           # 서비스 이미지 빌드
│   │   └── Dockerfile-base      # 베이스 이미지 빌드
│   └── manifests/               # Kubernetes 매니페스트
│       ├── configmap.yaml       # 환경 설정
│       ├── secret.yaml          # 민감 정보 (API 키)
│       ├── deployment.yaml      # 애플리케이션 배포
│       ├── service.yaml         # 서비스 노출
│       └── ingress.yaml         # 외부 접근
├── build-base.sh                 # 베이스 이미지 빌드 스크립트
├── build.sh                      # 서비스 이미지 빌드 스크립트
├── create-imagepullsecret.sh     # ACR 인증 설정 스크립트
├── setup.sh                      # 로컬 환경 설정 스크립트
└── README.md                     # 프로젝트 문서

🚀 빠른 시작

1. 로컬 개발 환경 설정

# 저장소 클론 (review-api/review 디렉토리로 이동)
cd review-api/review

# 환경 설정 스크립트 실행
chmod +x setup.sh
./setup.sh

# 가상환경 활성화
source venv/bin/activate

# 애플리케이션 실행
python app/main.py

2. 로컬 웹 브라우저 접속

# 애플리케이션이 정상 실행된 후 아래 URL로 접속

메인 페이지: http://localhost:19000
Swagger UI: http://localhost:19000/docs
ReDoc: http://localhost:19000/redoc
헬스체크: http://localhost:19000/health
진단 정보: http://localhost:19000/diagnostic
법적 경고: http://localhost:19000/legal-warning

3. API 테스트 (교육용)

# 기본 리뷰 분석 (교육용 - 실제 사용 금지)
curl -X POST "http://localhost:19000/analyze" \
     -H "Content-Type: application/json" \
     -d '{
       "store_id": "501745730",
       "days_limit": 7,
       "max_time": 300
     }'

# 환경 설정 확인
curl "http://localhost:19000/config"

# 법적 경고사항 확인
curl "http://localhost:19000/legal-warning"

🐳 Docker 컨테이너 실행

베이스 이미지 빌드

# ACR에 베이스 이미지 빌드 및 푸시
./build-base.sh latest acrdigitalgarage03 rg-digitalgarage-03

서비스 이미지 빌드

# ACR에 서비스 이미지 빌드 및 푸시
./build.sh latest acrdigitalgarage03 rg-digitalgarage-03

로컬 Docker 실행

# 컨테이너 실행
docker run -p 19000:19000 \
  -e APP_TITLE="카카오맵 리뷰 분석 API" \
  -e PORT=19000 \
  kakao-review-api:latest

# 백그라운드 실행
docker run -d -p 19000:19000 \
  --name kakao-review-api \
  -e PORT=19000 \
  kakao-review-api:latest

☸️ Kubernetes 배포

1. ACR Image Pull Secret 생성

# Image Pull Secret 생성
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03

2. Kubernetes 리소스 배포

# ConfigMap 및 Secret 적용
kubectl apply -f deployment/manifests/configmap.yaml
kubectl apply -f deployment/manifests/secret.yaml

# 애플리케이션 배포
kubectl apply -f deployment/manifests/deployment.yaml
kubectl apply -f deployment/manifests/service.yaml
kubectl apply -f deployment/manifests/ingress.yaml

3. 배포 상태 확인

# Pod 상태 확인
kubectl get pods -l app=kakao-review-api

# 서비스 상태 확인
kubectl get svc kakao-review-api-service

# Ingress 상태 확인
kubectl get ingress kakao-review-api-ingress

# 로그 확인
kubectl logs -l app=kakao-review-api -f

4. 🌐 외부 브라우저에서 접속하기

Ingress 주소 확인 방법

# 1. Ingress 설정된 호스트 확인
kubectl get ingress kakao-review-api-ingress -o jsonpath='{.spec.rules[0].host}'

# 2. Ingress External IP 확인 (LoadBalancer 타입인 경우)
kubectl get ingress kakao-review-api-ingress

# 3. Ingress Controller의 External IP 확인
kubectl get svc -n ingress-nginx ingress-nginx-controller

# 4. 현재 설정된 ingress 주소 확인
INGRESS_HOST=$(kubectl get ingress kakao-review-api-ingress -o jsonpath='{.spec.rules[0].host}')
echo "🌐 Review API URL: http://${INGRESS_HOST}"

브라우저 접속 주소

현재 설정된 주소로 접속하세요:

# 현재 설정된 기본 주소 (환경에 따라 다를 수 있음)
INGRESS_URL="http://kakao-review-api.20.249.191.180.nip.io"
echo "브라우저에서 접속: ${INGRESS_URL}"

주요 접속 페이지:

🏠 메인 페이지: http://kakao-review-api.20.249.191.180.nip.io
📖 Swagger UI: http://kakao-review-api.20.249.191.180.nip.io/docs
📄 ReDoc: http://kakao-review-api.20.249.191.180.nip.io/redoc
❤️ 헬스체크: http://kakao-review-api.20.249.191.180.nip.io/health
🔧 진단 정보: http://kakao-review-api.20.249.191.180.nip.io/diagnostic
⚠️ 법적 경고: http://kakao-review-api.20.249.191.180.nip.io/legal-warning

접속 테스트

# API 접속 테스트
curl "http://kakao-review-api.20.249.191.180.nip.io/health"

# 설정 정보 확인
curl "http://kakao-review-api.20.249.191.180.nip.io/config"

# Swagger UI 접속 확인
curl -I "http://kakao-review-api.20.249.191.180.nip.io/docs"

# 법적 경고 확인
curl "http://kakao-review-api.20.249.191.180.nip.io/legal-warning"

⚙️ 환경 설정

환경 변수

변수명	기본값	설명
`APP_TITLE`	`카카오맵 리뷰 분석 API`	애플리케이션 제목
`APP_VERSION`	`1.0.1`	애플리케이션 버전
`HOST`	`0.0.0.0`	서버 호스트
`PORT`	`19000`	서버 포트
`DEFAULT_MAX_TIME`	`300`	기본 최대 스크롤 시간(초)
`DEFAULT_DAYS_LIMIT`	`60`	기본 날짜 제한(일)
`MAX_DAYS_LIMIT`	`365`	최대 날짜 제한(일)
`CHROME_OPTIONS`	`--headless...`	Chrome 브라우저 옵션
`LEGAL_WARNING_ENABLED`	`true`	법적 경고 표시 여부
`CONTACT_EMAIL`	`admin@example.com`	연락처 이메일

Chrome 및 Selenium 설정

현재 서비스는 Chrome WebDriver를 사용합니다:

# Chrome 설치 확인
google-chrome --version

# ChromeDriver 설치 확인
chromedriver --version

# Selenium 테스트
python -c "from selenium import webdriver; print('Selenium 설치됨')"

📊 API 엔드포인트

주요 엔드포인트

Method	Endpoint	설명
`GET`	`/`	메인 페이지
`GET`	`/docs`	Swagger UI 문서
`GET`	`/health`	헬스체크
`GET`	`/diagnostic`	시스템 진단 정보
`POST`	`/analyze`	리뷰 분석 수행 (교육용)
`GET`	`/config`	환경 설정 확인
`GET`	`/legal-warning`	법적 경고사항

리뷰 분석 API 예시 (교육용)

POST /analyze
{
  "store_id": "501745730",
  "days_limit": 7,
  "max_time": 300
}

응답:

{
  "success": true,
  "message": "분석이 성공적으로 완료되었습니다.",
  "store_info": {
    "id": "501745730",
    "name": "맛있는 식당",
    "category": "한식",
    "rating": "4.2",
    "review_count": "1,234"
  },
  "reviews": [...],
  "analysis_date": "2024-06-12T10:30:00",
  "total_reviews": 25,
  "execution_time": 45.2
}

🔧 개발 및 확장

로컬 개발

# 개발 모드로 실행 (자동 재시작)
uvicorn app.main:app --host 0.0.0.0 --port 19000 --reload

# 의존성 추가
pip install 새패키지명
pip freeze > app/requirements.txt

# 코드 포맷팅
black app/main.py
flake8 app/main.py

Ingress 호스트 변경

현재 환경에 맞게 Ingress 호스트를 변경하려면:

# 1. 현재 External IP 확인
kubectl get svc -n ingress-nginx ingress-nginx-controller

# 2. deployment/manifests/ingress.yaml 파일에서 host 수정
# 예: kakao-review-api.{YOUR_EXTERNAL_IP}.nip.io

# 3. 변경사항 적용
kubectl apply -f deployment/manifests/ingress.yaml

# 4. 새로운 주소 확인
kubectl get ingress kakao-review-api-ingress

🐛 문제 해결

일반적인 문제

1. Chrome WebDriver 관련 문제

# Chrome 설치 상태 확인
docker run --rm kakao-review-api:latest google-chrome --version

# ChromeDriver 버전 확인
docker run --rm kakao-review-api:latest chromedriver --version

# 헤드리스 모드 테스트
curl -X POST "http://localhost:19000/analyze" \
     -H "Content-Type: application/json" \
     -d '{"store_id": "test", "days_limit": 1, "max_time": 30}'

2. Kubernetes 배포 실패

# Pod 로그 확인 (Chrome 에러 확인)
kubectl logs -l app=kakao-review-api

# ConfigMap 확인
kubectl get configmap kakao-review-api-config -o yaml

# 리소스 사용량 확인 (Chrome이 메모리를 많이 사용함)
kubectl top pods -l app=kakao-review-api

3. Ingress 접속 실패

# Ingress Controller 상태 확인
kubectl get pods -n ingress-nginx

# Ingress 규칙 확인
kubectl describe ingress kakao-review-api-ingress

# Service 연결 확인
kubectl get endpoints kakao-review-api-service

# 타임아웃 설정 확인 (Chrome 분석은 시간이 오래 걸림)
kubectl get ingress kakao-review-api-ingress -o yaml | grep timeout

4. 포트 관련 문제

로컬 개발: 19000번 포트 사용
Docker 컨테이너: 19000번 포트로 실행
Kubernetes: 19000번 포트로 실행 (Service에서 80번으로 노출, Ingress를 통해 외부 접근)

5. 법적 문제 회피

# 법적 경고 항상 확인
curl "http://kakao-review-api.20.249.191.180.nip.io/legal-warning"

# 교육용임을 명시하는 환경변수 설정
export LEGAL_WARNING_ENABLED=true
export EDUCATIONAL_USE_ONLY=true

🎯 성능 최적화

Chrome 최적화 설정

# deployment.yaml에서 Chrome 최적화를 위한 리소스 설정
resources:
  requests:
    memory: "1Gi"     # Chrome은 메모리를 많이 사용
    cpu: "500m"
  limits:
    memory: "2Gi"     # Chrome 분석을 위한 충분한 메모리
    cpu: "1000m"

타임아웃 설정

# ingress.yaml에서 긴 분석 시간을 고려한 타임아웃
nginx.ingress.kubernetes.io/proxy-read-timeout: "1800"    # 30분
nginx.ingress.kubernetes.io/proxy-send-timeout: "1800"    # 30분

📈 향후 확장 계획

Claude AI 연동: 리뷰 분석 및 개선 방안 자동 생성
Vector DB 구축: 유사 케이스 검색 및 템플릿 관리
PostgreSQL 연동: 분석 결과 영구 저장
다중 플랫폼 지원: 네이버, 구글 등 추가 플랫폼 (합법적 방법으로)
실시간 분석: WebSocket 기반 실시간 피드백
사용자 인증: JWT 기반 인증 시스템
대시보드: 분석 결과 시각화
알림 시스템: 새로운 리뷰 알림 기능
감정 분석 고도화: 더 정확한 감정 분류
비즈니스 통찰: AI 기반 개선 방안 제시

⚖️ 법적 준수 사항

필수 확인 사항

교육용 목적으로만 사용
실제 서비스 환경에서 사용 금지
카카오 이용약관 준수
개인정보보호법 준수
저작권 침해 금지

권장 대안

카카오 공식 API 사용
자체 플랫폼 개발
사용자 동의 기반 수집
정식 파트너십 체결

📞 지원 및 문의

이슈 리포트: GitHub Issues
기술 문의: 개발팀 Slack
법적 문의: 법무팀
API 문서: Swagger UI에서 상세 확인

⚠️ 재고지: 이 서비스는 교육용으로만 제작되었으며, 실제 운영 환경에서의 사용을 엄격히 금지합니다.