Update README.md (#1)

- Update README.md (ac977b12a8c55ffc3323f8622c5722f6b0478214)


Co-authored-by: Andrey Grabovoy <[email protected]>

README.md

@@ -11,10 +11,77 @@ metrics:
 - bleu
 - chrf
 ---
-Final model for paper ["Neural machine translation system for Lezgian, Russian and Azerbaijani languages"](https://arxiv.org/abs/2410.05472).
+# Neural machine translation system for Lezgian, Russian and Azerbaijani languages
 
-**Russian version of Qusar test set was machine translated from Azerbaijani.**
+We release the first neural machine translation system for translation between Russian, Azerbaijani and the endangered Lezgian languages, as well as monolingual and parallel datasets collected and aligned for training and evaluating the system.
 
+# Get Usage
+
+## Russian-Lezgian example
+
+```python
+from transformers import NllbTokenizer, AutoModelForSeq2SeqLM
+
+model = AutoModelForSeq2SeqLM.from_pretrained("AlidarAsvarov/nllb-200-600M-lez-rus-azj")
+tokenizer = NllbTokenizer.from_pretrained("AlidarAsvarov/nllb-200-600M-lez-rus-azj", )
+
+model.eval()
+
+tokenizer.src_lang = 'rus_Cyrl'
+inputs = tokenizer(
+    'Футбольная ассоциации Англии рассчитывала провести финал кубка на перестроенном стадионе "Уэмбли"', 
+    return_tensors='pt',
+    padding=True,
+    truncation=True,
+    max_length=40
+)
+
+tokenizer.tgt_lang = 'lez_Cyrl'
+tokenizer.batch_decode(
+    model.generate(
+        **inputs,
+        forced_bos_token_id=tokenizer.convert_tokens_to_ids(tokenizer.tgt_lang),
+        max_new_tokens=int(32 + 3 * inputs.input_ids.shape[1]),
+        num_beams=5
+    ),
+    skip_special_tokens=True
+)
+```
+
+## Azerbaijani-Lezgian example
+
+```python
+from transformers import NllbTokenizer, AutoModelForSeq2SeqLM
+
+model = AutoModelForSeq2SeqLM.from_pretrained("AlidarAsvarov/nllb-200-600M-lez-rus-azj")
+tokenizer = NllbTokenizer.from_pretrained("AlidarAsvarov/nllb-200-600M-lez-rus-azj", )
+
+model.eval()
+
+tokenizer.src_lang = 'azj_Latn'
+inputs = tokenizer(
+    '1741-ci ilin payızında Nadir s ̧ah Mu ̈s ̧ku ̈r lәzgilәrinә hu ̈cum edib onlara divan tutur.', 
+    return_tensors='pt',
+    padding=True,
+    truncation=True,
+    max_length=102
+)
+
+tokenizer.tgt_lang = 'lez_Cyrl'
+tokenizer.batch_decode(
+    model.generate(
+        **inputs,
+        forced_bos_token_id=tokenizer.convert_tokens_to_ids(tokenizer.tgt_lang),
+        max_new_tokens=int(32 + 3 * inputs.input_ids.shape[1]),
+        num_beams=5
+    ),
+    skip_special_tokens=True
+)
+```
+
+# Quality
+
+## BLEU score
 
 | BLEU   | All   | Bible | Quran | Qusar  |
 | ------ | ----- | ----- | ----- | -----  |
@@ -25,6 +92,8 @@ Final model for paper ["Neural machine translation system for Lezgian, Russian a
 | ru-az  | 31.65 | 25.73 | 32.93 | 41.10* |
 | az-ru  | 33.63 | 28.78 | 36.83 | 40.46* |
 
+## ChrF score
+
 | ChrF++ | All   | Bible | Quran | Qusar  |
 | ------ | ----- | ----- | ----- | -----  |
 | lez2az | 48.62 | 47.17 | 53.95 | 47.02  |
@@ -35,10 +104,26 @@ Final model for paper ["Neural machine translation system for Lezgian, Russian a
 | az2ru  | 54.71 | 49.21 | 56.32 | 62.54* |
 
 
-Random examples of translation from Russian to Lezgian:
+## Random examples of translation from Russian to Lezgian:
 
 |                        Russian (source)                                                                                               | Lezgian (target)                                                                                                      | Comment                                            |
 |---------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
 | Футбольная ассоциации Англии рассчитывала провести финал кубка на перестроенном стадионе "Уэмбли"                                     | Англиядин футболдин командадик цӀийи кьилелай эцигай "Уэмбли" стадионда кубокдин финал кьиле тухудай фикир кьуна      | "Association" translated as "team"                 |
 | На одиннадцатый день рождения Гарри узнаёт, что является волшебником, и ему уготовано место в школе волшебства "Хогвартс"             | ЦӀуд лагьай юкъуз Гарриди вич суьгьуьрчи тирди винел акъудна ва адал "Хогварц" суьгьуьрчивилин мектебда чка гьазурна. | "On eleven's bithday" translated as "On tenth day" |
-| В 1960-х годах Советский Союз развивал стратегические ракетные вооружения, в то же время США делали ставку на стратегическую авиацию. | 1960-йисара СССР-ди стратегиядин ракетдин яракьар вилик тухвана, гьакӀни АСШ-ди стратегиядин авиациядин хиве кьунай.  |                                                    |
+| В 1960-х годах Советский Союз развивал стратегические ракетные вооружения, в то же время США делали ставку на стратегическую авиацию. | 1960-йисара СССР-ди стратегиядин ракетдин яракьар вилик тухвана, гьакӀни АСШ-ди стратегиядин авиациядин хиве кьунай.  |                                                    |
+
+# Citation
+
+If you use that results in your research, please cite our paper:
+
+```bibtex
+@misc{asvarov2024neuralmachinetranslationlezgian,
+      title={Neural machine translation system for Lezgian, Russian and Azerbaijani languages}, 
+      author={Alidar Asvarov and Andrey Grabovoy},
+      year={2024},
+      eprint={2410.05472},
+      archivePrefix={arXiv},
+      primaryClass={cs.CL},
+      url={https://arxiv.org/abs/2410.05472}, 
+}
+```