Product Embedding Server

Python 기반 product embedding/indexing 서버입니다. bge-small-en-v1.5 모델로 384차원 벡터로 변환하고, Elasticsearch product embedding index에 반영합니다.

주요 기능

크게 3가지 기능을 처리합니다.

서버기능

• 사용자 검색어 query embedding API
• MySQL의 신규/수정/삭제 product 데이터를 읽고, 임베딩 값과 함께 ES에 갱신

별도 스크립트 기능

• MySQL에 있는 모든 product 전체 색인 후 ES에 갱신

Architecture

전체 시스템 아키텍처

전체 파이프라인

프로세스 플로우

Tech Stack

Component	Version	Role
Python	>= 3.11	Runtime
uv	uv.lock	Package and environment manager
FastAPI	0.138.2	HTTP API
Uvicorn	0.49.0	ASGI server
Pydantic Settings	2.14.2	Environment settings
SQLAlchemy	2.0.51	MySQL access layer
PyMySQL	1.2.0	MySQL driver
Elasticsearch Client	8.19.3	Elasticsearch client
Elasticsearch	8.x	Product embedding index
Sentence Transformers	5.6.0	Embedding model wrapper
PyTorch	2.12.1 CPU	Model runtime
bge-small-en-v1.5	384-dim	Product/query embedding model

Project Structure

product-embedding-server/
├── src/product_embedding_server/
│   ├── config/          # runtime settings
│   ├── db/              # MySQL access
│   ├── embedding/       # embedding text, model, query embedding
│   └── runtime/         # FastAPI and batch entrypoints
├── docs/                # design and operation documents
├── images/              # architecture diagrams
├── tests/               # test suite
├── .env.example
├── pyproject.toml
└── uv.lock

Requirements

• Python 3.11 이상
• uv
• MySQL 접속 정보
• Elasticsearch 8.x 접속 정보
• 모델 의존성 설치와 모델 캐시를 위한 로컬 디스크 여유 공간

권장 디스크 여유 공간

Purpose	Recommended
Python virtual environment	1 GB+
Model dependencies and cache	3 GB+
uv cache	3 GB+
Total local headroom	7 GB+

Quick Start

환경 파일을 준비합니다.

cp .env.example .env

.env에서 MySQL, Elasticsearch, embedding 설정을 환경에 맞게 수정합니다.

의존성을 설치합니다.

uv sync --extra model

테스트를 실행합니다.

uv run pytest

실제 모델 연동 테스트를 실행합니다.

uv run --extra model pytest -m model

FastAPI 서버를 실행합니다.

uv run product-embedding-api

Batch indexing command를 실행합니다.

uv run product-embedding-batch-indexing

주요 API:

• GET /health
• GET /ready
• POST /embeddings/query
• GET /runtime/status
• GET /outbox/status