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[source]

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)[source]

Determines whether this search method is compatible with transformation.

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

Must be overridden by specific search methods.

property 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)[source]

An attack that maintinas 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

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

Must be overridden by specific search methods.

property is_black_box

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

GreedySearch

class textattack.search_methods.GreedySearch[source]

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

Implemented by calling BeamSearch with beam_width set to 1.

GreedyWordSwapWIR

class textattack.search_methods.GreedyWordSwapWIR(wir_method='unk')[source]

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)[source]

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

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

Must be overridden by specific search methods.

property 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)[source]

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.

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)[source]

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.

ParticleSwarmOptimization

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

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)[source]

The genetic algorithm is specifically designed for word substitutions.

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

Must be overridden by specific search methods.

property is_black_box

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