shared-dg04-hi/ai-review

Fork 0

hiondal 6a5c411800 release

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

18 KiB

Raw Blame History

음식점 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 구축에는 시간이 오래 걸릴 수 있으니 충분한 타임아웃을 설정하고 진행 상황을 모니터링하세요.

18 KiB Raw Blame History