Update README.md

README.md

@@ -1,50 +1,113 @@
 ---
 license: mit
 tags:
-- generated_from_trainer
+- machine translation
+- iva
+- virtual assistants
+- natural-language-understanding
+- nlu
 metrics:
 - bleu
 model-index:
-- name: iva_mt_wslot-m2m100_1.2B-0.1.0
+- name: iva_mt_wslot-m2m100_1.2B-en-pl
   results: []
+datasets:
+- cartesinus/iva_mt_wslot
+language:
+- pl
+- en
+co2_eq_emissions:
+  emissions: 0.68
 ---
 
 <!-- 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. -->
 
-# iva_mt_wslot-m2m100_1.2B-0.1.0
+# iva_mt_wslot-m2m100_1.2B-en-pl (v0.1.0)
 
-This model is a fine-tuned version of [facebook/m2m100_1.2B](https://huggingface.co/facebook/m2m100_1.2B) on the None dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.3082
-- Bleu: 62.4604
-- Gen Len: 21.2847
+This model is a fine-tuned version of [facebook/m2m100_1.2B](https://huggingface.co/facebook/m2m100_1.2B) on the
+[iva_mt_wslot](https://huggingface.co/datasets/cartesinus/iva_mt_wslot) dataset. There is also smaller version of this model here:
+[cartesinus/iva_mt_wslot-m2m100_418M-en-pl](https://huggingface.co/cartesinus/iva_mt_wslot-m2m100_418M-0.1.0). This model (1.2B) achieves the following results:
 
-## Model description
+1) On the test set (iva_mt):
+- BLEU (plain text): **(result in preparation)**
+- BLEU (with slots): **(result in preparation)**
+- F1 score: (in preparation)
 
-More information needed
+For reference BLEU for baseline m2m100-418M (plain text) was 21.9468 and for m2m100-1.2B was **(result in preparation)**. Second result (BLEU with slots) is when tags
+are treated as "normal" words in sentence. Therefore that result might be a bit misleading. Please refer to plain text results if you are not sure how to interpret them.
 
-## Intended uses & limitations
+2) WMT20 (en2pl):
+- BLEU (lowercased, tags removed): **(result in preparation)**
+- BLEU for baseline m2m100-1.2B (plain text): **(result in preparation)**
 
-More information needed
+For reference WMT20 submission systems in en-pl direction had between 25 and 30 BLEU
+   
+3) BLEU on the evaluation set (same as in below table 'Training results'): **62.4604**
 
-## Training and evaluation data
+4) On the training set (to see how it adjusted to train):
+- BLEU (plain text): **(result in preparation)**
+- BLEU (with slots): **(result in preparation)**
+
+BLEU was measured with [sacreBLEU](https://github.com/mjpost/sacrebleu) library.
+
+## Model description, intended uses & limitations
+
+Model is biased towards virtual assistant (IVA) sentences in prediction/translation. These sentences are short, imperatives with a lot of name entities (slots) and 
+particular vocabulary (for example settings name). It can be observed in above results where WMT results are very low while in-domain test is very high.
+
+This model will most probably force IVA translations on your text. As long as sentences that you are translating are more or less similar to massive and leyzer domains it
+will be ok. If you will translate out-of-domain sentenences (such as for example News, Medical) that are not very similar then results will drop significantly.
+
+One last thing that needs to be mentioned is that BLEU is not particulary good metric to evaluate IVA sentences due to their length and it should be evalued with other
+metrices (e.g. [GLEU](https://aclanthology.org/P15-2097.pdf)).
 
-More information needed
+## How to use
 
-## Training procedure
+First please make sure to install `pip install transformers`. First download model: 
 
-### Training hyperparameters
+```python
+from transformers import M2M100ForConditionalGeneration, M2M100Tokenizer
+import torch
+
+def translate(input_text, lang):
+    input_ids = tokenizer(input_text, return_tensors="pt")
+    generated_tokens = model.generate(**input_ids, forced_bos_token_id=tokenizer.get_lang_id(lang))
+    return tokenizer.batch_decode(generated_tokens, skip_special_tokens=True)
+
+model_name = "cartesinus/iva_mt_wslot-m2m100_1.2B-en-pl"
+tokenizer = M2M100Tokenizer.from_pretrained(model_name, src_lang="en", tgt_lang="pl")
+model = M2M100ForConditionalGeneration.from_pretrained(model_name)
+```
+
+Then you can translate either plan text like this:
+```python
+print(translate("set the temperature on my thermostat", "pl"))
+```
+or you can translate with slot annotations that will be restored in tgt language:
+```python
+print(translate("wake me up at <a>nine am<a> on <b>friday<b>", "pl")) #translation: obudź mnie o <a>piątej rano<a> <b>w tym tygodniu<b>
+```
+Limitations of translation with slot transfer:
+1) Annotated words must be placed between semi-xml tags like this "this is \<a\>example\<a\>"
+2) There is no closing tag for example "\<\a\>" in above example - this is done on purpose to ommit problems with backslash escape
+3) If sentence consists of more than one slot then simply use next alphabet letter. For example "this is \<a\>example\<a\> with more than \<b\>one\<b\> slot"
+4) Please do not add space before first or last annotated word because this particular model was trained this way and it most probably will lower it's results 
+
+
+## Training and evaluation data
 
-The following hyperparameters were used during training:
-- learning_rate: 2e-05
-- train_batch_size: 4
-- eval_batch_size: 4
-- seed: 42
-- optimizer: Adam with betas=(0.9,0.999) and epsilon=1e-08
-- lr_scheduler_type: linear
-- num_epochs: 10
-- mixed_precision_training: Native AMP
+## Dataset Composition (en-pl)
+| Corpus                                                               | Train  | Dev   | Test  |
+|----------------------------------------------------------------------|--------|-------|-------|
+| [Massive 1.1](https://huggingface.co/datasets/AmazonScience/massive) | 11514  | 2033  | 2974  |
+| [Leyzer 0.2.0](https://github.com/cartesinus/leyzer/tree/0.2.0)      | 3974   | 701   | 1380  |
+| [OpenSubtitles from OPUS](https://opus.nlpl.eu/OpenSubtitles-v1.php) | 2329   | 411   | 500   |
+| [KDE from OPUS](https://opus.nlpl.eu/KDE4.php)                       | 1154   | 241   | 241   |
+| [CCMatrix from Opus](https://opus.nlpl.eu/CCMatrix.php)              | 1096   | 232   | 237   |
+| [Ubuntu from OPUS](https://opus.nlpl.eu/Ubuntu.php)                  | 281    | 60    | 59    |
+| [Gnome from OPUS](https://opus.nlpl.eu/GNOME.php)                    | 14     | 3     | 3     |
+| *total*                                                              | 20362  | 3681  | 5394  |
 
 ### Training results