gregassagraf/educability-norberto-4class-v1

NorBERTo Educability 4-Class v1

Português · English

Português

Visão geral

Este repositório contém um classificador ordinal de educabilidade de textos em português. Ele recebe exclusivamente text e devolve probabilidades calibradas para quatro níveis ordenados:

Score	Interpretação operacional
1	Valor educacional inexistente ou muito limitado.
2	Algum valor educacional, mas superficial, desorganizado ou pouco desenvolvido.
3	Adequado para uso educacional introdutório, possivelmente exigindo mediação.
4	Conteúdo educacional alto ou excepcional, claro, substancial e bem organizado.

O professor original usava scores de 1 a 5. Neste modelo, os scores 4 e 5 foram reunidos pela transformação min(score_original, 4). Portanto, a classe 4 não distingue conteúdo “alto” de conteúdo “excepcional”.

O artefato padrão é o ensemble promovido de três fine-tunings do Itau-Unibanco/NorBERTo-base, com seeds 13, 42 e 2026. As probabilidades dos membros são promediadas e recebem temperature scaling ajustado somente na validação (T=1.2075911963).

Instalação

Instale uma versão de PyTorch apropriada ao seu hardware e depois:

pip install "transformers>=4.53.3,<5" "safetensors>=0.5.3"

Uso recomendado: ensemble

O ensemble é o modelo incumbente e oferece o melhor resultado formal deste repositório. O código customizado é necessário para carregar os três membros. Revise os arquivos Python deste repositório e, em produção, fixe revision no hash de um commit confiável.

import torch
from transformers import AutoModelForSequenceClassification, AutoTokenizer

MODEL_ID = "gregassagraf/educability-norberto-4class-v1"

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForSequenceClassification.from_pretrained(
    MODEL_ID,
    trust_remote_code=True,
    torch_dtype=torch.bfloat16 if torch.cuda.is_available() else torch.float32,
).to("cuda" if torch.cuda.is_available() else "cpu")
model.eval()

text = "A fotossíntese converte energia luminosa em energia química nas plantas."
inputs = tokenizer(
    text,
    return_tensors="pt",
    truncation=True,
    max_length=1024,
).to(next(model.parameters()).device)

with torch.inference_mode():
    # Os logits do ensemble são log-probabilidades já calibradas.
    probabilities = torch.softmax(model(**inputs).logits, dim=-1)[0]

score = int(probabilities.argmax().item()) + 1
expected_score = float((probabilities * torch.arange(1, 5, device=probabilities.device)).sum())
print(score, expected_score, probabilities.tolist())

Uso econômico: somente a seed 42

Este modo baixa e carrega apenas um checkpoint, reduzindo aproximadamente a um terço o peso do modelo em memória. A seed 42 foi escolhida porque pertence ao ensemble RPS e possui calibração e avaliação individuais formais. Ela não é numericamente equivalente ao ensemble.

import torch
from transformers import AutoModelForSequenceClassification, AutoTokenizer

MODEL_ID = "gregassagraf/educability-norberto-4class-v1"
TEMPERATURE = 1.2555965735116554

tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForSequenceClassification.from_pretrained(
    MODEL_ID,
    subfolder="members/seed-42",
    torch_dtype=torch.bfloat16 if torch.cuda.is_available() else torch.float32,
).to("cuda" if torch.cuda.is_available() else "cpu")
model.eval()

inputs = tokenizer(
    "A água muda de estado físico conforme a temperatura e a pressão.",
    return_tensors="pt",
    truncation=True,
    max_length=1024,
).to(next(model.parameters()).device)

with torch.inference_mode():
    probabilities = torch.softmax(model(**inputs).logits.float() / TEMPERATURE, dim=-1)[0]

print(int(probabilities.argmax().item()) + 1, probabilities.tolist())

Helper para batch

O arquivo inference.py aplica automaticamente a calibração apropriada:

from inference import load_model, predict

loaded = load_model("gregassagraf/educability-norberto-4class-v1", mode="ensemble")
# Para o modo econômico: mode="single".
results = predict(
    loaded,
    [
        "O texto apresenta apenas um menu de navegação.",
        "Este tutorial explica passo a passo como resolver uma equação do segundo grau.",
    ],
    batch_size=2,
)
print(results)

Cada resultado contém score, expected_score e probabilidades para as classes 1–4.

Textos longos e memória

• O modelo foi treinado e avaliado por chunk com no máximo 1.024 tokens, incluindo tokens especiais. O tokenizer deste repositório também declara esse limite.
• A inferência acima trunca entradas maiores. Para documentos completos, divida o conteúdo em chunks sem sobreposição e faça inferência em cada um.
• Uma média das probabilidades ponderada pelos tokens de conteúdo pode ser usada como análise documental, mas não foi validada contra um alvo documental independente.
• Cada checkpoint ocupa aproximadamente 0,6 GB em disco. O ensemble contém três checkpoints; o consumo real de RAM/VRAM também depende do dtype, batch e comprimento. Reduza batch_size em caso de falta de memória.

