Update README.md

README.md

@@ -1,3 +1,174 @@
----
-license: apache-2.0
----
+---
+language:
+- es
+tags:
+- t5s
+- Spanish
+- text-generation
+- question-answering
+datasets:
+- GEM/FairytaleQA
+- benjleite/FairytaleQA-translated-spanish
+license: apache-2.0
+pipeline_tag: text-generation
+---
+
+# Model Card for t5s-spanish-qa
+
+## Model Description
+
+**t5s-spanish-qa** is a T5-based model, fine-tuned from [T5S](https://huggingface.co/vgaraujov/t5-base-spanish) in the **Spanish** [machine-translated version](https://huggingface.co/datasets/benjleite/FairytaleQA-translated-spanish) of the [original English FairytaleQA dataset](https://huggingface.co/datasets/GEM/FairytaleQA).
+The task of fine-tuning is Question Answering. You can check our [paper](https://arxiv.org/abs/2406.04233), accepted in ECTEL 2024.
+
+## Training Data
+**FairytaleQA** is an open-source dataset designed to enhance comprehension of narratives, aimed at students from kindergarten to eighth grade. The dataset is meticulously annotated by education experts following an evidence-based theoretical framework. It comprises 10,580 explicit and implicit questions derived from 278 child-friendly stories, covering seven types of narrative elements or relations.
+
+## Implementation Details
+
+The encoder concatenates the question and text, and the decoder generates the answer. We use special labels to differentiate the components. Our maximum token input is set to 512, while the maximum token output is set to 128. During training, the models undergo a maximum of 20 epochs and incorporate early stopping with a patience of 2. A batch size of 16 is employed. During inference, we utilize beam search with a beam width of 5. 
+
+## Evaluation - Question Answering
+
+| Model   | ROUGEL-F1   |
+| ---------------- | ----------    | 
+| t5 (for original english dataset, baseline)    | 0.551         | 
+| t5s-spanish-qa (for the spanish machine-translated dataset)    | 0.382         | 
+
+## Load Model and Tokenizer
+
+```py
+>>> from transformers import T5ForConditionalGeneration, T5Tokenizer
+>>> model = T5ForConditionalGeneration.from_pretrained("benjleite/t5s-spanish-qa")
+>>> tokenizer = T5Tokenizer.from_pretrained("vgaraujov/t5-base-spanish", model_max_length=512)
+```
+**Important Note**: Special tokens need to be added and model tokens must be resized:
+
+```py
+>>> tokenizer.add_tokens(['<nar>', '<atributo>', '<pregunta>', '<respuesta>', '<tiporespuesta>', '<texto>'], special_tokens=True)
+>>> model.resize_token_embeddings(len(tokenizer))
+```
+
+## Inference Example (same parameters as used in paper experiments)
+
+Note: See our [repository](https://github.com/bernardoleite/fairytaleqa-translated) for additional code details.
+
+```py
+input_text = '<pregunta>' + '¿Quién era Oso?' + '<texto>' + 'Érase una vez un oso al que le gustaba pasear por el bosque...'
+
+source_encoding = tokenizer(
+    input_text,
+    max_length=512,
+    padding='max_length',
+    truncation = 'only_second',
+    return_attention_mask=True,
+    add_special_tokens=True,
+    return_tensors='pt'
+)
+    
+input_ids = source_encoding['input_ids']
+attention_mask = source_encoding['attention_mask']
+
+generated_ids = model.generate(
+    input_ids=input_ids,
+    attention_mask=attention_mask,
+    num_return_sequences=1,
+    num_beams=5,
+    max_length=512,
+    repetition_penalty=1.0,
+    length_penalty=1.0,
+    early_stopping=True,
+    use_cache=True
+)
+
+prediction = {
+    tokenizer.decode(generated_id, skip_special_tokens=False, clean_up_tokenization_spaces=True)
+    for generated_id in generated_ids
+}
+
+generated_str = ''.join(preds)
+
+print(generated_str)
+```
+
+## Licensing Information
+
+This fine-tuned model is released under the [Apache-2.0 License](http://www.apache.org/licenses/LICENSE-2.0). 
+
+## Citation Information
+
+Our paper (preprint - accepted for publication at ECTEL 2024):
+
+```
+@article{leite_fairytaleqa_translated_2024,
+        title={FairytaleQA Translated: Enabling Educational Question and Answer Generation in Less-Resourced Languages}, 
+        author={Bernardo Leite and Tomás Freitas Osório and Henrique Lopes Cardoso},
+        year={2024},
+        eprint={2406.04233},
+        archivePrefix={arXiv},
+        primaryClass={cs.CL}
+}
+```
+
+Original FairytaleQA paper:
+
+```
+@inproceedings{xu-etal-2022-fantastic,
+    title = "Fantastic Questions and Where to Find Them: {F}airytale{QA} {--} An Authentic Dataset for Narrative Comprehension",
+    author = "Xu, Ying  and
+      Wang, Dakuo  and
+      Yu, Mo  and
+      Ritchie, Daniel  and
+      Yao, Bingsheng  and
+      Wu, Tongshuang  and
+      Zhang, Zheng  and
+      Li, Toby  and
+      Bradford, Nora  and
+      Sun, Branda  and
+      Hoang, Tran  and
+      Sang, Yisi  and
+      Hou, Yufang  and
+      Ma, Xiaojuan  and
+      Yang, Diyi  and
+      Peng, Nanyun  and
+      Yu, Zhou  and
+      Warschauer, Mark",
+    editor = "Muresan, Smaranda  and
+      Nakov, Preslav  and
+      Villavicencio, Aline",
+    booktitle = "Proceedings of the 60th Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers)",
+    month = may,
+    year = "2022",
+    address = "Dublin, Ireland",
+    publisher = "Association for Computational Linguistics",
+    url = "https://aclanthology.org/2022.acl-long.34",
+    doi = "10.18653/v1/2022.acl-long.34",
+    pages = "447--460",
+    abstract = "Question answering (QA) is a fundamental means to facilitate assessment and training of narrative comprehension skills for both machines and young children, yet there is scarcity of high-quality QA datasets carefully designed to serve this purpose. In particular, existing datasets rarely distinguish fine-grained reading skills, such as the understanding of varying narrative elements. Drawing on the reading education research, we introduce FairytaleQA, a dataset focusing on narrative comprehension of kindergarten to eighth-grade students. Generated by educational experts based on an evidence-based theoretical framework, FairytaleQA consists of 10,580 explicit and implicit questions derived from 278 children-friendly stories, covering seven types of narrative elements or relations. Our dataset is valuable in two folds: First, we ran existing QA models on our dataset and confirmed that this annotation helps assess models{'} fine-grained learning skills. Second, the dataset supports question generation (QG) task in the education domain. Through benchmarking with QG models, we show that the QG model trained on FairytaleQA is capable of asking high-quality and more diverse questions.",
+}
+```
+
+T5S model:
+
+```
+@inproceedings{araujo-etal-2024-sequence-sequence,
+    title = "Sequence-to-Sequence {S}panish Pre-trained Language Models",
+    author = "Araujo, Vladimir  and
+      Trusca, Maria Mihaela  and
+      Tufi{\~n}o, Rodrigo  and
+      Moens, Marie-Francine",
+    editor = "Calzolari, Nicoletta  and
+      Kan, Min-Yen  and
+      Hoste, Veronique  and
+      Lenci, Alessandro  and
+      Sakti, Sakriani  and
+      Xue, Nianwen",
+    booktitle = "Proceedings of the 2024 Joint International Conference on Computational Linguistics, Language Resources and Evaluation (LREC-COLING 2024)",
+    month = may,
+    year = "2024",
+    address = "Torino, Italia",
+    publisher = "ELRA and ICCL",
+    url = "https://aclanthology.org/2024.lrec-main.1283",
+    pages = "14729--14743",
+    abstract = "In recent years, significant advancements in pre-trained language models have driven the creation of numerous non-English language variants, with a particular emphasis on encoder-only and decoder-only architectures. While Spanish language models based on BERT and GPT have demonstrated proficiency in natural language understanding and generation, there remains a noticeable scarcity of encoder-decoder models explicitly designed for sequence-to-sequence tasks, which aim to map input sequences to generate output sequences conditionally. This paper breaks new ground by introducing the implementation and evaluation of renowned encoder-decoder architectures exclusively pre-trained on Spanish corpora. Specifically, we present Spanish versions of BART, T5, and BERT2BERT-style models and subject them to a comprehensive assessment across various sequence-to-sequence tasks, including summarization, question answering, split-and-rephrase, dialogue, and translation. Our findings underscore the competitive performance of all models, with the BART- and T5-based models emerging as top performers across all tasks. We have made all models publicly available to the research community to foster future explorations and advancements in Spanish NLP: https://github.com/vgaraujov/Seq2Seq-Spanish-PLMs.",
+}
+```