Skip to content

About

review llm 서비스입니다.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

🤖 AI 리뷰 분석 서비스

OpenAI GPT를 활용한 지능형 제품 리뷰 분석 서비스입니다. 스마트 파일 파싱, 고급 분석 기능, 한국어 뉘앙스 분석으로 다양한 형식의 파일을 자동으로 인식하여 심층 분석을 제공합니다.

🚀 실시간 서비스

Azure AKS에서 실행 중: http://20.28.65.165/docs

✨ 주요 기능

📊 파일 업로드 기반 리뷰 분석

  • 다중 리뷰 분석: 여러 리뷰를 동시에 분석하여 종합 리포트 생성
  • 통계적 요약: 평균 감정 점수, 평균 평점, 감정 분포 등
  • 트렌드 분석: 평점 변화 추이, 개선/하락 여부 판단
  • 스마트 권장사항: AI 기반 맞춤형 개선 제안

🧠 고급 분석 기능 (신규)

  • 날짜/시간 컬럼 자동 감지: date, timestamp, 작성일 등 시간 관련 컬럼 자동 인식
  • 리뷰-평점 불일치 탐지: AI 예측 평점과 실제 평점의 차이가 큰 리뷰 자동 탐지
  • 한국어 뉘앙스 분석: "가성비가 내리는", "~뿐" 같은 한국어 표현의 진짜 의미 파악
  • 심층 개선 제안: 감정, 평점, 트렌드, 불일치를 종합한 맞춤형 제안
  • 실시간 클라우드 배포: Azure AKS에서 24/7 운영

📁 스마트 파일 업로드 (신규)

  • 다양한 파일 형식 지원: .xlsx, .xls, .csv (최대 10MB)
  • 스마트 컬럼 인식: 파일의 컬럼명을 자동으로 분석하여 리뷰, 상품명, 평점 매핑
  • 유연한 파일 형식: 표준 형식이 아닌 파일도 자동으로 인식
  • 일괄 처리: 수백 개의 리뷰를 한 번에 업로드하여 분석
  • 오류 처리: 잘못된 데이터는 자동으로 필터링하고 처리 결과 보고

🧠 스마트 파싱 및 고급 분석 기능

자동 컬럼 인식

시스템이 파일의 컬럼을 자동으로 분석하여 다음 항목들을 찾아냅니다:

리뷰 텍스트 컬럼

  • 영어: review, comment, text, content, opinion, feedback
  • 한국어: 리뷰, 평가, 후기, 댓글, 내용, 의견
  • 스마트 추정: 컬럼명이 매칭되지 않으면 가장 긴 텍스트가 있는 컬럼을 자동 선택

상품명 컬럼

  • 영어: product, item, name, title
  • 한국어: 상품, 제품, 이름, 제목, 상품명, 제품명

평점 컬럼

  • 영어: rating, score, star, grade, point
  • 한국어: 평점, 점수, 별점, 등급, 점
  • 스마트 추정: 1-5 범위의 숫자 컬럼을 자동으로 평점으로 인식

날짜/시간 컬럼 자동 감지

  • 키워드 기반 매칭: date, time, timestamp, created_at, 작성일, 등록일 등
  • 내용 기반 매칭: 날짜 패턴이 있는 컬럼 자동 감지
  • 형식 자동 인식: YYYY-MM-DD, MM/DD/YYYY 등 다양한 날짜 형식 지원
  • 시간 정보 포함 여부: 날짜만 또는 시간까지 포함된 정보 자동 구분

한국어 뉘앙스 분석

  • 맥락 이해: "가성비가 내리는" = "가성비가 좋은" 의미 정확 파악
  • 부정 표현 해석: "~뿐", "~만" 같은 표현의 진짜 의미 이해
  • 전체적 의도 파악: 부정적 단어가 있어도 전체적으로 긍정적이면 긍정으로 분류

지원하는 파일 형식 예시

표준 형식

review_text,product_name,rating
좋은 제품입니다,스마트폰,5
별로예요,노트북,2

다양한 형식 (자동 인식)