Treinamento e proveniência

• Encoder: Itau-Unibanco/NorBERTo-base, revisão db73446f89c96044863ea05a39f680524b84bccb.
• Entrada do modelo: somente text.
• Supervisão: rótulos sintéticos produzidos por google/gemma-4-12B-it-qat-w4a16-ct.
• Alvo: score_4class = min(score_original, 4), mapeado internamente para 0–3.
• Loss: cross-entropy + 0,5 × Ranked Probability Score.
• Fine-tuning: LR 4e-5, weight decay 0,1, dropout 0,1, batch global 64, até cinco épocas.
• Seeds do ensemble: 13, 42 e 2026.
• Dados limpos disponíveis no experimento: 473.230 chunks; o teste expandido congelado contém 46.663 chunks e o benchmark histórico contém 5.692 chunks.
• Documentos e componentes de duplicatas foram mantidos no mesmo split. Fonte, documento, metadados de chunk e saídas do professor não foram usados como features.

Resultados

Resultados calibrados e não ponderados. As métricas completas e matrizes estão em evaluation/results.json.

Modelo / benchmark	QWK	Macro-F1	MAE	±1	NLL	RPS	ECE
Ensemble — teste expandido	0,8752	0,7493	0,2649	0,9860	0,5676	0,0620	0,0082
Ensemble — teste histórico	0,8667	0,7289	0,2822	0,9847	0,5978	0,0658	0,0269
Seed 42 — teste expandido	0,8685	0,7393	0,2784	0,9827	0,5937	0,0651	0,0084

No teste expandido, o recall da classe 4 foi 0,8217 para o ensemble. Os 85 exemplos cujo score original era 5 foram classificados como a nova classe 4, mas esse suporte é pequeno e não permite concluir que o comportamento se generalizará para todo conteúdo excepcional.

Uso pretendido e limitações

Uso pretendido:

• triagem, priorização e análise de grandes coleções de textos em português;
• pesquisa sobre fidelidade a um anotador sintético de educabilidade;
• apoio a pipelines nos quais previsões possam ser auditadas e revisadas.

Não use o modelo como:

• avaliação definitiva da qualidade pedagógica de um material;
• substituto de especialistas, professores ou avaliação humana;
• critério isolado para decisões de alto impacto sobre estudantes, autores ou instituições;
• classificador para idiomas ou domínios não avaliados sem validação adicional.

Os rótulos são sintéticos, potencialmente ruidosos e derivados de um único professor-modelo. Há heterogeneidade entre fontes, menor tamanho efetivo sob ponderação por probabilidade de inclusão e evidência de scores conflitantes em textos duplicados. O experimento formal não recomendou uma substituição automática; o ensemble foi tornado incumbente por decisão operacional explícita. As métricas medem fidelidade ao Gemma, não validade pedagógica humana.

Licença e atribuição

Este trabalho derivado é distribuído sob CC BY-NC-SA 4.0, acompanhando a licença do NorBERTo-base. O uso deve ser não comercial, com atribuição adequada e compartilhamento de adaptações sob a mesma licença. Consulte LICENSE para os termos completos.

Ao usar o modelo, cite a revisão exata deste repositório e atribua também o Itau-Unibanco/NorBERTo-base.

English

Overview

This repository contains an ordinal Portuguese text educability classifier. Its only model input is text, and it returns calibrated probabilities for four ordered scores. Scores 1, 2 and 3 indicate increasing educational usefulness; score 4 combines the teacher's original scores 4 and 5 and therefore represents both high and exceptional educational value.

The default artifact is a three-member ensemble of NorBERTo fine-tunings (seeds 13, 42 and 2026). It averages member probabilities and applies validation-only temperature scaling. Use the Portuguese ensemble example with trust_remote_code=True. Pin a trusted repository commit through revision in production.

For a lower-memory option, load only members/seed-42 as shown in the single-model example. This member has its own validation-fitted temperature (T=1.2555965735) but is not numerically equivalent to the ensemble.

Intended use and limitations

The model is intended for research, corpus triage, ranking and auditable analysis of Portuguese texts. It must not be treated as a definitive pedagogical-quality assessment or used alone for high-impact decisions.

Labels were generated by google/gemma-4-12B-it-qat-w4a16-ct. Evaluation therefore measures fidelity to a synthetic teacher, not human educational validity. Teacher noise, duplicate-label conflicts, source heterogeneity, selection effects and the small original class-5 support remain important limitations. See the Portuguese sections above and evaluation/results.json for the complete training, evaluation and provenance details.

License

This derivative is released under CC BY-NC-SA 4.0, following the NorBERTo-base license. Appropriate attribution, non-commercial use and ShareAlike terms apply. See LICENSE.