---
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).