음식점 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 포탈에서 애플리케이션 등록이 필요합니다.
- 포탈 접속: https://developers.kakao.com/console/app
- 애플리케이션 등록:
- 앱 이름:
VectorDBBuilder - 회사명:
{회사명} - 카테고리:
식음료
- 앱 이름:
- 카카오맵 활성화: 등록한 애플리케이션에서 좌측 '카카오맵' 메뉴 클릭하여 활성화
Claude API 설정
Anthropic Claude API 키가 필요합니다.
- 포탈 접속: https://console.anthropic.com/
- API 키 발급: Console에서 API Keys 메뉴에서 발급
- 모델 확인:
claude-sonnet-4-20250514사용
🚀 빠른 시작
1. 로컬 개발 환경 설정
# 저장소 클론 (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. 로컬 웹 브라우저 접속
# 애플리케이션이 정상 실행된 후 아래 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 테스트
# 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 컨테이너 실행
베이스 이미지 빌드
# ACR에 베이스 이미지 빌드 및 푸시
./build-base.sh latest acrdigitalgarage03 rg-digitalgarage-03
# 로컬 베이스 이미지 빌드
./build-base.sh latest
서비스 이미지 빌드
# ACR에 서비스 이미지 빌드 및 푸시
./build.sh latest acrdigitalgarage03 rg-digitalgarage-03
# 로컬 서비스 이미지 빌드
./build.sh latest
로컬 Docker 실행
# 컨테이너 실행 (환경변수 설정 필요)
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 생성
# Image Pull Secret 생성
./create-imagepullsecret.sh acrdigitalgarage03 rg-digitalgarage-03
2. Kubernetes 리소스 배포
# 영구 볼륨 생성 (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. 배포 상태 확인
# 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 주소 확인 방법
# 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}"
브라우저 접속 주소
현재 설정된 주소로 접속하세요:
# 현재 설정된 기본 주소 (환경에 따라 다를 수 있음)
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
접속 테스트
# 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 예시
POST /build-vector-db
{
"region": "서울특별시 강남구 역삼동",
"store_name": "맛있는 치킨집",
"force_rebuild": false
}
응답:
{
"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 예시
POST /action-request
{
"store_id": "12345",
"context": "매출이 감소하고 있어서 메뉴 개선이 필요합니다."
}
응답:
{
"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"
}
🔧 개발 및 확장
로컬 개발
# 개발 모드로 실행 (자동 재시작)
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 호스트를 변경하려면:
# 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 키 관련 문제
# 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 관련 문제
# 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 배포 실패
# 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. 메모리 부족 문제
# 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 최적화 설정
# deployment.yaml에서 Vector DB 최적화를 위한 리소스 설정
resources:
requests:
memory: "2Gi" # Vector DB와 ML 모델이 메모리를 많이 사용
cpu: "1000m" # 임베딩 계산을 위한 CPU
limits:
memory: "4Gi" # Vector 계산 및 Claude API 호출을 위한 충분한 메모리
cpu: "2000m" # 병렬 처리를 위한 CPU
영구 저장소 설정
# pvc.yaml에서 Vector DB 저장소 설정
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi # Vector 데이터 저장을 위한 충분한 공간
타임아웃 설정
# 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 구축 과정
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 액션 추천 과정
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 구축에는 시간이 오래 걸릴 수 있으니 충분한 타임아웃을 설정하고 진행 상황을 모니터링하세요.