| --- |
| license: mit |
| library_name: fastai |
| pipeline_tag: image-classification |
| tags: |
| - fastai |
| - timm |
| - convnext |
| - image-classification |
| - hierarchical-classification |
| - e-commerce |
| - fashion |
| metrics: |
| - accuracy |
| --- |
| |
| # Classificador hierárquico de produtos de e-commerce (flat + taxonomia) |
|
|
| Classificador de imagens de produtos de moda em **três níveis de taxonomia** |
| (`masterCategory → subCategory → articleType`): ConvNeXt-Tiny com fine-tuning |
| (fastai + timm) no dataset [Fashion Product Images](https://www.kaggle.com/datasets/paramaggarwal/fashion-product-images-small) |
| (~44 mil produtos de um catálogo real). |
|
|
| Esta é a variante **flat**, vencedora da comparação controlada flat × multi-head: |
| prevê apenas o nível mais fino (`articleType`) e deriva os níveis superiores |
| pela taxonomia (`taxonomy.json`), o que garante **100% de consistência |
| hierárquica por construção**. |
|
|
| | Nível | Acurácia (validação) | |
| |---|---| |
| | masterCategory | 99,6% | |
| | subCategory | 97,2% | |
| | articleType | 90,1% | |
|
|
| Validação estratificada por `articleType` (20%, seed 42), 224 px, ~3 h de |
| fine-tuning em uma Tesla T4. |
|
|
| ## Arquivos |
|
|
| - `export_flat.pkl` — pipeline fastai completo (transforms + vocab + pesos), |
| carregável com `fastai.learner.load_learner` (CPU basta). |
| - `taxonomy.json` — mapeamento hierárquico usado para derivar os níveis |
| superiores na inferência. |
|
|
| ## Uso |
|
|
| ```python |
| from huggingface_hub import hf_hub_download |
| from hierclf.inference import HierarchicalPredictor # pacote do repo GitHub |
| |
| pkl = hf_hub_download("thf-thiago/hierarchical-product-classifier", "export_flat.pkl") |
| tax = hf_hub_download("thf-thiago/hierarchical-product-classifier", "taxonomy.json") |
| predictor = HierarchicalPredictor.from_run(Path(pkl).parent) |
| print(predictor.predict("foto_do_produto.jpg")) |
| ``` |
|
|
| Código completo, desenho experimental, testes e análise de erros: |
| **[github.com/tf-ferreira/hierarchical-product-classifier](https://github.com/tf-ferreira/hierarchical-product-classifier)**. |
|
|
| ## Uso pretendido e limitações |
|
|
| Uso pretendido: sugestão de categoria no cadastro de produtos |
| (human-in-the-loop), triagem de produtos possivelmente mal categorizados, |
| apoio a matching entre catálogos, fins educacionais/portfólio. |
|
|
| **Não** use para: decisão automática final sem revisão humana, fotos de |
| usuário "in the wild" (o treino é 100% foto de estúdio/catálogo — o domain |
| gap é real), domínios fora de moda/vestuário, ou qualquer inferência sobre |
| pessoas nas imagens. |
|
|
| Limitações conhecidas (detalhadas no |
| [MODEL_CARD.md](https://github.com/tf-ferreira/hierarchical-product-classifier/blob/main/MODEL_CARD.md) |
| do repositório): taxonomia congelada do catálogo de origem; classes com <20 |
| exemplos removidas do escopo; vieses de sortimento/fotografia de um único |
| e-commerce; imagens em resolução reduzida (versão "small" do dataset). |
|
|
