A library for generating text adversarial examples
Project description
TextAttack 🐙
Generating adversarial examples for NLP models
About •
Setup •
Usage •
Design
About
TextAttack is a library for running adversarial attacks against NLP models. These may be useful for evaluating attack methods and evaluating model robustness. TextAttack is designed in order to be easily extensible to new NLP tasks, models, attack methods, and attack constraints. The separation between these aspects of an adversarial attack and standardization of constraint evaluation allows for easier ablation studies. TextAttack supports attacks on models trained for classification and entailment.
Setup
Installation
You should be running Python 3.6+ to use this package. A CUDA-compatible GPU is optional but will greatly improve code speed. After cloning this git repository, run the following commands to install the textattack
page a conda
environment:
conda create -n text-attack python=3.7
conda activate text-attack
pip install -e .
We use the NLTK package for its list of stopwords and access to the WordNet lexical database. To download them run in Python shell:
import nltk
nltk.download('stopwords')
nltk.download('wordnet')
We use spaCy's English model. To download it, after installing spaCy run:
python -m spacy download en
Cache
TextAttack provides pretrained models and datasets for user convenience. By default, all this stuff is downloaded to ~/.cache
. You can change this location by editing the CACHE_DIR
field in config.json
.
Common Errors
Errors regarding GCC
If you see an error that GCC is incompatible, make sure your system has an up-to-date version of the GCC compiler.
Errors regarding Java
Using the LanguageTool constraint relies on Java 8 internally (it's not ideal, we know). Please install Java 8 if you're interested in using the LanguageTool grammaticality constraint.
Usage
Basic Usage
We have a command-line interface for running different attacks on different datasets. Run it with default arguments with python scripts/run_attack.py
. See help info and list of arguments with python scripts/run_attack.py --help
.
Attack Recipes
We include attack recipes which build an attack such that only one command line argument has to be passed. To run an attack recipes, run python scripts/run_attack.py --recipe [recipe_name]
Currently, we include four recipes, each for synonym substitution-based classification and entailment attacks:
- deepwordbug: Replace-1 scoring and multi-transformation character-swap attack ("Black-box Generation of Adversarial Text Sequences to Evade Deep Learning Classifiers")
- textfooler: Greedy attack with word importance ranking ("Is Bert Really Robust?" (Jin et al., 2019))
- alzantot: Genetic algorithm attack from ("Generating Natural Language Adversarial Examples" (Alzantot et al., 2018))
- tf-adjusted: TextFooler attack with constraint thresholds adjusted based on human evaluation and grammaticality enforced.
- alz-adjusted: Alzantot's attack adjusted to follow the same constraints as tf-adjusted such that the only difference is the search method.
Adding to TextAttack
Clone the repository, add your code, and run run_attack to get results. If you would like your contribution to be added to the library, submit a pull request. Instructions for using TextAttack as a pip library coming soon!
Design
TokenizedText
To allow for word replacement after a sequence has been tokenized, we include a TokenizedText object which maintains both a list of tokens and the original text, with punctuation. We use this object in favor of a list of words or just raw text.
Models and Datasets
We've included a few pretrained models that you can download and run out-of-the-box. However, TextAttack is model agnostic! Anything that overrides __call__, takes in tokenized text, and outputs probabilities works.
Attacks
Attacks all take as input a TokenizedText, and output either an AttackResult if it succeeds or a FailedAttackResult if it fails. We split attacks into black box, which only have access to the model’s call function, and white box, which have access to the whole model. For standardization and ease of ablation, we formulate an attack as a series of transformations in a search space, subject to certain constraints. An attack may call get_transformations for a given transformation to get a list of possible transformations filtered by meeting all of the attack’s constraints.
Transformations
Transformations take as input a TokenizedText and return a list of possible transformed TokenizedTexts. For example, a transformation might return all possible synonym replacements.
Constraints
Constraints take as input an original TokenizedText, and a list of transformed TokenizedTexts. For each transformed option, the constraint returns a boolean representing whether the constraint is met.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for textattack-0.0.1.7-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9322333080602a101ea58bf77a83625b2de223cf0ed50bada5cc1a1a196cafdc |
|
MD5 | f0303227e9e6061947fa32136e3fdca8 |
|
BLAKE2b-256 | 5ad8ab3bc220fbbb07931f76e076b614739631ed1270e90703be0a55bad7d8b1 |