담당자: Sevan, Jimmy · 상태: 🚧 작성중 · 최종 수정: 2026-09-17

AI Repository

AI 파트는 자연어 도서 검색, 설명 가능한 AI 도서 추천, 사진으로 책 찾기(VLM) 를 담당합니다.

• 개발 일정
• 담당 기능
• 시스템 아키텍처
• 기술 스택
• 개발 가이드
• 컨벤션 룰
• 트러블 슈팅
• 설계 과제 문서

기간	주요 작업
MM/DD ~	작업 내용

기능	버전	설명
자연어 도서 검색	V1	키워드 + 벡터 하이브리드 검색 (LLM 미사용)
AI 도서 추천	V1	대화형 단일턴 추천, 추천 이유 제공
사진으로 책 찾기	V1	표지 이미지를 VLM으로 인식해 카탈로그 매칭
개인화 추천 · 재랭킹	V2	사용자 행동 기반 추천, 취향 기억
쇼핑 에이전트	V2	대화 중 담기·조회 등 tool 실행

(이미지 또는 도식 첨부)

• 검색 서버: FastAPI. 규칙 파서 → 키워드 + 벡터 하이브리드 → 랭킹. LLM 비의존.
• 추천 서버: 입력 해석 → 후보 검색 → 추천 이유 생성. 외부 LLM API 사용.
• 데이터 계층: AI 전용 PostgreSQL + pgvector. 백엔드와 공유하지 않는다. 커머스 데이터는 BE MySQL → AI Postgres 단방향 복제로만 들어오고(v_* 사본, 읽기 전용), AI가 쓰는 것은 book_embeddings·taste_profile·idempotency_records 셋뿐이다.
• 상세: 서비스 아키텍처 모듈화

분류	기술
언어	Python 3.12 (uv로 관리)
서빙	FastAPI + uvicorn
임베딩	multilingual-e5-small (384차원), 자체 서빙 · CPU
LLM · VLM	외부 API (게이트웨이 어댑터 뒤)
벡터 검색	PostgreSQL 17 + pgvector (HNSW)
키워드 검색	tsvector + pg_trgm
카탈로그 데이터	국립중앙도서관 서지 API + 도서관정보나루

문서	언제 보나
로컬 개발 환경 세팅	합류할 때 한 번. 따라 하면 /health까지 뜬다
개발 워크플로	매일. 브랜치·커밋·PR·리뷰·머지 실제 순서

브랜치·커밋·PR·머지 규칙은 팀 공통 문서를 따른다.

→ 팀 컨벤션

요약하면 이렇다.

항목	규칙
브랜치	`feature
커밋	<type>: <summary> · 마침표 없음 · 저장소 이름을 scope로 쓰지 않음
PR	승인 1명 필수 · 자가 승인 불가 · 400줄 권장
머지	Squash Merge만 · main 직접 push 금지

팀 공통 문서에는 Java·JS 규칙만 있어 AI 파트 규칙을 여기에 둔다.

대상	규칙	예시
함수·변수	snake_case	check_database
클래스	PascalCase	Settings
상수	UPPER_SNAKE_CASE	MAX_BATCH_SIZE
모듈·파일	snake_case	book_embedding.py
내부 전용	앞에 _	_pool

• 포매터·린터는 ruff를 기준으로 한다. CI의 Lint 단계가 이것으로 판정한다
• 함수 시그니처에 타입 힌트를 붙인다. pydantic은 이 타입으로 실제 검증을 수행한다
• 외부 I/O(DB·HTTP)를 하는 함수는 async def로 쓴다
• 시각은 항상 aware datetime을 쓴다. datetime.now()(naive)는 쓰지 않는다

• 모델·프롬프트를 바꾸는 PR에는 Provider, Model ID, Prompt Version, 고정 Dataset 검증 결과, 응답 시간·비용 변화를 적는다
• 벡터 차원이 바뀌는 변경은 book_embeddings·taste_profile 전량 재생성이 필요하므로 단독 배포로 분리한다
• 스키마 변경은 반드시 db/migrations/ 파일로 남긴다. 운영 DB 수동 DDL 금지

실제로 막혔다가 푼 기록. 날짜별로 쌓는다.

• 겪은 에러는 AI 저장소 docs/trouble/YYYY-MM-DD.md에 정리한다
• 팀 전체가 알아야 할 것만 여기로 올린다

• 모델 API 설계
• 모델 추론 성능 최적화
• 서비스 아키텍처 모듈화