README.md

---
language:
- pt
license: other
license_name: mit-bertimbau-base
license_link: https://huggingface.co/neuralmind/bert-large-portuguese-cased
library_name: transformers
pipeline_tag: text-classification
base_model: neuralmind/bert-large-portuguese-cased
tags:
- text-classification
- bert
- bertimbau
- portuguese
- lai
- acesso-a-informacao
- ouvidoria
- sus
- governo
- brasil
metrics:
- matthews_correlation
- accuracy
- f1
- precision
- recall
model-index:
- name: is-pedido-lai-classifier
  results:
  - task:
      type: text-classification
      name: Text Classification
    dataset:
      type: lai-falabr-ouvsus
      name: Fala.BR LAI (Ouvidoria do SUS), teste retido 10%
    metrics:
    - type: matthews_correlation
      value: 0.6825
      name: Matthews Correlation Coefficient (MCC)
    - type: accuracy
      value: 0.9139
      name: Accuracy
    - type: balanced_accuracy
      value: 0.8655
      name: Balanced Accuracy
    - type: f1
      value: 0.84
      name: Macro F1
    - type: f1
      value: 0.92
      name: Weighted F1
---

# Model Card: is-pedido-lai-classifier

Classificador binário que, dado um pedido que **chegou** ao Fala.BR como *Acesso à
Informação* (LAI / e-SIC), prediz se ele é genuinamente um pedido de LAI (`is_lai = 1`)
ou se deveria ser reclassificado para outro tipo de manifestação (`is_lai = 0`).

## 1. Detalhes do Modelo

- **Desenvolvido por**: Elias Jacob, no contexto de pesquisa
  sobre as manifestações da Ouvidoria do SUS na plataforma Fala.BR.
- **Data**: Junho de 2026 (dados extraídos do Fala.BR atualizados até
  03/06/2026).
- **Versão**: 1.0 (primeiro modelo publicado). Pacote do projeto em `0.1.0`.
- **Tipo de modelo**: Transformer encoder (BERT) ajustado para classificação binária de
  sequências. Checkpoint base: `neuralmind/bert-large-portuguese-cased` (BERTimbau Large,
  arquitetura BERT-large, 24 camadas, cerca de 330 milhões de parâmetros, português cased),
  com uma cabeça de classificação de 2 rótulos inicializada do zero (`BertForSequenceClassification`).
- **Algoritmos de treinamento, parâmetros, restrições de equidade e características de entrada**:
  - Otimizador: AdamW (padrão do `Trainer` do `transformers`).
  - Função de perda: `CrossEntropyLoss` ponderada por classe. Os pesos são inversos à
    frequência e calculados **somente no conjunto de treino**: `nao_lai` = 3.4269,
    `lai` = 0.5854.
  - Taxa de aprendizado e schedule: `2e-5`, schedule linear (padrão do `Trainer`), sem
    warmup explícito; `weight_decay` = 0.01.
  - Tamanho de batch: 64 por dispositivo. O modelo publicado foi treinado em 8 GPUs em
    paralelo (DataParallel de processo único, `world_size` = 1,
    `gradient_accumulation_steps` = 1), portanto o batch efetivo foi 64 x 8 = 512
    (78 passos por época, ceil(39677 / 512)).
  - Número de épocas / passos: até 10 épocas, totalizando 780 passos de otimização (78 por
    época). A melhor época é selecionada por MCC numa fatia de validação
    (`load_best_model_at_end=True`, `metric_for_best_model="mcc"`); no modelo publicado foi
    a época 9 (passo 702, MCC de validação 0.6887). Precisão mista `bf16`. Semente fixa 271828.
  - Restrições de equidade aplicadas: nenhuma. O único tratamento do desbalanceamento
    (cerca de 85/15) é a ponderação de classe na perda.
  - Características de entrada (features) e pré-processamento: um único campo de texto
    formado pela concatenação de `resumo_titulo` (`ResumoSolicitacao`) e `texto_pedido`
    (`Teor.DescricaoAtosOuFatos`), nessa ordem, separados por espaço. São os campos
    escritos pelo cidadão e que **sobrevivem** à reclassificação, portanto não vazam o
    rótulo. Tokenizado com o tokenizer do BERTimbau e truncado em 510 tokens. Os campos
    `leak_*` (`Assunto`, `SubAssunto`, `TipoSugeridoFalaBrIA`) são **deliberadamente
    excluídos** por vazarem o rótulo.

