Update README.md

README.md

@@ -15,22 +15,76 @@ should probably proofread and complete it, then remove this comment. -->
 # iva_mt_wslot-m2m100_418M-0.1.0 en-pl
 
 This model is a fine-tuned version of [facebook/m2m100_418M](https://huggingface.co/facebook/m2m100_418M) on the [iva_mt_wslot](https://huggingface.co/datasets/cartesinus/iva_mt_wslot) dataset.
-It achieves the following results on the evaluation set:
-- Loss: 0.0176
+
+
+It achieves the following results:
+1) On the test set (iva_mt):
+- Bleu (plain text): 39.1560
+- Bleu (with slots): 63.8767
+- Baseline m2m100-418M (plain text): TBD
+
+2) WMT20 (en2pl):
+- Bleu (lowercased, tags removed): 15.0863 (for reference WMT20 submission systems in en-pl direction had between 25 and 30 bleu)
+- Baseline m2m100-418M (plain text): TBD
+   
+4) On the evaluation set:
 - Bleu: 61.6249
-- Gen Len: 21.157
 
-On training set:
-- translated train witout slots in input: 93.8200 Bleu
-- translated train with slots in input: 70.5597 Bleu
+3) On the training set (to see how it adjusted to train):
+- Bleu (plain text): 70.5597
+- Bleu (with slots): 93.8200
+
+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, most of them are short, imperatives. Both of this facts
+can be observed in above results. WMT results are very low while in-domain test is very high. One 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)).
+
+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
+can work. If you will translate domains unseen in either of them results might drop significantly to the point where baseline m2m100-418M will be better than this model.
+
+This model will generate tags in output even if there is not tag in input sentence. Frequency of this depends on input text. When testing IVA utterances this occurs 
+between 3 and 5% of all cases. When WMT20 was translated it happened in % cases (input text was from News domain).
+This is not very severe and can be fixed easily in post-processing (something like `sed 's/<[a-z]>//g'` should be enough in most cases).
+
+Translations with slots very often differ from same sentences when slots are removed. This is quite frequent and it happens between 30 and 50% of translated utterances.
+For example there will be a difference between "is it raining in barcelona" and "is it raining in <a>barcelona<a>". In second case model will more likely localize name of
+city to some Polish name (here Lublin, because such city was given in Massive train set). This might be useful if you want to generate more variants.
+
+## How to use
+
+First please make sure to install `pip install transformers`. First download model: 
+
+```python
+from transformers import M2M100ForConditionalGeneration, M2M100Tokenizer
+import torch
 
-## Model description
+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)
 
-More information needed
+model_name = "cartesinus/iva_mt_wslot-m2m100_418M-0.1.0"
+tokenizer = M2M100Tokenizer.from_pretrained(model_name, src_lang="en", tgt_lang="pl")
+model = M2M100ForConditionalGeneration.from_pretrained(model_name)
+```
 
-## Intended uses & limitations
+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 
 
-More information needed
 
 ## Training and evaluation data