# Model hata ayıklama araç kutuları

Bu sayfa, kütüphanenin kullandığı tüm hata ayıklama ve model ekleme araçlarını, ayrıca bunlar için sağladığı yardımcı işlevleri listeler.

Bunların çoğu, kütüphaneye yeni modeller ekliyorsanız işe yarar.

## Model ekleme hata ayıklayıcıları

### Model ekleme hata ayıklayıcı - model ekleme araçları için bağlam yöneticisi

Bu bağlam yöneticisi, model ekleyicileri için tasarlanmış gelişmiş bir araçtır. Bir modelin forward çağrısı içindeki tüm forward çağrılarını izler ve her girdi ve çıktının bir dilimini iç içe geçmiş bir JSON üzerinde kaydeder. Not: Bu bağlam yöneticisi `torch.no_grad()` uygulamasını zorunlu kılar.

### Gerekçe

Modelleri transformers'a taşırken, hatta Python'dan Python'a taşırken bile, model ekleyenler genellikle tensörleri kaydetme ve yükleme, dtype'ları karşılaştırma gibi birçok manuel işlem yapmak zorunda kalır. Bu küçük araç, umarız ki, biraz zaman kazandırır.

### Kullanım

Bir modeli hata ayıklamak için bu bağlam yöneticisini aşağıdaki gibi ekleyin:

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

```

### Sonuçları okuma

Hata ayıklayıcı, ileri çağrıdan iki dosya üretir; her ikisi de aynı temel adı taşır ancak `_SUMMARY.json` veya `_FULL_TENSORS.json` uzantısıyla biter.

İlk modül, her modülün _girdi_ ve _çıktı_ tensör değerlerinin ve biçimlerinin bir özetini içerecektir.

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

`_FULL_TENSORS.json` dosyası, tüm tensörlerin tam görünümünü gösterir ve bu, iki dosyayı karşılaştırmak için kullanışlıdır.

```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')"
      },
```

#### Gergileri diske kaydetme

Bazı model ekleyicileri, örneğin farklı uygulamalar arasında sayısal analiz desteği sağlamak için, tam tensör değerlerini diske kaydetmekten fayda görebilir.

`use_repr=False` değerini ayarlayarak tensörleri [SafeTensors](https://huggingface.co/docs/safetensors/en/index) kullanarak diske yazdırın.

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

`use_repr=False` kullanıldığında, tensörler `_SUMMARY.json` ve `_FULL_TENSORS.json` dosyalarının yazıldığı aynı disk konumuna yazılır. `_FULL_TENSORS.json` dosyasındaki girdilerin `value` özelliği, ilgili `.safetensors` dosyasına göreli bir yol referansı içerir. Her tensör, durum sözlüğünün `data` özelliği olarak kendi dosyasına yazılır. Dosya adları, `module_path` öneki ve özyinelemeli olarak oluşturulan birkaç olası sonek kullanılarak oluşturulur.

* Modül girdileri `_inputs` ile, çıktıları ise `_outputs` ile belirtilir.
* `list` ve `tuple` örnekleri, örneğin `args` veya fonksiyon dönüş değerleri, `_{index}` ile sonlandırılır.
* `dict` örnekleri `_{key}` ile sonlandırılır.

### Uygulamalar arasında karşılaştırma

Hata ayıklayıcı tarafından iki modelin ileri geçişleri izlendikten sonra, `json` çıktı dosyaları karşılaştırılabilir. Aşağıda: bu iki uygulamanın anahtar projeksiyon katmanı arasında küçük farklar görebiliriz. Girdiler büyük ölçüde özdeştir, ancak tam olarak aynı değildir. Dosya farklarını incelemek, hangi katmanın hatalı olduğunu belirlemeyi kolaylaştırır.

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

### Kısıtlamalar ve kapsam[[transformers.model_addition_debugger_context]]

Bu özellik yalnızca torch tabanlı modeller için çalışır. Harici çekirdek çağrılarına büyük ölçüde bağımlı olan modeller çalışabilir, ancak izleme (trace) muhtemelen bazı unsurları kaçırır. Bununla birlikte, başka bir uygulamayı taklit etmeyi hedefleyen herhangi bir python uygulaması, N kez nokta kırıcılarıyla yeniden çalıştırılmak yerine bir kez izlenebilir.

Model hata ayıklayıcınıza `do_prune_layers=False` parametresini geçirirseniz, TÜM katmanlar `json` çıktısına yazılır. Aksi halde yalnızca ilk ve son katman gösterilir. Bu, bazı katmanların (genellikle çapraz dikkat) yalnızca N katmandan sonra görünmesi durumunda faydalıdır.

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

[Kaynak](https://github.com/huggingface/transformers/blob/main/src/transformers/model_debugging_utils.py#L391)

# Model ekleme hata ayıklayıcı - model ekleme araçları için bağlam yöneticisi
Bu bağlam yöneticisi, model ekleyicileri için tasarlanmış bir güç kullanıcısı aracıdır.

Modelin forward geçişindeki tüm forward çağrılarını izler ve her girdi ve çıktının bir dilimini iç içe geçmiş bir JSON dosyasına kaydeder. `use_repr=True` (varsayılan) ise, JSON dosyası tensörlerin `repr()` ile dönüştürülmüş halini bir dize listesi olarak kaydeder. `use_repr=False` ise, tam tensörler ayrı SafeTensors dosyalarında saklanır ve JSON dosyası bu dosyaya göreli bir yol sağlar.

Not olarak, bu bağlam yöneticisi `torch.no_grad()` uygulamasını zorunlu kılar.

## Kullanım

hata ayıklama için modele bağlam yöneticisi ekleyin

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

## Atlanan testlerin analizcisi

### Atlanan testleri tara - model ekleyicileri ve bakımcıları için

Bu küçük yardımcı araç, model ekleyicileri ve bakımcılar için tasarlanmış gelişmiş bir araçtır. `test_modeling_common.py` dosyasında bulunan ve tüm model testçi sınıfları tarafından devralınan test yöntemlerini listeler ve depoyu tarayarak kaç testin atlandığını ve hangi modeller için atlandığını ölçer.

### Gerekçe

Modelleri transformers'a taşırken testlerin başarısız olması beklenen bir durumdur ve bazen `test_modeling_common`, tamamen yeni modelimizin kendine özgü nitelikleriyle uzlaştırılamaz gibi hissedilir. Ancak, görünüşte masum bir atlamayı ekleyerek her şeyi bozmadığımızdan nasıl emin olabiliriz?

Bu yardımcı:

- tüm test_modeling_common yöntemlerini tarar
- bir metodun atlandığı zamanları arar
- DataFrame olarak yükleyebileceğiniz/inceleyebileceğiniz özet bir json döndürür

**Örneğin, bu yardımcı yazılırken test_inputs_embeds, inanılmaz bir oranda, %39 oranında atlanmaktadır.**

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

### Kullanım

Atlanan test analizcisini iki şekilde çalıştırabilirsiniz:

#### Tam tarama (varsayılan)

`transformers` deposunun kök dizininden, tüm yaygın test yöntemlerini tarar ve sonuçları bir JSON dosyasına yazar (varsayılan: `all_tests_scan_result.json`).

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

- `--output_dir` (isteğe bağlı): JSON sonuçlarının kaydedileceği dizin. Varsayılan olarak mevcut dizindir.

**Örnek çıktı:**

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

```