- **Como citar**:

  ```bibtex
  @misc{jacob2026ispedidolai,
    author       = {Jacob, Elias},
    title        = {is-pedido-lai-classifier: classificador binario de pedidos de
                    acesso a informacao (LAI) no Fala.BR},
    year         = {2026},
    howpublished = {Hugging Face Hub},
  }

  @inproceedings{souza2020bertimbau,
    author    = {Souza, Fabio and Nogueira, Rodrigo and Lotufo, Roberto},
    title      = {{BERTimbau}: Pretrained {BERT} Models for {Brazilian} {Portuguese}},
    booktitle = {Intelligent Systems (BRACIS)},
    year      = {2020},
  }
  ```

- **Licença**: Não disponível. O checkpoint
  base BERTimbau possui licença própria; verifique os termos de `neuralmind/bert-large-portuguese-cased`
  antes de redistribuir.

## 2. Uso Pretendido

- **Usos primários pretendidos**: triagem/apoio à reclassificação de manifestações que
  **chegaram como LAI** no Fala.BR, sinalizando aquelas que provavelmente não são pedidos de
  acesso à informação (`is_lai = 0`) e deveriam ser reclassificadas (tipicamente para
  Solicitação, Reclamação, Denúncia, etc.). É um classificador binário sobre o texto
  original do cidadão.
- **Usuários primários pretendidos**: equipes de ouvidoria responsáveis pela triagem,
  pesquisadores e desenvolvedores que constroem ferramentas de apoio a essa triagem.
- **Usos fora do escopo**:
  - Manifestações que **não** chegaram como LAI: o universo de treino e avaliação é
    restrito a `tipo_chegada == "Acesso a Informacao"`. Fora dele o comportamento é
    indefinido.
  - Decisão automática final sem revisão humana, em especial para fins legais (a Lei
    12.527/2011 fixa prazos e ritos próprios para a LAI).
  - Classificador geral de assunto/tipo de manifestação: o modelo só distingue LAI x não-LAI.
  - Domínios fora da saúde/SUS ou idiomas diferentes do português: o modelo não foi
    validado nesses contextos.

## 3. Fatores

- **Fatores relevantes**: comprimento do texto (pedidos muito curtos ou muito longos, sendo
  estes últimos truncados em 510 tokens); tipo de destino da reclassificação para os casos
  `is_lai = 0` (Solicitação, Reclamação, Denúncia, Sugestão, Elogio); domínio temático
  (saúde / SUS, já que os dados vêm da Ouvidoria do SUS); idioma (português brasileiro);
  órgão/unidade de destino (não registrado de forma estruturada no dataset).
- **Fatores avaliados**: a Seção 7 reporta o desempenho **por classe** (`nao_lai` vs `lai`)
  no conjunto de teste retido. Não houve avaliação desagregada por destino da
  reclassificação, por faixa de comprimento de texto nem por órgão; essa limitação está
  registrada na Seção 9.

## 4. Métricas

- **Medidas de desempenho do modelo**: a métrica principal é o **MCC** (coeficiente de
  correlação de Matthews), escolhido por ser robusto ao desbalanceamento de classes.
  Também são reportados F1, precisão e recall **da classe minoritária** (`nao_lai = 0`, a
  classe operacionalmente relevante), além de acurácia balanceada e acurácia global. A
  seleção da arquitetura (BERTimbau Large vs Base e vs modelos clássicos com TF-IDF) usou MCC
  médio em validação cruzada estratificada de 10 folds.
- **Limiares de decisão**: `argmax` do softmax (limiar implícito de 0.5). Não houve
  calibração de probabilidades nem ajuste de limiar no modelo final. A melhor época foi
  escolhida por MCC na fatia de validação.
- **Abordagens de incerteza e variabilidade**: a **seleção da arquitetura** apoiou-se em
  validação cruzada estratificada de 10 folds, com teste de Friedman + Nemenyi e análise
  bayesiana (ROPE) das diferenças. No CV de 10 folds, o BERTimbau Large
  obteve MCC = 0.6801 +/- 0.0131 (média +/- desvio), à frente do BERTimbau Base
  (0.6801 vs 0.6699; com a análise ROPE indicando que Large e Base são praticamente
  equivalentes) e de todos os modelos clássicos (melhor clássico: Regressão Logística,
  MCC = 0.6477 +/- 0.0140). O **modelo final publicado**, porém, foi treinado e avaliado
  **uma única vez** num split estratificado 90/10; não há intervalo de confiança por
  bootstrap calculado sobre esse teste retido específico. O MCC do teste retido (0.6825) é
  coerente com o intervalo observado no CV.

