Semantic Product Search

의미론적 제품 검색: 키워드 매칭 대신 쿼리의 의도를 이해하고(임베딩 + 유사도 검색) 에이전트를 사용하여 카탈로그에 대한 추천을 생성합니다. 카탈로그는 MCP 서버로 노출되며 별도의 에이전트가 소비합니다.

🚧 활발히 개발 중인 프로젝트입니다. 현재 1단계 · 백엔드 설정 중입니다. 아키텍처, 데모 및 설계 결정 섹션은 엔드투엔드 기능 플로우가 완성된 후에 작성될 예정입니다.

Stack

• API: FastAPI

• 에이전트 / 오케스트레이션: LangChain + LangChain Anthropic (Claude)

• 로컬 모델: Ollama

• 관찰 가능성: LangSmith

• 설정 / 검증: Pydantic + Pydantic Settings

• 데이터베이스: Postgres + pgvector (로컬 개발: SQLite)

• 패키지 관리자: uv

Related MCP server: Vertex AI Search for Commerce MCP Server

프로젝트 구조

app/
  main.py           # entrypoint de la API
  api/routes.py      # rutas HTTP
  catalog/           # ingesta + modelos de datos del catálogo
  search/             # embeddings + similarity search
  reviews/
  mcp_server/         # servidor MCP (expone el catálogo/búsqueda como tools)
  agent/               # agente que consume el MCP y arma la recomendación
  core/
    config.py         # settings (variables de entorno)
    db.py              # conexión a Postgres/pgvector
  models/
    schemas.py         # modelos Pydantic compartidos
tests/

로컬 설정

요구 사항: Python >= 3.12 및 uv 설치.

# Instalar dependencias
uv sync

# Configurar variables de entorno
cp .env.example .env
# completar ANTHROPIC_API_KEY y LANGSMITH_API_KEY en .env

# Correr el entrypoint
uv run python -m app.main

환경 변수

⚠️ API 키나 비밀 값은 절대 로깅하지 마세요 (ANTHROPIC_API_KEY, LANGSMITH_API_KEY 등). Settings를 디버깅해야 하는 경우, 실패한 필드의 이름만 출력하고 값은 출력하지 마세요 — app/core/config.py가 시작 시 검증할 때 이렇게 합니다.

로드맵

개발은 단계별로 구성되어 있습니다 (Notion 보드 참조):

1. 백엔드 설정

2. 카탈로그 + 임베딩

3. 의미론적 검색

4. 리뷰 + 댓글

5. MCP 서버

6. 에이전트 + 추천

7. REST API + 스트리밍

8. 최적화

9. 프론트엔드 + 배포

아키텍처, 데모 및 설계 결정

📝 보류 중 — 프로젝트가 엔드투엔드 기능 플로우에 도달하면 작성될 예정입니다.