shared-dg04-hi/ai-review

Fork 0

History

ondal 3d3f1e5383 release

2025-06-17 12:30:32 +09:00

app

release

2025-06-17 12:30:32 +09:00

deployment

release

2025-06-16 13:47:11 +09:00

build-base.sh

release

2025-06-15 13:52:26 +00:00

build.sh

release

2025-06-15 13:52:26 +00:00

create-imagepullsecret.sh

release

2025-06-15 13:52:26 +00:00

poetry.lock

release

2025-06-15 20:19:52 +00:00

pyproject.toml

release

2025-06-15 20:19:52 +00:00

README.md

release

2025-06-17 12:30:32 +09:00

setup.sh

release

2025-06-15 16:22:34 +00:00

README.md

🍽️ 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
`GET`	`/store/{store_id}`	store_id로 매장 정보 조회	Path Parameter	StoreInfoResponse 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",
    "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 기반 비즈니스 추천

요청

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": {
    "summary": {
      "current_situation": "일식 업종으로 매출 감소를 겪고 있으며, 경쟁이 치열한 고품질 시장에서 운영 중입니다. 업계 평균 평점은 4.23점이고, 경쟁업체들은 3.9-4.7점 범위의 평점을 보이고 있습니다.",
      "key_insights": [
        "업계 공통 이슈로 고객 만족도 양극화 문제 존재",
        "경쟁업체들은 가성비, 맛, 친절함에서 강점을 보임",
        "고객 참여도와 일관성 있는 서비스 품질이 성공의 핵심 요소"
      ],
      "priority_areas": [
        "서비스 일관성 개선",
        "고객 만족도 안정화"
      ]
    },
    "action_plans": {
      "short_term": [
        {
          "title": "서비스 표준화 매뉴얼 작성 및 적용",
          "description": "조리법, 서빙 방식, 고객 응대 등 모든 서비스 과정을 표준화하여 일관성 있는 품질 제공. 직원 교육 실시 및 체크리스트 활용",
          "expected_impact": "고객 만족도 양극화 해소, 평점 0.3-0.5점 상승 예상",
          "timeline": "2-4주",
          "cost": "50-100만원 (교육비, 매뉴얼 제작비)"
        },
        {
          "title": "고객 피드백 수집 시스템 구축",
          "description": "테이블 QR코드를 통한 실시간 피드백 수집, 불만사항 즉시 대응 체계 마련. 주간 피드백 분석 및 개선사항 도출",
          "expected_impact": "고객 불만 30% 감소, 재방문율 15% 증가",
          "timeline": "1-2주",
          "cost": "30-50만원 (QR코드 제작, 시스템 구축)"
        }
      ],
      "mid_term": [
        {
          "title": "메뉴 최적화 및 시그니처 메뉴 개발",
          "description": "경쟁업체 대비 차별화된 시그니처 메뉴 3-5개 개발. 기존 메뉴 중 인기도 낮은 메뉴 정리하고 가성비 우수 메뉴 강화",
          "expected_impact": "평균 주문 금액 20% 증가, 고객 재방문율 25% 향상",
          "timeline": "2-3개월",
          "cost": "200-300만원 (메뉴 개발, 재료비, 마케팅)"
        },
        {
          "title": "디지털 마케팅 강화",
          "description": "네이버 플레이스, 구글 마이비즈니스 최적화. SNS 활용한 메뉴 홍보 및 고객 후기 관리. 온라인 주문 시스템 도입",
          "expected_impact": "온라인 노출 50% 증가, 신규 고객 유입 30% 증가",
          "timeline": "3-4개월",
          "cost": "150-250만원 (마케팅비, 시스템 구축비)"
        }
      ],
      "long_term": [
        {
          "title": "고객 충성도 프로그램 구축",
          "description": "멤버십 시스템 도입, 단골 고객 특별 혜택 제공, 생일/기념일 이벤트 운영. 고객 데이터베이스 구축 및 맞춤형 서비스 제공",
          "expected_impact": "고객 유지율 40% 향상, 월 매출 25-30% 증가",
          "timeline": "6-8개월",
          "cost": "300-500만원 (시스템 개발, 운영비)"
        },
        {
          "title": "브랜드 아이덴티티 강화 및 확장 전략",
          "description": "독특한 브랜드 스토리 개발, 인테리어 리뉴얼, 패키징 디자인 개선. 향후 2호점 진출 또는 프랜차이즈 검토",
          "expected_impact": "브랜드 인지도 향상, 프리미엄 가격 정책 가능, 사업 확장 기반 마련",
          "timeline": "8-12개월",
          "cost": "500-1000만원 (리뉴얼, 브랜딩 비용)"
        }
      ]
    },
    "implementation_tips": [
      "단기 계획부터 차근차근 실행하되, 서비스 일관성 개선을 최우선으로 진행하세요",
      "고객 피드백을 적극 수집하고 빠르게 개선사항에 반영하여 고객과의 소통을 강화하세요",
      "경쟁업체의 강점(가성비, 맛, 친절)을 벤치마킹하되, 차별화 포인트를 명확히 설정하세요"
    ]
  },
  "error_message": null,
  "input_data": {
    "request_context": {
      "store_id": "501745730",
      "owner_request": "매출이 감소하고 있어서 개선 방안이 필요합니다.",
      "analysis_timestamp": "2025-06-16T03:34:08.622763"
    },
    "market_intelligence": {
      "total_competitors": 3,
      "industry_insights": [
        "경쟁이 치열한 고품질 시장",
        "업계 공통 이슈: 고객 만족도 양극화 (일관성 부족)"
      ],
      "performance_benchmarks": {
        "average_rating": 4.23,
        "rating_range": {
          "min": 3.9,
          "max": 4.7
        },
        "industry_standard": "Above Average",
        "review_activity": {
          "average_reviews": 224,
          "range": {
            "min": 103,
            "max": 412
          }
        }
      }
    },
    "competitive_insights": [
      {
        "rank": 1,
        "store_name": "",
        "category": "일식",
        "similarity_score": 0.389,
        "performance_analysis": {
          "performance": {
            "rating": "4.1",
            "review_count": "156",
            "status": "영업 중"
          },
          "feedback": {
            "positive_aspects": [
              "가성비",
              "맛",
              "분위기"
            ],
            "negative_aspects": [],
            "recent_trends": [
              "최근 만족도 상승"
            ],
            "rating_pattern": "안정적 고만족"
          },
          "insights": {
            "competitive_advantage": [
              "높은 고객 만족도",
              "활발한 고객 참여",
              "맛 우수"
            ],
            "critical_issues": [],
            "improvement_opportunities": []
          }
        }
      },
      {
        "rank": 2,
        "store_name": "",
        "category": "일식",
        "similarity_score": 0.347,
        "performance_analysis": {
          "performance": {
            "rating": "4.7",
            "review_count": "412",
            "status": "영업 중"
          },
          "feedback": {
            "positive_aspects": [
              "가성비",
              "맛",
              "친절",
              "분위기"
            ],
            "negative_aspects": [
              "고객 만족도 양극화 (일관성 부족)"
            ],
            "recent_trends": [
              "최근 만족도 상승"
            ],
            "rating_pattern": "안정적 고만족"
          },
          "insights": {
            "competitive_advantage": [
              "높은 고객 만족도",
              "활발한 고객 참여",
              "맛 우수",
              "친절 우수"
            ],
            "critical_issues": [],
            "improvement_opportunities": []
          }
        }
      },
      {
        "rank": 3,
        "store_name": "",
        "category": "일식",
        "similarity_score": 0.314,
        "performance_analysis": {
          "performance": {
            "rating": "3.9",
            "review_count": "103",
            "status": "영업 중"
          },
          "feedback": {
            "positive_aspects": [
              "가성비",
              "맛",
              "친절"
            ],
            "negative_aspects": [],
            "recent_trends": [],
            "rating_pattern": "양극화 패턴"
          },
          "insights": {
            "competitive_advantage": [
              "활발한 고객 참여",
              "맛 우수",
              "친절 우수"
            ],
            "critical_issues": [],
            "improvement_opportunities": []
          }
        }
      }
    ],
    "actionable_recommendations": {
      "immediate_actions": [
        "고객 만족도 양극화 (일관성 부족) 개선 (업계 1개 업체 공통 문제)"
      ],
      "strategic_improvements": [],
      "benchmarking_targets": []
    }
  }
}

