Update README.md

README.md

@@ -1,44 +1,70 @@
 ---
-language:
-- pt
-tags:
-- albertina-pt*
-- albertina-ptpt
-- albertina-ptbr
-- fill-mask
-license: other
+language: 
+  - pt
+tags: 
+  - albertina-pt*
+  - albertina-ptpt
+  - albertina-ptbr
+  - fill-mask
+license: mit
 datasets:
 - oscar
 - brwac
 - europarl
 widget:
-- text: "A culinária brasileira é rica em sabores e [MASK], tornando-se um dos maiores tesouros do país."
+ - text: "A culinária portuguesa é rica em sabores e [MASK], tornando-se um dos maiores tesouros do país."
 ---
 
 
-# Albertina PT-* Model
+# Albertina PT-PT
 
-To advance the neural encoding of Portuguese (PT), and a fortiori the technological preparation of this language for the digital age, we developed a Transformer-based foundation model that sets a **new state of the art** in this respect for two of its variants, namely **European Portuguese from Portugal (PT-PT) and American Portuguese from Brazil (PT-BR)**. 
+**Albertina PT-*** is a foundation, large language model for the **Portuguese language**.
 
-To develop this **encoder**, which we named **Albertina PT-***, a strong model was used as a starting point, DeBERTa, and its pre-training was done over data sets of Portuguese, namely over a data set we gathered for PT-PT and over the BrWaC corpus for PT-BR.
-The performance of Albertina and competing models was assessed by evaluating them on prominent downstream language processing tasks adapted for Portuguese.
+It is an **encoder** of the BERT family, based on a Transformer architecture, 
+developed over the DeBERTa model, with most competitive performance for this language. 
+It has different versions that were trained for different variants of Portuguese (PT), 
+namely the European variant from Portugal (PT-PT) and the American variant from Brazil (PT-BR), 
+and it is distributed free of charge and under a most permissible license.
 
-Both **Albertina PT-PT and PT-BR versions are distributed free of charge and under the most permissive license possible** and can be run on consumer-grade hardware, thus seeking to contribute to the advancement of research and innovation in language technology for Portuguese.
+**Albertina PT-PT** is the version for **European Portuguese from Portugal**, 
+and to the best of our knowledge, at the time of its initial distribution,
+it was the first competitive encoder for this language and variant 
+that had been made publicly available and distributed for reuse.
 
-Please check the [Albertina PT-* article]() for more details.
+It was developped by a joint team from the University of Lisbon and the University of Porto, Portugal. 
+For further details, check the respective publication:
 
+``` latex
+@misc{albertina-pt,
+      title={Advancing Neural Encoding of Portuguese
+             with Transformer Albertina PT-*}, 
+      author={João Rodrigues and Luís Gomes and João Silva and
+              António Branco and Rodrigo Santos and
+              Henrique Lopes Cardoso and Tomás Osório},
+      year={2023},
+      eprint={?},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL}
+}
+```
 
-## Model Description
+Please use the above cannonical reference when using or citing this model.
 
-**This model card is for the Albertina-PT-BR** model with a total of 900M parameters, 24 layers and a hidden size of 1536.
+<br>
 