## 5. Dados de Avaliação

- **Conjuntos de dados**: fatia de teste retida de 10% do `dataset_lai.parquet`, separada
  por amostragem estratificada por `is_lai` com semente 271828, e avaliada **uma única vez**.
  Tamanho: 4.899 exemplos (proporção `is_lai = 1` de 0.8541, ou seja 4.184 `lai` e 715
  `nao_lai`). O teste permaneceu intocado durante todo o treino e a seleção de época.
- **Motivação**: estimar o desempenho de generalização do modelo final em dados não vistos,
  preservando a mesma distribuição de classes da população.
- **Pré-processamento**: idêntico ao do treino (concatenação de `resumo_titulo` +
  `texto_pedido`, tokenização BERTimbau, truncamento em 510 tokens).

## 6. Dados de Treinamento

- **Conjuntos de dados**: o restante (90%) do `dataset_lai.parquet`, totalizando 44.086
  exemplos, dos quais 4.409 foram separados como fatia de **validação** (seleção da melhor
  época) e 39.677 usados de fato no treino. O dataset completo tem 48.985 linhas (após
  remoção de duplicatas por `texto_pedido`; eram 50.373 manifestações que chegaram como LAI).
- **Motivação**: capturar o texto original do cidadão em manifestações que chegaram como LAI,
  para aprender a distinguir pedidos genuínos de LAI daqueles que a ouvidoria reclassifica.
  A fonte é o FalaBR, atualizado até 03/06/2026; o domínio é saúde (Ouvidoria do SUS) e os
  textos são em português brasileiro.
- **Pré-processamento**:
  - Rotulagem reconstruída a partir do `Historico` de cada manifestação: o tipo de chegada
    é reconstruído pela gramática de reclassificação (o campo do snapshot é sobrescrito na
    reclassificação); o universo é `tipo_chegada == LAI`; `is_lai = 1` se o tipo final
    permanece LAI, senão `is_lai = 0`.
  - Features seguras: `resumo_titulo` e `texto_pedido` (texto do cidadão, não reescrito).
  - Remoção de linhas com texto vazio e deduplicação por `texto_pedido`.
- **Distribuição sobre fatores relevantes**: classes no dataset completo de 49.059 linhas:
  `is_lai = 1` (LAI genuíno) com 41.904 exemplos (85.4%) e `is_lai = 0` (reclassificado para
  fora) com 7.155 exemplos (14.6%). Entre os `is_lai = 0`, os destinos de reclassificação
  mais comuns são Solicitação, Reclamação e Denúncia (com Sugestão e Elogio raros). O texto
  do cidadão tem mediana de cerca de 68 palavras na classe `lai` e 52 palavras na classe
  `nao_lai`.

## 7. Análises Quantitativas

Resultados no conjunto de teste retido de 10% (4.899 exemplos), avaliado uma única vez.
Métricas globais: **MCC = 0.6825**, acurácia = 0.9139, acurácia balanceada = 0.8655.

- **Resultados unitários** (por classe; F1/precisão/recall da classe indicada):

  | Fator | Valor | Métrica | IC 95% |
  | ----- | ----- | ------- | ------ |
  | Classe `nao_lai` (0) | 0.67 | precisão | não calculado |
  | Classe `nao_lai` (0) | 0.80 | recall | não calculado |
  | Classe `nao_lai` (0) | 0.73 | F1 (suporte 715) | não calculado |
  | Classe `lai` (1) | 0.96 | precisão | não calculado |
  | Classe `lai` (1) | 0.93 | recall | não calculado |
  | Classe `lai` (1) | 0.95 | F1 (suporte 4184) | não calculado |
  | Global | 0.6825 | MCC | não calculado |
  | Global | 0.8655 | acurácia balanceada | não calculado |
  | Global | 0.9139 | acurácia | não calculado |

  Médias agregadas do relatório de classificação: macro F1 = 0.84, weighted F1 = 0.92.
  Para referência, na validação cruzada de 10 folds o BERTimbau Large obteve
  MCC = 0.6801 +/- 0.0131, fornecendo a melhor estimativa de variabilidade disponível
  (intervalos de confiança por bootstrap sobre o teste retido não foram calculados).