3. 매장 정보 조회 API

요청 예시

curl -X GET "http://vector-api.20.249.191.180.nip.io/store/501745730"

응답 예시 (성공)

{
  "success": true,
  "message": "매장 정보 조회 성공: 맛있는 치킨집",
  "store_id": "501745730",
  "store_info": {
    "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"
  },
  "reviews": [
    {
      "reviewer_name": "김○○",
      "rating": 5,
      "date": "2024-06-10",
      "content": "치킨이 정말 맛있어요!",
      "badges": ["맛집", "친절", "빠른배달"],
      "likes": 12
    }
  ],
  "review_summary": {
    "total_reviews": 23,
    "average_rating": 4.2,
    "rating_distribution": {
      "5": 12,
      "4": 8,
      "3": 2,
      "2": 1,
      "1": 0
    },
    "total_likes": 145,
    "common_keywords": ["맛집", "친절", "빠른배달", "바삭함"]
  },
  "metadata": {
    "store_id": "501745730",
    "store_name": "맛있는 치킨집",
    "food_category": "치킨",
    "region": "서울특별시 강남구 역삼동",
    "last_updated": "2024-06-17T10:30:00"
  },
  "last_updated": "2024-06-17T10:30:00",
  "total_reviews": 23,
  "execution_time": 0.15
}

응답 예시 (실패)

{
  "success": false,
  "message": "매장 정보를 찾을 수 없습니다: store_id=999999",
  "store_id": "999999",
  "store_info": null,
  "reviews": null,
  "review_summary": null,
  "metadata": null,
  "last_updated": null,
  "total_reviews": 0,
  "execution_time": 0.05
}

⚙️ 환경 설정

필수 환경변수

변수명	설명	예시	기본값
`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
    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 키 관리
멀티 테넌트: 고객별 격리된 데이터 관리
비즈니스 인텔리전스: 시장 분석 및 보고서 생성

🤝 기여 가이드

개발 워크플로우

이슈 생성: 기능 요청 또는 버그 리포트
브랜치 생성: feature/기능명 또는 fix/버그명
개발 및 테스트: 로컬에서 충분한 테스트
Pull Request: 코드 리뷰 요청
배포: 검토 후 메인 브랜치 병합

코딩 컨벤션

타입 힌팅: 모든 함수와 변수에 타입 명시
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와 데이터의 힘으로 소상공인의 성공을 돕습니다!
🎯 미션: 모든 소상공인이 데이터 기반으로 스마트한 경영 결정을 내릴 수 있도록 지원합니다.