Spaces:
Sleeping
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
3.54 kB
| title: ThreadNode | |
| emoji: ⚡ | |
| colorFrom: indigo | |
| colorTo: purple | |
| sdk: docker | |
| pinned: false | |
| app_port: 7860 | |
| # ThreadNode: Visual Inference Engine | |
| **Live Deployment:** [Hugging Face Space](https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode) | |
| **Source Code:** [GitHub Repository](https://github.com/abdur-rehmansaeed/ThreadNode) | |
| 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](https://www.kaggle.com/datasets/paramaggarwal/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 `/predict` endpoint. | |
| * **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](https://huggingface.co/spaces/abdurrehmansaeed/ThreadNode) |