# Debugging

Masalah pelatihan terdistribusi yang di-debug biasanya masuk ke salah satu kategori berikut: masalah numerik, kegagalan komunikasi, error runtime, dan error build.

## Deteksi underflow dan overflow

Underflow dan overflow terjadi ketika aktivasi atau bobot mencapai `inf` atau `nan`, atau ketika `loss=NaN`. Untuk mendeteksi hal ini, aktifkan modul `DebugUnderflowOverflow` di `TrainingArguments.debug()`, atau impor dan tambahkan ke loop pelatihan Anda sendiri.

```py
from transformers import TrainingArguments

args = TrainingArguments(
    debug="underflow_overflow",
    ...
)
```

```py
from transformers.debug_utils import DebugUnderflowOverflow

debug_overflow = DebugUnderflowOverflow(model)
```

[DebugUnderflowOverflow](/docs/transformers/v5.23.0/id/internal/trainer_utils#transformers.debug_utils.DebugUnderflowOverflow) menyisipkan hook ke dalam model untuk menguji variabel input dan output serta bobot model yang bersesuaian setelah setiap pemanggilan forward. Ketika `inf` atau `nan` terdeteksi pada setidaknya satu elemen dari aktivasi atau bobot, modul tersebut mencetak laporan seperti di bawah ini.

Contoh di bawah ini adalah untuk pelatihan presisi campuran fp16 dengan [google/mt5-small](https://huggingface.co/google/mt5-small).

```shell
Detected inf/nan during batch_number=0
Last 21 forward frames:
abs min  abs max  metadata
                  encoder.block.1.layer.1.DenseReluDense.dropout Dropout
0.00e+00 2.57e+02 input[0]
0.00e+00 2.85e+02 output
[...]
                  encoder.block.2.layer.0 T5LayerSelfAttention
6.78e-04 3.15e+03 input[0]
2.65e-04 3.42e+03 output[0]
             None output[1]
2.25e-01 1.00e+04 output[2]
                  encoder.block.2.layer.1.layer_norm T5LayerNorm
8.69e-02 4.18e-01 weight
2.65e-04 3.42e+03 input[0]
1.79e-06 4.65e+00 output
                  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.dropout Dropout
0.00e+00 8.76e+03 input[0]
0.00e+00 9.74e+03 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
```

Baris pertama menunjukkan nomor batch tempat kesalahan terjadi. Dalam kasus ini, kesalahan terjadi pada batch 0.

Setiap frame menggambarkan modul yang dilaporkan. Sebagai contoh, frame di bawah ini melaporkan tentang `encoder.block.2.layer.1.layer_norm`, yaitu layer norm pada layer pertama dari blok kedua encoder. Panggilan forward adalah ke `T5LayerNorm`.

```shell
                  encoder.block.2.layer.1.layer_norm T5LayerNorm
8.69e-02 4.18e-01 weight
2.65e-04 3.42e+03 input[0]
1.79e-06 4.65e+00 output
```

Frame terakhir melaporkan fungsi `Dropout.forward`, yang memanggil atribut `dropout` di dalam kelas `DenseReluDense`. Overflow (`inf`) terjadi pada blok kedua encoder di batch pertama. Elemen input terbesar adalah 6.27e+04.

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

Aktivasi keluaran `T5DenseGatedGeluDense.forward` mencapai maksimum 6.27e+04, yang mendekati maksimum fp16 sebesar 6.4e+04. Pada langkah berikutnya, `Dropout` menormalisasi ulang bobot setelah menolkan beberapa elemen, sehingga mendorong nilai maksimum melewati 6.4e+04 dan menyebabkan overflow.

Sekarang Anda sudah tahu di mana kesalahan terjadi, periksa kode pemodelan di [modeling_t5.py](https://github.com/huggingface/transformers/blob/main/src/transformers/models/t5/modeling_t5.py).

```py
class T5DenseGatedGeluDense(nn.Module):
    def __init__(self, config):
        super().__init__()
        self.wi_0 = nn.Linear(config.d_model, config.d_ff, bias=False)
        self.wi_1 = nn.Linear(config.d_model, config.d_ff, bias=False)
        self.wo = nn.Linear(config.d_ff, config.d_model, bias=False)
        self.dropout = nn.Dropout(config.dropout_rate)
        self.gelu_act = ACT2FN["gelu_new"]

    def forward(self, hidden_states):
        hidden_gelu = self.gelu_act(self.wi_0(hidden_states))
        hidden_linear = self.wi_1(hidden_states)
        hidden_states = hidden_gelu * hidden_linear
        hidden_states = self.dropout(hidden_states)
        hidden_states = self.wo(hidden_states)
        return hidden_states
```

Salah satu solusinya adalah beralih ke fp32 beberapa langkah sebelum nilai menjadi terlalu besar, sehingga angka tidak meluap saat dikalikan atau dijumlahkan. Opsi lain adalah menonaktifkan pelatihan presisi campuran (`amp`) secara sementara.

```py
import torch

def forward(self, hidden_states):
    device_type = hidden_states.device.type
    if torch.is_autocast_enabled(device_type):
        with torch.amp.autocast(device_type, enabled=False):
            return self._forward(hidden_states)
    else:
        return self._forward(hidden_states)
```

Laporan ini hanya mencakup input dan output dari frame penuh. Untuk menganalisis nilai perantara di dalam fungsi `forward` mana pun, tambahkan `detect_overflow` setelah setiap panggilan forward untuk melacak `inf` atau `nan` di `forwarded_states`.

```py
from transformers.debug_utils import detect_overflow

class T5LayerFF(nn.Module):
    [...]

    def forward(self, hidden_states):
        forwarded_states = self.layer_norm(hidden_states)
        detect_overflow(forwarded_states, "after layer_norm")
        forwarded_states = self.DenseReluDense(forwarded_states)
        detect_overflow(forwarded_states, "after DenseReluDense")
        return hidden_states + self.dropout(forwarded_states)
```

Konfigurasikan jumlah frame yang dicetak oleh [DebugUnderflowOverflow](/docs/transformers/v5.23.0/id/internal/trainer_utils#transformers.debug_utils.DebugUnderflowOverflow).

```py
from transformers.debug_utils import DebugUnderflowOverflow

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

### Pelacakan batch

[DebugUnderflowOverflow](/docs/transformers/v5.23.0/id/internal/trainer_utils#transformers.debug_utils.DebugUnderflowOverflow) juga dapat melacak nilai minimum dan maksimum absolut di setiap batch dengan deteksi underflow dan overflow dinonaktifkan. Hal ini membantu Anda menemukan di mana nilai mulai menyimpang dalam model Anda.

Contoh di bawah ini menelusuri batch 1 dan 3 (batch menggunakan indeks nol).

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

```shell
                  *** Starting batch number=1 ***
abs min  abs max  metadata
                  shared Embedding
1.01e-06 7.92e+02 weight
0.00e+00 2.47e+04 input[0]
5.36e-05 7.92e+02 output
[...]
                  decoder.dropout Dropout
1.60e-07 2.27e+01 input[0]
0.00e+00 2.52e+01 output
                  decoder T5Stack
     not a tensor output
                  lm_head Linear
1.01e-06 7.92e+02 weight
0.00e+00 1.11e+00 input[0]
6.06e-02 8.39e+01 output
                   T5ForConditionalGeneration
     not a tensor output

                  *** Starting batch number=3 ***
abs min  abs max  metadata
                  shared Embedding
1.01e-06 7.92e+02 weight
0.00e+00 2.78e+04 input[0]
5.36e-05 7.92e+02 output
[...]
```

[DebugUnderflowOverflow](/docs/transformers/v5.23.0/id/internal/trainer_utils#transformers.debug_utils.DebugUnderflowOverflow) melaporkan banyak frame, yang memudahkan Anda menemukan di mana nilai mulai menyimpang. Jika Anda tahu masalahnya berada di sekitar batch 150, fokuskan trace pada batch 149 dan 150 untuk membandingkan di mana angka mulai berbeda.

Anda juga dapat menghentikan trace setelah nomor batch tertentu, misalnya batch 3.

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

## Komunikasi

Pelatihan terdistribusi memerlukan komunikasi antar-proses dan antar-node, yang merupakan sumber kesalahan yang umum.

Unduh skrip di bawah untuk mendiagnosis masalah jaringan, lalu jalankan untuk menguji komunikasi GPU. Perintah di bawah menguji dua GPU. Sesuaikan `--nproc_per_node` dan `--nnodes` untuk sistem Anda.

```bash
wget https://raw.githubusercontent.com/huggingface/transformers/main/scripts/distributed/torch-distributed-gpu-test.py
python -m torch.distributed.run --nproc_per_node 2 --nnodes 1 torch-distributed-gpu-test.py
```

Skrip mencetak `OK` jika kedua GPU berkomunikasi dan mengalokasikan memori dengan sukses. Lihat skrip diagnostik untuk detail lebih lanjut dan resep untuk menjalankannya di lingkungan SLURM.

Setel `NCCL_DEBUG=INFO` untuk mendapatkan output debugging NCCL yang detail.

```bash
NCCL_DEBUG=INFO python -m torch.distributed.run --nproc_per_node 2 --nnodes 1 torch-distributed-gpu-test.py
```

## DeepSpeed

Saat Anda menemui error, periksa terlebih dahulu apakah DeepSpeed adalah penyebabnya. Ulangi setup Anda tanpa DeepSpeed, dan jika error tetap terjadi, laporkan masalah tersebut. Untuk masalah yang tidak terkait dengan integrasi Transformers, buka issue di [repository](https://github.com/microsoft/DeepSpeed) DeepSpeed.

Untuk masalah yang terkait dengan integrasi Transformers, sertakan informasi berikut.

* File konfigurasi DeepSpeed lengkap.
* Argumen baris perintah untuk [Trainer](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.Trainer) atau [TrainingArguments](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.TrainingArguments) jika Anda mengonfigurasi [Trainer](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.Trainer) sendiri melalui skrip (jangan menyalin seluruh [TrainingArguments](/docs/transformers/v5.23.0/id/main_classes/trainer#transformers.TrainingArguments) yang berisi banyak entri yang tidak relevan).
* Hasil keluaran dari perintah-perintah ini.

    ```bash
    python -c 'import torch; print(f"torch: {torch.__version__}")'
    python -c 'import transformers; print(f"transformers: {transformers.__version__}")'
    python -c 'import deepspeed; print(f"deepspeed: {deepspeed.__version__}")'
    ```

* Tautan ke notebook Google Colab untuk mereproduksi masalah tersebut.
* Dataset standar atau non-kustom, atau contoh yang sudah ada untuk mereproduksi masalah tersebut.

### Proses dihentikan saat startup

Jika proses DeepSpeed dihentikan saat peluncuran tanpa traceback, program tersebut mencoba mengalokasikan memori CPU lebih banyak daripada yang tersedia atau diizinkan. Kernel OS akan mengakhiri proses dalam kedua kasus tersebut.

Periksa apakah file konfigurasi Anda memiliki `offload_optimizer`, `offload_param`, atau keduanya yang dikonfigurasi untuk offload ke CPU.

Jika Anda telah menyiapkan NVMe dan ZeRO-3, coba offload ke NVMe. [Perkirakan](https://deepspeed.readthedocs.io/en/latest/memory.html) kebutuhan memori model Anda terlebih dahulu.

### Loss NaN

Loss NaN sering terjadi ketika model dipretrain dalam bf16 dan kemudian digunakan dengan fp16 (hal ini terutama umum pada model yang dilatih dengan TPU). Gunakan fp32 atau bf16 jika perangkat keras Anda mendukungnya (TPU, GPU Ampere atau yang lebih baru).

fp16 juga dapat menyebabkan overflow. Jika file konfigurasi Anda terlihat seperti di bawah ini, Anda mungkin akan melihat error overflow di log.

```json
{
    "fp16": {
        "enabled": "auto",
        "loss_scale": 0,
        "loss_scale_window": 1000,
        "initial_scale_power": 16,
        "hysteresis": 2,
        "min_loss_scale": 1
    }
}
```

Error `OVERFLOW!` di bawah ini berarti loss scaler DeepSpeed tidak dapat menemukan koefisien penskalaan untuk mengatasi overflow loss. Coba gunakan nilai `initial_scale_power` yang lebih tinggi (32 biasanya berhasil).

```bash
0%|                                                                                                                             | 0/189 [00:00<?, ?it/s]
 [deepscale] OVERFLOW! Rank 0 Skipping step. Attempted loss scale: 262144, reducing to 262144
  1%|▌                                                                                                                    | 1/189 [00:00<01:26,  2.17it/s]
 [deepscale] OVERFLOW! Rank 0 Skipping step. Attempted loss scale: 262144, reducing to 131072.0
  1%|█▏
 [...]
 [deepscale] OVERFLOW! Rank 0 Skipping step. Attempted loss scale: 1, reducing to 1
 14%|████████████████▌                                                                                                   | 27/189 [00:14<01:13,  2.21it/s]
 [deepscale] OVERFLOW! Rank 0 Skipping step. Attempted loss scale: 1, reducing to 1
 15%|█████████████████▏                                                                                                  | 28/189 [00:14<01:13,  2.18it/s]
 [deepscale] OVERFLOW! Rank 0 Skipping step. Attempted loss scale: 1, reducing to 1
 15%|█████████████████▊                                                                                                  | 29/189 [00:15<01:13,  2.18it/s]
 [deepscale] OVERFLOW! Rank 0 Skipping step. Attempted loss scale: 1, reducing to 1
[...]
```

## DeepSpeed CUDA

DeepSpeed mengompilasi kode CUDA C++, yang merupakan sumber umum kesalahan build untuk ekstensi PyTorch yang memerlukan CUDA. Kesalahan ini bergantung pada cara CUDA diinstal di sistem Anda.

```bash
pip install deepspeed
```

> [!TIP]
> Untuk masalah instalasi lainnya, [buka issue](https://github.com/microsoft/DeepSpeed/issues) dengan tim DeepSpeed.

### Toolkit yang tidak identik

PyTorch dilengkapi dengan toolkit CUDA-nya sendiri, tetapi DeepSpeed memerlukan versi CUDA yang identik terpasang di seluruh sistem. Jika Anda menginstal PyTorch dengan `cudatoolkit==10.2` di lingkungan Python Anda, Anda juga perlu menginstal CUDA 10.2 di semua tempat.

Lokasi pastinya bervariasi tergantung sistem, tetapi `/usr/local/cuda-10.2` adalah jalur yang paling umum pada sistem Unix. Setelah CUDA diinstal dan ditambahkan ke `PATH` Anda, temukan lokasi instalasinya dengan perintah ini.

```bash
which nvcc
```

### Beberapa toolkit

Sistem Anda mungkin memiliki lebih dari satu toolkit CUDA yang terinstal.

```text
/usr/local/cuda-10.2
/usr/local/cuda-11.0
```

Pemasang paket biasanya mengatur path ke versi yang terakhir diinstal. Jika build gagal karena tidak dapat menemukan versi CUDA yang tepat, konfigurasikan `PATH` dan `LD_LIBRARY_PATH` agar menunjuk ke path yang benar.

Periksa variabel lingkungan ini terlebih dahulu.

```bash
echo $PATH
echo $LD_LIBRARY_PATH
```

`PATH` mencantumkan lokasi file yang dapat dieksekusi. `LD_LIBRARY_PATH` mencantumkan lokasi pustaka bersama. Entri yang lebih awal memiliki prioritas lebih tinggi, dan `:` memisahkan beberapa entri. Tambahkan jalur CUDA yang benar di awal untuk memberikannya prioritas.

```bash
# adjust the version and full path if needed
export PATH=/usr/local/cuda-10.2/bin:$PATH
export LD_LIBRARY_PATH=/usr/local/cuda-10.2/lib64:$LD_LIBRARY_PATH
```

Juga periksa apakah direktori yang ditugaskan ada. Sub-direktori `lib64` berisi objek CUDA `.so` seperti `libcudart.so`. Periksa nama file yang sebenarnya dan perbarui sesuai kebutuhan.

### Versi yang lebih lama

Versi CUDA yang lebih lama terkadang memerlukan versi compiler yang lebih lama. Misalnya, jika CUDA membutuhkan `gcc-7` tetapi sistem Anda hanya memiliki `gcc-9`, proses build akan gagal. Instal compiler versi lama yang diperlukan dan buat symlink agar sistem build CUDA dapat menemukannya.

```bash
# adjust the path to your system
sudo ln -s /usr/bin/gcc-7  /usr/local/cuda-10.2/bin/gcc
sudo ln -s /usr/bin/g++-7  /usr/local/cuda-10.2/bin/g++
```

### Prebuild

Jika Anda masih mengalami kesulitan menginstal DeepSpeed atau membangunnya saat runtime, bangun modul DeepSpeed terlebih dahulu. Jalankan perintah di bawah ini untuk build lokal.

```bash
git clone https://github.com/deepspeedai/DeepSpeed/
cd DeepSpeed
rm -rf build
TORCH_CUDA_ARCH_LIST="8.6" DS_BUILD_CPU_ADAM=1 DS_BUILD_UTILS=1 pip install . \
--global-option="build_ext" --global-option="-j8" --no-cache -v \
--disable-pip-version-check 2>&1 | tee build.log
```

> [!TIP]
> Tambahkan `DS_BUILD_AIO=1` ke perintah build untuk menggunakan NVMe offload. Pastikan Anda menginstal paket libaio-dev secara sistem.

Selanjutnya, atur arsitektur GPU Anda di `TORCH_CUDA_ARCH_LIST`. Daftar lengkap GPU NVIDIA beserta arsitekturnya tersedia di [halaman CUDA GPUs](https://developer.nvidia.com/cuda-gpus). Untuk memeriksa versi PyTorch yang sesuai dengan arsitektur Anda, jalankan perintah di bawah ini.

```bash
python -c "import torch; print(torch.cuda.get_arch_list())"
```

Temukan arsitektur untuk GPU dengan perintah berikut.

```bash
CUDA_VISIBLE_DEVICES=0 python -c "import torch; print(torch.cuda.get_device_capability())"
```

Jalankan perintah berikut untuk menemukan arsitektur GPU `0`. Output menampilkan nilai `major` dan `minor` yang bersama-sama membentuk arsitektur GPU. Contoh di bawah ini menunjukkan arsitektur `8.6`.

```bash
CUDA_VISIBLE_DEVICES=0 python -c "import torch; \
print(torch.cuda.get_device_properties(torch.device('cuda')))
"_CudaDeviceProperties(name='GeForce RTX 3090', major=8, minor=6, total_memory=24268MB, multi_processor_count=82)"
```

Untuk hasil `8, 6`, atur `TORCH_CUDA_ARCH_LIST="8.6"`. Untuk beberapa GPU dengan arsitektur yang berbeda, daftarkan seperti `TORCH_CUDA_ARCH_LIST="6.1;8.6"`.

Anda dapat mengabaikan `TORCH_CUDA_ARCH_LIST` dan membiarkan program build mendeteksi arsitektur GPU secara otomatis, tetapi hasilnya mungkin tidak sesuai dengan GPU aktual pada mesin target. Menetapkan arsitektur secara eksplisit lebih andal.

Untuk pelatihan di beberapa mesin dengan konfigurasi yang sama, bangun binary wheel.

```bash
git clone https://github.com/deepspeedai/DeepSpeed/
cd DeepSpeed
rm -rf build
TORCH_CUDA_ARCH_LIST="8.6" DS_BUILD_CPU_ADAM=1 DS_BUILD_UTILS=1 \
python setup.py build_ext -j8 bdist_wheel
```

Ini menghasilkan binary wheel seperti `dist/deepspeed-0.3.13+8cd046f-cp38-cp38-linux_x86_64.whl`. Instal secara lokal atau di mesin lain.

```bash
pip install deepspeed-0.3.13+8cd046f-cp38-cp38-linux_x86_64.whl
```

