hierarchical-product-classifier

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.

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

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