# Utilitas untuk Trainer

Halaman ini mencantumkan semua fungsi utilitas yang digunakan oleh [Trainer](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.Trainer).

Sebagian besar dari itu hanya berguna jika Anda sedang mempelajari kode Trainer di pustaka tersebut.

## Utilitas[[transformers.EvalPrediction]]

#### transformers.EvalPrediction[[transformers.EvalPrediction]]

```python
transformers.EvalPrediction(predictions: numpy.ndarray | tuple[numpy.ndarray], label_ids: numpy.ndarray | tuple[numpy.ndarray], inputs: numpy.ndarray | tuple[numpy.ndarray] | None = None, losses: numpy.ndarray | tuple[numpy.ndarray] | None = None)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_utils.py#L210)

**Parameter:**

predictions (`np.ndarray`) : Prediksi dari model.

label_ids (`np.ndarray`) : Target yang akan dicocokkan.

inputs (`np.ndarray`, *opsional*) : Data input yang diteruskan ke model.

losses (`np.ndarray`, *opsional*) : Nilai loss yang dihitung selama evaluasi.

Output evaluasi (selalu berisi label), untuk digunakan dalam menghitung metrik.

#### transformers.IntervalStrategy[[transformers.IntervalStrategy]]

```python
transformers.IntervalStrategy(value, names = None, module = None, qualname = None, type = None, start = 1, boundary = None)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_utils.py#L389)

#### transformers.enable_full_determinism[[transformers.enable_full_determinism]]

```python
transformers.enable_full_determinism(seed: int, warn_only: bool = False)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_utils.py#L154)

Fungsi bantu untuk perilaku yang dapat direproduksi selama pelatihan terdistribusi. Lihat https://pytorch.org/docs/stable/notes/randomness.html untuk pytorch

#### transformers.set_seed[[transformers.set_seed]]

```python
transformers.set_seed(seed: int, deterministic: bool = False)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_utils.py#L180)

**Parameter:**

seed (`int`) : Seed yang akan disetel.

deterministic (`bool`, *opsional*, default `False`) : Apakah akan menggunakan algoritma deterministik jika tersedia. Dapat memperlambat proses pelatihan.

Fungsi bantu untuk perilaku yang dapat direproduksi guna mengatur seed di `random`, `numpy`, `torch` (jika terinstal).

#### transformers.torch_distributed_zero_first[[transformers.torch_distributed_zero_first]]

```python
transformers.torch_distributed_zero_first(local_rank: int)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_pt_utils.py#L309)

**Parameter:**

local_rank (`int`) : Rank dari proses lokal.

Decorator untuk membuat semua proses dalam pelatihan terdistribusi menunggu setiap local_master untuk melakukan sesuatu.

## Internal Callbacks[[transformers.trainer_callback.CallbackHandler]]

#### transformers.trainer_callback.CallbackHandler[[transformers.trainer_callback.CallbackHandler]]

```python
transformers.trainer_callback.CallbackHandler(callbacks, model, processing_class, optimizer, lr_scheduler)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/trainer_callback.py#L429)

Kelas internal yang hanya memanggil daftar callback secara berurutan.

## Parser Argumen Trainer[[transformers.HfArgumentParser]]

#### transformers.HfArgumentParser[[transformers.HfArgumentParser]]

```python
transformers.HfArgumentParser(dataclass_types: typing.Union[transformers.hf_argparser.DataClassType, collections.abc.Iterable[transformers.hf_argparser.DataClassType], NoneType] = None, **kwargs)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L111)

**Parameter:**

dataclass_types (`DataClassType` atau `Iterable[DataClassType]`, *opsional*) : Tipe dataclass, atau daftar tipe dataclass yang instansnya akan "diisi" dengan argumen yang telah diurai.

kwargs (`dict[str, Any]`, *opsional*) : Diteruskan ke `argparse.ArgumentParser()` dengan cara reguler.

Subkelas dari `argparse.ArgumentParser` ini menggunakan type hints pada dataclasses untuk menghasilkan argumen.

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.

#### parse_args_into_dataclasses[[transformers.HfArgumentParser.parse_args_into_dataclasses]]

```python
parse_args_into_dataclasses(args = None, return_remaining_strings = False, look_for_args_file = True, args_filename = None, args_file_flag = None)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L272)