Ve inceleyebileceğiniz `all_tests_scan_result.json` dosyasını oluşturur. JSON, yöntem adıyla indekslenir ve her giriş bu şemayı izler; ayrıca kaynağı da ( `common` veya `GenerationMixin` ) belirtir.

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

Bunu örneğin `pandas` ile yukarıdaki gibi görselleştirebilirsiniz

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

```

### Tek bir test metodunu tara

`--test_method_name` kullanarak belirli bir test yöntemine odaklanabilirsiniz:

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

- `--test_method_name`: Taranacak test yönteminin adı (ör. `test_inputs_embeds`).
- `--output_dir` (isteğe bağlı): JSON sonucunun kaydedileceği dizin.

**Örnek çıktı:**

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

```

## Modüler model algılayıcı

### Kod benzerliği analizörü - model ekleyiciler için

Bu yardımcı araç, modülerleştirme fırsatlarını belirlemek için model uygulamaları arasındaki kod benzerliklerini analiz eder. Yeni veya mevcut bir modelleme dosyasını, gömme tabanlı ve belirteç tabanlı benzerlik ölçütlerini kullanarak kütüphanedeki tüm modellerle karşılaştırır.

### Gerekçe

Transformers'a yeni bir model eklenirken, birçok bileşen (dikkat katmanları, MLP'ler, çıktılar vb.) benzer bir formda diğer modellerde zaten mevcut olabilir. Her şeyi sıfırdan uygulamak yerine, model ekleyiciler, modülerleştirme yoluyla hangi mevcut sınıfların benzer ve potansiyel olarak yeniden kullanılabilir olduğunu belirleyebilir.

Araç iki benzerlik puanı hesaplar:

- **Gömme skoru**: Farklı adlandırmalara sahip olsa bile işlevsel olarak benzer kodu tespit etmek için anlamsal kod gömmelerini (via `Qwen/Qwen3-Embedding-4B`) kullanır
- **Jaccard skoru**: Yapısal olarak benzer kod kalıplarını belirlemek için token küme örtüşmesini ölçer

1.00 puan, kodun birebir aynı olduğunu ifade eder.

### Kullanım

`transformers` deposunun kökünden:

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

Araç, Hub'dan önceden derlenmiş indeksi otomatik olarak indirir (gömme modeli için RAM/VRAM gerektirir).

**Örnek çıktı:**

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

`intersection` alanı, her iki top-5 sonucunda da yer alan sınıfları gösterir ve modülerleşme adayları için yüksek güven düzeyini belirtir.

### Özel bir indeks oluşturma

Yerel kod tabanınızdan yeniden oluşturmak için (yeni modeller ekledikten veya farklı bir gömme modeli kullandıktan sonra faydalıdır):

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

Yeniden oluşturulan indeksi bir Hub veri setine göndermek için:

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

### Seçenekler

- `--modeling-file`: Analiz edilecek modelleme dosyasının yolu
- `--build`: `src/transformers/models/` içindeki tüm modelleme dosyalarından kod benzerliği dizinini oluşturur
- `--push-new-index`: Derleme işleminden sonra indeksi bir Hub veri setine gönderir (`--build` gerektirir)
- `--hub-dataset`: İndeksin çekileceği/itileceği Hub veri seti deposu kimliği (varsayılan: `hf-internal-testing/transformers_code_embeddings`)

### Kısıtlamalar

Bu araç, gömme modelini (`Qwen/Qwen3-Embedding-4B`) çalıştırmak için GPU/CPU kaynakları gerektirir. Hazır indeks varsayılan olarak Hub'dan indirilir ve bu, ilk kullanımda internet bağlantısı gerektirir.

Sonuçlar, kod benzerliğine dayalı önerilerdir ve modülerleştirme öncesinde manuel olarak gözden geçirilmelidir. Yüksek benzerlik puanları, mükemmel uyumluluğu garanti etmez.