722 lines
22 KiB
Markdown
722 lines
22 KiB
Markdown
# 🍽️ 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",
|
|
"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": {
|
|
"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와 데이터의 힘으로 소상공인의 성공을 돕습니다!
|
|
**🎯 미션**: 모든 소상공인이 데이터 기반으로 스마트한 경영 결정을 내릴 수 있도록 지원합니다. |