- **Resultados interseccionais**: não avaliados. Não foi feito recorte por combinação de
  fatores (por exemplo, destino da reclassificação x comprimento do texto). Ver Seção 9.

  | Fatores | Valores | Métrica | IC 95% |
  | ------- | ------- | ------- | ------ |
  | Não aplicável | Não avaliado | Não avaliado | Não avaliado |

## 8. Considerações Éticas

- **Dados sensíveis**: sim. As manifestações contêm dados pessoais (nomes, e-mails, relatos
  de saúde) e foram tratadas como sensíveis. O acesso ao banco foi somente leitura e os
  textos crus não são publicados junto com o modelo. O modelo não usa atributos protegidos
  como feature, mas o texto livre do cidadão pode contê-los implicitamente.
- **Vida humana**: indiretamente. As manifestações referem-se a serviços de saúde do SUS;
  uma classificação incorreta pode atrasar ou desviar o encaminhamento de uma demanda do
  cidadão. Por isso o modelo deve **assistir**, e não substituir, a triagem humana.
- **Mitigações**: remoção dos campos que vazam o rótulo; ponderação de classe na
  perda para o desbalanceamento; seleção de modelo por MCC (robusto ao desbalanceamento);
  teste retido avaliado uma única vez; uso apenas das features seguras escritas pelo cidadão;
  acesso somente leitura aos dados; não publicação dos textos crus.
- **Riscos e danos**: um falso negativo (pedido de LAI genuíno marcado como `nao_lai`) pode
  levar a tratar como não-LAI um pedido que tem direito ao rito da Lei de Acesso à
  Informação, prejudicando o cidadão; um falso positivo (manifestação mantida como LAI
  indevidamente) pode aplicar prazos/ritos errados. Com recall de 0.80 na classe `nao_lai`,
  cerca de 20% das reclassificações verdadeiras passam despercebidas pelo modelo. Viés de
  domínio (apenas saúde/SUS) e por órgão/região não foi avaliado.
- **Casos de uso**: qualquer reclassificação automática sem revisão humana; cálculo de
  prazos legais; uso fora do domínio de saúde/SUS; aplicação a manifestações que não
  chegaram como LAI. Todos merecem cautela.

## 9. Ressalvas e Recomendações

- Não há análise desagregada nem interseccional (por destino da reclassificação, faixa de
  comprimento de texto, órgão ou região). Recomenda-se produzi-la antes de uso operacional.
- O modelo final não tem probabilidades calibradas nem ajuste de limiar; se forem usadas
  probabilidades, recomenda-se calibração (por exemplo, temperature scaling) e escolha de
  limiar conforme o custo relativo de falsos positivos e negativos.
- O desempenho do modelo final vem de um único split 90/10 avaliado uma vez; não há IC por
  bootstrap sobre esse teste. A seleção de arquitetura, porém, usou CV de 10 folds com
  testes estatísticos (Friedman/Nemenyi e análise bayesiana ROPE).
- O rótulo é um proxy reconstruído (tipo final como verdade da reclassificação), incluindo
  cerca de 28 casos `nao_lai` recuperados pelo canal de recurso. Alguns destinos são raros
  (por exemplo, Elogio), de modo que o desempenho nesses subcasos é incerto.
- Domínio restrito à saúde/SUS e ao português; transferência para outros órgãos, domínios ou
  idiomas não foi testada.
- Há dados pessoais nos textos de entrada: os usuários a jusante devem cumprir a LGPD e não
  republicar textos crus.
- Truncamento em 510 tokens: pedidos muito longos são cortados, o que pode descartar
  contexto relevante.
- Recomenda-se monitorar deriva (drift): mudanças nos templates e processos do Fala.BR podem
  degradar o desempenho ao longo do tempo.
- Um dataset de avaliação ideal para este modelo teria rótulos verificados manualmente (não
  apenas reconstruídos do histórico), cobertura balanceada dos destinos de reclassificação e
  de órgãos, e exemplos de fronteira entre LAI e não-LAI.