Classificador NCM com Inteligência Artificial — aberto, offline e gratuito
Transforma descrições de itens de NF-e em códigos NCM de 8 dígitos, com confiança calibrada — e a honestidade de dizer quando não sabe. Roda na sua CPU; nenhum dado sai da sua máquina.
pip install ncm-classificador PyPI Hugging Face
cClassTrib válidos passam a ser rejeitadas — e um
cClassTrib correto pressupõe um NCM correto. Revisar o NCM do cadastro de
produtos antes do prazo deixou de ser opcional.
O que faz
Todo cadastro de produtos tem descrições como
PARAFUSO SEXT ZINC M8X40 DIN933 — abreviadas, sem padrão, escritas para
humanos apressados. Classificar cada uma entre os milhares de códigos NCM da tabela
do Mercosul é trabalho lento, repetitivo e caro; errar significa imposto errado,
multa, e agora rejeição da nota.
O ncm-classificador recebe a descrição do jeito que ela está e devolve os 3 códigos NCM mais prováveis, cada um com um grau de confiança calibrado. Quando a confiança no código completo de 8 dígitos é insuficiente, ele estreita a resposta para a posição de 4 dígitos — e quando nem isso é confiável, ele se abstém e diz que não sabe, em vez de chutar.
Na prática, o comando devolve uma tabela com os três candidatos e a confiança de
cada um — sem a descrição textual do código, só o número e o percentual — e, no
rodapé, o disclaimer de responsabilidade que acompanha toda saída do pacote,
inclusive a API e o modo em lote. Quando um item abstém, uma linha extra
(ABSTEVE) aparece antes do disclaimer; quando a posição de 4 dígitos
fecha mesmo sem fechar a folha completa, a linha é RESPOSTA PARCIAL em
vez disso — o top-3 continua exibido do mesmo jeito nos dois casos.
É um modelo aberto: pesos publicados no Hugging Face, benchmark público, uso gratuito. Não encontramos nenhum outro modelo aberto de classificação NCM publicado — este é, até onde sabemos, o primeiro.
Como funciona
Na base há um modelo de linguagem em português — o BERTimbau — ajustado para classificação fiscal com decisões reais de classificação da Receita Federal. Três escolhas de projeto importam mais que o resto:
- Confiança calibrada. O número que acompanha cada sugestão é uma estimativa honesta de probabilidade — não um chute de marketing. Em cerca de metade dos itens o modelo responde com alta confiança; nos demais, diz que não sabe — em vez de chutar um código que rejeita sua nota.
- Abstenção é resposta. Um "não sei" explícito vale mais que um código errado: ele te diz exatamente quais itens do cadastro merecem a atenção de um profissional.
- 100% offline. O modelo roda na sua CPU, sem GPU e sem chamadas a APIs de nuvem. Descrições de produtos e dados fiscais são dados sensíveis do seu negócio — com o classificador local, nada sai da sua máquina (um argumento de LGPD, não só de custo).
Uma camada adicional de honestidade é a resposta parcial de posição: quando o modelo não tem confiança para fechar os 8 dígitos completos, mas está bastante seguro sobre os 4 primeiros — a posição da tabela NCM — ele devolve esse apoio extra em vez de uma abstenção muda. O item continua marcado como abstenção (a posição não é uma segunda forma de decisão automática), mas o profissional recebe um universo bem mais estreito de folhas candidatas para escolher, em vez de partir do zero entre milhares de códigos. Esse recurso, medido em dados reais, fecha parte relevante das consultas que de outra forma ficariam sem nenhum apoio.
Instalação e uso
Requer Python 3.12 ou superior:
pip install ncm-classificador
ncm classificar "PARAFUSO SEXT ZINC M8X40 DIN933"Para classificar um cadastro inteiro em lote (CSV) ou servir uma API local:
# lote: um item por linha, resultado em CSV
ncm lote itens.csv > resultado.csv
# API local (FastAPI): POST /v1/classificar
pip install "ncm-classificador[api]"
ncm servir --host 0.0.0.0 --porta 8000O modo em lote lê um CSV com a coluna obrigatória descricao e devolve
outro CSV com os três candidatos, as confianças, a flag de abstenção e — quando
aplicável — o nível e o código da resposta parcial de posição. A API local expõe os
mesmos dados em JSON, com autenticação por chave e limite de requisições por
minuto, para quem quer integrar o classificador a um ERP ou a um pipeline de
emissão de notas. Detalhes e opções na página do
pacote no PyPI.
Benchmark: rfb-bench
O modelo é avaliado no rfb-bench, um benchmark público que construímos com 4.944 soluções de consulta reais da Receita Federal — decisões vinculantes em que a própria Receita determinou o NCM correto para descrições reais de mercadorias. Não é dado sintético: é o padrão-ouro possível para esse problema.
| Métrica | Resultado |
|---|---|
| Acerto no nível de posição (4 dígitos), em 321 itens reais | 93,8% |
| Itens respondidos com alta confiança (validação) | ~51% |
Leia os números com cuidado: 93,8% é o acerto no nível de posição (4 dígitos), não no código completo de 8 dígitos. Publicamos o benchmark justamente para que qualquer pessoa possa verificar — e superar — esses resultados.
Limitações
- O pacote está em beta (v0.2.0). A cobertura e a calibração melhoram a cada versão, mas trate as sugestões como apoio, não como decisão.
- Em cerca de metade dos itens da validação o modelo prefere se abster ou responder só a posição de 4 dígitos a arriscar um código completo errado. Isso é projeto, não defeito — mas significa que ele não elimina o trabalho humano; ele o concentra nos itens difíceis.
- Descrições muito curtas ou genéricas ("PEÇA", "MATERIAL DIVERSO") não dão informação suficiente para classificar — nenhum modelo resolve isso.
- A responsabilidade legal pela classificação segue sendo do contribuinte e de seu contador.
Perguntas frequentes
Substitui um classificador fiscal humano?
Não. É uma ferramenta de apoio, de caráter orientativo: acelera o trabalho e aponta onde estão os casos difíceis, mas a decisão final — e a responsabilidade — é do contribuinte e de seu contador.
Funciona offline mesmo?
Sim. Depois de instalado, o modelo roda inteiramente na sua CPU. Nenhuma descrição de produto é enviada para servidores ou APIs de terceiros.
É gratuito?
Sim. O código é aberto (licença MIT) e os pesos do modelo são publicados sob CC BY 4.0 no Hugging Face.
O que é a "abstenção"?
Quando a confiança do modelo é baixa, ele responde "não sei" (ou estreita para a posição de 4 dígitos) em vez de chutar um código completo. Um chute errado numa NF-e custa caro; um "não sei" te diz onde olhar.
Qual a relação entre NCM e cClassTrib?
O cClassTrib — obrigatório com a Reforma Tributária — é derivado da
natureza da operação e da mercadoria, e pressupõe um NCM correto. NCM errado
propaga erro para o cClassTrib e, a partir de 03/08/2026, pode levar à
rejeição da NF-e de empresas do Regime Normal.
Consigo classificar meu cadastro inteiro de uma vez?
Sim: ncm lote itens.csv processa um CSV com um item por linha e devolve
outro CSV com os códigos sugeridos e as confianças. Há também uma API local
(ncm servir) para integrar a sistemas.
De onde vêm os dados de treino e avaliação?
A avaliação usa o rfb-bench, construído com 4.944 soluções de consulta reais da Receita Federal — decisões públicas e vinculantes de classificação fiscal.
Links
- Pacote: ncm-classificador no PyPI
- Modelo: ncm-classificador-bertimbau no Hugging Face
- Benchmark: rfb-bench (dataset)
Um projeto Softgrande, por Edelmar Schneider (DominuZ no Hugging Face).