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
(~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 comfastai.learner.load_learner(CPU basta).taxonomy.json— mapeamento hierárquico usado para derivar os níveis superiores na inferência.
Uso
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.
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 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).