From 57ee3be53dba83d7f8fca9c2ae8ba874aae58f03 Mon Sep 17 00:00:00 2001 From: hiondal Date: Mon, 16 Jun 2025 02:32:56 +0000 Subject: [PATCH] release --- vector/README.md | 952 ++++++++++++++++++++++++--------------------- vector/app/main.py | 2 +- 2 files changed, 502 insertions(+), 452 deletions(-) diff --git a/vector/README.md b/vector/README.md index f8d1eba..6e12411 100644 --- a/vector/README.md +++ b/vector/README.md @@ -1,614 +1,664 @@ -# 음식점 Vector DB 구축 서비스 +# 🍽️ Vector - 음식점 Vector DB 구축 및 AI 추천 서비스 -카카오 로컬 API를 활용하여 음식점 정보를 수집하고 Vector DB로 구축한 후, Claude AI와 연동하여 점주의 비즈니스 개선 요청을 처리하는 서비스입니다. +카카오 로컬 API를 활용하여 음식점 정보와 리뷰를 수집하고, **Chroma DB** 기반 Vector DB로 구축한 후, **Claude AI**와 연동하여 소상공인의 비즈니스 개선을 지원하는 마이크로서비스입니다. -## 📋 프로젝트 개요 +## 🎯 프로젝트 개요 -### 주요 기능 -- 🔍 **카카오 로컬 API 연동**: 키워드 및 지역 기반 음식점 검색 -- 🤖 **Vector DB 구축**: Sentence Transformer를 이용한 임베딩 및 Chroma DB 저장 -- 🔄 **중복 처리 개선**: 기존 데이터 존재 여부 확인 및 업데이트/신규 추가 분리 -- 🧠 **Claude AI 연동**: 점주 액션 요청에 대한 맞춤형 조언 생성 -- 🎯 **유사도 검색**: Vector DB를 활용한 유사 음식점 검색 -- 📊 **처리 통계**: 신규 추가, 업데이트, 중복 등 상세 통계 제공 -- 🚀 **RESTful API 제공**: FastAPI 기반의 완전한 API 서비스 -- 📚 **Swagger UI 지원**: 자동 생성되는 API 문서 -- ☸️ **Kubernetes 배포**: 완전한 컨테이너 오케스트레이션 지원 -- 🔧 **환경변수 설정**: ConfigMap과 Secret을 통한 유연한 설정 관리 +### 핵심 기능 +- **🔍 스마트 음식점 검색**: 지역과 가게명으로 타겟 음식점 자동 발견 +- **📊 동종업체 리뷰 수집**: 카카오맵 리뷰 대량 수집 및 전처리 +- **🤖 Vector DB 구축**: Sentence Transformers 기반 고품질 임베딩 생성 +- **🧠 AI 비즈니스 컨설팅**: Claude Sonnet 4 기반 맞춤형 액션 플랜 제공 +- **🔄 실시간 API 서비스**: RESTful API 기반 완전 자동화 시스템 +- **☸️ 클라우드 네이티브**: Kubernetes 기반 확장 가능한 마이크로서비스 -### 기술 스택 -- **Backend**: Python 3.11, FastAPI, aiohttp -- **Vector DB**: Chroma DB -- **ML**: Sentence Transformers, torch -- **AI**: Anthropic Claude API -- **External API**: Kakao Local API -- **Container**: Docker, Multi-stage build -- **Orchestration**: Kubernetes (AKS) +### 비즈니스 가치 +- **소상공인**: 동종업체 분석을 통한 데이터 기반 경영 개선 +- **경쟁 우위**: AI 기반 개인화된 비즈니스 전략 제공 +- **운영 효율**: 완전 자동화된 분석 및 추천 시스템 + +## 🏗️ 기술 아키텍처 + +### 🔧 백엔드 스택 +- **Framework**: FastAPI 0.115.9 (고성능 비동기 API) +- **Language**: Python 3.11 (최신 타입 힌팅 지원) +- **Dependency Management**: Poetry (락 파일 기반 재현 가능한 빌드) + +### 🤖 AI/ML 스택 +- **Vector DB**: ChromaDB 1.0.12 (HNSW 알고리즘 기반) +- **Embedding Model**: `sentence-transformers/all-MiniLM-L6-v2` (384차원) +- **AI Engine**: Claude Sonnet 4 (`claude-sonnet-4-20250514`) +- **ML Framework**: PyTorch 2.7.1+cpu, Transformers 4.52.4 + +### 🚀 인프라 스택 +- **Container**: Docker (Multi-stage build 최적화) +- **Orchestration**: Kubernetes (AKS 배포) - **Registry**: Azure Container Registry (ACR) -- **Documentation**: Swagger UI, ReDoc +- **Storage**: Persistent Volume (Vector DB 데이터 영속화) -## 🏗️ 프로젝트 구조 +### 🔗 외부 연동 +- **Restaurant API**: 카카오 로컬 API 기반 음식점 검색 서비스 +- **Review API**: 카카오맵 리뷰 수집 서비스 +- **Claude API**: Anthropic Claude AI API + +## 📁 프로젝트 구조 ``` -review-api/vector/ -├── app/ # 애플리케이션 소스 -│ ├── main.py # 메인 애플리케이션 -│ ├── requirements.txt # Python 의존성 -│ ├── config/ # 설정 관리 -│ │ └── settings.py # 환경 설정 -│ ├── models/ # 데이터 모델 -│ ├── services/ # 비즈니스 로직 -│ │ ├── vector_service.py # Vector DB 서비스 -│ │ ├── claude_service.py # Claude AI 서비스 -│ │ └── kakao_service.py # 카카오 API 서비스 -│ └── utils/ # 유틸리티 함수 -│ └── data_utils.py # 데이터 처리 유틸 -├── deployment/ # 배포 관련 파일 -│ ├── container/ # 컨테이너 이미지 빌드 -│ │ ├── Dockerfile # 서비스 이미지 빌드 -│ │ └── Dockerfile-base # 베이스 이미지 빌드 -│ └── manifests/ # Kubernetes 매니페스트 -│ ├── configmap.yaml # 환경 설정 -│ ├── secret.yaml # 민감 정보 (API 키) -│ ├── deployment.yaml # 애플리케이션 배포 -│ ├── service.yaml # 서비스 노출 -│ ├── ingress.yaml # 외부 접근 -│ └── pvc.yaml # 영구 저장소 (Vector DB) -├── build-base.sh # 베이스 이미지 빌드 스크립트 -├── build.sh # 서비스 이미지 빌드 스크립트 -├── create-imagepullsecret.sh # ACR 인증 설정 스크립트 -├── setup.sh # 로컬 환경 설정 스크립트 -└── README.md # 프로젝트 문서 +vector/ +├── app/ # 메인 애플리케이션 +│ ├── main.py # FastAPI 애플리케이션 엔트리포인트 +│ ├── config/ +│ │ └── settings.py # 환경별 설정 관리 +│ ├── models/ # Pydantic 데이터 모델 +│ │ ├── vector_models.py # Vector DB 요청/응답 모델 +│ │ ├── restaurant_models.py # 음식점 정보 모델 +│ │ └── review_models.py # 리뷰 데이터 모델 +│ ├── services/ # 비즈니스 로직 서비스 +│ │ ├── vector_service.py # Vector DB 관리 서비스 +│ │ ├── claude_service.py # Claude AI 통합 서비스 +│ │ ├── restaurant_service.py # 음식점 검색 서비스 +│ │ └── review_service.py # 리뷰 수집 서비스 +│ └── utils/ +│ └── category_utils.py # 음식 카테고리 추출 유틸 +├── deployment/ # 배포 인프라 +│ ├── container/ +│ │ ├── Dockerfile # 메인 서비스 이미지 +│ │ └── Dockerfile-base # 베이스 의존성 이미지 +│ └── manifests/ # Kubernetes 리소스 +│ ├── configmap.yaml # 환경 설정 +│ ├── secret.yaml # API 키 등 민감 정보 +│ ├── deployment.yaml # 애플리케이션 배포 +│ ├── service.yaml # 내부 서비스 노출 +│ ├── ingress.yaml # 외부 접근 설정 +│ └── pvc.yaml # Vector DB 영구 볼륨 +├── pyproject.toml # Poetry 의존성 정의 +├── poetry.lock # 의존성 락 파일 +├── setup.sh # 로컬 개발 환경 자동 설정 +├── build-base.sh # 베이스 이미지 빌드 +├── build.sh # 메인 이미지 빌드 +├── create-imagepullsecret.sh # ACR 인증 설정 +└── README.md # 프로젝트 문서 ``` -## 📋 사전 작업 +## 📊 API 엔드포인트 -### 카카오 API 설정 -카카오 developers 포탈에서 애플리케이션 등록이 필요합니다. +### 🏠 메인 서비스 +| Method | Endpoint | 설명 | 요청 모델 | 응답 모델 | +|--------|----------|------|-----------|-----------| +| `GET` | `/` | 서비스 홈페이지 (HTML) | - | HTMLResponse | +| `GET` | `/docs` | Swagger UI API 문서 | - | HTMLResponse | +| `GET` | `/health` | 헬스체크 | - | JSONResponse | +| `GET` | `/vector-status` | Vector DB 상태 확인 | - | VectorDBStatusResponse | -1. **포탈 접속**: https://developers.kakao.com/console/app -2. **애플리케이션 등록**: - - 앱 이름: `VectorDBBuilder` - - 회사명: `{회사명}` - - 카테고리: `식음료` -3. **카카오맵 활성화**: 등록한 애플리케이션에서 좌측 '카카오맵' 메뉴 클릭하여 활성화 - -### Claude API 설정 -Anthropic Claude API 키가 필요합니다. - -1. **포탈 접속**: https://console.anthropic.com/ -2. **API 키 발급**: Console에서 API Keys 메뉴에서 발급 -3. **모델 확인**: `claude-sonnet-4-20250514` 사용 +### 🔍 핵심 비즈니스 API +| Method | Endpoint | 설명 | 요청 모델 | 응답 모델 | +|--------|----------|------|-----------|-----------| +| `POST` | `/find-reviews` | 리뷰 수집 및 Vector DB 저장 | VectorBuildRequest | FindReviewsResponse | +| `POST` | `/action-recommendation` | AI 기반 비즈니스 추천 | ActionRecommendationRequest | ActionRecommendationSimpleResponse | ## 🚀 빠른 시작 -### 1. 로컬 개발 환경 설정 +### 1. 사전 준비 +#### 필수 API 키 발급 + +**카카오 API 설정** ```bash -# 저장소 클론 (review-api/vector 디렉토리로 이동) -cd review-api/vector +# 1. 카카오 개발자 센터 접속 +https://developers.kakao.com/console/app -# 환경 설정 스크립트 실행 (시간이 오래 걸림) +# 2. 애플리케이션 등록 +- 앱 이름: VectorDBBuilder +- 카테고리: 식음료 + +# 3. 카카오맵 API 활성화 +- 좌측 메뉴 > 카카오맵 > 활성화 +``` + +**Claude API 설정** +```bash +# 1. Anthropic Console 접속 +https://console.anthropic.com/ + +# 2. API 키 발급 +- API Keys 메뉴에서 새 키 생성 +- 모델: claude-sonnet-4-20250514 +``` + +### 2. 로컬 개발 환경 + +#### 자동 환경 설정 +```bash +# 저장소 클론 +git clone +cd vector + +# Poetry 및 의존성 자동 설치 chmod +x setup.sh ./setup.sh +``` -# 가상환경 활성화 -source venv/bin/activate - -# Claude API 키 설정 (.env 파일 생성/수정) +#### 환경변수 설정 +```bash +# .env 파일 생성 cat > .env << EOF -CLAUDE_API_KEY=your-actual-claude-api-key -KAKAO_API_KEY=your-kakao-api-key +# Claude API 설정 +CLAUDE_API_KEY=your-claude-api-key +CLAUDE_MODEL=claude-sonnet-4-20250514 + +# API 서버 설정 (로컬 개발용) +RESTAURANT_API_HOST=0.0.0.0 +RESTAURANT_API_PORT=18000 +REVIEW_API_HOST=0.0.0.0 +REVIEW_API_PORT=19000 + +# Vector DB 설정 +VECTOR_DB_PATH=./vectordb +VECTOR_DB_COLLECTION=restaurant_reviews +EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2 + +# 애플리케이션 설정 +HOST=0.0.0.0 +PORT=8000 +LOG_LEVEL=info EOF - -# 애플리케이션 실행 -python app/main.py ``` -### 2. 로컬 웹 브라우저 접속 - +#### 서비스 실행 ```bash -# 애플리케이션이 정상 실행된 후 아래 URL로 접속 +# 개발 모드 (자동 재시작) +poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload + +# 또는 직접 실행 +poetry run python app/main.py ``` -- **메인 페이지**: http://localhost:8000 -- **Swagger UI**: http://localhost:8000/docs -- **ReDoc**: http://localhost:8000/redoc -- **헬스체크**: http://localhost:8000/health -- **Vector DB 상태**: http://localhost:8000/vector-status -- **환경 설정**: http://localhost:8000/config - -### 3. API 테스트 +### 3. Docker 실행 ```bash -# 1. Vector DB 구축 (지역과 가게명으로 동종업체 분석) -curl -X POST "http://localhost:8000/build-vector-db" \ - -H "Content-Type: application/json" \ - -d '{ - "region": "서울특별시 강남구 역삼동", - "store_name": "맛있는 치킨집", - "force_rebuild": false - }' +# 베이스 이미지 빌드 (의존성 캐싱) +./build-base.sh -# 2. 점주 액션 요청 (Claude AI 기반 조언) -curl -X POST "http://localhost:8000/action-request" \ - -H "Content-Type: application/json" \ - -d '{ - "store_id": "12345", - "context": "매출이 감소하고 있어서 메뉴 개선이 필요합니다." - }' +# 메인 서비스 이미지 빌드 +./build.sh -# 3. Vector DB 상태 확인 -curl "http://localhost:8000/vector-status" - -# 4. 환경 설정 확인 -curl "http://localhost:8000/config" - -# 5. 유사 음식점 검색 -curl -X POST "http://localhost:8000/search-similar" \ - -H "Content-Type: application/json" \ - -d '{ - "query": "분위기 좋은 카페", - "business_type": "카페", - "limit": 5 - }' +# 컨테이너 실행 (환경변수 파일 사용) +docker run -p 8000:8000 --env-file .env vector-api:latest ``` -## 🐳 Docker 컨테이너 실행 - -### 베이스 이미지 빌드 +### 4. Kubernetes 배포 +#### ACR 인증 설정 ```bash -# ACR에 베이스 이미지 빌드 및 푸시 -./build-base.sh latest acrdigitalgarage03 rg-digitalgarage-03 - -# 로컬 베이스 이미지 빌드 -./build-base.sh latest -``` - -### 서비스 이미지 빌드 - -```bash -# ACR에 서비스 이미지 빌드 및 푸시 -./build.sh latest acrdigitalgarage03 rg-digitalgarage-03 - -# 로컬 서비스 이미지 빌드 -./build.sh latest -``` - -### 로컬 Docker 실행 - -```bash -# 컨테이너 실행 (환경변수 설정 필요) -docker run -p 8000:8000 \ - -e KAKAO_API_KEY="your-kakao-api-key" \ - -e CLAUDE_API_KEY="your-claude-api-key" \ - -e PORT=8000 \ - -v $(pwd)/vector_db:/app/vectordb \ - vector-api:latest - -# 백그라운드 실행 (영구 볼륨 사용) -docker volume create vector_db_vol -docker run -d -p 8000:8000 \ - --name vector-api \ - -e KAKAO_API_KEY="your-kakao-api-key" \ - -e CLAUDE_API_KEY="your-claude-api-key" \ - -e PORT=8000 \ - -v vector_db_vol:/app/vectordb \ - vector-api:latest - -# 컨테이너 로그 확인 -docker logs vector-api -f - -# Vector DB 데이터 확인 -docker exec -it vector-api ls -la /app/vectordb/ -``` - -## ☸️ Kubernetes 배포 - -### 1. ACR Image Pull Secret 생성 - -```bash -# Image Pull Secret 생성 +# Azure Container Registry 인증 ./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03 ``` -### 2. Kubernetes 리소스 배포 - +#### 리소스 배포 ```bash -# 영구 볼륨 생성 (Vector DB 저장용) +# 1. 영구 볼륨 생성 (Vector DB 저장용) kubectl apply -f deployment/manifests/pvc.yaml -# ConfigMap 및 Secret 적용 +# 2. 설정 정보 생성 kubectl apply -f deployment/manifests/configmap.yaml kubectl apply -f deployment/manifests/secret.yaml -# 애플리케이션 배포 +# 3. 애플리케이션 배포 kubectl apply -f deployment/manifests/deployment.yaml kubectl apply -f deployment/manifests/service.yaml kubectl apply -f deployment/manifests/ingress.yaml ``` -### 3. 배포 상태 확인 - +#### 배포 상태 확인 ```bash # Pod 상태 확인 kubectl get pods -l app=vector-api -# 서비스 상태 확인 +# 서비스 상태 확인 kubectl get svc vector-api-service -# Ingress 상태 확인 +# Ingress 확인 kubectl get ingress vector-api-ingress -# PVC 상태 확인 (Vector DB 저장소) -kubectl get pvc vector-db-pvc - -# 로그 확인 +# 로그 모니터링 kubectl logs -l app=vector-api -f - -# Vector DB 디렉토리 확인 -kubectl exec -it deployment/vector-api -- ls -la /app/vectordb/ ``` -### 4. 🌐 외부 브라우저에서 접속하기 +## 🌐 서비스 접속 -#### Ingress 주소 확인 방법 +### 배포된 서비스 URL ```bash -# 1. Ingress 설정된 호스트 확인 -kubectl get ingress vector-api-ingress -o jsonpath='{.spec.rules[0].host}' - -# 2. Ingress External IP 확인 (LoadBalancer 타입인 경우) -kubectl get ingress vector-api-ingress - -# 3. Ingress Controller의 External IP 확인 -kubectl get svc -n ingress-nginx ingress-nginx-controller - -# 4. 현재 설정된 ingress 주소 확인 -INGRESS_HOST=$(kubectl get ingress vector-api-ingress -o jsonpath='{.spec.rules[0].host}') -echo "🌐 Vector API URL: http://${INGRESS_HOST}" -``` - -#### 브라우저 접속 주소 - -현재 설정된 주소로 접속하세요: - -```bash -# 현재 설정된 기본 주소 (환경에 따라 다를 수 있음) +# 현재 배포된 서비스 주소 INGRESS_URL="http://vector-api.20.249.191.180.nip.io" -echo "브라우저에서 접속: ${INGRESS_URL}" ``` -**주요 접속 페이지:** -- **🏠 메인 페이지**: http://vector-api.20.249.191.180.nip.io -- **📖 Swagger UI**: http://vector-api.20.249.191.180.nip.io/docs -- **📄 ReDoc**: http://vector-api.20.249.191.180.nip.io/redoc -- **❤️ 헬스체크**: http://vector-api.20.249.191.180.nip.io/health -- **🗂️ Vector DB 상태**: http://vector-api.20.249.191.180.nip.io/vector-status -- **⚙️ 환경 설정**: http://vector-api.20.249.191.180.nip.io/config +| 서비스 | URL | 설명 | +|--------|-----|------| +| **🏠 홈페이지** | http://vector-api.20.249.191.180.nip.io | 서비스 대시보드 | +| **📖 API 문서** | http://vector-api.20.249.191.180.nip.io/docs | Swagger UI | +| **📄 ReDoc** | http://vector-api.20.249.191.180.nip.io/redoc | API 문서 (ReDoc) | +| **❤️ 헬스체크** | http://vector-api.20.249.191.180.nip.io/health | 서비스 상태 | +| **🗂️ Vector DB 상태** | http://vector-api.20.249.191.180.nip.io/vector-status | DB 상태 확인 | -#### 접속 테스트 +### 접속 테스트 ```bash -# API 접속 테스트 +# 서비스 상태 확인 curl "http://vector-api.20.249.191.180.nip.io/health" # Vector DB 상태 확인 curl "http://vector-api.20.249.191.180.nip.io/vector-status" +``` -# 설정 정보 확인 -curl "http://vector-api.20.249.191.180.nip.io/config" +## 💡 API 사용 예제 -# Swagger UI 접속 확인 -curl -I "http://vector-api.20.249.191.180.nip.io/docs" +### 1. 리뷰 수집 및 Vector DB 구축 + +**요청** +```bash +curl -X POST "http://vector-api.20.249.191.180.nip.io/find-reviews" \ + -H "Content-Type: application/json" \ + -d '{ + "region": "서울특별시 강남구 역삼동", + "store_name": "맛있는 치킨집" + }' +``` + +**응답** +```json +{ + "success": true, + "message": "총 127개 리뷰, 8개 업체 분석됨", + "target_store": { + "id": "501745730", + "place_name": "맛있는 치킨집", + "category_name": "음식점 > 치킨", + "address_name": "서울특별시 강남구 역삼동 123-45", + "phone": "02-123-4567", + "x": "127.0276", + "y": "37.4979" + }, + "food_category": "치킨", + "total_reviews": 127, + "total_stores": 8, + "execution_time": 45.2, + "stored_data": { + "501745730": { + "store_info": { /* 가게 정보 */ }, + "reviews": [ /* 리뷰 목록 */ ], + "review_summary": { + "total_reviews": 23, + "average_rating": 4.2, + "positive_keywords": ["맛있음", "친절", "깨끗"] + }, + "combined_at": "2024-06-16T10:30:00" + } + } +} +``` + +### 2. AI 기반 비즈니스 추천 + +**요청** +```bash +curl -X POST "http://vector-api.20.249.191.180.nip.io/action-recommendation" \ + -H "Content-Type: application/json" \ + -d '{ + "store_id": "501745730", + "context": "매출이 감소하고 있어서 메뉴 개선이 필요합니다." + }' +``` + +**응답** +```json +{ + "success": true, + "recommendation": { + "priority_actions": [ + { + "category": "메뉴 혁신", + "action": "시즌 한정 메뉴 도입", + "description": "여름 시즌 한정으로 매운 치킨 신메뉴를 출시하여 화제성과 재방문율을 높입니다.", + "priority": "high", + "timeframe": "1-2주", + "expected_impact": "매출 15-20% 증가 예상" + }, + { + "category": "고객 경험", + "action": "배달 서비스 최적화", + "description": "포장재 개선과 배달 시간 단축으로 고객 만족도를 높입니다.", + "priority": "medium", + "timeframe": "2-3주", + "expected_impact": "고객 만족도 향상" + } + ], + "market_insights": { + "competitor_analysis": "동종업체 대비 평균 별점 0.3점 낮음", + "improvement_areas": ["서비스 속도", "메뉴 다양성", "매장 청결도"] + }, + "success_cases": [ + { + "store_name": "○○치킨", + "improvement": "신메뉴 출시 후 월 매출 25% 증가", + "key_factors": ["SNS 마케팅", "맛 차별화", "가격 경쟁력"] + } + ] + }, + "input_data": { + "store_context": "치킨 전문점, 강남구 위치", + "similar_stores_analyzed": 7, + "total_reviews_considered": 104 + } +} ``` ## ⚙️ 환경 설정 ### 필수 환경변수 -| 변수명 | 설명 | 기본값 | 예시 | -|--------|------|--------|------| -| `KAKAO_API_KEY` | 카카오 API 키 | - | `your-kakao-api-key` | -| `CLAUDE_API_KEY` | Claude API 키 | - | `sk-ant-api03-...` | -| `CLAUDE_MODEL` | Claude 모델명 | `claude-sonnet-4-20250514` | `claude-sonnet-4-20250514` | +| 변수명 | 설명 | 예시 | 기본값 | +|--------|------|------|--------| +| `CLAUDE_API_KEY` | Claude AI API 키 | `sk-ant-api03-...` | - | +| `RESTAURANT_API_HOST` | Restaurant API 호스트 | `localhost` | `0.0.0.0` | +| `RESTAURANT_API_PORT` | Restaurant API 포트 | `18000` | `18000` | +| `REVIEW_API_HOST` | Review API 호스트 | `localhost` | `0.0.0.0` | +| `REVIEW_API_PORT` | Review API 포트 | `19000` | `19000` | ### 선택적 환경변수 -| 변수명 | 설명 | 기본값 | 예시 | -|--------|------|--------|------| -| `HOST` | 서버 호스트 | `0.0.0.0` | `localhost` | -| `PORT` | 서버 포트 | `8000` | `8000` | -| `LOG_LEVEL` | 로그 레벨 | `info` | `debug` | -| `VECTOR_DB_PATH` | Vector DB 경로 | `/app/vectordb` | `/data/vectordb` | -| `VECTOR_DB_COLLECTION` | 컬렉션명 | `restaurant_reviews` | `stores` | -| `EMBEDDING_MODEL` | 임베딩 모델 | `sentence-transformers/all-MiniLM-L6-v2` | - | -| `MAX_RESTAURANTS_PER_CATEGORY` | 카테고리별 최대 음식점 수 | `50` | `100` | -| `MAX_REVIEWS_PER_RESTAURANT` | 음식점별 최대 리뷰 수 | `100` | `200` | +| 변수명 | 설명 | 기본값 | +|--------|------|--------| +| `CLAUDE_MODEL` | Claude 모델명 | `claude-sonnet-4-20250514` | +| `VECTOR_DB_PATH` | Vector DB 저장 경로 | `./vectordb` | +| `VECTOR_DB_COLLECTION` | 컬렉션명 | `restaurant_reviews` | +| `EMBEDDING_MODEL` | 임베딩 모델 | `sentence-transformers/all-MiniLM-L6-v2` | +| `MAX_RESTAURANTS_PER_CATEGORY` | 카테고리별 최대 수집 음식점 | `50` | +| `MAX_REVIEWS_PER_RESTAURANT` | 음식점별 최대 리뷰 수 | `100` | +| `LOG_LEVEL` | 로그 레벨 | `info` | -## 📊 API 엔드포인트 +### Kubernetes 환경 자동 감지 -### 주요 엔드포인트 +시스템이 자동으로 환경을 감지하여 적절한 설정을 적용합니다: -| Method | Endpoint | 설명 | -|--------|----------|------| -| `GET` | `/` | 메인 페이지 | -| `GET` | `/docs` | Swagger UI 문서 | -| `GET` | `/health` | 헬스체크 | -| `GET` | `/vector-status` | Vector DB 상태 확인 | -| `GET` | `/config` | 환경 설정 확인 | -| `POST` | `/build-vector-db` | Vector DB 구축 | -| `POST` | `/action-request` | AI 액션 요청 | -| `POST` | `/search-similar` | 유사 음식점 검색 | -| `GET` | `/collections` | 컬렉션 목록 조회 | +- **로컬 개발**: `localhost` 기반 API 연동 +- **Kubernetes**: 서비스 디스커버리 기반 연동 + - `restaurant-api-service:80` + - `kakao-review-api-service:80` -### Vector DB 구축 API 예시 - -```json -POST /build-vector-db -{ - "region": "서울특별시 강남구 역삼동", - "store_name": "맛있는 치킨집", - "force_rebuild": false -} -``` - -**응답:** -```json -{ - "success": true, - "message": "Vector DB 구축이 완료되었습니다.", - "statistics": { - "total_processed": 150, - "newly_added": 120, - "updated": 25, - "duplicates": 5, - "total_vectors": 1450 - }, - "execution_time": 245.8, - "store_info": { - "name": "맛있는 치킨집", - "region": "서울특별시 강남구 역삼동", - "business_type": "치킨", - "similar_stores_found": 15 - } -} -``` - -### AI 액션 요청 API 예시 - -```json -POST /action-request -{ - "store_id": "12345", - "context": "매출이 감소하고 있어서 메뉴 개선이 필요합니다." -} -``` - -**응답:** -```json -{ - "success": true, - "recommendations": [ - { - "category": "메뉴 개선", - "priority": "high", - "action": "시즌 한정 메뉴 도입", - "description": "고객 선호도가 높은 트렌디한 메뉴를 계절별로 출시하여 재방문율을 높입니다.", - "timeframe": "1-2주", - "expected_impact": "매출 15-20% 증가 예상" - } - ], - "similar_cases": 3, - "analysis_date": "2024-06-12T10:30:00" -} -``` - -## 🔧 개발 및 확장 +## 🔧 개발 가이드 ### 로컬 개발 ```bash -# 개발 모드로 실행 (자동 재시작) -uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload - # 의존성 추가 -pip install 새패키지명 -pip freeze > app/requirements.txt +poetry add 새패키지명 -# Vector DB 디렉토리 확인 -ls -la ./vector_db/ +# 개발 서버 실행 (Hot Reload) +poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload -# 코드 포맷팅 -black app/ -flake8 app/ +# 직접 실행 +poetry run python app/main.py + +# 의존성 업데이트 +poetry update + +# 가상환경 정보 확인 +poetry env info ``` -### Ingress 호스트 변경 - -현재 환경에 맞게 Ingress 호스트를 변경하려면: +### 코드 품질 ```bash -# 1. 현재 External IP 확인 -kubectl get svc -n ingress-nginx ingress-nginx-controller +# 코드 포맷팅 +poetry run black app/ -# 2. deployment/manifests/ingress.yaml 파일에서 host 수정 -# 예: vector-api.{YOUR_EXTERNAL_IP}.nip.io +# 린팅 +poetry run flake8 app/ -# 3. 변경사항 적용 -kubectl apply -f deployment/manifests/ingress.yaml +# 타입 체크 +poetry run mypy app/ +``` -# 4. 새로운 주소 확인 -kubectl get ingress vector-api-ingress +### Docker 개발 + +```bash +# 베이스 이미지 재빌드 (의존성 변경 시) +./build-base.sh + +# 서비스 이미지 빌드 +./build.sh + +# 로컬 실행 +docker run -p 8000:8000 --env-file .env vector-api:latest ``` ## 🐛 문제 해결 ### 일반적인 문제 -**1. Claude API 키 관련 문제** +**1. Vector DB 초기화 실패** ```bash -# API 키 유효성 확인 +# Vector DB 상태 확인 +curl "http://localhost:8000/vector-status" + +# 로그 확인 +kubectl logs -l app=vector-api | grep -i vector + +# Vector DB 디렉토리 확인 (Kubernetes) +kubectl exec -it deployment/vector-api -- ls -la /app/vectordb/ +``` + +**2. Claude API 연결 실패** +```bash +# API 키 유효성 테스트 curl -X POST "https://api.anthropic.com/v1/messages" \ - -H "x-api-key: your-claude-api-key" \ - -H "Content-Type: application/json" \ - -d '{ - "model": "claude-sonnet-4-20250514", - "max_tokens": 10, - "messages": [{"role": "user", "content": "Hi"}] - }' + -H "x-api-key: your-claude-api-key" \ + -H "Content-Type: application/json" \ + -d '{ + "model": "claude-sonnet-4-20250514", + "max_tokens": 10, + "messages": [{"role": "user", "content": "Hi"}] + }' # 환경변수 확인 -echo $CLAUDE_API_KEY +kubectl exec -it deployment/vector-api -- env | grep CLAUDE ``` -**2. Vector DB 관련 문제** +**3. 외부 API 연동 실패** ```bash -# Vector DB 디렉토리 권한 확인 -ls -la /app/vectordb/ +# Restaurant API 연결 테스트 +kubectl exec -it deployment/vector-api -- curl http://restaurant-api-service/health -# Vector DB 초기화 -curl -X POST "http://localhost:8000/reset-vector-db" +# Review API 연결 테스트 +kubectl exec -it deployment/vector-api -- curl http://kakao-review-api-service/health -# Collection 상태 확인 -curl "http://localhost:8000/vector-status" -``` - -**3. Kubernetes 배포 실패** -```bash -# Pod 로그 확인 (Vector DB 초기화 에러) -kubectl logs -l app=vector-api - -# PVC 상태 확인 -kubectl get pvc vector-db-pvc -kubectl describe pvc vector-db-pvc - -# ConfigMap 확인 -kubectl get configmap vector-api-config -o yaml - -# Secret 확인 -kubectl get secret vector-api-secret -o yaml +# 서비스 디스커버리 확인 +kubectl get svc | grep -E "(restaurant|review)" ``` **4. 메모리 부족 문제** ```bash -# Vector DB 및 ML 모델이 메모리를 많이 사용 +# 리소스 사용량 확인 kubectl top pods -l app=vector-api -# 리소스 제한 확인 -kubectl describe pod -l app=vector-api +# Pod 리소스 제한 확인 +kubectl describe pod -l app=vector-api | grep -A 5 -B 5 Resources + +# 메모리 사용량 모니터링 +kubectl exec -it deployment/vector-api -- free -h ``` -**5. 포트 관련 문제** -- 로컬 개발: 8000번 포트 -- Docker 컨테이너: 8000번 포트 -- Kubernetes: Service 80번 → Ingress 외부 접근 +**5. 영구 볼륨 문제** +```bash +# PVC 상태 확인 +kubectl get pvc vector-db-pvc +kubectl describe pvc vector-db-pvc -## 🎯 성능 최적화 +# 볼륨 마운트 확인 +kubectl exec -it deployment/vector-api -- df -h /app/vectordb +``` -### Vector DB 최적화 설정 +### 성능 최적화 +**메모리 최적화** ```yaml -# deployment.yaml에서 Vector DB 최적화를 위한 리소스 설정 +# deployment.yaml에서 리소스 조정 resources: requests: - memory: "2Gi" # Vector DB와 ML 모델이 메모리를 많이 사용 - cpu: "1000m" # 임베딩 계산을 위한 CPU + memory: "2Gi" # Vector DB + ML 모델 + cpu: "1000m" # 임베딩 계산 limits: - memory: "4Gi" # Vector 계산 및 Claude API 호출을 위한 충분한 메모리 - cpu: "2000m" # 병렬 처리를 위한 CPU + memory: "4Gi" # 대량 처리를 위한 여유 + cpu: "2000m" # 병렬 처리 ``` -### 영구 저장소 설정 +**Vector DB 최적화** +- 임베딩 배치 처리로 메모리 효율성 향상 +- 중복 데이터 감지로 불필요한 재처리 방지 +- 적절한 청크 크기로 메모리 사용량 조절 -```yaml -# pvc.yaml에서 Vector DB 저장소 설정 -spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 10Gi # Vector 데이터 저장을 위한 충분한 공간 +## 📈 모니터링 및 로깅 + +### 헬스체크 모니터링 + +```bash +# 주기적 헬스체크 +watch -n 5 "curl -s http://vector-api.20.249.191.180.nip.io/health | jq" + +# Vector DB 상태 모니터링 +watch -n 10 "curl -s http://vector-api.20.249.191.180.nip.io/vector-status | jq" ``` -### 타임아웃 설정 +### 로그 분석 -```yaml -# ingress.yaml에서 Vector DB 구축 시간을 고려한 타임아웃 -nginx.ingress.kubernetes.io/proxy-read-timeout: "1800" # 30분 -nginx.ingress.kubernetes.io/proxy-send-timeout: "1800" # 30분 +```bash +# 실시간 로그 스트림 +kubectl logs -l app=vector-api -f + +# 에러 로그 필터링 +kubectl logs -l app=vector-api | grep -i error + +# Claude API 호출 로그 +kubectl logs -l app=vector-api | grep -i claude + +# Vector DB 작업 로그 +kubectl logs -l app=vector-api | grep -i vector ``` -## 📈 Vector DB 워크플로우 +## 🎯 워크플로우 다이어그램 -### 1. Vector DB 구축 과정 +### Vector DB 구축 프로세스 ```mermaid -graph TD - A[점주 요청] --> B[지역 및 업종 분석] - B --> C[카카오 API 음식점 수집] - C --> D[리뷰 데이터 수집] - D --> E[텍스트 전처리] - E --> F[Sentence Transformer 임베딩] - F --> G[Chroma DB 저장] - G --> H[중복 제거 및 메타데이터 구성] - H --> I[Vector DB 완성] +sequenceDiagram + participant Client + participant VectorAPI + participant RestaurantAPI + participant ReviewAPI + participant VectorDB + participant ClaudeAI + + Client->>VectorAPI: POST /find-reviews + VectorAPI->>RestaurantAPI: 타겟 음식점 검색 + RestaurantAPI-->>VectorAPI: 음식점 정보 반환 + VectorAPI->>RestaurantAPI: 동종업체 검색 + RestaurantAPI-->>VectorAPI: 경쟁업체 목록 반환 + + loop 각 음식점 + VectorAPI->>ReviewAPI: 리뷰 수집 + ReviewAPI-->>VectorAPI: 리뷰 데이터 반환 + end + + VectorAPI->>VectorAPI: 텍스트 전처리 및 임베딩 + VectorAPI->>VectorDB: Vector 저장 + VectorDB-->>VectorAPI: 저장 완료 + VectorAPI-->>Client: 결과 반환 ``` -### 2. AI 액션 추천 과정 +### AI 추천 프로세스 ```mermaid -graph TD - A[점주 액션 요청] --> B[컨텍스트 분석] - B --> C[Vector 유사도 검색] - C --> D[관련 케이스 추출] - D --> E[Claude AI 프롬프트 구성] - E --> F[Claude API 호출] - F --> G[맞춤형 액션 플랜 생성] - G --> H[우선순위 및 실행 방안 제시] +sequenceDiagram + participant Client + participant VectorAPI + participant VectorDB + participant ClaudeAI + + Client->>VectorAPI: POST /action-recommendation-simple + VectorAPI->>VectorDB: 유사 케이스 검색 + VectorDB-->>VectorAPI: 관련 데이터 반환 + VectorAPI->>VectorAPI: 컨텍스트 구성 + VectorAPI->>ClaudeAI: 추천 요청 + ClaudeAI-->>VectorAPI: 액션 플랜 반환 + VectorAPI->>VectorAPI: JSON 파싱 + VectorAPI-->>Client: 구조화된 추천 반환 ``` -## 📈 향후 확장 계획 +## 📈 향후 로드맵 -- [ ] **다중 Vector DB 지원**: FAISS, Pinecone 추가 지원 -- [ ] **실시간 업데이트**: 새로운 리뷰 자동 임베딩 및 추가 -- [ ] **감정 분석 고도화**: 더 정교한 감정 및 의도 분류 -- [ ] **업종별 특화**: 업종별 맞춤형 Vector 모델 개발 -- [ ] **A/B 테스트**: 추천 효과 측정 및 개선 -- [ ] **대시보드**: Vector DB 현황 및 성능 모니터링 -- [ ] **배치 처리**: 대규모 데이터 처리 최적화 -- [ ] **API 버전 관리**: 하위 호환성 보장 -- [ ] **멀티모달 지원**: 이미지, 텍스트 통합 임베딩 -- [ ] **비즈니스 인텔리전스**: 시장 트렌드 분석 기능 +### Phase 1: 기능 안정화 ✅ +- [x] Vector DB 구축 및 관리 +- [x] Claude AI 통합 +- [x] 마이크로서비스 아키텍처 +- [x] Kubernetes 배포 +- [x] API 문서화 -## 🧠 AI/ML 구성 요소 +### Phase 2: 기능 확장 🚧 +- [ ] **실시간 데이터 수집**: 새로운 리뷰 자동 업데이트 +- [ ] **다중 Vector DB 지원**: FAISS, Pinecone 추가 +- [ ] **감정 분석 고도화**: 세밀한 감정 분류 및 트렌드 분석 +- [ ] **업종별 특화 모델**: 음식점 유형별 맞춤 추천 -### Sentence Transformers -- **모델**: `all-MiniLM-L6-v2` (다국어 지원, 384차원) -- **용도**: 한국어 텍스트 임베딩 -- **특징**: 빠른 속도, 합리적인 정확도 +### Phase 3: 고급 기능 📋 +- [ ] **실시간 대시보드**: Grafana 기반 모니터링 +- [ ] **A/B 테스트 프레임워크**: 추천 효과 측정 +- [ ] **멀티모달 분석**: 이미지 + 텍스트 통합 분석 +- [ ] **예측 분석**: 매출 및 트렌드 예측 모델 -### Chroma Vector DB -- **저장 방식**: 영구 저장 (PVC) -- **인덱싱**: HNSW 알고리즘 -- **메타데이터**: 필터링 및 검색 최적화 +### Phase 4: 엔터프라이즈 📊 +- [ ] **API 배치 처리**: 대량 데이터 일괄 처리 +- [ ] **고급 보안**: OAuth 2.0, API 키 관리 +- [ ] **멀티 테넌트**: 고객별 격리된 데이터 관리 +- [ ] **비즈니스 인텔리전스**: 시장 분석 및 보고서 생성 -### Claude AI -- **모델**: `claude-sonnet-4-20250514` -- **용도**: 비즈니스 액션 추천 -- **특징**: 높은 품질의 한국어 분석 +## 🤝 기여 가이드 ---- +### 개발 워크플로우 + +1. **이슈 생성**: 기능 요청 또는 버그 리포트 +2. **브랜치 생성**: `feature/기능명` 또는 `fix/버그명` +3. **개발 및 테스트**: 로컬에서 충분한 테스트 +4. **Pull Request**: 코드 리뷰 요청 +5. **배포**: 검토 후 메인 브랜치 병합 + +### 코딩 컨벤션 + +- **타입 힌팅**: 모든 함수와 변수에 타입 명시 +- **Docstring**: Google 스타일 문서화 +- **에러 처리**: 모든 외부 API 호출에 예외 처리 +- **로깅**: 적절한 로그 레벨과 구조화된 메시지 ## 📞 지원 및 문의 -- **이슈 리포트**: GitHub Issues -- **기술 문의**: 개발팀 Slack -- **API 문의**: Anthropic Support -- **API 문서**: Swagger UI에서 상세 확인 +### 기술 지원 +- **🐛 버그 리포트**: GitHub Issues +- **💡 기능 제안**: GitHub Discussions +- **📚 API 문의**: Swagger UI 문서 참조 +- **📧 기술 지원**: 개발팀 Slack 채널 + +### 문서 및 리소스 +- **📖 API 문서**: http://vector-api.20.249.191.180.nip.io/docs +- **🔧 모니터링**: http://vector-api.20.249.191.180.nip.io/vector-status +- **❤️ 헬스체크**: http://vector-api.20.249.191.180.nip.io/health --- -**💡 팁: Vector DB 구축에는 시간이 오래 걸릴 수 있으니 충분한 타임아웃을 설정하고 진행 상황을 모니터링하세요.** +## 📝 라이선스 +이 프로젝트는 소상공인의 성장과 데이터 기반 의사결정을 지원하는 목적으로 개발되었습니다. + +--- + +**💡 핵심 가치**: AI와 데이터의 힘으로 소상공인의 성공을 돕습니다! +**🎯 미션**: 모든 소상공인이 데이터 기반으로 스마트한 경영 결정을 내릴 수 있도록 지원합니다. \ No newline at end of file diff --git a/vector/app/main.py b/vector/app/main.py index 8837001..d07f51d 100644 --- a/vector/app/main.py +++ b/vector/app/main.py @@ -542,7 +542,7 @@ async def find_reviews( ) @app.post( - "/action-recommendation-simple", + "/action-recommendation", response_model=ActionRecommendationSimpleResponse, summary="간소화된 액션 추천 요청", description="JSON 추천 결과만 반환하는 최적화된 엔드포인트 + INPUT 데이터 포함"