**Parameter:**

args : Daftar string untuk diurai. Nilai default diambil dari sys.argv. (sama seperti argparse.ArgumentParser)

return_remaining_strings : Jika true, juga kembalikan daftar string argumen yang tersisa.

look_for_args_file : Jika true, akan mencari file ".args" dengan nama dasar yang sama dengan skrip entry point untuk proses ini, dan akan menambahkan konten potensialnya ke argumen baris perintah.

args_filename : Jika bukan None, akan menggunakan file ini alih-alih file ".args" yang ditentukan dalam argumen sebelumnya.

args_file_flag : Jika bukan None, akan mencari file dalam argumen baris perintah yang ditentukan dengan flag ini. Flag dapat ditentukan beberapa kali dan prioritas ditentukan berdasarkan urutan (yang terakhir menang).

**Mengembalikan:** `Tuple consisting of`

- instance dataclass dalam urutan yang sama seperti yang diteruskan ke inisialisator.
- jika berlaku, namespace tambahan untuk argumen (yang tidak didukung oleh dataclass) yang ditambahkan ke parser setelah inisialisasi.
- Daftar potensial string argumen yang tersisa. (sama seperti argparse.ArgumentParser.parse_known_args)

Parse argumen command-line menjadi instance dari tipe dataclass yang ditentukan.

Ini bergantung pada `ArgumentParser.parse_known_args` dari argparse. Lihat dokumentasi di: docs.python.org/3/library/argparse.html#argparse.ArgumentParser.parse_args

#### parse_dict[[transformers.HfArgumentParser.parse_dict]]

```python
parse_dict(args: dict[str, typing.Any], allow_extra_keys: bool = False)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L358)

**Parameter:**

args (`dict`) : dict yang berisi nilai konfigurasi

allow_extra_keys (`bool`, *opsional*, defaultnya `False`) : Defaultnya False. Jika False, akan melempar pengecualian jika dict berisi kunci yang tidak diurai.

**Mengembalikan:** `Tuple consisting of`

- instance dataclass dalam urutan yang sama seperti yang diteruskan ke inisialisator.

Metode bantu alternatif yang sama sekali tidak menggunakan `argparse`, melainkan menggunakan dict dan mengisi tipe dataclass.

#### parse_json_file[[transformers.HfArgumentParser.parse_json_file]]

```python
parse_json_file(json_file: str | os.PathLike, allow_extra_keys: bool = False)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L386)

**Parameter:**

json_file (`str` atau `os.PathLike`) : Nama file dari file json yang akan diurai

allow_extra_keys (`bool`, *opsional*, defaultnya `False`) : Defaultnya False. Jika False, akan melempar pengecualian jika file json berisi kunci yang tidak diurai.

**Mengembalikan:** `Tuple consisting of`

- instance dataclass dalam urutan yang sama seperti yang diteruskan ke inisialisator.

Metode bantu alternatif yang sama sekali tidak menggunakan `argparse`, melainkan memuat file json dan mengisi tipe dataclass.

#### parse_yaml_file[[transformers.HfArgumentParser.parse_yaml_file]]

```python
parse_yaml_file(yaml_file: str | os.PathLike, allow_extra_keys: bool = False)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/hf_argparser.py#L408)

**Parameter:**

yaml_file (`str` atau `os.PathLike`) : Nama file dari file yaml yang akan diurai

allow_extra_keys (`bool`, *opsional*, defaultnya `False`) : Defaultnya False. Jika False, akan melempar pengecualian jika file json berisi kunci yang tidak diurai.

**Mengembalikan:** `Tuple consisting of`

- instance dataclass dalam urutan yang sama seperti yang diteruskan ke inisialisator.

Metode bantu alternatif yang sama sekali tidak menggunakan `argparse`, melainkan memuat file yaml dan mengisi tipe dataclass.

## Utilitas Debug[[transformers.debug_utils.DebugUnderflowOverflow]]

#### transformers.debug_utils.DebugUnderflowOverflow[[transformers.debug_utils.DebugUnderflowOverflow]]

```python
transformers.debug_utils.DebugUnderflowOverflow(model, max_frames_to_save = 21, trace_batch_nums = None, abort_after_batch_num = None)
```

[Sumber](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/debug_utils.py#L27)

**Parameter:**

model (`nn.Module`) : Model yang akan di-debug.

max_frames_to_save (`int`, *opsional*, default 21) : Berapa banyak frame ke belakang yang akan direkam

trace_batch_nums(`list[int]`, *opsional*, default `[]`) : Nomor batch mana yang akan ditrace (mematikan deteksi)

abort_after_batch_num  (`int``, *opsional*) : Apakah akan dihentikan setelah nomor batch tertentu selesai