리뷰,상품명,별점
좋은 제품입니다,스마트폰,5
별로예요,노트북,2
후기,제품,점수
좋은 제품입니다,스마트폰,5
별로예요,노트북,2
comment,item,star
좋은 제품입니다,스마트폰,5
별로예요,노트북,2

🛠 기술 스택

  • Backend: FastAPI (Python 3.10.12)
  • AI/ML: OpenAI GPT-3.5-turbo
  • Container: Docker
  • Cloud: Azure Kubernetes Service (AKS)
  • Frontend: HTML5, CSS3, JavaScript (Vanilla)
  • API: RESTful API
  • Data Processing: Pandas, OpenPyXL (엑셀/CSV 파일 처리)
  • Smart Parsing: 자동 컬럼 인식 및 매핑
  • Advanced Analysis: 날짜/시간 감지, 불일치 탐지, 한국어 뉘앙스 분석
  • Deployment: Docker Hub, Azure Container Registry

📋 사전 요구사항

로컬 개발

  • Python 3.10.12
  • Docker & Docker Compose
  • OpenAI API Key

클라우드 배포

  • Azure CLI
  • Azure 구독 (Azure for Students 포함)
  • kubectl CLI 도구
  • Docker Hub 계정

🚀 빠른 시작

🌐 실시간 서비스 사용 (가장 빠름)

Azure AKS에서 실행 중: http://20.28.65.165/docs

바로 파일을 업로드하고 분석을 시작할 수 있습니다!

1. 로컬 환경 설정

# 저장소 클론
git clone <repository-url>
cd review-service

# 가상환경 생성 및 활성화
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 의존성 설치
pip install -r requirements.txt

2. 환경 변수 설정

.env 파일을 생성하고 OpenAI API 키를 설정하세요:

# .env 파일 생성
echo "OPENAI_API_KEY=your-openai-api-key-here" > .env
echo "MODE=development" >> .env

3. Docker로 실행 (권장)

# Docker 이미지 빌드
docker build -t <docker id>/review-service:dev .

# 컨테이너 실행
docker run -d --rm --name review-service \
  -p 5001:5001 \
  --env-file .env \
  <docker id>/review-service:dev

# 컨테이너 상태 확인
docker ps

4. 로컬 개발 모드 실행

# 개발 모드로 실행
uvicorn src.app:app --host 0.0.0.0 --port 5001 --reload

📡 API 엔드포인트

🌐 실시간 클라우드 서비스 (Azure AKS)

엔드포인트 메서드 설명
/api/review/health GET 서비스 상태 확인
/api/review/upload-file POST 파일 업로드 및 리뷰 분석
/api/review/batch-manual POST 수동 배치 리뷰 분석
/api/review/integrated-analysis POST 고급 통합 분석
/docs GET API 문서 (Swagger UI)

🏠 로컬 개발 환경

기본 URL: http://localhost:5001

엔드포인트 메서드 설명 접근 URL
/api/review/health GET 서비스 상태 확인 http://localhost:5001/api/review/health
/api/review/upload-file POST 파일 업로드 및 리뷰 분석 http://localhost:5001/api/review/upload-file
/api/review/batch-manual POST 수동 배치 리뷰 분석 http://localhost:5001/api/review/batch-manual
/api/review/integrated-analysis POST 고급 통합 분석 http://localhost:5001/api/review/integrated-analysis
/docs GET API 문서 (Swagger UI) http://localhost:5001/docs

📡 API 사용법

실시간 클라우드 서비스

curl -X POST "http://20.28.65.165/api/review/upload-file" \
  -F "file=@reviews.csv" \
  -F "product_name=스마트폰"

로컬 개발 환경

curl -X POST "http://localhost:5001/api/review/upload-file" \
  -F "file=@reviews.csv" \
  -F "product_name=스마트폰"

응답 예시:

{
  "status": "success",
  "message": "총 3개의 리뷰가 성공적으로 처리되었습니다.",
  "total_reviews": 3,
  "processed_reviews": 3,
  "failed_reviews": 0,
  "analysis_report": {
    "product_name": "스마트폰",
    "summary": {
      "total_reviews": 3,
      "average_sentiment_score": 0.7,
      "sentiment_distribution": {"긍정": 2, "부정": 0, "중립": 1},
      "average_rating": 4.0,
      "common_key_points": ["제품 품질", "배송 속도"],
      "top_suggestions": ["가격 정책 검토", "현재 품질 유지"],
      "overall_sentiment": "긍정",
      "confidence_score": 0.67
    },
    "individual_analyses": [...],
    "trends": {...},
    "recommendations": [...],
    "date_analysis": {
      "message": "날짜/시간 컬럼 '작성일'이 감지되었습니다. 날짜 정보만 (형식: YYYY-MM-DD)",
      "date_column": "작성일",
      "has_time": false,
      "date_format": "YYYY-MM-DD"
    },
    "discrepancy_analysis": {
      "total_discrepancies": 1,
      "discrepancy_reviews": [
        {
          "review_text": "가성비가 내리는 제품, 고민은 배송만 늦출 뿐...",
          "actual_rating": 5,
          "predicted_rating": 2,
          "discrepancy_score": 0.75,
          "sentiment": "긍정",
          "reason": "주의 필요: 실제 평점(5점)이 예측 평점(2점)보다 높음; 부정적인 감정이지만 높은 평점을 부여"
        }
      ]
    }
  }
}

🌐 웹 인터페이스

실시간 클라우드 서비스 (권장)

Azure AKS에서 실행 중: http://20.28.65.165/docs

주요 기능:

  • 🌐 실시간 API 문서: Swagger UI를 통한 인터랙티브 테스트
  • 📁 파일 업로드: 엑셀/CSV 파일 직접 업로드 및 분석
  • 🧠 스마트 컬럼 인식: 자동 컬럼 매핑
  • 📊 실시간 분석 결과: JSON 형태의 상세 분석 리포트
  • 🔍 오류 처리: 상세한 오류 메시지 및 디버깅 정보

로컬 파일 업로드 테스트

브라우저에서 test_excel_upload.html 파일을 열어 다양한 형식의 파일 업로드를 테스트할 수 있습니다.

주요 기능:

  • 📁 엑셀/CSV 파일 드래그 앤 드롭 업로드
  • 🧠 스마트 컬럼 인식 및 매핑
  • 📋 파일 형식 안내 및 샘플 파일 다운로드
  • ⚡ 실시간 업로드 진행 상황 표시
  • 📊 업로드 결과 및 분석 리포트 표시
  • 🔍 오류 발생 시 상세 오류 메시지 제공

🔧 개발 모드

로컬 실행

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

# 개발 모드로 실행
uvicorn src.app:app --host 0.0.0.0 --port 5001 --reload

API 테스트

# 헬스 체크
curl http://localhost:5001/api/review/health

# 기본 API 테스트
curl http://localhost:5001/api/review/health

🐳 Docker 배포

개발 환경

# 이미지 빌드
docker build -t <docker id>/review-service:dev .

# 컨테이너 실행
docker run -d --rm --name review-service \
  -p 5001:5001 \
  --env-file .env \
  <docker id>/review-service:dev

프로덕션 환경

# 환경 변수 설정
export MODE=production
export OPENAI_API_KEY="your-api-key"

# 컨테이너 실행
docker run -d --name review-service \
  -p 5001:5001 \
  --env-file .env \
  <docker id>/review-service:dev

☁️ Azure Kubernetes Service (AKS) 배포

📋 사전 요구사항

  • Azure CLI 설치 및 로그인
  • Azure 구독 (Azure for Students 포함)
  • kubectl CLI 도구
  • Docker Hub 계정

🔧 Azure CLI 설정

# Azure CLI 설치 (macOS)
brew install azure-cli

# Azure 로그인
az login

# 구독 확인
az account show

# 리소스 그룹 생성 (필요시)
az group create --name sangsang --location australiacentral

🚀 AKS 클러스터 생성

# AKS 확장 설치
az extension add --name aks-preview

# 필요한 서비스 공급자 등록
az provider register --namespace Microsoft.ContainerService
az provider register --namespace Microsoft.OperationsManagement
az provider register --namespace Microsoft.OperationalInsights

