Spaces:
Sleeping
Download README.md from abdurrehmansaeed/ThreadNode: direct link, hf CLI and curl.
- Browser
- Download file 3.54 kB
-
https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode/resolve/main/README.md
- Command line
-
hf download hf://spaces/abdurrehmansaeed/ThreadNode/README.md
-
curl -L -o README.md https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode/resolve/main/README.md
title: ThreadNode
emoji: ⚡
colorFrom: indigo
colorTo: purple
sdk: docker
pinned: false
app_port: 7860
ThreadNode: Visual Inference Engine
Live Deployment: Hugging Face Space
Source Code: GitHub Repository
ThreadNode is a production-ready, hierarchical multi-label computer vision pipeline designed to automate product categorization for e-commerce platforms.
The Vision: E-Commerce Automation
The primary motivation behind ThreadNode is not simply to build a standalone classifier, but to solve a massive operational bottleneck in retail technology. Currently, many e-commerce platforms rely on manual data entry to categorize thousands of new product listings.
ThreadNode demonstrates an automated pipeline where raw product imagery is instantly parsed into a highly accurate semantic taxonomy (e.g., Apparel > Topwear > Tshirts). By integrating this visual inference engine, platforms can automatically route inventory into the correct catalog architecture, entirely bypassing manual human classification.
Dataset & Taxonomy
This engine was trained using the Fashion Product Images Dataset, which provides a robust corpus of high-resolution e-commerce imagery paired with rich product metadata.
To create the taxonomy engine, the raw tabular metadata was parsed to extract a hierarchical relationship (e.g., MasterCategory > SubCategory > ArticleType). This text data was then vectorized into a 132-node MultiLabelBinarizer matrix to serve as the ground truth for the neural network's classification head.
System Architecture
This project utilizes a decoupled microservice architecture:
- The Brain (PyTorch): An EfficientNet-B0 CNN, optimized with transfer learning, featuring a custom 132-node classification head.
- The Engine (FastAPI): An asynchronous Python backend that holds the model state in memory and executes inference via a RESTful
/predictendpoint. - The Client (Vanilla JS/Tailwind): A lightweight, zero-dependency diagnostic dashboard for real-time visual inference.
Engineering Solutions
1. Solving the "Long-Tail" Class Imbalance
The original dataset exhibited a severe 1:1000 class imbalance (e.g., thousands of "Shirts" but only a few "Shrugs"). A standard binary cross-entropy (BCE) loss function resulted in a model that simply ignored minority classes (Macro F1: ~0.05).
The Fix: I engineered a dynamically calculated pos_weight tensor and injected it directly into the BCEWithLogitsLoss function. This mathematically penalized the network heavily for missing rare items, forcing it to learn minority visual features and drastically improving the Macro F1 score across all 132 classes.
2. The API Confidence Threshold
To prevent the model from hallucinating "safe" guesses, business logic was separated from the neural network. The FastAPI endpoint enforces a strict 85% confidence threshold.
- Micro Precision: Increased from 35.5% to 61.5%.
- Micro Recall: Maintained at an excellent 93.5%.
- Micro F1-Score: Stabilized at a highly functional 0.7422.
Usage & Deployment
ThreadNode is fully containerized via Docker and is deployed live on Hugging Face Spaces for public access and testing.
Try the live application here: ThreadNode on Hugging Face