# Kotak perkakas untuk debugging model

Halaman ini mencantumkan semua alat debugging dan penambahan model yang digunakan oleh pustaka, serta fungsi utilitas yang disediakan untuknya.

Sebagian besar dari hal tersebut hanya berguna jika Anda menambahkan model baru ke dalam pustaka.

## Debugger penambahan model

### Debugger penambahan model - context manager untuk penambah model

Context manager ini adalah alat untuk pengguna tingkat lanjut yang ditujukan bagi pengembang model. Alat ini melacak semua pemanggilan forward di dalam forward model dan mencatat potongan dari setiap input dan output ke dalam JSON bersarang. Perlu dicatat bahwa context manager ini memaksa penggunaan `torch.no_grad()`.

### Rasional

Saat memindahkan model ke Transformers, bahkan dari Python ke Python, pengembang model sering kali harus melakukan banyak operasi manual, seperti menyimpan dan memuat tensor, membandingkan dtype, dan sebagainya. Alat kecil ini diharapkan dapat memangkas sebagian waktu tersebut.

### Penggunaan

Tambahkan context manager ini sebagai berikut untuk men-debug model:

```python
import torch
from PIL import Image
import requests
from transformers import LlavaProcessor, LlavaForConditionalGeneration
from transformers.model_debugging_utils import model_addition_debugger_context
torch.random.manual_seed(673)

# load pretrained model and processor
model_id = "llava-hf/llava-1.5-7b-hf"
processor = LlavaProcessor.from_pretrained(model_id)
model = LlavaForConditionalGeneration.from_pretrained(model_id)

# create random image input
random_image = Image.fromarray(torch.randint(0, 256, (224, 224, 3), dtype=torch.uint8).numpy())

# prompt
prompt = "<image>Describe this image."

# process inputs
inputs = processor(text=prompt, images=random_image, return_tensors="pt")

# call forward method (not .generate!)
with model_addition_debugger_context(
    model,
    debug_path="optional_path_to_your_directory",
    do_prune_layers=False # This will output ALL the layers of a model.
):
    output = model.forward(**inputs)

```

### Membaca hasil

Debugger menghasilkan dua file dari panggilan forward, keduanya dengan nama dasar yang sama, tetapi diakhiri dengan `_SUMMARY.json` atau `_FULL_TENSORS.json`.

Yang pertama akan berisi ringkasan nilai dan bentuk tensor _input_ dan _output_ dari setiap modul.

```json
{
  "module_path": "MolmoForConditionalGeneration",
  "inputs": {
    "args": [],
    "kwargs": {
      "input_ids": {
        "shape": "torch.Size([1, 589])",
        "dtype": "torch.int64"
      },
      "attention_mask": {
        "shape": "torch.Size([1, 589])",
        "dtype": "torch.int64"
      },
      "pixel_values": {
        "shape": "torch.Size([1, 5, 576, 588])",
        "dtype": "torch.float32",
        "mean": "tensor(-8.9514e-01, device='cuda:0')",
        "std": "tensor(9.2586e-01, device='cuda:0')",
        "min": "tensor(-1.7923e+00, device='cuda:0')",
        "max": "tensor(1.8899e+00, device='cuda:0')"
    }
  },
  "children": [
    {
      "module_path": "MolmoForConditionalGeneration.language_model.model.embed_tokens",
      "inputs": {
        "args": [
          {
            "shape": "torch.Size([1, 589])",
            "dtype": "torch.int64"
          }
        ]
      },
      "outputs": {
        "shape": "torch.Size([1, 589, 3584])",
        "dtype": "torch.float32",
        "mean": "tensor(6.5460e-06, device='cuda:0')",
        "std": "tensor(2.3807e-02, device='cuda:0')",
        "min": "tensor(-3.3398e-01, device='cuda:0')",
        "max": "tensor(3.9453e-01, device='cuda:0')"
      }
    },
    {
      "module_path": "MolmoForConditionalGeneration.vision_tower",
      "inputs": {
        "args": [
          {
            "shape": "torch.Size([5, 1, 576, 588])",
            "dtype": "torch.float32",
            "mean": "tensor(-8.9514e-01, device='cuda:0')",
            "std": "tensor(9.2586e-01, device='cuda:0')",
            "min": "tensor(-1.7923e+00, device='cuda:0')",
            "max": "tensor(1.8899e+00, device='cuda:0')"
          }
        ],
        "kwargs": {
          "output_hidden_states": "True"
        }
      },
      "children": [
        { ... and so on
```

