File size: 5,378 Bytes
5b6fdc0 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 | ---
title: Interlace Multimodal Fashion Search
emoji: 👗
colorFrom: purple
colorTo: pink
sdk: docker
app_port: 7860
pinned: false
---
# Interlace — Multimodal Fashion Search Engine
A semantic fashion search engine built on FashionCLIP, FAISS, and BM25, with a Next.js frontend. Supports text search, image upload search, and multimodal queries against an ASOS product catalog.
---
## Prerequisites
| Tool | Version | Install |
|------|---------|---------|
| Python | 3.11 | [python.org](https://python.org) |
| Node.js | 18+ | [nodejs.org](https://nodejs.org) |
| npm | 9+ | bundled with Node.js |
---
## Project Structure
```
Asos_Engine_Project/
backend/ FastAPI backend (ML engine + REST API)
app/
engine/ FashionCLIP encoder, FAISS index, BM25, reranker
routers/ API route handlers
services/ Search orchestration
models/ Pydantic schemas
requirements.txt
Dockerfile
frontend/ Next.js 15 App Router frontend
src/
app/ Pages (/, /search, /products/[sku])
components/ UI components
lib/ API client, types, mock data
asos_clean.csv Product catalog (not in repo — required for backend)
asos_engine/ FAISS indexes + embeddings (auto-generated on first run)
```
---
## Running Locally
There are two modes:
- **Mock mode** — frontend only, uses hardcoded sample products. No backend needed. Good for UI demos.
- **Full stack** — frontend + backend, returns real ASOS search results with images.
---
### Option A: Frontend only (mock mode)
Use this if you just want to demo the UI without running the ML backend.
**Terminal 1:**
```bash
cd frontend
npm install
npm run dev
```
Open [http://localhost:3000](http://localhost:3000)
The app detects that no backend URL is configured and falls back to mock data automatically.
---
### Option B: Full stack (backend + frontend)
Use this for a real demo with live search results.
#### Step 1: Set up the backend
> **Important:** All backend commands must be run from the **project root** (`Asos_Engine_Project/`), not from inside `backend/`. The module imports use the `backend.` prefix and require the project root on the Python path.
**Terminal 1 — install and start the backend:**
```bash
# From Asos_Engine_Project/
python -m pip install -r backend/requirements.txt
python -m uvicorn backend.app.main:app --reload --port 8000
```
> **Windows note:** Use `python -m uvicorn` (not bare `uvicorn`). PowerShell does not automatically add Python's `Scripts/` folder to PATH, so the bare command is not found.
On first run, the engine will build FAISS indexes from `asos_clean.csv`. This takes a few minutes and produces files in `asos_engine/`. Subsequent runs skip this and load directly.
Expected output when ready:
```
Engine ready with 46,000+ products
INFO: Uvicorn running on http://0.0.0.0:8000
```
Verify it is running:
```bash
curl http://localhost:8000/api/v1/health
# Expected: {"status":"ok","engine_ready":true,"product_count":...}
```
Interactive API docs: [http://localhost:8000/docs](http://localhost:8000/docs)
#### Step 2: Set up the frontend
**Terminal 2 — configure and start the frontend:**
```bash
cd frontend
# Create local env file pointing to the running backend
# Use printf, not echo -- PowerShell's echo writes UTF-16 which Next.js cannot read
printf 'NEXT_PUBLIC_API_URL=http://localhost:8000\n' > .env.local
npm install
npm run dev
```
Open [http://localhost:3000](http://localhost:3000)
---
## Data File
`asos_clean.csv` is not stored in this repository (too large for Git). It must be present in the project root for the backend to start. The config auto-detects it:
```
Asos_Engine_Project/
asos_clean.csv <-- place it here
```
If you have the `.parquet` version instead (`asos_clean.parquet`), that also works and is preferred (faster to load).
---
## Environment Variables
### Backend
Set via shell environment or a `.env` file in `backend/`:
| Variable | Default | Description |
|----------|---------|-------------|
| `ASOS_DATA_PATH` | auto-detected | Path to `asos_clean.csv` / `.parquet` |
| `ASOS_PERSISTENT_DIR` | `./asos_engine` | Where FAISS indexes are saved |
| `ASOS_LOG_LEVEL` | `INFO` | Logging verbosity |
| `HF_TOKEN` | (none) | HuggingFace token — needed to download FashionCLIP on first run if rate-limited |
### Frontend
Set in `frontend/.env.local` (this file is gitignored):
| Variable | Example | Description |
|----------|---------|-------------|
| `NEXT_PUBLIC_API_URL` | `http://localhost:8000` | Backend base URL. If unset, app uses mock data. |
---
## API Endpoints
All routes are prefixed with `/api/v1`.
| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/health` | Engine status and product count |
| POST | `/search` | Text, image (base64), or multimodal search |
| POST | `/search/image` | Image file upload search |
| GET | `/search/similar/{sku}` | Visually similar products |
| GET | `/products/{sku}` | Product detail by SKU |
| GET | `/products/{sku}/outfit` | Outfit recommendations for a product |
---
## Tech Stack
**Backend:** Python 3.11 · FastAPI · FashionCLIP · FAISS · BM25 · PyTorch · Pydantic v2 · Pandas · Uvicorn
**Frontend:** Next.js 15 (App Router) · TypeScript · Tailwind CSS v4 · Framer Motion · GSAP
|