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
.
- abstract perform_search(initial_result)[source]
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
- perform_search(initial_result)[source]
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
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.
- perform_search(initial_result)[source]
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 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)[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 Truemax_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.
- perform_search(initial_result)[source]
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.