File `_FULL_TENSORS.json` akan menampilkan tampilan lengkap dari semua tensor, yang berguna untuk membandingkan dua file.

```json
      "pixel_values": {
        "shape": "torch.Size([1, 5, 576, 588])",
        "dtype": "torch.float32",
        "value": [
          "tensor([[[[-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          ...,",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00]],",
          "",
          "         [[-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          ...,",
          "          [-1.4857e+00, -1.4820e+00, -1.2100e+00,  ..., -6.0979e-01, -5.9650e-01, -3.8527e-01],",
          "          [-1.6755e+00, -1.7221e+00, -1.4518e+00,  ..., -7.5577e-01, -7.4658e-01, -5.5592e-01],",
          "          [-7.9957e-01, -8.2162e-01, -5.7014e-01,  ..., -1.3689e+00, -1.3169e+00, -1.0678e+00]],",
          "",
          "         [[-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          ...,",
          "          [-3.0322e-01, -5.0645e-01, -5.8436e-01,  ..., -6.2439e-01, -7.9160e-01, -8.1188e-01],",
          "          [-4.4921e-01, -6.5653e-01, -7.2656e-01,  ..., -3.4702e-01, -5.2146e-01, -5.1326e-01],",
          "          [-3.4702e-01, -5.3647e-01, -5.4170e-01,  ..., -1.0915e+00, -1.1968e+00, -1.0252e+00]],",
          "",
          "         [[-1.1207e+00, -1.2718e+00, -1.0678e+00,  ..., 1.2013e-01, -1.3126e-01, -1.7197e-01],",
          "          [-6.9738e-01, -9.1166e-01, -8.5454e-01,  ..., -5.5050e-02, -2.8134e-01, -4.2793e-01],",
          "          [-3.4702e-01, -5.5148e-01, -5.8436e-01,  ..., 1.9312e-01, -8.6235e-02, -2.1463e-01],",
          "          ...,",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00]],",
          "",
          "         [[-1.0039e+00, -9.5669e-01, -6.5546e-01,  ..., -1.4711e+00, -1.4219e+00, -1.1389e+00],",
          "          [-1.0039e+00, -9.5669e-01, -6.5546e-01,  ..., -1.7193e+00, -1.6771e+00, -1.4091e+00],",
          "          [-1.6317e+00, -1.6020e+00, -1.2669e+00,  ..., -1.2667e+00, -1.2268e+00, -8.9720e-01],",
          "          ...,",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00],",
          "          [-1.7923e+00, -1.7521e+00, -1.4802e+00,  ..., -1.7923e+00, -1.7521e+00, -1.4802e+00]]]], device='cuda:0')"
        ],
        "mean": "tensor(-8.9514e-01, device='cuda:0')",
        "std": "tensor(9.2586e-01, device='cuda:0')",
        "min": "tensor(-1.7923e+00, device='cuda:0')",
        "max": "tensor(1.8899e+00, device='cuda:0')"
      },
```

#### Menyimpan tensor ke disk

Beberapa pengembang model mungkin diuntungkan dengan pencatatan nilai tensor penuh ke disk untuk mendukung, misalnya, analisis numerik di antara berbagai implementasi.

