AmandaGondra/ncm-classifier-bertimbau

NCM Classifier — experimento com BERTimbau (não é o modelo principal)

Este é um experimento documentado. O modelo recomendado para uso é AmandaGondra/ncm-classifier, que empatou com este na qualidade e é bem mais leve. Sugestões, não decisões fiscais: a responsabilidade pela classificação fiscal permanece com quem emite a nota.

Identificação

Modelo	AmandaGondra/ncm-classifier-bertimbau
Versão	v0.1.0 (publicado em 2026-11-03)
Autora	Amanda Gondra
Modelo pré-treinado	neuralmind/bert-base-portuguese-cased, revisão 94d69c95f98f7d5b2a8700c420230ae10def0baa (licença MIT)
Treino	fine-tuning de classificação em 37 posições NCM, numa Tesla T4, em ~8 min
Código	https://github.com/amanda-gondra/ncm-classifier (notebooks/bertimbau_finetuning_kaggle.py)

Como foi treinado

• Dados: os mesmos do modelo principal (900 linhas), conferidos por SHA-256, e as mesmas 5 dobras.
• Escolha na validação cruzada:
  • entrada normalized (o mesmo normalize_text do baseline);
  • 10 épocas;
  • macro F1 médio de 0.8715 fora da dobra.
• Treino: perda ponderada por classe, AdamW com learning rate 3e-5, warmup de 10%, batch 16, até 128 tokens, float16 na GPU, semente 0.
• Calibração e revisão: temperatura (T = 0.5391) e limiar de revisão ajustados fora da dobra (calibration.json).
• Regra 31.05: a mesma do modelo principal, aplicada depois da calibração.

Resultados nos testes congelados (calibrado + regra 31.05)

Métrica	test_v1	test_v2
top-1	0.9589 [0.9247–0.9863]	0.9189 [0.8514–0.9730]
top-3	0.9932 [0.9795–1.0000]	0.9865 [0.9595–1.0000]
macro F1	0.9599 [0.9225–0.9863]	0.9180 [0.8628–0.9778]
macro precisão	0.9730 [0.9234–0.9924]	0.9141 [0.8590–0.9835]
macro recall	0.9646 [0.9398–0.9868]	0.9339 [0.8841–0.9822]
ECE bruto → calibrado	0.2091 → 0.0144	0.1960 → 0.0574
Enviado para revisão	0.0205 [0.0000–0.0479]	0.0405 [0.0000–0.0946]
top-1 dos aceitos	0.9720 [0.9441–0.9931]	0.9437 [0.8873–0.9863]
Linhas	146	74

Contra o modelo principal, com bootstrap pareado e teste de McNemar, nenhuma diferença de top-1, top-3 ou macro F1 foi distinguível de zero. Em resumo:

• A favor deste modelo: probabilidades mais bem calibradas no test_v1 e menos casos enviados para revisão.
• Contra: mais erros com confiança alta e cerca de 50 vezes mais tempo por previsão em CPU.

A análise completa está em docs/experiments/model_comparison.md, no repositório do código.

Como usar

from huggingface_hub import snapshot_download
from ncm_classifier.models.bertimbau import load_model, predict_proba
from ncm_classifier.models.transformer_support import prepare_input

path = snapshot_download("AmandaGondra/ncm-classifier-bertimbau", revision="v0.1.0")
model, tokenizer, classes = load_model(path)
proba = predict_proba(
    model, tokenizer, prepare_input(["Ureia agrícola, pacote 1 kg"], "normalized"), 128
)

Estas são probabilidades brutas. Para chegar às sugestões avaliadas, aplique a temperatura de calibration.json e a regra 31.05 (ncm_classifier.rules.small_package).

Limitações

• Semente única: a variação entre sementes não foi medida.
• A época escolhida foi a última da grade testada.
• A calibração ajustada nas dobras não se transferiu bem para o modelo final. Ele ficou mais confiante, e a meta de 95% nos aceitos não se manteve no test_v2.
• Valem as mesmas limitações de escopo e de qualidade da descrição do modelo principal.

Licença

MIT, como o modelo de origem. Os dados de treino incluem descrições de anúncios de terceiros, que não são redistribuídas.