# AKS 클러스터 생성
az aks create \
  --resource-group sangsang \
  --name review-service-cluster \
  --node-count 1 \
  --generate-ssh-keys \
  --disable-rbac

# 클러스터 자격 증명 가져오기
az aks get-credentials --resource-group sangsang --name review-service-cluster

📦 멀티 플랫폼 Docker 이미지 빌드

# Buildx 활성화
docker buildx create --use

# 멀티 플랫폼 이미지 빌드 및 푸시
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t <docker id>/review-service:latest \
  --push .

🔐 Kubernetes Secret 생성

# OpenAI API 키를 Secret으로 생성
kubectl create secret generic openai-secret \
  --from-literal=api-key="$OPENAI_API_KEY"

🚀 AKS에 배포

# 쿠버네티스 리소스 배포
kubectl apply -f kubernetes/

# 배포 상태 확인
kubectl get pods -l app=review-service
kubectl get services -l app=review-service

🌐 외부 접근 설정

# Load Balancer 서비스 생성
kubectl expose deployment review-service \
  --type=LoadBalancer \
  --port=80 \
  --target-port=5001

# 외부 IP 확인
kubectl get services

📊 배포 상태 확인

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

# 서비스 상태 확인
kubectl get services

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

# 헬스 체크
curl http://<EXTERNAL-IP>/api/review/health

🌐 서비스 접근

배포 완료 후 다음 URL로 접근 가능:

  • API 문서: http:///docs
  • 헬스 체크: http:///api/review/health
  • 파일 업로드: http:///api/review/upload-file

🛠 문제 해결

이미지 풀 오류

# Pod 상세 정보 확인
kubectl describe pod -l app=review-service

# 이미지 태그 확인
docker images <docker id>/review-service

Secret 오류

# Secret 확인
kubectl get secret openai-secret -o yaml

# Secret 재생성
kubectl delete secret openai-secret
kubectl create secret generic openai-secret \
  --from-literal=api-key="$OPENAI_API_KEY"

클러스터 연결 오류

# 클러스터 정보 확인
kubectl cluster-info

# 자격 증명 재설정
az aks get-credentials --resource-group sangsang --name review-service-cluster --overwrite-existing

🗑 정리

# AKS 클러스터 삭제
az aks delete --resource-group sangsang --name review-service-cluster

# 리소스 그룹 삭제 (모든 리소스 포함)
az group delete --name sangsang --yes --no-wait

☸️ 로컬 Kubernetes 배포 (Docker Desktop)

# Docker Desktop에서 Kubernetes 활성화
# Docker Desktop → Settings → Kubernetes → Enable Kubernetes

# 배포 실행
bash scripts/kube-run.sh <docker id>

# Port Forward로 접근
kubectl port-forward service/review-service-svc 5001:5001

📊 모니터링

헬스 체크

curl http://localhost:5001/api/review/health

로그 확인

# Docker 로그
docker logs review-service

# 쿠버네티스 로그
kubectl logs deployment/review-service

🔍 문제 해결

실시간 서비스 접근

  1. 서비스 상태 확인: http://20.28.65.165/api/review/health
  2. API 문서 확인: http://20.28.65.165/docs
  3. 네트워크 연결: 인터넷 연결 상태 확인

파일 업로드 오류

  1. 파일 형식 확인: .xlsx, .xls, .csv 형식만 지원
  2. 파일 크기 확인: 최대 10MB 제한
  3. 컬럼 인식 확인: 리뷰 내용이 포함된 컬럼이 있는지 확인

스마트 파싱 오류

  1. 컬럼명 확인: 리뷰, 상품명, 평점 관련 키워드가 포함된 컬럼명 사용
  2. 데이터 형식 확인: 평점은 1-5 범위의 숫자여야 함
  3. 텍스트 길이 확인: 리뷰 텍스트는 충분한 길이(10자 이상)여야 함

고급 분석 관련

  1. 날짜 컬럼 인식: 날짜 관련 키워드가 포함된 컬럼명 사용 권장
  2. 한국어 뉘앙스: 복잡한 한국어 표현의 경우 정확한 분석을 위해 충분한 컨텍스트 제공
  3. 불일치 탐지: AI 예측과 실제 평점의 차이가 0.3 이상일 때 불일치로 분류

