Create README.md

README.md

@@ -0,0 +1,236 @@
+---
+language:
+- aa
+- af
+- am
+- ak
+- bm
+- ff
+- fon
+- ha
+- ig
+- ki
+- lg
+- ln
+- mg
+- nr
+- om
+- rn
+- run
+- sw
+- sn
+- tn
+- ti
+- ve
+- wo
+- xh
+- yo
+- zu
+pipeline_tag: text-generation
+tags:
+- UBC
+- African
+- pytorch
+- Chaeetah
+- DLNLP
+extra_gated_fields:
+  First Name: text
+  Last Name: text
+  Country: country
+  Affiliation: text
+  Job title:
+    type: select
+    options:
+    - Student
+    - Research Graduate
+    - AI researcher
+    - AI developer/engineer
+    - Reporter
+    - Other
+  I agree to use this model for non-commercial use ONLY: checkbox
+  I agree to cite the Cheetah paper: checkbox
+  geo: ip_location
+  By clicking Submit below I accept the terms of the license: checkbox
+extra_gated_button_content: Submit
+---
+
+<div style='text-align: justify;'>
+  
+This is the repository accompanying our ACL 2024 paper [Toucan: Many-to-Many Translation for 150 African Language Pairs](https://aclanthology.org/2024.findings-acl.781/). 
+We address a notable gap in Natural Language Processing (NLP) by introducing a collection of resources designed to improve Machine Translation (MT) for low-resource languages, with a specific focus on African languages. First, We introduce two language models (LMs), Cheetah-1.2B and Cheetah-3.7B, with 1.2 billion and 3.7 billion parameters respectively. Next, we finetune the aforementioned models to create Toucan, an Afrocentric machine translation model designed to support 156 African language pairs. To evaluate Toucan, we carefully develop an extensive machine translation benchmark, dubbed AfroLingu-MT, tailored for evaluating machine translation. Toucan significantly outperforms other models, showcasing its remarkable performance on MT for African languages. Finally, we train a new model, spBLEU_1K, to enhance translation evaluation metrics, covering 1K languages, including 614 African languages. This work aims to advance the field of NLP, fostering cross-cultural understanding and knowledge exchange, particularly in regions with limited language resources such as Africa. 
+
+</div>
+
+## Models
+
+<div style='text-align: justify;'>
+
+  To effectively train a MT language model for African languages, it is crucial to start with a powerful, Afrocentric pretrained language model. For this purpose, we select Cheetah (Adebara et al.,
+2024), a recently introduced SoTA model with extensive coverage encompassing 517 African languages. One limitation of Cheetah, however, is that it is available only in a base architecture, featuring
+580M parameters. Given our objective to develop a large-scale language model for machine translation capabale of serving 156 directions, this base model does not fully meet our requirements. To address this limitation, we embark on training larger and more expansive Afrocentric sequence-to-sequence models. We focus on two sizes: one model with 1.2B parameters and another with 3.7B parameters. We refer to the new models “Cheetah-1.2B” and “Cheetah-3.7B”, respectively, to reflect their enhanced capabilities and parameter scale. These models represent a significant advancement in our efforts to improve machine
+translation for African languages, offering greater capacities in handling the rich linguistic nuances of African languages. Cheetah Pertaining. To train the new Cheetah models, we utilize the same pre-training dataset employed in training the original Cheetah-base model (Adebara et al., 2024). This strategic choice ensures consistency in the foundational data across models, enabling the advanced Cheetah-1.2B and Cheetah-3.7B versions to build upon the rich linguistic diversity captured in the original dataset. We refer to (Adebara et al., 2024) for more information about the pretraining data of Cheetah models. We employ a learning rate of 0.01, a batch size of 1, 024 sequences, and a maximum sequence length of 1, 024. Each model undergoes pretraining for 1 million steps. The training process is conducted on Google Cloud TPU with 128 cores (v3 − 128) provided by the TensorFlow Research Cloud (TFRC). We provide additional details on pretraining in Section B in the Appendix.
+
+</div>
+
+- Please refer to [**supported-languages**]("https://github.com/UBC-NLP/Cheetah/blob/main/supported-languages.txt")
+- More details about Cheetah's pretraning data, visit Cheetah's GitHub [**Cheetah paper GitHub**]("https://github.com/UBC-NLP/Cheetah")
+- More details about Toucan's pretraning data, visit Toucan's GitHub [**Toucan paper GitHub**]("https://github.com/UBC-NLP/Toucan")
+
+
+| **Cheetah Models**   | **Link** | 
+|---------|:------------------:|    
+| 🔥**Cheetah-base**🔥|     [https://huggingface.co/UBC-NLP/cheetah-base](https://huggingface.co/UBC-NLP/cheetah-base) 
+| 🔥**Cheetah-1.2B**🔥|     [https://huggingface.co/UBC-NLP/cheetah-1.2B](https://huggingface.co/UBC-NLP/cheetah-1.2B)   
+| 🔥**Cheetah-3.7B**🔥|    TBA
+
+
+| **Tocan Models**   | **Link** | 
+|---------|:------------------:|    
+| 🔥**Toucan-base**🔥|     [https://huggingface.co/UBC-NLP/toucan-base](https://huggingface.co/UBC-NLP/toucan-base) 
+| 🔥**Toucan-1.2B**🔥|     [https://huggingface.co/UBC-NLP/toucan-1.2B](https://huggingface.co/UBC-NLP/toucan-1.2B)   
+| 🔥**Toucan-3.7B**🔥|    TBA
+
+#  3. How to use Cheetah-1.2B model
+
+Below is an example for using **Cheetah-1.2B** predict masked tokens. 
+``` bash
+from transformers import T5Tokenizer, AutoModelForSeq2SeqLM
+
+tokenizer = T5Tokenizer.from_pretrained("UBC-NLP/cheetah-1.2B")
+model = AutoModelForSeq2SeqLM.from_pretrained("UBC-NLP/cheetah-1.2B")
+
+yor_prompt="ìròyìn kan nípa owó ìjọba <extra_id_0> kan"
+
+input_ids = tokenizer(yor_prompt, return_tensors="pt").input_ids
+outputs = model.generate(input_ids)
+print("Cheetah-1.2B - Tokenized input:", tokenizer.tokenize(yor_prompt))
+print("Cheetah-1.2B - Decoded output:", tokenizer.decode(outputs[0], skip_special_tokens=True))
+
+```
+Output:
+```bash
+Cheetah-1.2B - Tokenized input: ['▁ìròyìn', '▁kan', '▁nípa', '▁owó', '▁ìjọba', '<extra_id_0>', '▁kan']
+Cheetah-1.2B - Decoded output: Nàìjíríà
+```
+
+#  3. How to use Toucan model
+To translate using Toucan models, use the target language ISO-3 code as preix. Below the supported langauges
+```
+lang_names={
+    "aar": "Afar",
+    "ach": "Acholi",
+    "afr": "Afrikaans",
+    "aka": "Akan",
+    "amh": "Amharic",
+    "bam": "Bambara",
+    "bas": "Basaa",
+    "bem": "Bemba",
+    "btg": "Bete Gagnoa",
+    "eng": "English",
+    "ewe": "Ewe",
+    "fon": "Fon",
+    "fra": "French",
+    "hau": "Hausa",
+    "ibo": "Igbo",
+    "kbp": "Kabiye",
+    "lgg": "Lugbara",
+    "lug": "Luganda",
+    "mlg": "Malagasy",
+    "nyn": "Nyakore",
+    "orm": "Oromo",
+    "som": "Somali",
+    "sot": "Sesotho",
+    "swa": "Swahili",
+    "tir": "Tigrinya",
+    "yor": "Yoruba",
+    "teo": "Ateso",
+    "gez": "Geez",
+    "wal": "Wolaytta",
+    "fan": "Fang",
+    "kau": "Kanuri",
+    "kin": "Kinyawanda",
+    "kon": "Kongo",
+    "lin": "Lingala",
+    "nya": "Chichewa",
+    "pcm": "Nigerian Pidgin",
+    "ssw": "Siswati",
+    "tsn": "Setswana",
+    "tso": "Tsonga",
+    "twi": "Twi",
+    "wol": "Wolof",
+    "xho": "Xhosa",
+    "zul": "Zulu",
+    "nnb": "Nande",
+    "swc": "Swahili Congo",
+    "ara": "Arabic"
+}
+```
+Below is an example for translating using **Toucan-1.2B**. 
+``` bash
+from transformers import AutoTokenizer, MT5ForConditionalGeneration
+import torch
+tokenizer = AutoTokenizer.from_pretrained("UBC-NLP/toucan-1.2B")
+model = MT5ForConditionalGeneration.from_pretrained("UBC-NLP/toucan-1.2B", torch_dtype=torch.float16, device_map="auto")
+model.eval()
+
+#Translate from Enlglish to Zulu
+text="zul: Clear all items from the recent documents list"
+input_ids = tokenizer(text, return_tensors="pt", max_length=1024, truncation=True).to("cuda:0")
+with torch.no_grad():
+    generated_ids = model.generate(**input_ids, num_beams=5, max_new_tokens=len(text), do_sample=True, temperature=0.6, top_p=0.9)
+print(tokenizer.batch_decode(generated_ids, skip_special_tokens=True,  skip_prompt=True)[0])
+
+```
+Output:
+```bash
+Vala zonke izinto kusuka kwihlu lamadokhumende elidlule
+```
+
+
+
+## Citation
+If you use the pre-trained model (Cheetah-1.2B) for your scientific publication, or if you find the resources in this repository useful, please cite our papers as follows (to be updated):
+
+
+**Toucan's Paper**
+```
+@inproceedings{adebara-etal-2024-cheetah,
+    title = "Cheetah: Natural Language Generation for 517 {A}frican Languages",
+    author = "Adebara, Ife  and
+      Elmadany, AbdelRahim  and
+      Abdul-Mageed, Muhammad",
+    editor = "Ku, Lun-Wei  and
+      Martins, Andre  and
+      Srikumar, Vivek",
+    booktitle = "Proceedings of the 62nd Annual Meeting of the Association for Computational Linguistics (Volume 1: Long Papers)",
+    month = aug,
+    year = "2024",
+    address = "Bangkok, Thailand and virtual meeting",
+    publisher = "Association for Computational Linguistics",
+    url = "https://aclanthology.org/2024.acl-long.691",
+    pages = "12798--12823",
+}
+```
+
+**Cheetah's Paper**
+```
+@inproceedings{elmadany-etal-2024-toucan,
+    title = "Toucan: Many-to-Many Translation for 150 {A}frican Language Pairs",
+    author = "Elmadany, AbdelRahim  and
+      Adebara, Ife  and
+      Abdul-Mageed, Muhammad",
+    editor = "Ku, Lun-Wei  and
+      Martins, Andre  and
+      Srikumar, Vivek",
+    booktitle = "Findings of the Association for Computational Linguistics ACL 2024",
+    month = aug,
+    year = "2024",
+    address = "Bangkok, Thailand and virtual meeting",
+    publisher = "Association for Computational Linguistics",
+    url = "https://aclanthology.org/2024.findings-acl.781",
+    pages = "13189--13206",
+}
+```
+
+## Acknowledgments
+We gratefully acknowledges support from Canada Research Chairs (CRC), the Natural Sciences and Engineering Research Council of Canada (NSERC; RGPIN-2018-04267), the Social Sciences and Humanities Research Council of Canada (SSHRC; 435-2018-0576; 895-2020-1004; 895-2021-1008), Canadian Foundation for Innovation (CFI; 37771), [Digital Research Alliance of Canada](https://alliancecan.ca), [UBC ARC-Sockeye](https://arc.ubc.ca/ubc-arc-sockeye), Advanced Micro Devices, Inc. (AMD), and Google. Any opinions, conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of CRC, NSERC, SSHRC, CFI, the Alliance, AMD, Google, or UBC ARC-Sockeye.