Snowflake-Labs/demo-content-rec-with-online-feature-serving

Snowflake-Labs/demo-content-rec-with-online-feature-serving

Language: Python

License: Apache-2.0

Stars: 1

Forks: 0

Open issues: 0

Created: 2026-01-09T12:01:30Z

Pushed: 2026-01-31T00:58:24Z

Default branch: main

Fork: no

Archived: no

README:

Demo: Content Recommendation with Snowflake Online Feature Serving

Real-time product recommendation demo powered by Snowflake Online Feature Serving and Two-Tower architecture. This application demonstrates how to build a personalized recommendation system with real-time embedding updates based on user click behavior.

Two-Tower Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│ Two-Tower Recommendation Model │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────┐ ┌─────────────────────┐ │
│ │ User Tower │ │ Item Tower │ │
│ │ │ │ │ │
│ │ ┌─────────────────┐ │ │ ┌─────────────────┐ │ │
│ │ │ Base Embedding │ │ Weighted │ │ Item Embedding │ │ │
│ │ │ (Batch: Daily) │ │ Combination │ │ (Batch: Daily) │ │ │
│ │ └────────┬────────┘ │ │ └────────┬────────┘ │ │
│ │ │ 60% │ │ │ │ │
│ │ ▼ │ │ │ │ │
│ │ ┌─────────────────┐ │ │ │ │ │
│ │ │ Delta Embedding │ │ │ │ │ │
│ │ │ (Real-time) │ │ │ │ │ │
│ │ └────────┬────────┘ │ │ │ │ │
│ │ │ 40% │ │ │ │ │
│ │ ▼ │ │ │ │ │
│ │ ┌─────────────────┐ │ │ │ │ │
│ │ │Combined Embedding│◀──────────────┼──────────┼──────────┘ │
│ │ │ (32-dim) │ │ Cosine │ │ │
│ │ └────────┬────────┘ │ Similarity │ │ │
│ └──────────┼──────────┘ └──────────┼──────────┘ │
│ │ │ │
│ └────────────────┬───────────────────┘ │
│ ▼ │
│ ┌─────────────────────┐ │
│ │ Ranked Products │ │
│ │ (Top-N by score) │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

Two-Tower DNN Architecture

Same neural network logic is used in both production (Snowflake) and demo (mock) environments.

┌─────────────────────────────────────────────────────────────────────┐
│ Two-Tower Deep Neural Network │
├─────────────────────────────────┬───────────────────────────────────┤
│ User Tower │ Item Tower │
│ │ │
│ Input: 38 dimensions │ Input: 8 dimensions │
│ - category_prefs (5) │ - category one-hot (5) │
│ - total_clicks (1) │ - price (1) │
│ - delta_embedding (32) │ - rating (1) │
│ │ - popularity (1) │
│ ↓ │ ↓ │
│ [Linear 38 → 64 + ReLU] │ [Linear 8 → 64 + ReLU] │
│ [Linear 64 → 64 + ReLU] │ [Linear 64 → 64 + ReLU] │
│ [Linear 64 → 32] │ [Linear 64 → 32] │
│ [L2 Normalize] │ [L2 Normalize] │
│ ↓ │ ↓ │
│ User Embedding (32-dim) │ Item Embedding (32-dim) │
└─────────────────────────────────┴───────────────────────────────────┘
↓ ↓
Cosine Similarity = dot(user_emb, item_emb)

| Component | DNN Architecture | Frequency | Latency | |-----------|------------------|-----------|---------| | Item Tower | MLP: 8 → 64 → 64 → 32 | Batch (Daily) | ~1ms | | User Tower | MLP: 38 → 64 → 64 → 32 | Real-time | ~1ms | | Delta Embedding | Exponential moving average | Real-time | < 1ms |

Features

• Two-Tower Model: User and Item embeddings for semantic similarity matching
• Real-time Delta Updates: User embedding updates instantly on each click
• Low-latency Feature Serving: Online Feature Serving provides sub-100ms feature retrieval
• Embedding Visualization: Debug panel shows real-time embedding heatmaps
• Similarity Scores: Each recommendation shows its cosine similarity match percentage
• Consistent Logic: Same embedding algorithm in production and demo modes
• Mock Mode: Works without Snowflake connection for development

System Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│ React Frontend │
│ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────────────┐ │
│ │ Product Grid │ │ Recommend Section │ │ Feature Debug Panel │ │
│ │ │ │ (with scores) │ │ (Embeddings + Latency) │ │
│ └────────┬────────┘ └────────┬─────────┘ └─────────────────────────────┘ │
└───────────┼────────────────────┼────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ FastAPI Backend │
│ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────────────┐ │
│ │ POST /click │ │ GET /recommend │ │ Embedding Service │ │
│ │ + Delta Update │ │ + Cosine Sim │ │ (Two-Tower computation) │ │
│ └────────┬────────┘ └────────┬─────────┘ └─────────────────────────────┘ │
└───────────┼────────────────────┼────────────────────────────────────────────┘
│ │
▼ ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Snowflake Feature Store │
│ ┌─────────────────┐ ┌──────────────────────────────────────────────────┐ │
│ │ Item Embeddings │ │ User Features + Embeddings │ │
│ │ (Batch computed)│ │ - base_embedding (32-dim, batch) │ │
│ └─────────────────┘ │ - delta_embedding (32-dim, real-time) │ │
│ │ - category_preference (dict) │ │
│ │ - recent_click_ids (array) │ │
│ └──────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘

Tech Stack

• Frontend: React 18, TypeScript, Framer Motion, Vite
• Backend: Python, FastAPI, uv (package manager)
• ML: PyTorch Two-Tower DNN with 32-dimensional embeddings
• Feature Store: Snowflake ML Feature Store with Online Serving
• Styling: CSS Modules with custom design system

Prerequisites

• Python 3.11+ (3.12 recommended)
• Node.js 18+
• uv (Python package manager)
• Snowflake account (optional - mock mode available for development)

Quick Start

1. Clone and Setup Backend

cd backend

# Install Python 3.12 if needed (using uv)
uv python install 3.12

# Install dependencies with uv
uv sync

# Copy environment file and configure
cp env.example .env
# Edit .env with your settings (USE_MOCK=true for development)

# Start the backend server
uv run uvicorn app.main:app --reload --port 8000

2. Setup Frontend

cd frontend

# Install dependencies
npm install

# Start development server
npm run dev

3. Access the Application

Open http://localhost:5173 in your browser.

Snowflake Setup (Production)

To use real Snowflake Feature Store with Online Serving:

1. Run SQL Scripts

# Execute in Snowflake Worksheets in order:
snowflake/01_create_database.sql…