shared-dg04-hi/ai-review
7
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ai-review/vector/README.md
hiondal ea36d7b221 release
2025-06-16 02:39:55 +00:00

972 lines
29 KiB
Markdown
Raw Blame History

# 🍽️ Vector - 음식점 Vector DB 구축 및 AI 추천 서비스
카카오 로컬 API를 활용하여 음식점 정보와 리뷰를 수집하고, **Chroma DB** 기반 Vector DB로 구축한 후, **Claude AI**와 연동하여 소상공인의 비즈니스 개선을 지원하는 마이크로서비스입니다.
## 🎯 프로젝트 개요
### 핵심 기능
- **🔍 스마트 음식점 검색**: 지역과 가게명으로 타겟 음식점 자동 발견
- **📊 동종업체 리뷰 수집**: 카카오맵 리뷰 대량 수집 및 전처리
- **🤖 Vector DB 구축**: Sentence Transformers 기반 고품질 임베딩 생성
- **🧠 AI 비즈니스 컨설팅**: Claude Sonnet 4 기반 맞춤형 액션 플랜 제공
- **🔄 실시간 API 서비스**: RESTful API 기반 완전 자동화 시스템
- **☸️ 클라우드 네이티브**: Kubernetes 기반 확장 가능한 마이크로서비스
### 비즈니스 가치
- **소상공인**: 동종업체 분석을 통한 데이터 기반 경영 개선
- **경쟁 우위**: 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)
- **Storage**: Persistent Volume (Vector DB 데이터 영속화)
### 🔗 외부 연동
- **Restaurant API**: 카카오 로컬 API 기반 음식점 검색 서비스
- **Review API**: 카카오맵 리뷰 수집 서비스
- **Claude API**: Anthropic Claude AI API
## 📁 프로젝트 구조
```
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 엔드포인트
### 🏠 메인 서비스
| Method | Endpoint | 설명 | 요청 모델 | 응답 모델 |
|--------|----------|------|-----------|-----------|
| `GET` | `/` | 서비스 홈페이지 (HTML) | - | HTMLResponse |
| `GET` | `/docs` | Swagger UI API 문서 | - | HTMLResponse |
| `GET` | `/health` | 헬스체크 | - | JSONResponse |
| `GET` | `/vector-status` | Vector DB 상태 확인 | - | VectorDBStatusResponse |
### 🔍 핵심 비즈니스 API
| Method | Endpoint | 설명 | 요청 모델 | 응답 모델 |
|--------|----------|------|-----------|-----------|
| `POST` | `/find-reviews` | 리뷰 수집 및 Vector DB 저장 | VectorBuildRequest | FindReviewsResponse |
| `POST` | `/action-recommendation` | AI 기반 비즈니스 추천 | ActionRecommendationRequest | ActionRecommendationSimpleResponse |
## 🚀 빠른 시작
### 1. 사전 준비
#### 필수 API 키 발급
**카카오 API 설정**
```bash
# 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 <repository-url>
cd vector
# Poetry 및 의존성 자동 설치
chmod +x setup.sh
./setup.sh
```
#### 환경변수 설정
```bash
# .env 파일 생성
cat > .env << EOF
# 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
```
#### 서비스 실행
```bash
# 개발 모드 (자동 재시작)
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# 또는 직접 실행
poetry run python app/main.py
```
### 3. Docker 실행
```bash
# 베이스 이미지 빌드 (의존성 캐싱)
./build-base.sh
# 메인 서비스 이미지 빌드
./build.sh
# 컨테이너 실행 (환경변수 파일 사용)
docker run -p 8000:8000 --env-file .env vector-api:latest
```
### 4. Kubernetes 배포
#### ACR 인증 설정
```bash
# Azure Container Registry 인증
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03
```
#### 리소스 배포
```bash
# 1. 영구 볼륨 생성 (Vector DB 저장용)
kubectl apply -f deployment/manifests/pvc.yaml
# 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
```
#### 배포 상태 확인
```bash
# Pod 상태 확인
kubectl get pods -l app=vector-api
# 서비스 상태 확인
kubectl get svc vector-api-service
# Ingress 확인
kubectl get ingress vector-api-ingress
# 로그 모니터링
kubectl logs -l app=vector-api -f
```
## 🌐 서비스 접속
### 배포된 서비스 URL
```bash
# 현재 배포된 서비스 주소
INGRESS_URL="http://vector-api.20.249.191.180.nip.io"
```
| 서비스 | 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
# 서비스 상태 확인
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"
```
## 💡 API 사용 예제
### 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",
"place_url": "http://place.map.kakao.com/501745730",
"x": "127.0276543",
"y": "37.4979234"
},
"food_category": "치킨",
"total_reviews": 127,
"total_stores": 8,
"execution_time": 45.2,
"stored_data": {
"501745730": {
"store_info": {
"id": "501745730",
"name": "맛있는 치킨집",
"category": "음식점 > 치킨",
"rating": "4.2",
"review_count": "23",
"status": "영업중",
"address": "서울특별시 강남구 역삼동 123-45",
"phone": "02-123-4567",
"place_url": "http://place.map.kakao.com/501745730",
"x": "127.0276543",
"y": "37.4979234"
},
"reviews": [
{
"reviewer_name": "김○○",
"reviewer_level": "골드리뷰어",
"reviewer_stats": {
"reviews": 156,
"average_rating": 4.3,
"followers": 23
},
"rating": 5,
"date": "2024-06-10",
"content": "치킨이 정말 맛있어요! 바삭하고 양념이 잘 배어있어서 자꾸 손이 갑니다. 배달도 빨라서 좋았어요.",
"badges": ["맛집", "친절", "빠른배달"],
"likes": 12,
"photo_count": 3,
"has_photos": true
},
{
"reviewer_name": "이○○",
"reviewer_level": "실버리뷰어",
"reviewer_stats": {
"reviews": 89,
"average_rating": 4.1,
"followers": 8
},
"rating": 4,
"date": "2024-06-08",
"content": "치킨은 맛있는데 가격이 조금 비싼 것 같아요. 그래도 재주문 의향 있습니다.",
"badges": ["맛있음", "가격"],
"likes": 7,
"photo_count": 1,
"has_photos": true
},
{
"reviewer_name": "박○○",
"reviewer_level": "브론즈리뷰어",
"reviewer_stats": {
"reviews": 34,
"average_rating": 3.9,
"followers": 2
},
"rating": 3,
"date": "2024-06-05",
"content": "치킨은 괜찮은데 배달이 좀 늦었어요. 포장도 조금 아쉬웠습니다.",
"badges": ["배달지연", "포장"],
"likes": 3,
"photo_count": 0,
"has_photos": false
}
],
"review_summary": {
"total_reviews": 23,
"average_rating": 4.2,
"rating_distribution": {
"5": 8,
"4": 9,
"3": 4,
"2": 1,
"1": 1
},
"positive_keywords": [
"맛있음",
"바삭함",
"친절",
"빠른배달"
],
"negative_keywords": [
"가격",
"배달지연",
"포장"
],
"common_keywords": [
"맛있음",
"치킨",
"배달",
"친절",
"가격",
"바삭함"
],
"sentiment_analysis": {
"positive": 65.2,
"neutral": 26.1,
"negative": 8.7
},
"photo_reviews": 15,
"recent_trend": "상승",
"peak_hours": ["19:00-21:00", "12:00-13:00"]
},
"combined_at": "2024-06-16T10:30:15"
},
"502156891": {
"store_info": {
"id": "502156891",
"name": "황금치킨",
"category": "음식점 > 치킨",
"rating": "4.4",
"review_count": "67",
"status": "영업중",
"address": "서울특별시 강남구 역삼동 234-56",
"phone": "02-234-5678",
"place_url": "http://place.map.kakao.com/502156891",
"x": "127.0298765",
"y": "37.4965432"
},
"reviews": [
{
"reviewer_name": "최○○",
"reviewer_level": "플래티넘리뷰어",
"reviewer_stats": {
"reviews": 234,
"average_rating": 4.5,
"followers": 45
},
"rating": 5,
"date": "2024-06-12",
"content": "여기 치킨은 정말 최고예요! 특히 양념치킨이 달콤하면서도 매콤해서 중독성이 있어요. 사장님도 너무 친절하시고 서비스도 좋습니다.",
"badges": ["최고", "양념치킨", "친절", "서비스"],
"likes": 18,
"photo_count": 4,
"has_photos": true
},
{
"reviewer_name": "정○○",
"reviewer_level": "골드리뷰어",
"reviewer_stats": {
"reviews": 145,
"average_rating": 4.2,
"followers": 19
},
"rating": 4,
"date": "2024-06-09",
"content": "맛은 좋은데 매장이 좀 좁아요. 포장해서 먹는 걸 추천합니다.",
"badges": ["맛좋음", "매장좁음", "포장추천"],
"likes": 9,
"photo_count": 2,
"has_photos": true
}
],
"review_summary": {
"total_reviews": 67,
"average_rating": 4.4,
"rating_distribution": {
"5": 32,
"4": 25,
"3": 7,
"2": 2,
"1": 1
},
"positive_keywords": [
"최고",
"양념치킨",
"친절",
"맛좋음",
"서비스"
],
"negative_keywords": [
"매장좁음",
"대기시간"
],
"common_keywords": [
"양념치킨",
"맛좋음",
"친절",
"서비스",
"최고",
"포장"
],
"sentiment_analysis": {
"positive": 73.1,
"neutral": 20.9,
"negative": 6.0
},
"photo_reviews": 45,
"recent_trend": "상승",
"peak_hours": ["18:00-20:00", "12:00-14:00"]
},
"combined_at": "2024-06-16T10:31:22"
},
"503789456": {
"store_info": {
"id": "503789456",
"name": "크리스피치킨",
"category": "음식점 > 치킨",
"rating": "3.9",
"review_count": "34",
"status": "영업중",
"address": "서울특별시 강남구 역삼동 345-67",
"phone": "02-345-6789",
"place_url": "http://place.map.kakao.com/503789456",
"x": "127.0312345",
"y": "37.4951234"
},
"reviews": [
{
"reviewer_name": "한○○",
"reviewer_level": "실버리뷰어",
"reviewer_stats": {
"reviews": 76,
"average_rating": 3.8,
"followers": 5
},
"rating": 4,
"date": "2024-06-11",
"content": "바삭한 치킨을 좋아한다면 추천! 다만 양념이 좀 짜요.",
"badges": ["바삭함", "양념짠맛"],
"likes": 6,
"photo_count": 1,
"has_photos": true
}
],
"review_summary": {
"total_reviews": 34,
"average_rating": 3.9,
"rating_distribution": {
"5": 8,
"4": 15,
"3": 7,
"2": 3,
"1": 1
},
"positive_keywords": [
"바삭함",
"맛있음"
],
"negative_keywords": [
"양념짠맛",
"서비스"
],
"common_keywords": [
"바삭함",
"치킨",
"양념",
"맛있음"
],
"sentiment_analysis": {
"positive": 58.8,
"neutral": 29.4,
"negative": 11.8
},
"photo_reviews": 18,
"recent_trend": "보통",
"peak_hours": ["19:00-21:00"]
},
"combined_at": "2024-06-16T10:32:05"
}
}
}
```
### 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": {
"summary": {
"current_situation": "치킨 전문점으로 강남구 역삼동에 위치, 평균 별점 3.8점으로 동종업체 대비 개선 여지 존재",
"key_insights": [
"배달 서비스 만족도가 경쟁업체 대비 낮음",
"신메뉴 출시 주기가 3개월 이상으로 긴 편",
"온라인 리뷰 관리 시스템 부재"
],
"priority_areas": ["배달 품질 개선", "메뉴 혁신"]
},
"action_plans": {
"short_term": [
{
"title": "배달 포장재 개선",
"description": "보온성이 우수한 친환경 포장재로 교체하여 배달 만족도 향상",
"expected_impact": "배달 리뷰 평점 0.5점 상승 예상",
"timeline": "2주",
"cost": "월 50만원"
}
],
"mid_term": [
{
"title": "시즌 한정 메뉴 런칭",
"description": "여름 시즌 매운맛 신메뉴 2종 개발 및 SNS 마케팅",
"expected_impact": "신규 고객 유입 20% 증가",
"timeline": "6주",
"cost": "초기 투자 300만원"
}
],
"long_term": [
{
"title": "브랜드 리뉴얼",
"description": "매장 인테리어 개선 및 브랜드 아이덴티티 강화",
"expected_impact": "브랜드 인지도 향상, 객단가 15% 상승",
"timeline": "4개월",
"cost": "1,500만원"
}
]
},
"implementation_tips": [
"배달앱 리뷰 모니터링 시스템 도입",
"경쟁업체 메뉴 트렌드 주기적 분석",
"고객 피드백 기반 개선사항 우선순위 설정"
]
},
"input_data": {
"request_context": {
"store_id": "501745730",
"owner_request": "매출이 감소하고 있어서 메뉴 개선이 필요합니다.",
"analysis_timestamp": "2024-06-16T10:30:00"
},
"market_intelligence": {
"total_competitors": 7,
"industry_insights": [
"업계 전반적으로 고객 만족도 개선 필요",
"고성과 업체 3개 벤치마킹 가능"
],
"performance_benchmarks": {
"average_rating": 4.1,
"review_volume_trend": "증가"
}
},
"competitive_insights": [
{
"rank": 1,
"store_name": "○○치킨",
"similarity_score": 0.892,
"performance_analysis": {
"performance": {
"rating": "4.3",
"review_count": "156"
},
"feedback": {
"positive_aspects": ["맛", "친절", "빠른배달"],
"negative_aspects": ["가격"]
},
"business_insights": {
"key_finding": "신메뉴 런칭으로 리뷰 급증"
}
}
}
],
"actionable_recommendations": {
"immediate_actions": [
"배달 서비스 개선 (업계 5개 업체 공통 문제)"
],
"strategic_improvements": [
"메뉴 다양성 확대"
],
"benchmarking_targets": [
"○○치킨: 신메뉴 마케팅 전략"
]
}
}
}
```
## ⚙️ 환경 설정
### 필수 환경변수
| 변수명 | 설명 | 예시 | 기본값 |
|--------|------|------|--------|
| `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` |
### 선택적 환경변수
| 변수명 | 설명 | 기본값 |
|--------|------|--------|
| `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` |
### Kubernetes 환경 자동 감지
시스템이 자동으로 환경을 감지하여 적절한 설정을 적용합니다:
- **로컬 개발**: `localhost` 기반 API 연동
- **Kubernetes**: 서비스 디스커버리 기반 연동
- `restaurant-api-service:80`
- `kakao-review-api-service:80`
## 🔧 개발 가이드
### 로컬 개발
```bash
# 의존성 추가
poetry add 새패키지명
# 개발 서버 실행 (Hot Reload)
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload
# 직접 실행
poetry run python app/main.py
# 의존성 업데이트
poetry update
# 가상환경 정보 확인
poetry env info
```
### 코드 품질
```bash
# 코드 포맷팅
poetry run black app/
# 린팅
poetry run flake8 app/
# 타입 체크
poetry run mypy app/
```
### Docker 개발
```bash
# 베이스 이미지 재빌드 (의존성 변경 시)
./build-base.sh
# 서비스 이미지 빌드
./build.sh
# 로컬 실행
docker run -p 8000:8000 --env-file .env vector-api:latest
```
## 🐛 문제 해결
### 일반적인 문제
**1. Vector DB 초기화 실패**
```bash
# 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"}]
}'
# 환경변수 확인
kubectl exec -it deployment/vector-api -- env | grep CLAUDE
```
**3. 외부 API 연동 실패**
```bash
# Restaurant API 연결 테스트
kubectl exec -it deployment/vector-api -- curl http://restaurant-api-service/health
# Review API 연결 테스트
kubectl exec -it deployment/vector-api -- curl http://kakao-review-api-service/health
# 서비스 디스커버리 확인
kubectl get svc | grep -E "(restaurant|review)"
```
**4. 메모리 부족 문제**
```bash
# 리소스 사용량 확인
kubectl top pods -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. 영구 볼륨 문제**
```bash
# PVC 상태 확인
kubectl get pvc vector-db-pvc
kubectl describe pvc vector-db-pvc
# 볼륨 마운트 확인
kubectl exec -it deployment/vector-api -- df -h /app/vectordb
```
### 성능 최적화
**메모리 최적화**
```yaml
# deployment.yaml에서 리소스 조정
resources:
requests:
memory: "2Gi" # Vector DB + ML 모델
cpu: "1000m" # 임베딩 계산
limits:
memory: "4Gi" # 대량 처리를 위한 여유
cpu: "2000m" # 병렬 처리
```
**Vector DB 최적화**
- 임베딩 배치 처리로 메모리 효율성 향상
- 중복 데이터 감지로 불필요한 재처리 방지
- 적절한 청크 크기로 메모리 사용량 조절
## 📈 모니터링 및 로깅
### 헬스체크 모니터링
```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"
```
### 로그 분석
```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 구축 프로세스
```mermaid
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: 결과 반환
```
### AI 추천 프로세스
```mermaid
sequenceDiagram
participant Client
participant VectorAPI
participant VectorDB
participant ClaudeAI
Client->>VectorAPI: POST /action-recommendation
VectorAPI->>VectorDB: 유사 케이스 검색
VectorDB-->>VectorAPI: 관련 데이터 반환
VectorAPI->>VectorAPI: 컨텍스트 구성
VectorAPI->>ClaudeAI: 추천 요청
ClaudeAI-->>VectorAPI: 액션 플랜 반환
VectorAPI->>VectorAPI: JSON 파싱
VectorAPI-->>Client: 구조화된 추천 반환
```
## 📈 향후 로드맵
### Phase 1: 기능 안정화 ✅
- [x] Vector DB 구축 및 관리
- [x] Claude AI 통합
- [x] 마이크로서비스 아키텍처
- [x] Kubernetes 배포
- [x] API 문서화
### Phase 2: 기능 확장 🚧
- [ ] **실시간 데이터 수집**: 새로운 리뷰 자동 업데이트
- [ ] **다중 Vector DB 지원**: FAISS, Pinecone 추가
- [ ] **감정 분석 고도화**: 세밀한 감정 분류 및 트렌드 분석
- [ ] **업종별 특화 모델**: 음식점 유형별 맞춤 추천
### Phase 3: 고급 기능 📋
- [ ] **실시간 대시보드**: Grafana 기반 모니터링
- [ ] **A/B 테스트 프레임워크**: 추천 효과 측정
- [ ] **멀티모달 분석**: 이미지 + 텍스트 통합 분석
- [ ] **예측 분석**: 매출 및 트렌드 예측 모델
### Phase 4: 엔터프라이즈 📊
- [ ] **API 배치 처리**: 대량 데이터 일괄 처리
- [ ] **고급 보안**: OAuth 2.0, API 키 관리
- [ ] **멀티 테넌트**: 고객별 격리된 데이터 관리
- [ ] **비즈니스 인텔리전스**: 시장 분석 및 보고서 생성
## 🤝 기여 가이드
### 개발 워크플로우
1. **이슈 생성**: 기능 요청 또는 버그 리포트
2. **브랜치 생성**: `feature/기능명` 또는 `fix/버그명`
3. **개발 및 테스트**: 로컬에서 충분한 테스트
4. **Pull Request**: 코드 리뷰 요청
5. **배포**: 검토 후 메인 브랜치 병합
### 코딩 컨벤션
- **타입 힌팅**: 모든 함수와 변수에 타입 명시
- **Docstring**: Google 스타일 문서화
- **에러 처리**: 모든 외부 API 호출에 예외 처리
- **로깅**: 적절한 로그 레벨과 구조화된 메시지
## 📞 지원 및 문의
### 기술 지원
- **🐛 버그 리포트**: 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
---
## 📝 라이선스
이 프로젝트는 소상공인의 성장과 데이터 기반 의사결정을 지원하는 목적으로 개발되었습니다.
---
**💡 핵심 가치**: AI와 데이터의 힘으로 소상공인의 성공을 돕습니다!
**🎯 미션**: 모든 소상공인이 데이터 기반으로 스마트한 경영 결정을 내릴 수 있도록 지원합니다.
Reference in New Issue View Git Blame Copy Permalink