Kelas debug ini membantu mendeteksi dan memahami di mana model mulai memiliki nilai yang sangat besar atau sangat kecil, dan yang lebih penting, elemen bobot dan aktivasi berupa `nan` atau `inf`.

Terdapat 2 mode kerja:

1. Deteksi underflow/overflow (default)
2. Pelacakan min/maks absolut batch tertentu tanpa deteksi

Mode 1: Deteksi underflow/overflow

Untuk mengaktifkan deteksi underflow/overflow, inisialisasi objek dengan model:

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

lalu jalankan pelatihan seperti biasa, dan jika `nan` atau `inf` terdeteksi pada setidaknya satu elemen bobot, input, atau output, modul ini akan melempar pengecualian dan mencetak `max_frames_to_save` frame yang menyebabkan kejadian ini, dengan setiap frame melaporkan

1. nama modul yang sepenuhnya memenuhi syarat ditambah nama kelas yang `forward`-nya dijalankan
2. nilai min dan max absolut dari semua elemen untuk setiap bobot modul, serta input dan output

Sebagai contoh, berikut adalah header dan beberapa frame terakhir dalam laporan deteksi untuk `google/mt5-small` yang dijalankan dalam fp16

presisi campuran :

```
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
```

Di sini dapat dilihat bahwa `T5DenseGatedGeluDense.forward` menghasilkan aktivasi output, di mana nilai absolut maksimumnya sekitar 62,7K, yang sangat mendekati batas atas fp16 sebesar 64K. Pada frame berikutnya terdapat `Dropout` yang menormalisasi ulang bobot setelah menolkan beberapa elemen, sehingga mendorong nilai absolut maksimum melebihi 64K, dan terjadi overflow.

Seperti yang dapat Anda lihat, frame sebelumnya adalah yang perlu kita periksa ketika angka mulai menjadi sangat besar untuk angka fp16.

Pelacakan dilakukan dalam hook maju, yang dipanggil segera setelah `forward` selesai.

Secara default, 21 frame terakhir yang dicetak. Anda dapat mengubah default ini untuk menyesuaikan dengan kebutuhan Anda. Sebagai contoh:

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

Untuk memvalidasi bahwa Anda telah mengatur fitur debugging ini dengan benar, dan Anda bermaksud menggunakannya dalam pelatihan yang mungkin memakan waktu berjam-jam untuk diselesaikan, pertama jalankan dengan tracing normal yang diaktifkan untuk beberapa batch, seperti yang dijelaskan di bagian berikutnya.

Mode 2. Pelacakan min/maks absolut batch tertentu tanpa deteksi

Mode kerja kedua adalah pelacakan per-batch dengan fitur deteksi underflow/overflow dimatikan.

Misalnya, Anda ingin memantau nilai minimum dan maksimum absolut untuk semua bahan dari setiap panggilan `forward` dari

batch yang diberikan, dan hanya lakukan itu untuk batch 1 dan 3. Kemudian Anda menginstansiasi kelas ini sebagai :

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

Dan sekarang batch penuh 1 dan 3 akan ditelusuri menggunakan format yang sama seperti yang dijelaskan di atas. Batch menggunakan indeks 0.

Hal ini sangat membantu jika Anda tahu bahwa program mulai berperilaku tidak normal setelah nomor batch tertentu, sehingga Anda dapat langsung melompat ke area tersebut.

Penghentian dini:

Anda juga dapat menentukan nomor batch setelah mana pelatihan akan dihentikan, dengan:

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

Fitur ini terutama berguna dalam mode tracing, tetapi Anda dapat menggunakannya untuk mode apa pun.

**Kinerja**:

Karena modul ini mengukur `min`/``max` absolut dari setiap bobot model pada setiap forward, proses pelatihan akan melambat. Oleh karena itu, ingatlah untuk mematikannya setelah kebutuhan debugging terpenuhi.