-The Albertina-PT-BR is distributed free of charge under the same permissions defined for the training dataset, [BrWac](https://huggingface.co/datasets/brwac):
-*It is available solely for academic research purposes and not for commercial use.*
 
+# Model Description
+
+**This model card is for Albertina-PT-PT**, with 900M parameters, 24 layers and a hidden size of 1536.
+
+This model is distributed free of charge under the [MIT](https://choosealicense.com/licenses/mit/) license (permits commercial use, distribution, modification and private use).
+
+
+<br>
 
 # Training Data
 
-The **Albertina PT-PT** resorted to a data set that resulted from gathering some openly available corpora of European Portuguese from the following sources:
+**Albertina PT-PT** was trained over a data set that resulted from gathering some openly available corpora of European Portuguese from the following sources:
 
 - [OSCAR](https://huggingface.co/datasets/oscar-corpus/OSCAR-2301): the OSCAR data set includes documents in more than one hundred languages, including Portuguese, and it is widely used in the literature. It is the result of a selection performed over the [Common Crawl](https://commoncrawl.org/) data set, crawled from the Web, that retains only pages whose metadata indicates permission to be crawled, that performs deduplication, and that removes some boilerplate, among other filters. Given that it does not discriminate between the Portuguese variants, we performed extra filtering by retaining only documents whose meta-data indicate the Internet country code top-level domain of Portugal. We used the January 2023 version of OSCAR, which is based on the November/December 2022 version of Common Crawl.
 - [DCEP](https://joint-research-centre.ec.europa.eu/language-technology-resources/dcep-digital-corpus-european-parliament_en): the Digital Corpus of the European Parliament is a multilingual corpus including documents in all official EU languages published on the European Parliament&#39;s official website. We retained its European Portuguese portion.
@@ -46,38 +72,43 @@ The **Albertina PT-PT** resorted to a data set that resulted from gathering some
 - [ParlamentoPT](https://www.parlamento.pt/): the ParlamentoPT is a data set we obtained by gathering the publicly available documents with the transcription of the debates in the Portuguese Parliament.
 
 
-The **Albertina PT-BR** resorted to the [BrWac](https://huggingface.co/datasets/brwac) data set.
+**Albertina PT-BR**, in turn, was trained over the [BrWac](https://huggingface.co/datasets/brwac) data set.
 
 
 ## Preprocessing
 
-We filtered the PT-PT corpora using the [BLOOM pre-processing](https://github.com/bigscience-workshop/data-preparation) pipeline resulting in a data set of 8 million documents, containing around 2.2 billion tokens.
+We filtered the PT-PT corpora using the [BLOOM pre-processing](https://github.com/bigscience-workshop/data-preparation) pipeline, resulting in a data set of 8 million documents, containing around 2.2 billion tokens.
 We skipped the default filtering of stopwords since it would disrupt the syntactic structure, and also the filtering for language identification given the corpus was pre-selected as Portuguese.
 
-# Training
+
+## Training
 
 As codebase, we resorted to the [DeBERTa V2 XLarge](https://huggingface.co/microsoft/deberta-v2-xlarge), for English.
 
+To train **Albertina-PT-PT**, the data set was tokenized with the original DeBERTa tokenizer with a 128 token sequence truncation and dynamic padding.
+The model was trained using the maximum available memory capacity resulting in a batch size of 832 samples (52 samples per GPU and applying gradient accumulation in order to approximate the batch size of the PT-BR model).
+Similarly to the PT-BR variant above, we opted for a learning rate of 1e-5 with linear decay and 10k warm-up steps.
+However, since the number of training examples is approximately twice of that in the PT-BR variant, we reduced the number of training epochs to half and completed only 25 epochs, which resulted in approximately 245k steps.
+The model was trained for 3 days on a2-highgpu-8gb Google Cloud A2 VMs with 8 GPUs, 96 vCPUs and 680 GB of RAM.
+
 To train **Albertina-PT-BR** the BrWac data set was tokenized with the original DeBERTA tokenizer with a 128 token sequence truncation and dynamic padding.
 The model was trained using the maximum available memory capacity resulting in a batch size of 896 samples (56 samples per GPU without gradient accumulation steps).
 We chose a learning rate of 1e-5 with linear decay and 10k warm-up steps based on the results of exploratory experiments. 
 In total, around 200k training steps were taken across 50 epochs.
 The model was trained for 1 day and 11 hours on a2-megagpu-16gb Google Cloud A2 VMs with 16 GPUs, 96 vCPUs and 1.360 GB of RAM.
 
-To train **Albertina-PT-PT**, the data set was tokenized with the original DeBERTa tokenizer with a 128 token sequence truncation and dynamic padding.
-The model was trained using the maximum available memory capacity resulting in a batch size of 832 samples (52 samples per GPU and applying gradient accumulation in order to approximate the batch size of the PT-BR model).
-Similarly to the PT-BR variant above, we opted for a learning rate of 1e-5 with linear decay and 10k warm-up steps.
-However, since the number of training examples is approximately twice of that in the PT-BR variant, we reduced the number of training epochs to half and completed only 25 epochs, which resulted in approximately 245k steps.
-The model was trained for 3 days on a2-highgpu-8gb Google Cloud A2 VMs with 8 GPUs, 96 vCPUs and 680 GB of RAM.
+
+<br>
 
 # Evaluation
 
-The models were evaluated on downstream tasks organized into two groups.
+The two model versions were evaluated on downstream tasks organized into two groups.
 
 In one group, we have the two data sets from the [ASSIN 2 benchmark](https://huggingface.co/datasets/assin2), namely STS and RTE, that were used to evaluate the previous state-of-the-art model [BERTimbau Large](https://huggingface.co/neuralmind/bert-large-portuguese-cased).
 In the other group of data sets, we have the translations into PT-BR and PT-PT of the English data sets used for a few of the tasks in the widely-used [GLUE benchmark](https://huggingface.co/datasets/glue), which allowed us to test both Albertina-PT-* variants on a wider variety of downstream tasks.
 
-### ASSIN 2
+
+## ASSIN 2
 
 [ASSIN 2](https://huggingface.co/datasets/assin2) is a **PT-BR data** set of approximately 10.000 sentence pairs, split into 6.500 for training, 500 for validation, and 2.448 for testing, annotated with semantic relatedness scores (range 1 to 5) and with binary entailment judgments.
 This data set supports the task of semantic textual similarity (STS), which consists of assigning a score of how semantically related two sentences are; and the task of recognizing textual entailment (RTE), which given a pair of sentences, consists of determining whether the first entails the second.
@@ -88,7 +119,7 @@ This data set supports the task of semantic textual similarity (STS), which cons
 | BERTimbau-large     | 0.8913         | 0.8531       |
 
 
-### GLUE tasks translated
+## GLUE tasks translated
 
 We resort to [PLUE](https://huggingface.co/datasets/dlb/plue) (Portuguese Language Understanding Evaluation), a data set that was obtained by automatically translating GLUE into **PT-BR**.
 We address four tasks from those in PLUE, namely:
@@ -113,6 +144,7 @@ We automatically translated the same four tasks from GLUE using [DeepL Translate
 | |   |      |  |           |
 | **Albertina-PT-BR** | 0.7942         | 0.4085         | 0.9048    | **0.8847**      |
 
+<br>
 
 # How to use
 
@@ -120,14 +152,15 @@ You can use this model directly with a pipeline for masked language modeling:
 
 ```python
 >>> from transformers import pipeline
->>> unmasker = pipeline('fill-mask', model='PORTULAN/albertina-ptbr')
->>> unmasker("culinária brasileira")
+>>> unmasker = pipeline('fill-mask', model='PORTULAN/albertina-ptpt')
+>>> unmasker("A culinária portuguesa é rica em sabores e [MASK], tornando-se um dos maiores tesouros do país.")
+
+[{'score': 0.9166129231452942, 'token': 23395, 'token_str': 'aromas', 'sequence': 'A culinária portuguesa é rica em sabores e aromas, tornando-se um dos maiores tesouros do país.'}, 
+{'score': 0.022932516410946846, 'token': 10392, 'token_str': 'costumes', 'sequence': 'A culinária portuguesa é rica em sabores e costumes, tornando-se um dos maiores tesouros do país.'}, 
+{'score': 0.013932268135249615, 'token': 21925, 'token_str': 'cores', 'sequence': 'A culinária portuguesa é rica em sabores e cores, tornando-se um dos maiores tesouros do país.'}, 
+{'score': 0.009870869107544422, 'token': 22647, 'token_str': 'nuances', 'sequence': 'A culinária portuguesa é rica em sabores e nuances, tornando-se um dos maiores tesouros do país.'}, 
+{'score': 0.007260020822286606, 'token': 12881, 'token_str': 'aroma', 'sequence': 'A culinária portuguesa é rica em sabores e aroma, tornando-se um dos maiores tesouros do país.'}]
 
-[{'score': 0.5964823365211487, 'token': 34214, 'token_str': 'Angola', 'sequence': 'Países como Angola falam a língua portuguesa.'},
-{'score': 0.12712880969047546, 'token': 9959, 'token_str': 'Portugal', 'sequence': 'Países como Portugal falam a língua portuguesa.'},
-{'score': 0.07715518027544022, 'token': 30812, 'token_str': 'Macau', 'sequence': 'Países como Macau falam a língua portuguesa.'},
-{'score': 0.05533565580844879, 'token': 41164, 'token_str': 'Timor', 'sequence': 'Países como Timor falam a língua portuguesa.'},
-{'score': 0.02593935653567314, 'token': 9716, 'token_str': 'Cuba', 'sequence': 'Países como Cuba falam a língua portuguesa.'}]
 
 ```
 
@@ -137,8 +170,8 @@ The model can be used by fine-tuning it for a specific task:
 >>> from transformers import AutoTokenizer, AutoModelForSequenceClassification, TrainingArguments, Trainer
 >>> from datasets import load_dataset
 
->>> model = AutoModelForSequenceClassification.from_pretrained("PORTULAN/albertina-ptbr", num_labels=2)
->>> tokenizer = AutoTokenizer.from_pretrained("PORTULAN/albertina-ptbr")
+>>> model = AutoModelForSequenceClassification.from_pretrained("PORTULAN/albertina-ptpt", num_labels=2)
+>>> tokenizer = AutoTokenizer.from_pretrained("PORTULAN/albertina-ptpt")
 >>> dataset = load_dataset("PORTULAN/glueptpt", "rte")
 
 >>> def tokenize_function(examples):
@@ -146,7 +179,7 @@ The model can be used by fine-tuning it for a specific task:
 
 >>> tokenized_datasets = dataset.map(tokenize_function, batched=True)
 
->>> training_args = TrainingArguments(output_dir="albertina-ptbr-rte", evaluation_strategy="epoch")
+>>> training_args = TrainingArguments(output_dir="albertina-ptpt-rte", evaluation_strategy="epoch")
 >>> trainer = Trainer(
 ...     model=model,
 ...     args=training_args,
@@ -158,14 +191,19 @@ The model can be used by fine-tuning it for a specific task:
 
 ```
 
+<br>
+
 # Citation
 
-If Albertina proves useful for your work, we kindly ask that you cite the following paper to acknowledge its contribution:
+When using or citing this model, kindly cite the following publication:
 
 ``` latex
 @misc{albertina-pt,
-      title={Advancing Neural Encoding of Portuguese with Transformer Albertina PT-*}, 
-      author={João Rodrigues and Luís Gomes and João Silva and António Branco and Rodrigo Santos and Henrique Lopes and Tomás Osório},
+      title={Advancing Neural Encoding of Portuguese
+             with Transformer Albertina PT-*}, 
+      author={João Rodrigues and Luís Gomes and João Silva and
+              António Branco and Rodrigo Santos and
+              Henrique Lopes Cardoso and Tomás Osório},
       year={2023},
       eprint={?},
       archivePrefix={arXiv},
@@ -173,6 +211,11 @@ If Albertina proves useful for your work, we kindly ask that you cite the follow
 }
 ```
 
+<br>
+
 # Acknowledgments
 
-TODO
+The research reported here was partially supported by: PORTULAN CLARIN—Research Infrastructure for the Science and Technology of Language,
+funded by Lisboa 2020, Alentejo 2020 and FCT—Fundação para a Ciência e Tecnologia under the
+grant PINFRA/22117/2016; research project ALBERTINA - Foundation Encoder Model for Portuguese and AI, funded by FCT—Fundação para a Ciência e Tecnologia under the
+grant CPCA-IAC/AV/478394/2022; and innovation project ACCELERAT.AI - Multilingual Intelligent Contact Centers, funded by IAPMEI, I.P. - Agência para a Competitividade e Inovação under the grant C625734525-00462629, of Plano de Recuperação e Resiliência, call RE-C05-i01.01 – Agendas/Alianças Mobilizadoras para a Reindustrialização.