Document attacking translation models with morpheus/seq2sick

textattack/attack_recipes/morpheus_tan_2020.py

@@ -25,6 +25,41 @@ class MorpheusTan2020(AttackRecipe):
     Inflectional Perturbations
 
     https://www.aclweb.org/anthology/2020.acl-main.263/
+
+    Like :class:`~textattack.attack_recipes.Seq2SickCheng2018BlackBox`, this
+    works against any encoder-decoder generation model loaded via
+    :class:`~textattack.models.wrappers.HuggingFaceModelWrapper`, so it can
+    attack machine-translation checkpoints (e.g. MarianMT, mBART, a BART
+    checkpoint fine-tuned for translation) the same way it attacks the
+    text-classification models used elsewhere in this codebase's examples.
+    ``MinimizeBleu``'s ``ground_truth_output`` is the *reference*
+    translation (not the model's own unperturbed output, unlike
+    ``NonOverlappingOutput``/seq2sick), so pass the target-language
+    reference sentence as the second argument to ``.attack()``. See
+    https://github.com/QData/TextAttack/issues/725.
+
+    Example, attacking an English-to-German translation model (any
+    encoder-decoder checkpoint works the same way, including BART/MarianMT/
+    mBART translation checkpoints -- swap in the ``model``/``tokenizer``
+    below for one of those)::
+
+        import transformers
+        from textattack.attack_recipes import MorpheusTan2020
+        from textattack.models.wrappers import HuggingFaceModelWrapper
+
+        model = transformers.AutoModelForSeq2SeqLM.from_pretrained("t5-small")
+        tokenizer = transformers.AutoTokenizer.from_pretrained("t5-small")
+        # `max_length` avoids `transformers`' 20-token generation default,
+        # which truncates sentence-length translations.
+        model_wrapper = HuggingFaceModelWrapper(model, tokenizer, max_length=200)
+
+        attack = MorpheusTan2020.build(model_wrapper)
+        # t5-small needs the task prefix; other translation checkpoints
+        # (BART/MarianMT/mBART) typically don't.
+        input_text = "translate English to German: The quick brown fox jumps over the lazy dog."
+        reference_translation = "Der schnelle braune Fuchs springt über den faulen Hund."
+        result = attack.attack(input_text, reference_translation)
+        print(result.__str__(color_method="ansi"))
     """
 
     @staticmethod

textattack/attack_recipes/seq2sick_cheng_2018_blackbox.py

@@ -51,6 +51,15 @@ class Seq2SickCheng2018BlackBox(AttackRecipe):
         attack = Seq2SickCheng2018BlackBox.build(model_wrapper)
         result = attack.attack(input_text, original_summary)
         print(result.__str__(color_method="ansi"))
+
+    This also works against translation models (e.g. attacking BART/MarianMT
+    on an en-de translation task): pass the model's own unperturbed
+    translation as the second argument to ``.attack()``, since
+    ``NonOverlappingOutput`` (unlike ``MinimizeBleu``, used by
+    :class:`~textattack.attack_recipes.MorpheusTan2020`) compares against
+    that rather than a ground-truth reference translation. See
+    :class:`~textattack.attack_recipes.MorpheusTan2020` for a worked
+    translation example and https://github.com/QData/TextAttack/issues/725.
     """
 
     @staticmethod