[AI]3단계_서비스_아키텍처_모듈화_성향기반_장소추천 - 100-hours-a-week/12-marong-Wiki GitHub Wiki

1. 모듈화 적용 후 새롭게 설계된 서비스 아키텍처 다이어그램 작성

장소 추천 서비스 아키텍처 다이어그램 (MVP Model)

2. 각 모듈의 책임(domain) 및 기능 설명

location.py (MVP: 장소 추천 메인 API)

FastAPI 기반으로 구성된 이 모듈은 사용자 성향과 위치 정보를 기반으로
맞춤형 장소를 추천하는 주요 API를 제공함

1. 입력 방식 (POST)

엔드포인트: /recommend/place
요청 방식: POST

입력 파라미터

파라미터명	타입	설명
`id`	`str`	사용자 식별자
`mbti_vector`	`array[int]`	4차원 MBTI 성향 벡터
`category`	`str`	장소 카테고리 (예: 한식, 카페 등)
`latitude`	`float`	현재 위도
`longitude`	`float`	현재 경도
`max_distance`	`int`	검색 반경 (기본값: 1000m)

2. 내부 모듈 및 모델 구성

이 API는 다음과 같은 모듈 및 모델 로직을 활용:

RecommendPlace
최종 추천 결과를 반환하는 메인 클래스
ExtractMBTIKeywords
사용자 MBTI 벡터 → 자연어 키워드 생성
GetReviewEmbedding
장소 리뷰 텍스트 → 감성 임베딩 벡터화 (SBERT)
ComputeSimilarityScore
사용자 성향 임베딩 vs 장소 감성 임베딩 → 유사도 계산
Haversine
위도/경도 기반 거리 계산
MBTIProjector
4D MBTI 벡터를 SBERT 문장 임베딩 공간으로 투영하는 PyTorch 모델

3. 결과 반환

응답 형식: JSON

{
  "user_id": "kimss",
  "message": "recommend_success",
  "data": [
    {
      "name": "원조부안집",
      "address": "경기도 성남시 분당구 삼평동",
      "rating": 4.3,
      "distance": 123.1
    },
    ...
  ]
}

RecommendPlace (MVP: 장소 추천 모듈)

사용자 MBTI 벡터 기반으로 ChromaDB에서 유사도가 높은 상위 5위 장소 리스트 반환
내부 변수:
- model, embedding_model, mbti_vector, query, latitude, longitude, max_distance
모듈 활용:
- ExtractMBTIKeywords: 사용자 MBTI 벡터 → 문장 생성
- GetReviewEmbedding: 장소 리뷰 → 벡터 변환
- ComputeSimilarityScore: 리뷰 벡터 vs 사용자 문장 벡터 → 유사도 계산
- Haversine: 거리 계산
추천 점수로 장소들을 정렬하여 recommendations_sorted 반환

ExtractMBTIKeywords (MVP: MBTI 벡터 → 자연어 변환)

4차원 MBTI 벡터를 분석하여 각 차원(E/I, S/N, T/F, J/P)에 대한 대표 성향 결정
각 차원에 대응되는 문장 생성
결과 예시: '매우 외향적이고 활발한, 다소 감각적이고 경험을 중시하는, 매우 논리적이고 사고를 중시하는, 계획적이고 절차를 중시하는/즉흥적이고 유연한 균형'

ComputeSimilarityScore (MVP: 유사도 계산)

사용자 성향 벡터와 장소 리뷰 벡터 간 cosine_similarity 계산
여러 리뷰 벡터일 경우 평균 유사도 산출
장소 추천 점수로 사용됨

Haversine (MVP: 거리 계산)

위도, 경도를 라디안으로 변환
Haversine 공식을 사용하여 사용자와 장소 간 거리 계산 (단위: 미터)
max_distance 필터링에 활용됨

mbti_projector.py (MVP: MBTI 벡터 → 문장 임베딩 공간 변환)

사용자 MBTI 4차원 벡터를 입력으로 받아 768차원 문장 임베딩 벡터로 투영
MLP 기반 모델 구조:

Linear → ReLU → Dropout → Linear → ReLU → Dropout → Linear

PyTorch 기반 모델이며, .pt 파일로부터 가중치 로딩

3. 모듈 간 인터페이스 설계 (API 명세, 데이터 포맷, 통신 방식 등)

전체 흐름 요약

사용자 요청 → FastAPI (/recommend/place)
    └▶ ExtractMBTIKeywords(MBTI → 키워드)
        └▶ MBTIProjector(MBTI → 768차원 벡터)
    └▶ 장소 검색 (Google Maps API)
        └▶ 각 장소 리뷰 추출
            └▶ GetReviewEmbedding(리뷰 리스트 → 평균 벡터)
                └▶ ComputeSimilarityScore(유사도 계산)
                    └▶ Haversine(거리 계산)
결과 리스트 → JSON 응답 반환

API 명세 (FastAPI 기준)

Method	Endpoint	Description
POST	`/recommend/place`	사용자에게 장소 추천

예시 JSON (POST /recommend/place)

{
"user_id": "KIMSS",
"mbti_vector": [0.5, 0.5, 0.5, 0.5],
"category": "한식",
"latitude": 37.401115170038,
"longitude": 127.10625450375,
"max_distance": 1000
}

테스트 실행 결과

4. 모듈화로 기대되는 효과 및 장점 정리

유지보수 용이성

각 기능이 독립적인 모듈로 구현되어 있어, 특정 기능 수정 시 전체 서비스에 영향이 적음
예: GetReviewEmbedding만 다른 임베딩 모델로 교체 가능

재사용성 향상

동일한 모듈을 다른 프로젝트나 API에서도 재사용 가능
예: MBTIProjector는 다른 추천 시스템에서도 사용 가능

테스트 및 디버깅 편의성

각 모듈 단위로 유닛 테스트 가능
오류 발생 시 해당 모듈에서 빠르게 문제 파악 가능

협업 효율성

여러 개발자가 모듈 단위로 역할 분담하여 병렬 개발 가능

5. 모듈화된 설계의 서비스 시나리오 적합성 근거 제시

사용자가 다양한 장소 카테고리를 요청하는 경우

사용자의 MBTI 성향과 장소의 리뷰 감성 유사도를 비교하여 개인 맞춤형 추천이 가능
모듈화 구조 덕분에 카테고리별 세부 로직만 변경하면 범용 확장 가능

리뷰 데이터 추가/변경 대응

리뷰 처리(GetReviewEmbedding, ComputeSimilarityScore)가 분리되어 있어, 리뷰 데이터의 변화나 추가 필터링이 필요한 경우에도 유연하게 대응 가능

다른 입력 벡터 시스템과의 호환성

MBTI 외에 Big Five, 사용자 클러스터링 벡터 등으로 확장 가능
MBTIProjector 모듈만 교체하거나 병렬 사용 가능

실시간 처리 및 응답

FastAPI 기반의 경량 REST 서버 구조로 실시간 응답이 가능하며, 병렬 처리 성능이 뛰어남
장소 탐색 시 위도, 경도 + 거리 계산(Haversine)으로 필터링 정확도 향상