Featured Project / 대표 프로젝트

Project Cyan

AI Goods Shopping Assistant

AI 챗봇이 안내하는 아이돌/팬덤 굿즈 쇼핑몰입니다. 사용자가 자연어로 원하는 굿즈를 말하면, AI가 실제 판매 가능한 상품 후보를 조회하고 추천 문장을 생성하며 상품 상세 이동, 상품 하이라이트, 장바구니 담기 같은 화면 액션까지 실행하도록 설계했습니다.

GitHub 목록 보기

Focus / 작업 초점

AI / Architecture / Integration

Core Problem / 핵심 문제

LLM 추천을 실제 판매 가능한 상품과 화면 액션으로 제한

Stack / 주요 기술

FastAPI, WebSocket, Spring, React, pgvector, OpenAI

Overview / 프로젝트 소개

쇼핑몰 AI 챗봇의 핵심은 답변을 잘 쓰는 것보다, 실제 구매 가능한 상품 안에서 추천하고 그 추천이 화면 행동으로 자연스럽게 이어지도록 만드는 것이었습니다. Project Cyan에서는 추천 후보 조회, LLM 응답 생성, 프론트엔드 액션 실행을 하나의 계약으로 묶어 hallucination과 잘못된 화면 조작을 줄였습니다.

Focus / 작업 초점

FastAPI WebSocket 기반 AI 챗봇 서버 구현

Spring 상품/회원/대화 API와 연동되는 추천 흐름 설계

LLM 응답을 화면 액션으로 변환하는 ACTION 계약 구현

상품 추천 hallucination 방지를 위한 후보 기반 grounding 처리

로그인/비로그인 사용자별 개인화·저장·제한 정책 구현

React 챗봇 UI와 WebSocket 메시지/action 실행 연결

API 계약 문서화, Jira 일정 관리, Notion 구현 기록/TODO 관리

Architecture / 전체 구조

React Chat UI

사용자 메시지, AI 답변, 상품 카드 하이라이트, 장바구니 액션 실행을 WebSocket 메시지와 연결했습니다.

FastAPI AI Server

대화 컨텍스트를 관리하고 Spring API, embedding 검색, LLM 응답 생성을 조합하는 오케스트레이션 계층입니다.

Spring Semantic Search

사용자 발화를 embedding으로 변환한 뒤 pgvector에서 실제 판매 가능한 상품 후보를 조회합니다.

Commerce API

상품 상세 이동, 상품 하이라이트, 장바구니 담기처럼 화면에서 실행 가능한 액션을 API 계약과 맞춥니다.

Iteration / 추천 방식 개선 과정

1차 추천 / Keyword

사용자 발화에서 키워드를 추출해 상품 후보를 조회했습니다. 단순하고 빠르지만 조사, 부정형, 표현 차이를 충분히 처리하기 어려웠습니다.

2차 추천 / Normalize & Alias

조사 제거, 어미 처리, 띄어쓰기 정리, alias 테이블을 적용했습니다. 다만 예외가 늘어날수록 서버 수정과 데이터 보강이 반복됐습니다.

3차 추천 / Semantic Embedding

상품 정보와 사용자 발화를 embedding으로 변환해 pgvector에서 의미적으로 가까운 상품 후보를 찾도록 추천 방식을 확장했습니다.

Project Cyan recommendation request architecture — 01초기에는 사용자 질문에서 키워드를 추출해 상품 DB를 조회하는 방식으로 추천 흐름을 구현했습니다. 빠르게 후보를 찾을 수 있었지만 조사, 부정형, 표현 차이를 충분히 걸러내지 못하면 사용자 의도와 다른 상품이 검색되는 한계가 있었습니다.원본 보기

Project Cyan keyword normalization and alias recommendation flow — 02다음 단계에서는 조사 제거, 어미 처리, 띄어쓰기 정리, alias 테이블을 적용해 동의어나 팬덤식 표현을 보정했습니다. 정확도는 개선됐지만 예외가 생길 때마다 서버 로직 수정과 테이블 데이터 보강이 필요했습니다.원본 보기

Project Cyan product embedding and vector database storage — 03최종적으로 상품 정보를 embedding으로 변환해 pgvector에 저장하고, 사용자 발화도 embedding으로 변환해 의미적으로 가까운 상품 후보를 찾도록 추천 방식을 확장했습니다.원본 보기

Semantic Search / 벡터 검색 기반 추천

상품명, 아티스트, 카테고리, 태그, 설명을 text-embedding-3-small로 벡터화
embedding 결과를 PostgreSQL pgvector에 저장
사용자 발화를 embedding으로 변환
Spring semantic-search에서 판매 가능한 상품 후보 조회
LLM은 후보 goodsId 안에서만 답변과 ACTION 생성

Project Cyan semantic search recommendation flow — 04사용자 질문 embedding, vector DB 유사도 검색, 상위 후보 선정, AI 응답 생성, 프론트엔드 추천 표시까지 이어지는 semantic search 기반 추천 흐름을 더 상세히 정리한 이미지입니다.원본 보기

Grounded Action / 안전한 ACTION 실행

Allowed Actions

navigatehighlightaddToCart

AI가 임의의 화면 명령을 만들지 못하도록 action allowlist, Pydantic schema, 프론트엔드 검증을 함께 적용했습니다. 추천 문장과 화면 실행을 분리하지 않고 같은 후보 상품 집합에 묶어, 잘못된 상품으로 이동하거나 장바구니에 담기는 상황을 차단했습니다.

Data Pipeline / AI용 상품 데이터 공급

DB camelCase 정규화

TSV-JSON export

Supabase Storage upload

signed URL + TTL cache

상품 DB를 AI가 읽기 쉬운 camelCase 컬럼으로 정규화하고, TSV-JSON 스냅샷을 Supabase Storage에 업로드했습니다. AI 서버는 signed URL로 최신 스냅샷을 조회하고 TTL 기반 cache로 반복 접근 비용을 줄였습니다.

Personalization / 개인화와 세션 기억

로그인 사용자는 선호 아티스트, 최근 대화 요약, 언급 상품, 가격 조건, 싫어하는 상품을 다음 추천에 반영

비회원은 민감 액션과 요청 횟수를 제한해 저장 범위와 실행 권한을 분리

Project Cyan logged-in user personalization memory flow — 05로그인 사용자는 챗봇 세션을 생성하고 대화 내용을 요약해 DB에 저장합니다. 이후 추천 시 선호 아티스트, 가격 조건, 언급 상품 같은 요약 정보를 불러와 다음 응답에 반영하도록 설계했습니다.원본 보기

Collaboration / 협업과 문서화

API 계약 문서, Jira 일정, Notion 구현 기록과 TODO를 함께 관리했습니다. 특히 ACTION 계약은 백엔드 응답, AI 서버 schema, 프론트엔드 실행 로직이 동시에 맞아야 했기 때문에 변경 사항을 문서화하고 팀이 같은 용어로 확인할 수 있게 정리했습니다.

Retrospective / 배운 점

LLM 기능은 모델 성능보다 데이터 후보와 실행 권한을 어떻게 제한하는지가 제품 안정성에 더 직접적으로 영향을 줬습니다.

추천 품질 개선은 한 번에 semantic search로 넘어가기보다 키워드, 정규화, alias, embedding 순서로 실패 지점을 좁히는 방식이 효과적이었습니다.

Projects 목록으로 돌아가기