Update README.md

README.md

@@ -3,58 +3,159 @@ library_name: transformers
 license: apache-2.0
 base_model: answerdotai/ModernBERT-base
 tags:
+- text-classification
+- multi-label-classification
+- human-values
 - generated_from_trainer
 metrics:
 - f1
+- roc_auc
 - accuracy
 model-index:
 - name: valueeval24-modern-bert-cos
-  results: []
+  results:
+  - task:
+      type: text-classification
+      name: Multi-label Text Classification
+    dataset:
+      name: ValueEval'24
+      type: valueeval24
+      config: en
+    metrics:
+    - name: F1 (micro)
+      value: 0.4296
+      type: f1
+    - name: ROC AUC (micro)
+      value: 0.6834
+      type: roc_auc
+    - name: Accuracy
+      value: 0.2849
+      type: accuracy
 language:
 - en
 pipeline_tag: text-classification
 ---
 
-<!-- This model card has been generated automatically according to the information the Trainer had access to. You
-should probably proofread and complete it, then remove this comment. -->
+# Modelo de Classificação de Valores: ModernBERT em ValueEval'24
 
-# valueeval24-modern-bert-cos
+Este repositório contém o modelo `answerdotai/ModernBERT-base` após passar por um processo de ajuste fino (fine-tuning) para a tarefa de classificação de texto multirr rótulo (multi-label) do shared task [ValueEval'24](https://zenodo.org/doi/10.5281/zenodo.10396293).
 
-This model is a fine-tuned version of [answerdotai/ModernBERT-base](https://huggingface.co/answerdotai/ModernBERT-base) on  [ValueEval'24](https://zenodo.org/doi/10.5281/zenodo.10396293) dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.1822
-- F1: 0.4181
-- Roc Auc: 0.6703
-- Accuracy: 0.28
+O modelo foi treinado para identificar 19 valores humanos fundamentais (baseados na Teoria de Valores Humanos Básicos de Schwartz) em sentenças em inglês. Como é uma tarefa multirr rótulo, uma única sentença pode ser associada a múltiplos valores simultaneamente.
 
-## Model description
+O melhor checkpoint, com base na métrica F1 no conjunto de validação, alcançou os seguintes resultados:
 
-More information needed
+* **Loss**: 0.1315
+* **F1 (micro)**: 0.4296
+* **ROC AUC (micro)**: 0.6834
+* **Accuracy**: 0.2849
 
-## Intended uses & limitations
+## Como Usar
 
-More information needed
+Para usar este modelo para inferência, você pode utilizar o pipeline `text-classification` da biblioteca `transformers`. O código abaixo demonstra como obter as predições para uma nova sentença.
 
-## Training and evaluation data
+```python
+from transformers import pipeline, AutoTokenizer, AutoModelForSequenceClassification
+import torch
 
-More information needed
+# Carregue o modelo e o tokenizer
+model_name = "DayCardoso/valueeval24-modern-bert-cos"
+tokenizer = AutoTokenizer.from_pretrained(model_name)
+model = AutoModelForSequenceClassification.from_pretrained(model_name)
 
-## Training procedure
+# Crie o pipeline de classificação
+classifier = pipeline(
+    "text-classification",
+    model=model,
+    tokenizer=tokenizer,
+    return_all_scores=True # Importante para multirr rótulo
+)
 
-### Training hyperparameters
+# Exemplo de uso
+text = "She always tries to help people, even strangers. Her door is always open to those in need."
 
-The following hyperparameters were used during training:
-- learning_rate: 3e-05
-- train_batch_size: 8
-- eval_batch_size: 8
-- seed: 42
-- optimizer: Use adamw_torch with betas=(0.9,0.999) and epsilon=1e-08 and optimizer_args=No additional optimizer arguments
-- lr_scheduler_type: cosine
-- lr_scheduler_warmup_ratio: 0.01
-- num_epochs: 20
-- mixed_precision_training: Native AMP
+# A saída do pipeline precisa ser processada com uma função sigmoid
+# para converter os logits em probabilidades independentes para cada classe.
+outputs = classifier(text)
 
-### Training results
+# Mapeamento de rótulos (verifique o arquivo de configuração do modelo para a lista completa e ordem correta)
+labels = model.config.id2label
+
+# Defina um limiar para considerar um rótulo como positivo
+threshold = 0.5
+
+print(f"Analisando texto: '{text}'\n")
+print("Valores identificados (probabilidade > 50%):")
+for output in outputs[0]:
+    label_name = output['label']
+    score = torch.sigmoid(torch.tensor(output['score'])).item() # Aplica sigmoid
+    if score > threshold:
+        print(f"- {label_name}: {score:.4f}")
+
+````
+
+## Detalhes do Treinamento
+
+### A Tarefa: ValueEval'24
+
+A tarefa ValueEval'24 foca na identificação de valores humanos em textos. A tarefa envolve a classificação de um texto em uma ou mais das 19 categorias de valores humanos definidas pelos organizadores. Cada valor é definido por um objetivo específico e uma motivação, conforme detalhado abaixo:
+
+| Nome do Valor | Objetivo |
+|:-----------------------------|:--------------------------------------------------------------------------------------|
+| Self-direction: thought | Liberdade para cultivar as próprias ideias e habilidades. |
+| Self-direction: action | Liberdade para determinar as próprias ações. |
+| Stimulation | Excitação, novidade e mudança. |
+| Hedonism | Prazer e gratificação sensual. |
+| Achievement | Sucesso de acordo com os padrões sociais. |
+| Power: dominance | Poder através do exercício de controle sobre as pessoas. |
+| Power: resources | Poder através do controle de recursos materiais e sociais. |
+| Face | Segurança e poder através da manutenção da imagem pública e evitando humilhação. |
+| Security: personal | Segurança no ambiente imediato. |
+| Security: societal | Segurança e estabilidade na sociedade em geral. |
+| Tradition | Manter e preservar tradições culturais, familiares ou religiosas. |
+| Conformity: rules | Conformidade com regras, leis e obrigações formais. |
+| Conformity: interpersonal | Evitar chatear ou prejudicar outras pessoas. |
+| Humility | Reconhecer a própria insignificância no esquema geral das coisas. |
+| Benevolence: caring | Devoção ao bem-estar dos membros do grupo de pertença (in-group). |
+| Benevolence: dependability | Ser um membro confiável e fidedigno do grupo de pertença (in-group). |
+| Universalism: concern | Compromisso com a igualdade, justiça e proteção para todas as pessoas. |
+| Universalism: nature | Preservação do ambiente natural. |
+| Universalism: tolerance | Aceitação e compreensão daqueles que são diferentes de si mesmo. |
+
+### Dados de Fine-Tuning
+
+O ajuste fino foi realizado utilizando os arquivos `augmented_sentences_labeled.tsv` e `labels_labeled.tsv` do dataset oficial. A natureza "aumentada" dos dados sugere que técnicas de data augmentation podem ter sido aplicadas para melhorar a robustez do modelo.
+
+### Pré-processamento
+
+O tokenizer de `answerdotai/ModernBERT-base` foi adaptado para a tarefa. Tokens especiais (um para cada rótulo de valor, ex: `<Benevolence: caring>`) foram adicionados ao vocabulário. Esta técnica pode ajudar o modelo a criar representações distintas para cada classe, melhorando o foco durante a classificação. Os textos foram truncados e preenchidos (padded) para um comprimento máximo de 512 tokens.
+
+### Procedimento de Fine-Tuning
+
+O modelo `ModernBERT-base` pré-treinado foi ajustado usando a API `Trainer` do `transformers`. Os hiperparâmetros e a configuração foram os seguintes:
+
+  * **Modelo**: `AutoModelForSequenceClassification`
+  * **Problem Type**: `multi_label_classification`
+  * **Otimizador**: AdamW com `learning_rate` de `3e-5`
+  * **LR Scheduler**: `cosine` com `warmup_ratio` de 0.01
+  * **Épocas**: 20 (com parada antecipada)
+  * **Batch Size**: 8 por dispositivo
+  * **Precisão**: Mista (FP16)
+  * **Callback**: `EarlyStoppingCallback` monitorando a métrica `f1` com uma paciência de 5 épocas para prevenir overfitting.
+
+## Avaliação
+
+### Métricas Finais
+
+O desempenho final é reportado usando o checkpoint que obteve o maior F1 Score no conjunto de validação, que ocorreu na **Época 5**.
+
+  * **Métrica Principal (F1 micro)**: **0.4296**
+  * **ROC AUC (micro)**: 0.6834
+  * **Accuracy**: 0.2849
+  * **Validation Loss**: 0.1315
+
+### Trajetória de Desempenho
+
+A tabela abaixo mostra a evolução das métricas no conjunto de validação a cada época. O treinamento foi interrompido após a época 10, pois a métrica `f1` não melhorou por 5 épocas consecutivas após seu pico na época 5. Graças ao uso de `load_best_model_at_end=True`, o modelo salvo e reportado aqui é o da Época 5.
 
 | Training Loss | Epoch | Step  | Validation Loss | F1     | Roc Auc | Accuracy |
 |:-------------:|:-----:|:-----:|:---------------:|:------:|:-------:|:--------:|
@@ -62,17 +163,45 @@ The following hyperparameters were used during training:
 | 0.0771        | 2.0   | 5766  | 0.0871          | 0.3997 | 0.6464  | 0.2675   |
 | 0.0494        | 3.0   | 8649  | 0.0970          | 0.3983 | 0.6513  | 0.2757   |
 | 0.025         | 4.0   | 11532 | 0.1187          | 0.4085 | 0.6699  | 0.2805   |
-| 0.0132        | 5.0   | 14415 | 0.1315          | 0.4296 | 0.6834  | 0.2849   |
+| **0.0132** | **5.0** | **14415** | **0.1315** | **0.4296** | **0.6834** | **0.2849** |
 | 0.0077        | 6.0   | 17298 | 0.1478          | 0.4066 | 0.6707  | 0.2668   |
 | 0.0044        | 7.0   | 20181 | 0.1619          | 0.4123 | 0.6716  | 0.2734   |
 | 0.0029        | 8.0   | 23064 | 0.1705          | 0.4124 | 0.6653  | 0.275    |
 | 0.0022        | 9.0   | 25947 | 0.1766          | 0.4082 | 0.6626  | 0.2764   |
 | 0.0014        | 10.0  | 28830 | 0.1822          | 0.4181 | 0.6703  | 0.28     |
 
+## Usos Pretendidos & Limitações
+
+**Uso Pretendido**: Este modelo é destinado à pesquisa acadêmica e a aplicações que buscam analisar o conteúdo de textos (como postagens de mídia social ou artigos de notícias) para identificar os valores humanos que estão sendo expressos.
+
+**Limitações**:
+
+  * **Especificidade de Domínio**: O modelo foi treinado em dados do ValueEval'24 e pode não generalizar bem para domínios textuais muito diferentes.
+  * **Vieses Herdados**: O modelo pode refletir vieses linguísticos e sociais presentes tanto no corpus de pré-treinamento do ModernBERT quanto no dataset de fine-tuning.
+  * **Interpretação**: O modelo identifica a *expressão* de um valor no texto, o que não é necessariamente um reflexo dos valores pessoais do autor.
+  * **Tamanho do Modelo**: Sendo um modelo de tamanho `base`, pode ter um desempenho inferior a modelos maiores (`large`) em tarefas com alta complexidade semântica.
+
+## Citação
+
+Se você usar este modelo ou o dataset em sua pesquisa, por favor, cite o trabalho original do ValueEval'24:
+
+```bibtex
+@inproceedings{kiesel-etal-2024-semeval,
+    title = "Sem{E}val-2024 Task 3: The {V}alue{E}val 2.0 Shared Task on Identifying Human Values Behind Arguments",
+    author = "Kiesel, Johannes and ....",
+    booktitle = "Proceedings of the 18th International Workshop on Semantic Evaluation (SemEval-2024)",
+    year = "2024"
+}
+```
+
+### Versões das Frameworks
+
+  - Transformers 4.53.0
+  - Pytorch 2.5.1+cu121
+  - Datasets 3.6.0
+  - Tokenizers 0.21.2
 
-### Framework versions
+<!-- end list -->
 
-- Transformers 4.53.0
-- Pytorch 2.5.1+cu121
-- Datasets 3.6.0
-- Tokenizers 0.21.2
+```
+```