Setel `use_repr=False` untuk menulis tensor ke disk menggunakan [SafeTensors](https://huggingface.co/docs/safetensors/en/index).

```python
with model_addition_debugger_context(
    model,
    debug_path="optional_path_to_your_directory",
    do_prune_layers=False,
    use_repr=False,   # Defaults to True
):
    output = model.forward(**inputs)
```

Saat menggunakan `use_repr=False`, tensor ditulis ke lokasi disk yang sama dengan file `_SUMMARY.json` dan `_FULL_TENSORS.json`. Properti `value` dari entri dalam file `_FULL_TENSORS.json` akan berisi referensi jalur relatif ke file `.safetensors` yang terkait. Setiap tensor ditulis ke file miliknya sendiri sebagai properti `data` dari state dictionary. Nama file dibangun menggunakan `module_path` sebagai prefiks dengan beberapa kemungkinan sufiks yang dibangun secara rekursif.

* Input modul ditandai dengan `_inputs` dan output dengan `_outputs`.
* Instans `list` dan `tuple`, seperti `args` atau nilai pengembalian fungsi, akan diberi akhiran `_{index}`.
* Instans `dict` akan diberi akhiran `_{key}`.

### Membandingkan antar implementasi

Setelah forward pass dari dua model ditelusuri oleh debugger, file output `json` dapat dibandingkan. Perhatikan di bawah: kita dapat melihat perbedaan kecil pada lapisan proyeksi key dari kedua implementasi ini. Inputnya sebagian besar identik, tetapi tidak sepenuhnya. Menelusuri perbedaan dalam file memudahkan penentuan lapisan mana yang salah.

![download-icon](https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/transformers/files_difference_debugging.png)

### Batasan dan cakupan[[transformers.model_addition_debugger_context]]

Fitur ini hanya akan berfungsi untuk model berbasis torch. Model yang sangat bergantung pada panggilan kernel eksternal mungkin tetap dapat berfungsi, tetapi trace kemungkinan akan melewatkan beberapa hal. Terlepas dari hal tersebut, implementasi python mana pun yang bertujuan meniru implementasi lain dapat ditrace sekali alih-alih dijalankan ulang N kali dengan breakpoint.

Jika Anda meneruskan `do_prune_layers=False` ke model debugger Anda, SEMUA layer akan dioutput ke `json`. Sebaliknya, hanya layer pertama dan terakhir yang akan ditampilkan. Hal ini berguna ketika beberapa layer (biasanya cross-attention) hanya muncul setelah N layer.

#### transformers.model_addition_debugger_context[[transformers.model_addition_debugger_context]]

```python
transformers.model_addition_debugger_context(model, debug_path: str | None = None, do_prune_layers: bool = True, use_repr: bool = True)
```

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

# Debugger penambahan model - context manager untuk penambah model
Context manager ini adalah alat untuk pengguna lanjutan yang ditujukan bagi pengembang model.

It melacak semua panggilan forward di dalam forward model dan mencatat potongan dari setiap input dan output ke dalam file JSON bersarang. Jika `use_repr=True` (default), file JSON akan mencatat versi `repr()`-ized dari tensor sebagai daftar string. Jika `use_repr=False`, tensor penuh akan disimpan dalam file SafeTensors terpisah dan file JSON akan menyediakan path relatif ke file tersebut.

Perlu dicatat, context manager ini menerapkan `torch.no_grad()`.

## Penggunaan

tambahkan context manager ke model untuk debug

```python
import torch

from PIL import Image
from transformers import LlavaProcessor, LlavaForConditionalGeneration, model_addition_debugger_context

torch.random.manual_seed(673)

# load pretrained model and processor
model_id = "llava-hf/llava-1.5-7b-hf"
processor = LlavaProcessor.from_pretrained(model_id)
model = LlavaForConditionalGeneration.from_pretrained(model_id)

# create random image input
random_image = Image.fromarray(torch.randint(0, 256, (224, 224, 3), dtype=torch.uint8).numpy())

# prompt
prompt = "<image>Describe this image."

# process inputs
inputs = processor(text=prompt, images=random_image, return_tensors="pt")

# call forward method (not .generate!)
with model_addition_debugger_context(model, debug_path="Your_debug_path", do_prune_layers=False):
    output = model.forward(**inputs)
```

## Analyzer dari tes yang dilewati

### Pindai tes yang dilewati - untuk penambah dan pemelihara model

Util kecil ini adalah alat untuk pengguna tingkat lanjut yang ditujukan bagi pihak yang menambahkan dan memelihara model. Util ini mendaftar semua metode uji yang ada di `test_modeling_common.py`, yang diwarisi oleh semua kelas pengujian model, dan memindai repositori untuk mengukur berapa banyak uji yang dilewati serta untuk model mana saja.

### Rasional

Saat memindahkan model ke Transformers, tes gagal sebagaimana mestinya, dan terkadang `test_modeling_common` terasa sulit didamaikan dengan kekhasan model baru kami. Namun, bagaimana kita bisa yakin bahwa kita tidak merusak segalanya dengan menambahkan skip yang tampak tidak berbahaya?

Utilitas ini:

- memindai semua metode test_modeling_common
- mencari waktu di mana sebuah metode dilewati
- mengembalikan ringkasan json yang dapat Anda muat sebagai DataFrame/memeriksanya

**Sebagai contoh, test_inputs_embeds dilewati dengan proporsi yang sangat besar, yaitu 39%, pada saat utilitas ini ditulis.**

![download-icon](https://huggingface.co/datasets/huggingface/documentation-images/resolve/f7f671f69b88ce4967e19179172c248958d35742/transformers/tests_skipped_visualisation.png)

### Penggunaan

Anda dapat menjalankan analyzer test yang dilewati dengan dua cara:

#### Pindai penuh (default)

Dari root repo `transformers`, memindai semua metode pengujian umum dan mengoutputkan hasilnya ke file JSON (default: `all_tests_scan_result.json`).

```bash
python utils/scan_skipped_tests.py --output_dir path/to/output
```

- `--output_dir` (opsional): Direktori tempat hasil JSON disimpan. Bawaan adalah direktori saat ini.

**Contoh output:**

```text
🔬 Parsing 331 model test files once each...
📝 Aggregating 224 tests...
  (224/224) test_update_candidate_strategy_with_matches_1es_3d_is_nonecodet_schedule_fa_kwargs
✅ Scan complete.

📄 JSON saved to /home/pablo/git/transformers/all_tests_scan_result.json

```

Dan akan menghasilkan file `all_tests_scan_result.json` yang dapat Anda periksa. JSON diindeks berdasarkan nama metode, dan setiap entri mengikuti skema ini, yang juga menunjukkan asalnya (dari `common` atau `GenerationMixin`.)

```json
{
  "<method_name>": {
    "origin": "<test suite>"
    "models_ran": ["<model_name>", ...],
    "models_skipped": ["<model_name>", ...],
    "skipped_proportion": <float>,
    "reasons_skipped": ["<model_name>: <reason>",
      ...
    ]
  },
  ...
}
```

Yang dapat Anda visualisasikan seperti di atas dengan, misalnya, `pandas`

```python
df = pd.read_json('all_tests_scan_result.json').T
df.sort_values(by=['skipped_proportion'], ascending=False)

```

### Pindai satu metode pengujian

Anda dapat berfokus pada metode pengujian tertentu menggunakan `--test_method_name`:

```bash
python utils/scan_skipped_tests.py --test_method_name test_inputs_embeds --output_dir path/to/output
```

- `--test_method_name`: Nama metode pengujian yang akan dipindai (misalnya, `test_inputs_embeds`).
- `--output_dir` (opsional): Direktori tempat hasil JSON akan disimpan.

**Contoh output:**

```bash
$ python utils/scan_skipped_tests.py --test_method_name test_inputs_embeds

🔬 Parsing 331 model test files once each...

== test_inputs_embeds ==

Ran    : 199/323
Skipped : 124/323 (38.4%)
 - aimv2: Aimv2 does not use inputs_embeds
 - align: Inputs_embeds is tested in individual model tests
 - altclip: Inputs_embeds is tested in individual model tests
 - audio_spectrogram_transformer: AST does not use inputs_embeds
 - beit: BEiT does not use inputs_embeds
 - bit: Bit does not use inputs_embeds
 - blip: Blip does not use inputs_embeds
 - blip_2: Inputs_embeds is tested in individual model tests
 - bridgetower:
 - canine: CANINE does not have a get_input_embeddings() method.
 - ...

📄 JSON saved to /home/pablo/git/transformers/scan_test_inputs_embeds.json

```

## Detektor model modular

### Analisis kesamaan kode - untuk penambah model

Utilitas ini menganalisis kemiripan kode antara implementasi model untuk mengidentifikasi peluang modularisasi. Utilitas ini membandingkan file pemodelan baru atau yang sudah ada dengan semua model di pustaka menggunakan metrik kemiripan berbasis embedding dan berbasis token.

### Rasional

Saat menambahkan model baru ke Transformers, banyak komponen (lapisan perhatian, MLP, output, dll.) mungkin sudah ada dalam bentuk serupa di model lain. Alih-alih mengimplementasikan semuanya dari awal, penambah model dapat mengidentifikasi kelas mana yang serupa dan berpotensi dapat digunakan kembali melalui modularisasi.

Alat ini menghitung dua skor kemiripan:

- **Skor embedding**: Menggunakan embedding kode semantik (melalui `Qwen/Qwen3-Embedding-4B`) untuk mendeteksi kode yang secara fungsional serupa meskipun memiliki penamaan yang berbeda
- **Skor Jaccard**: Mengukur tumpang tindih himpunan token untuk mengidentifikasi pola kode yang serupa secara struktural

Skor 1.00 berarti kode tersebut identik.

### Penggunaan

Dari root repositori `transformers`:

```bash
python utils/modular_model_detector.py --modeling-file path/to/modeling_file.py
```

Alat ini akan secara otomatis mengunduh indeks yang sudah dibangun sebelumnya dari Hub (memerlukan RAM/VRAM untuk model embedding).

**Contoh output:**

```text
Loading checkpoint shards: 100%|████████████████████| 2/2 [00:00<00:00, 33.62it/s]
encoding 21 query definitions with Qwen/Qwen3-Embedding-4B (device=cuda, batch=16, max_length=4096)

stuff.py::Beit3ImageTextMatchingOutput:
embedding:
    blip_2::Blip2ImageTextMatchingModelOutput (0.9994)
    chinese_clip::ChineseCLIPOutput (0.9818)
    owlvit::OwlViTOutput (0.9818)
jaccard:
    owlv2::Owlv2Output (0.9667)
    metaclip_2::MetaClip2Output (0.9667)
    altclip::AltCLIPOutput (0.9667)
intersection:
    blip::BlipOutput
    owlvit::OwlViTOutput

stuff.py::Beit3MLP:
embedding:
    efficientloftr::EfficientLoFTRMLP (0.9718)
    seggpt::SegGptMlp (0.9650)
jaccard:
    chinese_clip::ChineseCLIPTextSelfOutput (0.5294)
    bert::BertSelfOutput (0.5294)
intersection:
```

Bidang `intersection` menampilkan kelas yang muncul di kedua hasil top-5, menunjukkan tingkat kepercayaan tinggi untuk kandidat modularisasi.

### Membangun indeks kustom

Untuk membangun ulang indeks dari basis kode lokal Anda (berguna setelah menambahkan model baru atau menggunakan model embedding yang berbeda):

```bash
python utils/modular_model_detector.py --build
```

Untuk mendorong indeks yang dibangun ulang ke dataset Hub:

```bash
python utils/modular_model_detector.py --build --push-new-index --hub-dataset your-org/your-dataset
```

### Opsi

- `--modeling-file`: Path ke file modeling yang akan dianalisis
- `--build`: Membangun indeks kemiripan kode dari semua file pemodelan di `src/transformers/models/`
- `--push-new-index`: Setelah membangun, dorong indeks ke dataset Hub (memerlukan `--build`)
- `--hub-dataset`: ID repositori dataset Hub untuk menarik/mengirimkan indeks (default: `hf-internal-testing/transformers_code_embeddings`)

### Keterbatasan

Alat ini memerlukan sumber daya GPU/CPU untuk menjalankan model embedding (`Qwen/Qwen3-Embedding-4B`). Indeks yang sudah dibangun diunduh dari Hub secara default, yang memerlukan koneksi internet pada penggunaan pertama.

Hasil yang ditampilkan adalah saran berdasarkan kemiripan kode dan sebaiknya ditinjau secara manual sebelum modularisasi. Skor kemiripan yang tinggi tidak menjamin kompatibilitas yang sempurna.

