educability-norberto-mini-4class-v1

educability-norberto-mini-4class-v1

Português

Classificador ordinal de educabilidade de textos em português, com 6 camadas, 69.367.300 parâmetros e limite de 1.024 tokens por entrada, incluindo tokens especiais. Recebe somente texto e estima quatro níveis de valor educacional. Os pesos FP32 ocupam aproximadamente 277 MB (265 MiB). É um único estudante destilado do ensemble educability-norberto-4class-v1, construído a partir do Itau-Unibanco/NorBERTo-base.

As classes originais 4 e 5 foram reunidas: min(score_original, 4). Os índices internos 0–3 correspondem aos scores 1–4.

Instalação e uso

Instale o PyTorch adequado ao seu hardware e pip install -r requirements.txt. A exportação foi verificada com Transformers 4.53.3 e PyTorch 2.7.1 em CPU FP32. O carregamento usa a implementação nativa de ModernBERT no Transformers. Não requer trust_remote_code=True.

import torch
from transformers import AutoModelForSequenceClassification, AutoTokenizer

# Para testar a pasta baixada, use MODEL_ID = "." dentro dela.
MODEL_ID = "gregassagraf/educability-norberto-mini-4class-v1"
device = "cuda" if torch.cuda.is_available() else "cpu"
tokenizer = AutoTokenizer.from_pretrained(MODEL_ID)
model = AutoModelForSequenceClassification.from_pretrained(
    MODEL_ID, torch_dtype=torch.float32,
).to(device).eval()
inputs = tokenizer(
    "A fotossíntese converte energia luminosa em energia química nas plantas.",
    truncation=True, max_length=1024, return_tensors="pt",
).to(device)
with torch.inference_mode():
    logits = model(**inputs).logits.float()
    probabilities = torch.softmax(logits / model.config.temperature_calibration, dim=-1)[0]
print({
    "score": int(probabilities.argmax()) + 1,
    "expected_score": float(probabilities @ torch.arange(1, 5, device=device, dtype=probabilities.dtype)),
    "probabilities": probabilities.tolist(),  # ordem: classes 1, 2, 3, 4
})

Calibração: o modelo retorna logits brutos. Aplique softmax(logits / T) uma vez, com T=1.138848624315927, ajustado somente na validação. O campo de configuração não aplica a calibração automaticamente. O pipeline("text-classification") padrão retorna probabilidades sem essa calibração; elas não correspondem às métricas calibradas. A temperatura de destilação usada no treinamento (2.0) é um parâmetro diferente.

O helper local aplica a calibração e preserva a ordem das entradas. Execute de dentro da pasta baixada, onde se encontra inference.py:

from inference import load_model, predict
loaded = load_model(".", device="cpu")
print(predict(loaded, [
    "Este tutorial explica como resolver uma equação do segundo grau.",
    "Clique aqui para acessar o menu de navegação.",
], batch_size=2))

Entradas maiores são truncadas. Para analisar documentos completos, divida-os em chunks antes da inferência; não há validação independente de uma agregação documental. O consumo de memória depende de comprimento, lote, dispositivo e precisão.

Construção e treinamento

• Base: Itau-Unibanco/NorBERTo-base, revisão db73446f89c96044863ea05a39f680524b84bccb.
• Redução de 22 para seis camadas, hidden size 768. Inicialização nas camadas [0, 4, 8, 13, 17, 21] (índices começando em zero), com média dos pesos dos professores de seeds 13, 42 e 2026. O modelo publicado já contém o resultado treinado.
• Destilação das distribuições de saída do ensemble; KL com temperatura 2.0 e alpha 1.0. Não há perda de alinhamento das representações intermediárias.
• Learning rate 5e-5, weight decay 0.1, dropout 0.1, batch 16.
• Checkpoint selecionado: seed 13, pela regra de seed mediana em QWK na validação.
• Supervisão original: rótulos sintéticos de google/gemma-4-12B-it-qat-w4a16-ct.
• Entrada exclusiva text; metadados e respostas do anotador não são features.
• Splits congelados do experimento; documentos e componentes de duplicatas agrupados.

Avaliação

Métricas calibradas, não ponderadas, por chunk. Os arquivos completos incluem métricas ponderadas, intervalos bootstrap e análises por classe: expandido e histórico.

O mini é uma alternativa compacta com perda de desempenho em relação ao ensemble. Não passou todos os critérios de substituição do incumbente no experimento de compressão. Os approval_gates de cada avaliação individual não representam a decisão comparativa final de promoção. Esta publicação não significa que o mini substituiu o ensemble.

Uso pretendido e limitações

Pesquisa, triagem e priorização de coleções de textos em português, com revisão humana quando necessário. Os resultados medem fidelidade à supervisão sintética, não validade pedagógica humana. Ruído do anotador, heterogeneidade de fontes e mudanças de domínio podem afetar as previsões. A classe 4 não separa valor alto de excepcional. Não trate as previsões como avaliação definitiva de materiais ou como critério isolado para decisões sobre estudantes, autores ou instituições.

Licença e atribuição

Distribuído sob CC BY-NC-SA 4.0, seguindo a licença do NorBERTo-base e do artefato anterior. Veja LICENSE. Atribua o NorBERTo-base, este modelo e a revisão utilizada; preserve os termos de uso não comercial e compartilhamento pela mesma licença.

English

Six-layer Portuguese educability classifier distilled from the three-member educability-norberto-4class-v1 ensemble. It has 69,367,300 parameters, takes text only, and supports chunks of up to 1,024 tokens. Scores range from 1 (very limited educational value) to 4 (high or exceptional value); original teacher scores 4 and 5 are merged.

Load with native AutoModelForSequenceClassification and AutoTokenizer using the example above. Outputs are raw logits: apply softmax(logits / 1.138848624315927) once for validation-calibrated probabilities. The local inference.py helper does this automatically. Standard Transformers pipelines do not apply this custom calibration field.

Expanded-test QWK is 0.8573 versus 0.8752 for the ensemble. This compact model did not pass all incumbent-replacement gates. Evaluation measures synthetic-label fidelity, not human pedagogical validity. Intended for research and auditable corpus triage; not a definitive assessment of educational quality. Released under CC BY-NC-SA 4.0; see LICENSE and credit the base model and this model's exact revision.