Search Methods API Reference

SearchMethod attempts to find the optimal set of perturbations that will produce an adversarial example. Finding such optimal perturbations becomes a combinatorial optimization problem, and search methods are typically heuristic search algorithms designed to solve the underlying combinatorial problem.

More in-depth study of search algorithms for NLP adversarial attacks can be found in the following work Searching for a Search Method: Benchmarking Search Algorithms for Generating NLP Adversarial Examples by Jin Yong Yoo, John X. Morris, Eli Lifland, and Yanjun Qi.

SearchMethod

class textattack.search_methods.SearchMethod

This is an abstract class that contains main helper functionality for search methods.

A search method is a strategy for applying transformations until the goal is met or the search is exhausted.

check_transformation_compatibility(transformation)

Determines whether this search method is compatible with transformation.

perform_search(initial_result)

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

is_black_box

Returns True if search method does not require access to victim model’s internal states.

BeamSearch

class textattack.search_methods.BeamSearch(beam_width=8)

An attack that maintains a beam of the beam_width highest scoring AttackedTexts, greedily updating the beam with the highest scoring transformations from the current beam.

Parameters:

• goal_function – A function for determining how well a perturbation is doing at achieving the attack’s goal.
• transformation – The type of transformation.
• beam_width (int) – the number of candidates to retain at each step

extra_repr_keys()

extra fields to be included in the representation of a class.

perform_search(initial_result)

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

is_black_box

Returns True if search method does not require access to victim model’s internal states.

GreedySearch

class textattack.search_methods.GreedySearch

A search method that greedily chooses from a list of possible perturbations.

Implemented by calling BeamSearch with beam_width set to 1.

extra_repr_keys()

extra fields to be included in the representation of a class.

GreedyWordSwapWIR

class textattack.search_methods.GreedyWordSwapWIR(wir_method='unk', unk_token='[UNK]')

An attack that greedily chooses from a list of possible perturbations in order of index, after ranking indices by importance.

Parameters:

• wir_method – method for ranking most important words
• model_wrapper – model wrapper used for gradient-based ranking

check_transformation_compatibility(transformation)

Since it ranks words by their importance, GreedyWordSwapWIR is limited to word swap and deletion transformations.

extra_repr_keys()

extra fields to be included in the representation of a class.

perform_search(initial_result)

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

is_black_box

Returns True if search method does not require access to victim model’s internal states.

AlzantotGeneticAlgorithm

class textattack.search_methods.AlzantotGeneticAlgorithm(pop_size=60, max_iters=20, temp=0.3, give_up_if_no_improvement=False, post_crossover_check=True, max_crossover_retries=20)

Attacks a model with word substiutitions using a genetic algorithm.

Parameters:

• pop_size (int) – The population size. Defaults to 60.
• max_iters (int) – The maximum number of iterations to use. Defaults to 20.
• temp (float) – Temperature for softmax function used to normalize probability dist when sampling parents. Higher temperature increases the sensitivity to lower probability candidates.
• give_up_if_no_improvement (bool) – If True, stop the search early if no candidate that improves the score is found.
• post_crossover_check (bool) – If True, check if child produced from crossover step passes the constraints.
• max_crossover_retries (int) – Maximum number of crossover retries if resulting child fails to pass the constraints. Applied only when post_crossover_check is set to True. Setting it to 0 means we immediately take one of the parents at random as the child upon failure.

ImprovedGeneticAlgorithm

class textattack.search_methods.ImprovedGeneticAlgorithm(pop_size=60, max_iters=20, temp=0.3, give_up_if_no_improvement=False, post_crossover_check=True, max_crossover_retries=20, max_replace_times_per_index=5)

Attacks a model with word substiutitions using a genetic algorithm.

Parameters:

• pop_size (int) – The population size. Defaults to 20.
• max_iters (int) – The maximum number of iterations to use. Defaults to 50.
• temp (float) – Temperature for softmax function used to normalize probability dist when sampling parents. Higher temperature increases the sensitivity to lower probability candidates.
• give_up_if_no_improvement (bool) – If True, stop the search early if no candidate that improves the score is found.
• post_crossover_check (bool) – If True, check if child produced from crossover step passes the constraints.
• max_crossover_retries (int) – Maximum number of crossover retries if resulting child fails to pass the constraints. Applied only when post_crossover_check is set to True. Setting it to 0 means we immediately take one of the parents at random as the child upon failure.
• max_replace_times_per_index (int) – The maximum times words at the same index can be replaced in improved genetic algorithm.

extra_repr_keys()

extra fields to be included in the representation of a class.

ParticleSwarmOptimization

class textattack.search_methods.ParticleSwarmOptimization(pop_size=60, max_iters=20, post_turn_check=True, max_turn_retries=20)

Attacks a model with word substiutitions using a Particle Swarm Optimization (PSO) algorithm. Some key hyper-parameters are setup according to the original paper:

“We adjust PSO on the validation set of SST and set ω_1 as 0.8 and ω_2 as 0.2. We set the max velocity of the particles V_{max} to 3, which means the changing probability of the particles ranges from 0.047 (sigmoid(-3)) to 0.953 (sigmoid(3)).”

Parameters:

• pop_size (int, optional) – The population size. Defaults to 60.
• max_iters (int, optional) – The maximum number of iterations to use. Defaults to 20.
• post_turn_check (bool, optional) – If True, check if new position reached by moving passes the constraints. Defaults to True
• max_turn_retries (bool, optional) – Maximum number of movement retries if new position after turning fails to pass the constraints. Applied only when post_movement_check is set to True. Setting it to 0 means we immediately take the old position as the new position upon failure.

check_transformation_compatibility(transformation)

The genetic algorithm is specifically designed for word substitutions.

extra_repr_keys()

extra fields to be included in the representation of a class.

perform_search(initial_result)

Perturbs attacked_text from initial_result until goal is reached or search is exhausted.

Must be overridden by specific search methods.

is_black_box

Returns True if search method does not require access to victim model’s internal states.