CORS 오류

브라우저에서 API 호출 시 CORS 오류가 발생하면:

  1. FastAPI에 CORS 미들웨어가 설정되어 있는지 확인
  2. 올바른 포트로 접근하는지 확인

OpenAI API 오류

  1. 로컬 환경: .env 파일에 올바른 API 키가 설정되어 있는지 확인
  2. 클라우드 환경: Azure AKS의 Secret이 올바르게 설정되어 있는지 확인
  3. API 키 크레딧: API 키에 충분한 크레딧이 있는지 확인
  4. 네트워크 연결: 인터넷 연결 상태 확인

Docker 연결 오류

# 컨테이너 상태 확인
docker ps

# 컨테이너 재시작
docker restart review-service

# 로그 확인
docker logs review-service

Azure AKS 연결 오류

# 클러스터 상태 확인
kubectl cluster-info

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

# 서비스 상태 확인
kubectl get services

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

📈 성능 최적화

  • 배치 처리: 여러 리뷰를 한 번에 분석하여 API 호출 최소화
  • 스마트 파싱: 파일 형식에 관계없이 자동으로 컬럼 인식
  • 캐싱: 자주 분석되는 패턴에 대한 결과 캐싱
  • 비동기 처리: FastAPI의 비동기 특성을 활용한 동시 처리
  • 클라우드 스케일링: Azure AKS를 통한 자동 확장 및 고가용성
  • 멀티 플랫폼: ARM64/AMD64 아키텍처 호환으로 다양한 환경 지원

📊 프로젝트 요약

🎯 현재 상태

🏗 아키텍처

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   Frontend      │    │   Backend       │    │   Cloud         │
│   (HTML/JS)     │───▶│   (FastAPI)     │───▶│   (Azure AKS)   │
│                 │    │                 │    │                 │
│ - 파일 업로드      │    │ - AI 분석        │    │ - 24/7 운영      │
│ - 결과 표시       │    │ - 스마트 파싱      │    │ - 자동 스케일링    │
└─────────────────┘    └─────────────────┘    └─────────────────┘

🚀 새로운 기능

v2.2 업데이트 (최신)

  • ✅ 실시간 클라우드 서비스: Azure AKS에서 24/7 운영 중
  • ✅ 한국어 뉘앙스 분석 개선: "~뿐" 같은 표현의 정확한 의미 파악
  • ✅ 고급 분석 기능 완성: 날짜/시간 컬럼 자동 감지, 리뷰-평점 불일치 탐지
  • ✅ 심층 개선 제안: 감정, 평점, 트렌드, 불일치를 종합한 맞춤형 제안
  • ✅ 모듈화된 구조: advanced_analysis.py로 고급 기능 분리
  • ✅ 완전한 배포 파이프라인: Docker → Docker Hub → Azure AKS

v2.1 업데이트

  • ✅ 고급 분석 기능: 날짜/시간 컬럼 자동 감지, 리뷰-평점 불일치 탐지
  • ✅ 한국어 뉘앙스 분석: "~뿐" 같은 표현의 정확한 의미 파악
  • ✅ 심층 개선 제안: 감정, 평점, 트렌드, 불일치를 종합한 맞춤형 제안
  • ✅ 모듈화된 구조: advanced_analysis.py로 고급 기능 분리
  • ✅ Azure AKS 배포: 클라우드 환경에서의 완전한 배포 가이드
  • ✅ 멀티 플랫폼 지원: ARM64/AMD64 아키텍처 호환 이미지

v2.0 업데이트

  • ✅ 스마트 파일 파싱: 다양한 컬럼명 자동 인식
  • ✅ CSV 파일 지원: UTF-8 인코딩으로 한글 지원
  • ✅ 통합 API 엔드포인트: /api/review/upload-file
  • ✅ 향상된 오류 처리: 더 상세한 오류 메시지
  • ✅ 코드 간소화: 불필요한 기능 제거로 유지보수성 향상

About

review llm 서비스입니다.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages