# 음식점 Vector DB 구축 서비스

카카오 로컬 API를 활용하여 음식점 정보를 수집하고 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을 통한 유연한 설정 관리

### 기술 스택
- **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)
- **Registry**: Azure Container Registry (ACR)
- **Documentation**: Swagger UI, ReDoc

## 🏗️ 프로젝트 구조

```
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                     # 프로젝트 문서
```

## 📋 사전 작업

### 카카오 API 설정
카카오 developers 포탈에서 애플리케이션 등록이 필요합니다.

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` 사용

## 🚀 빠른 시작

### 1. 로컬 개발 환경 설정

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

# 환경 설정 스크립트 실행 (시간이 오래 걸림)
chmod +x setup.sh
./setup.sh

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

# Claude API 키 설정 (.env 파일 생성/수정)
cat > .env << EOF
CLAUDE_API_KEY=your-actual-claude-api-key
KAKAO_API_KEY=your-kakao-api-key
EOF

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

### 2. 로컬 웹 브라우저 접속

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

- **메인 페이지**: 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 테스트

```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
     }'

# 2. 점주 액션 요청 (Claude AI 기반 조언)
curl -X POST "http://localhost:8000/action-request" \
     -H "Content-Type: application/json" \
     -d '{
       "store_id": "12345",
       "context": "매출이 감소하고 있어서 메뉴 개선이 필요합니다."
     }'

# 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 컨테이너 실행

### 베이스 이미지 빌드

```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 생성
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03
```

### 2. Kubernetes 리소스 배포

```bash
# 영구 볼륨 생성 (Vector DB 저장용)
kubectl apply -f deployment/manifests/pvc.yaml

# 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. 배포 상태 확인

```bash
# Pod 상태 확인
kubectl get pods -l app=vector-api

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

# 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 주소 확인 방법

```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

#### 접속 테스트

```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"

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

## ⚙️ 환경 설정

### 필수 환경변수

| 변수명 | 설명 | 기본값 | 예시 |
|--------|------|--------|------|
| `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` |

### 선택적 환경변수

| 변수명 | 설명 | 기본값 | 예시 |
|--------|------|--------|------|
| `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` |

## 📊 API 엔드포인트

### 주요 엔드포인트

| 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` | 컬렉션 목록 조회 |

### 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

# Vector DB 디렉토리 확인
ls -la ./vector_db/

# 코드 포맷팅
black app/
flake8 app/
```

### Ingress 호스트 변경

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

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

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

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

# 4. 새로운 주소 확인
kubectl get ingress vector-api-ingress
```

## 🐛 문제 해결

### 일반적인 문제

**1. 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"}]
     }'

# 환경변수 확인
echo $CLAUDE_API_KEY
```

**2. Vector DB 관련 문제**
```bash
# Vector DB 디렉토리 권한 확인
ls -la /app/vectordb/ 

# Vector DB 초기화
curl -X POST "http://localhost:8000/reset-vector-db"

# 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
```

**4. 메모리 부족 문제**
```bash
# Vector DB 및 ML 모델이 메모리를 많이 사용
kubectl top pods -l app=vector-api

# 리소스 제한 확인
kubectl describe pod -l app=vector-api
```

**5. 포트 관련 문제**
- 로컬 개발: 8000번 포트
- Docker 컨테이너: 8000번 포트
- Kubernetes: Service 80번 → Ingress 외부 접근

## 🎯 성능 최적화

### Vector DB 최적화 설정

```yaml
# deployment.yaml에서 Vector DB 최적화를 위한 리소스 설정
resources:
  requests:
    memory: "2Gi"     # Vector DB와 ML 모델이 메모리를 많이 사용
    cpu: "1000m"      # 임베딩 계산을 위한 CPU
  limits:
    memory: "4Gi"     # Vector 계산 및 Claude API 호출을 위한 충분한 메모리
    cpu: "2000m"      # 병렬 처리를 위한 CPU
```

### 영구 저장소 설정

```yaml
# pvc.yaml에서 Vector DB 저장소 설정
spec:
  accessModes:
    - ReadWriteOnce
  resources:
    requests:
      storage: 10Gi    # Vector 데이터 저장을 위한 충분한 공간
```

### 타임아웃 설정

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

## 📈 Vector DB 워크플로우

### 1. 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 완성]
```

### 2. AI 액션 추천 과정

```mermaid
graph TD
    A[점주 액션 요청] --> B[컨텍스트 분석]
    B --> C[Vector 유사도 검색]
    C --> D[관련 케이스 추출]
    D --> E[Claude AI 프롬프트 구성]
    E --> F[Claude API 호출]
    F --> G[맞춤형 액션 플랜 생성]
    G --> H[우선순위 및 실행 방안 제시]
```

## 📈 향후 확장 계획

- [ ] **다중 Vector DB 지원**: FAISS, Pinecone 추가 지원
- [ ] **실시간 업데이트**: 새로운 리뷰 자동 임베딩 및 추가
- [ ] **감정 분석 고도화**: 더 정교한 감정 및 의도 분류
- [ ] **업종별 특화**: 업종별 맞춤형 Vector 모델 개발
- [ ] **A/B 테스트**: 추천 효과 측정 및 개선
- [ ] **대시보드**: Vector DB 현황 및 성능 모니터링
- [ ] **배치 처리**: 대규모 데이터 처리 최적화
- [ ] **API 버전 관리**: 하위 호환성 보장
- [ ] **멀티모달 지원**: 이미지, 텍스트 통합 임베딩
- [ ] **비즈니스 인텔리전스**: 시장 트렌드 분석 기능

## 🧠 AI/ML 구성 요소

### Sentence Transformers
- **모델**: `all-MiniLM-L6-v2` (다국어 지원, 384차원)
- **용도**: 한국어 텍스트 임베딩
- **특징**: 빠른 속도, 합리적인 정확도

### Chroma Vector DB
- **저장 방식**: 영구 저장 (PVC)
- **인덱싱**: HNSW 알고리즘
- **메타데이터**: 필터링 및 검색 최적화

### Claude AI
- **모델**: `claude-sonnet-4-20250514`
- **용도**: 비즈니스 액션 추천
- **특징**: 높은 품질의 한국어 분석

---

## 📞 지원 및 문의

- **이슈 리포트**: GitHub Issues
- **기술 문의**: 개발팀 Slack
- **API 문의**: Anthropic Support
- **API 문서**: Swagger UI에서 상세 확인

---

**💡 팁: Vector DB 구축에는 시간이 오래 걸릴 수 있으니 충분한 타임아웃을 설정하고 진행 상황을 모니터링하세요.**