---
local: utilities-for-trainer
sections:
- local: transformers.EvalPrediction
  title: Utilities
- local: transformers.trainer_callback.CallbackHandler
  title: Callbacks internals
- local: transformers.trainer_pt_utils.DistributedTensorGatherer
  title: Distributed Evaluation
- local: transformers.HfArgumentParser
  title: Distributed Evaluation
- local: transformers.debug_utils.DebugUnderflowOverflow
  title: Debug Utilities
title: Utilities for Trainer
---
<script>
import Tip from "./Tip.svelte";
import Youtube from "./Youtube.svelte";
import Docstring from "./Docstring.svelte";
import CodeBlock from "./CodeBlock.svelte";
import CodeBlockFw from "./CodeBlockFw.svelte";
import DocNotebookDropdown from "./DocNotebookDropdown.svelte";
import IconCopyLink from "./IconCopyLink.svelte";
export let fw: "pt" | "tf"
</script>
<!--Copyright 2020 The HuggingFace Team. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with
the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on
an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the
specific language governing permissions and limitations under the License.
-->

<h1 id="utilities-for-trainer">Utilities for Trainer</h1>

This page lists all the utility functions used by [Trainer](/docs/transformers/pr_15592/en/main_classes/trainer#transformers.Trainer).

Most of those are only useful if you are studying the code of the Trainer in the library.

<h2 id="transformers.EvalPrediction">Utilities</h2>

<div class="docstring">

<docstring><name>class transformers.EvalPrediction</name><anchor>transformers.EvalPrediction</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/trainer_utils.py#L67</source><parameters>[{"name": "predictions", "val": ": typing.Union[numpy.ndarray, typing.Tuple[numpy.ndarray]]"}, {"name": "label_ids", "val": ": typing.Union[numpy.ndarray, typing.Tuple[numpy.ndarray]]"}]</parameters><paramsdesc>- **predictions** (`np.ndarray`) -- Predictions of the model.
- **label_ids** (`np.ndarray`) -- Targets to be matched.</paramsdesc><paramgroups>0</paramgroups></docstring>

Evaluation output (always contains labels), to be used to compute metrics.




</div>

<div class="docstring">

<docstring><name>class transformers.IntervalStrategy</name><anchor>transformers.IntervalStrategy</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/trainer_utils.py#L115</source><parameters>[{"name": "value", "val": ""}, {"name": "names", "val": " = None"}, {"name": "module", "val": " = None"}, {"name": "qualname", "val": " = None"}, {"name": "type", "val": " = None"}, {"name": "start", "val": " = 1"}]</parameters></docstring>
An enumeration.

</div>

<div class="docstring">

<docstring><name>transformers.set\_seed</name><anchor>transformers.set_seed</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/trainer_utils.py#L50</source><parameters>[{"name": "seed", "val": ": int"}]</parameters><paramsdesc>- **seed** (`int`) -- The seed to set.</paramsdesc><paramgroups>0</paramgroups></docstring>

Helper function for reproducible behavior to set the seed in `random`, `numpy`, `torch` and/or `tf` (if installed).




</div>

<div class="docstring">

<docstring><name>transformers.torch\_distributed\_zero\_first</name><anchor>transformers.torch_distributed_zero_first</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/trainer_pt_utils.py#L212</source><parameters>[{"name": "local_rank", "val": ": int"}]</parameters><paramsdesc>- **local_rank** (`int`) -- The rank of the local process.</paramsdesc><paramgroups>0</paramgroups></docstring>

Decorator to make all processes in distributed training wait for each local_master to do something.




</div>

<h2 id="transformers.trainer_callback.CallbackHandler">Callbacks internals</h2>

<div class="docstring">

<docstring><name>class transformers.trainer\_callback.CallbackHandler</name><anchor>transformers.trainer_callback.CallbackHandler</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/trainer_callback.py#L284</source><parameters>[{"name": "callbacks", "val": ""}, {"name": "model", "val": ""}, {"name": "tokenizer", "val": ""}, {"name": "optimizer", "val": ""}, {"name": "lr_scheduler", "val": ""}]</parameters></docstring>
Internal class that just calls the list of callbacks in order.

</div>

<h2 id="transformers.trainer_pt_utils.DistributedTensorGatherer">Distributed Evaluation</h2>

<div class="docstring">

<docstring><name>class transformers.trainer\_pt\_utils.DistributedTensorGatherer</name><anchor>transformers.trainer_pt_utils.DistributedTensorGatherer</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/trainer_pt_utils.py#L338</source><parameters>[{"name": "world_size", "val": ""}, {"name": "num_samples", "val": ""}, {"name": "make_multiple_of", "val": " = None"}, {"name": "padding_index", "val": " = -100"}]</parameters><paramsdesc>- **world_size** (`int`) --
  The number of processes used in the distributed training.
- **num_samples** (`int`) --
  The number of samples in our dataset.
- **make_multiple_of** (`int`, *optional*) --
  If passed, the class assumes the datasets passed to each process are made to be a multiple of this argument
  (by adding samples).
- **padding_index** (`int`, *optional*, defaults to -100) --
  The padding index to use if the arrays don't all have the same sequence length.</paramsdesc><paramgroups>0</paramgroups></docstring>

A class responsible for properly gathering tensors (or nested list/tuple of tensors) on the CPU by chunks.

If our dataset has 16 samples with a batch size of 2 on 3 processes and we gather then transfer on CPU at every
step, our sampler will generate the following indices:

`[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 0, 1]`

to get something of size a multiple of 3 (so that each process gets the same dataset length). Then process 0, 1 and
2 will be responsible of making predictions for the following samples:

- P0: `[0, 1, 2, 3, 4, 5]`
- P1: `[6, 7, 8, 9, 10, 11]`
- P2: `[12, 13, 14, 15, 0, 1]`

The first batch treated on each process will be

- P0: `[0, 1]`
- P1: `[6, 7]`
- P2: `[12, 13]`

So if we gather at the end of the first batch, we will get a tensor (nested list/tuple of tensor) corresponding to
the following indices:

`[0, 1, 6, 7, 12, 13]`

If we directly concatenate our results without taking any precautions, the user will then get the predictions for
the indices in this order at the end of the prediction loop:

`[0, 1, 6, 7, 12, 13, 2, 3, 8, 9, 14, 15, 4, 5, 10, 11, 0, 1]`

For some reason, that's not going to roll their boat. This class is there to solve that problem.





<div class="docstring">
<docstring><name>add\_arrays</name><anchor>transformers.trainer_pt_utils.DistributedTensorGatherer.add_arrays</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/trainer_pt_utils.py#L399</source><parameters>[{"name": "arrays", "val": ""}]</parameters></docstring>

Add `arrays` to the internal storage, Will initialize the storage to the full size at the first arrays passed
so that if we're bound to get an OOM, it happens at the beginning.


</div>
<div class="docstring">
<docstring><name>finalize</name><anchor>transformers.trainer_pt_utils.DistributedTensorGatherer.finalize</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/trainer_pt_utils.py#L435</source><parameters>[]</parameters></docstring>

Return the properly gathered arrays and truncate to the number of samples (since the sampler added some extras
to get each process a dataset of the same length).


</div></div>

<h2 id="transformers.HfArgumentParser">Distributed Evaluation</h2>

<div class="docstring">

<docstring><name>class transformers.HfArgumentParser</name><anchor>transformers.HfArgumentParser</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/hf_argparser.py#L44</source><parameters>[{"name": "dataclass_types", "val": ": typing.Union[DataClassType, typing.Iterable[DataClassType]]"}, {"name": "**kwargs", "val": ""}]</parameters></docstring>

This subclass of `argparse.ArgumentParser` uses type hints on dataclasses to generate arguments.

The class is designed to play well with the native argparse. In particular, you can add more (non-dataclass backed)
arguments to the parser after initialization and you'll get the output back after parsing as an additional
namespace. Optional: To create sub argument groups use the `_argument_group_name` attribute in the dataclass.



<div class="docstring">
<docstring><name>parse\_args\_into\_dataclasses</name><anchor>transformers.HfArgumentParser.parse_args_into_dataclasses</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/hf_argparser.py#L160</source><parameters>[{"name": "args", "val": " = None"}, {"name": "return_remaining_strings", "val": " = False"}, {"name": "look_for_args_file", "val": " = True"}, {"name": "args_filename", "val": " = None"}]</parameters><paramsdesc>args --
List of strings to parse. The default is taken from sys.argv. (same as argparse.ArgumentParser)
return_remaining_strings --
If true, also return a list of remaining argument strings.
look_for_args_file --
If true, will look for a ".args" file with the same base name as the entry point script for this
process, and will append its potential content to the command line args.
args_filename --
If not None, will uses this file instead of the ".args" file specified in the previous argument.</paramsdesc><paramgroups>0</paramgroups><rettype>Tuple consisting of</rettype><retdesc>- the dataclass instances in the same order as they were passed to the initializer.abspath
- if applicable, an additional namespace for more (non-dataclass backed) arguments added to the parser
  after initialization.
- The potential list of remaining argument strings. (same as argparse.ArgumentParser.parse_known_args)</retdesc></docstring>

Parse command-line args into instances of the specified dataclass types.

This relies on argparse's `ArgumentParser.parse_known_args`. See the doc at:
docs.python.org/3.7/library/argparse.html#argparse.ArgumentParser.parse_args








</div>
<div class="docstring">
<docstring><name>parse\_dict</name><anchor>transformers.HfArgumentParser.parse_dict</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/hf_argparser.py#L233</source><parameters>[{"name": "args", "val": ": dict"}]</parameters></docstring>

Alternative helper method that does not use `argparse` at all, instead uses a dict and populating the dataclass
types.


</div>
<div class="docstring">
<docstring><name>parse\_json\_file</name><anchor>transformers.HfArgumentParser.parse_json_file</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/hf_argparser.py#L219</source><parameters>[{"name": "json_file", "val": ": str"}]</parameters></docstring>

Alternative helper method that does not use `argparse` at all, instead loading a json file and populating the
dataclass types.


</div></div>

<h2 id="transformers.debug_utils.DebugUnderflowOverflow">Debug Utilities</h2>

<div class="docstring">

<docstring><name>class transformers.debug\_utils.DebugUnderflowOverflow</name><anchor>transformers.debug_utils.DebugUnderflowOverflow</anchor><source>https://github.com/huggingface/transformers/blob/pr_15592/src/transformers/debug_utils.py#L28</source><parameters>[{"name": "model", "val": ""}, {"name": "max_frames_to_save", "val": " = 21"}, {"name": "trace_batch_nums", "val": " = []"}, {"name": "abort_after_batch_num", "val": " = None"}]</parameters><paramsdesc>- **model** (`nn.Module`) --
  The model to debug.
- **max_frames_to_save** (`int`, *optional*, defaults to 21) --
  How many frames back to record
- **trace_batch_nums(`List[int]`,** *optional*, defaults to `[]`) --
  Which batch numbers to trace (turns detection off)
- **abort_after_batch_num**  (`int``, *optional*) --
  Whether to abort after a certain batch number has finished</paramsdesc><paramgroups>0</paramgroups></docstring>

This debug class helps detect and understand where the model starts getting very large or very small, and more
importantly `nan` or `inf` weight and activation elements.

There are 2 working modes:

1. Underflow/overflow detection (default)
2. Specific batch absolute min/max tracing without detection

Mode 1: Underflow/overflow detection

To activate the underflow/overflow detection, initialize the object with the model :

```python
debug_overflow = DebugUnderflowOverflow(model)
```

then run the training as normal and if `nan` or `inf` gets detected in at least one of the weight, input or output
elements this module will throw an exception and will print `max_frames_to_save` frames that lead to this event,
each frame reporting

1. the fully qualified module name plus the class name whose `forward` was run
2. the absolute min and max value of all elements for each module weights, and the inputs and output

For example, here is the header and the last few frames in detection report for `google/mt5-small` run in fp16
mixed precision :

```
Detected inf/nan during batch_number=0
Last 21 forward frames:
abs min  abs max  metadata
[...]
                  encoder.block.2.layer.1.DenseReluDense.wi_0 Linear
2.17e-07 4.50e+00 weight
1.79e-06 4.65e+00 input[0]
2.68e-06 3.70e+01 output
                  encoder.block.2.layer.1.DenseReluDense.wi_1 Linear
8.08e-07 2.66e+01 weight
1.79e-06 4.65e+00 input[0]
1.27e-04 2.37e+02 output
                  encoder.block.2.layer.1.DenseReluDense.wo Linear
1.01e-06 6.44e+00 weight
0.00e+00 9.74e+03 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.DenseReluDense T5DenseGatedGeluDense
1.79e-06 4.65e+00 input[0]
3.18e-04 6.27e+04 output
                  encoder.block.2.layer.1.dropout Dropout
3.18e-04 6.27e+04 input[0]
0.00e+00      inf output
```

You can see here, that `T5DenseGatedGeluDense.forward` resulted in output activations, whose absolute max value was
around 62.7K, which is very close to fp16's top limit of 64K. In the next frame we have `Dropout` which
renormalizes the weights, after it zeroed some of the elements, which pushes the absolute max value to more than
64K, and we get an overlow.

As you can see it's the previous frames that we need to look into when the numbers start going into very large for
fp16 numbers.

The tracking is done in a forward hook, which gets invoked immediately after `forward` has completed.

By default the last 21 frames are printed. You can change the default to adjust for your needs. For example :

```python
debug_overflow = DebugUnderflowOverflow(model, max_frames_to_save=100)
```

To validate that you have set up this debugging feature correctly, and you intend to use it in a training that
may take hours to complete, first run it with normal tracing enabled for one of a few batches as explained in
the next section.


Mode 2. Specific batch absolute min/max tracing without detection

The second work mode is per-batch tracing with the underflow/overflow detection feature turned off.

Let's say you want to watch the absolute min and max values for all the ingredients of each `forward` call of a
given batch, and only do that for batches 1 and 3. Then you instantiate this class as :

```python
debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3])
```

And now full batches 1 and 3 will be traced using the same format as explained above. Batches are 0-indexed.

This is helpful if you know that the program starts misbehaving after a certain batch number, so you can
fast-forward right to that area.


Early stopping:

You can also specify the batch number after which to stop the training, with :

```python
debug_overflow = DebugUnderflowOverflow(model, trace_batch_nums=[1, 3], abort_after_batch_num=3)
```

This feature is mainly useful in the tracing mode, but you can use it for any mode.


**Performance**:

As this module measures absolute `min`/``max` of each weight of the model on every forward it'll slow the training
down. Therefore remember to turn it off once the debugging needs have been met.




</div>
