ai-review/vector

🍽️ 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 설정

# 1. 카카오 개발자 센터 접속
https://developers.kakao.com/console/app

# 2. 애플리케이션 등록
- 앱 이름: VectorDBBuilder
- 카테고리: 식음료

# 3. 카카오맵 API 활성화
- 좌측 메뉴 > 카카오맵 > 활성화

Claude API 설정

# 1. Anthropic Console 접속
https://console.anthropic.com/

# 2. API 키 발급
- API Keys 메뉴에서 새 키 생성
- 모델: claude-sonnet-4-20250514

2. 로컬 개발 환경

자동 환경 설정

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

# Poetry 및 의존성 자동 설치
chmod +x setup.sh
./setup.sh

환경변수 설정

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

서비스 실행

# 개발 모드 (자동 재시작)
poetry run uvicorn app.main:app --host 0.0.0.0 --port 8000 --reload

# 또는 직접 실행
poetry run python app/main.py

3. Docker 실행

# 베이스 이미지 빌드 (의존성 캐싱)
./build-base.sh

# 메인 서비스 이미지 빌드
./build.sh

# 컨테이너 실행 (환경변수 파일 사용)
docker run -p 8000:8000 --env-file .env vector-api:latest

4. Kubernetes 배포

ACR 인증 설정

# Azure Container Registry 인증
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03

리소스 배포

# 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

배포 상태 확인

# 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

# 현재 배포된 서비스 주소
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 상태 확인

접속 테스트

# 서비스 상태 확인
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 구축

요청

curl -X POST "http://vector-api.20.249.191.180.nip.io/find-reviews" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "서울특별시 강남구 역삼동",
    "store_name": "맛있는 치킨집"
  }'

응답

{
  "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 기반 비즈니스 추천

요청

curl -X POST "http://vector-api.20.249.191.180.nip.io/action-recommendation" \
  -H "Content-Type: application/json" \
  -d '{
    "store_id": "501745730",
    "context": "매출이 감소하고 있어서 메뉴 개선이 필요합니다."
  }'

응답

{
  "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
  }
}

⚙️ 환경 설정

필수 환경변수

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

🔧 개발 가이드

로컬 개발

# 의존성 추가
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

코드 품질

# 코드 포맷팅
poetry run black app/

# 린팅
poetry run flake8 app/

# 타입 체크
poetry run mypy app/

Docker 개발

# 베이스 이미지 재빌드 (의존성 변경 시)
./build-base.sh

# 서비스 이미지 빌드
./build.sh

# 로컬 실행
docker run -p 8000:8000 --env-file .env vector-api:latest

🐛 문제 해결

일반적인 문제

1. Vector DB 초기화 실패

# 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 연결 실패

# 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 연동 실패

# 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. 메모리 부족 문제

# 리소스 사용량 확인
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. 영구 볼륨 문제

# PVC 상태 확인
kubectl get pvc vector-db-pvc
kubectl describe pvc vector-db-pvc

# 볼륨 마운트 확인
kubectl exec -it deployment/vector-api -- df -h /app/vectordb

성능 최적화

메모리 최적화

# deployment.yaml에서 리소스 조정
resources:
  requests:
    memory: "2Gi"     # Vector DB + ML 모델
    cpu: "1000m"      # 임베딩 계산
  limits:
    memory: "4Gi"     # 대량 처리를 위한 여유
    cpu: "2000m"      # 병렬 처리

Vector DB 최적화

• 임베딩 배치 처리로 메모리 효율성 향상
• 중복 데이터 감지로 불필요한 재처리 방지
• 적절한 청크 크기로 메모리 사용량 조절

📈 모니터링 및 로깅

헬스체크 모니터링

# 주기적 헬스체크
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"

로그 분석

# 실시간 로그 스트림
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 구축 프로세스

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 추천 프로세스

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: 구조화된 추천 반환

📈 향후 로드맵

Phase 1: 기능 안정화 ✅

• Vector DB 구축 및 관리
• Claude AI 통합
• 마이크로서비스 아키텍처
• Kubernetes 배포
• 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와 데이터의 힘으로 소상공인의 성공을 돕습니다!
🎯 미션: 모든 소상공인이 데이터 기반으로 스마트한 경영 결정을 내릴 수 있도록 지원합니다.