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 ekleyiciler için tasarlanmış bir güç kullanıcısı aracıdı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 ekleyicileri 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:

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.

{
  "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.

      "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 uygulamalar arası sayısal analizi desteklemek için, tam tensör değerlerini diske kaydetmekten fayda görebilir.

use_repr=False değerini ayarlayarak tensörleri SafeTensors kullanarak diske yazdırın.

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 aynıdır, ancak tam olarak değil. Dosya farklarını incelemek, hangi katmanın hatalı olduğunu belirlemeyi kolaylaştırır.

download-icon

Kısıtlamalar ve kapsam

Bu özellik yalnızca torch tabanlı modeller için çalışır. Harici çekirdek çağrılarına büyük ölçüde bağımlı modeller çalışabilir, ancak izleme (trace) muhtemelen bazı şeyleri kaçırır. Yine de, başka bir uygulamayı taklit etmeyi hedefleyen herhangi bir python uygulaması, N kez nokta kırıcılarıyla (breakpoint) 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

< source >

( modeldebug_path: str | None = Nonedo_prune_layers: bool = Trueuse_repr: bool = True )

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.

Bir 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ında kaydeder. use_repr=True (varsayılan) ise, JSON dosyası tensörlerin repr() ile işlenmiş versiyonunu bir dizi dizgi olarak kaydeder. use_repr=False ise, tam tensörler ayrı SafeTensors dosyalarında saklanır ve JSON dosyası o 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

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 ekleyenler ve bakımcılar için tasarlanmış bir güç kullanıcısı aracıdır. test_modeling_common.py içindeki, tüm model testçi sınıfları tarafından devralınan tüm 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 hissedilebilir. 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

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

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

🔬 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.

{
  "<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

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:

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

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

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

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

python utils/modular_model_detector.py --build

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

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.

Update on GitHub