Transformers documentation

Modelin ara çıktılarını izleme

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Modelin ara çıktılarını izleme

Her modelin forward() metodu, output_attentions gibi None bayraklarını yapılandırma varsayılanlarından manuel olarak çözmek, katman başına dikkat ağırlıklarını ve gizli durumları tuple'lara biriktirmek ve return_dict=False olduğunda ModelOutput dataclass'larını düz tuple'lara dönüştürmek için kullanılıyordu. İki dekoratör, tüm bu kalıp kodu değiştirir.

  • @capture_outputs çıktı bayraklarını çözer, ara değerleri toplar ve return_dict dönüşümünü işler.
  • @merge_with_config_defaults, use_cache değerini config'ten çözer. CLIPModel gibi önbellek kullanmayan modeller için bunu atlayın.

Bu dekoratörlerle çoğunlukla yeni bir model entegre ederken karşılaşacaksınız. Adım adım bir kılavuz için 🤗 Transformers'a model ekleme bölümüne bakın.

Sadece ihtiyacınız olan gizli durumları yakalayın

output_hidden_states=True, ileri geçiş (forward pass) sona erene kadar her katmanın gizli durumunu (hidden state) bellekte tutar. Sadece bir veya birkaçına ihtiyacınız varsa, bunun yerine bir indeks veya indeks listesi iletin. İndeksler, output_hidden_states=True tarafından döndürülen demetten seçim yapar; burada indeks 0 gömme (embedding) çıktısını temsil eder ve negatif indeksler sondan sayılır.

from transformers import AutoModel, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen3-0.6B")
model = AutoModel.from_pretrained("Qwen/Qwen3-0.6B")
inputs = tokenizer("Hello world", return_tensors="pt")

outputs = model(**inputs, output_hidden_states=[0, -2])
len(outputs.hidden_states)
# 29
[i for i, h in enumerate(outputs.hidden_states) if h is not None]
# [0, 27]

Döndürülen tuple tam uzunluğunu koruduğu için hidden_states[k], output_hidden_states=True kullanıldığında olduğu gibi aynı katmana işaret eder. Seçmediğiniz gizli durumlar None olur, seçtikleriniz ise tam bir yakalama ile birebir aynıdır.

  • Negatif indeksler, gömme çıktısı için bir eklenerek config.num_hidden_layers üzerinden ileri geçişten önce çözümlenir. Yapılandırma num_hidden_layers tanımlamıyorsa, negatif bir indeks ValueError oluşturur. Bu modeller için pozitif indeksler kullanın.
  • Aralık dışındaki indeksler hata vermeden atılır ve hiçbir şey seçmezler.
  • config.output_hidden_states=True her gizli durumu yine yakalar.

v5.17'den v5.22'ye kadar, bir liste indeksi olan k, k katmanının çıktısını seçer ve gömme (embedding) çıktısını hariç tutardı. Artık hidden_states[k] değerini seçtiğinden, bu sürümler için yazılmış olan her pozitif indekse bir ekleyin.

Hangi alt modüllerin yakalanacağını belirtin

Taban modelin forward() yöntemine @capture_outputs uygulayın. Bu, aşağıdakileri yapan ileri kancaları ekler:

  • İleri geçiş sırasında, bu alt modüllerin gözlemlendiklerinin farkında olmalarına gerek kalmadan, belirtilen alt modül sınıflarından gelen çıktıları yakalayın.
  • Katman başına dikkat ağırlıklarını ve gizli durumları demetlere (tuples) toplayın.
  • Toplanan değerleri döndürülen ModelOutput veri sınıfına enjekte edin.
  • return_dict=False olduğunda dataclass'ı düz bir tuple'a dönüştürün.
  • None olduğunda output_attentions ve output_hidden_states değerlerini kwargs veya self.config üzerinden çözün.

Çıktı alanlarını alt modüllere eşleyin

@capture_outputs, hangi alt modülün hangi çıktıyı ürettiğini bilmelidir. PreTrainedModel alt sınıfınızda _can_record_outputs sınıf düzeyinde bir sözlük tanımlayın. Her anahtar bir çıktı alanı adıdır ("hidden_states", "attentions", "cross_attentions") ve her değer bir modül sınıfı, bir sınıf adı dizesi, bir OutputRecorder örneği veya tek bir anahtar altında birden fazla modül türünü kaydetmek için bunlardan oluşan bir listedir.

OutputRecorder ile ince taneli kontrol

OutputRecorder, toplanacak çıktıları olan bir nn.Module alt sınıfı olan target_class ve modülün çıktı demetindeki hangi öğenin alınacağını seçmek için isteğe bağlı bir index alır. Kanca eklemek için yalnızca belirli bir öznitelik adına sahip modülleri hedeflemek üzere layer_name parametresini iletin. Örneğin self-attention ile cross-attention gibi iki katman aynı sınıfı paylaşıyorsa layer_name kullanın. Yapılandırma, katman sayısını num_hidden_layers dışında bir ad altında saklıyorsa, negatif output_hidden_states indekslerinin doğru şekilde çözümlenmesi için num_hidden_layers_key değerini bu özniteliğe ayarlayın.

Aşağıdaki örnek, farklı çıktı kontrol seviyeleriyle her iki dekoratörü de uygulamada göstermektedir. Gerçek dünya referansı için LlamaModel sınıfına bakın.

from ...processing_utils import Unpack
from ...utils import TransformersKwargs
from ...utils.generic import merge_with_config_defaults
from ...utils.output_capturing import capture_outputs, OutputRecorder

class MyPreTrainedModel(PreTrainedModel):
    _can_record_outputs = {
        # Capture hidden_states: hook fires after each MyDecoderBlock forward,
        # grabbing its first output (index 0 by default).
        "hidden_states": MyDecoderBlock,

        # Capture self-attention weights: hook fires after each MyAttention
        # forward, grabbing its second output (index=1 by default).
        "attentions": MyAttention,

        # Capture cross-attention weights: same class, different submodule.
        # layer_name targets the attribute `self.crossattention` inside the block.
        # Captures second output as requested (index=1)
        "cross_attentions": OutputRecorder(
            MyAttention, layer_name="crossattention", index=1
        ),
    }

# Now in base model's forward we need the decorators and `Unpack` `kwargs`
class MyModel(MyPreTrainedModel):

    @merge_with_config_defaults # ← resolves use_cache
    @capture_outputs            # ← handles output collection + return_dict
    def forward(
        self,
        input_ids: torch.LongTensor | None = None,
        past_key_values: Cache = None,
        **kwargs: Unpack[TransformersKwargs],
    ) -> BaseModelOutputWithPast:

        # No manual collection needed. Just run your layers normally.
        hidden_states = self.embed_tokens(input_ids)
        for layer in self.layers:
            hidden_states = layer(hidden_states, **kwargs)

        # Return the primary outputs. The decorator will fill in
        # hidden_states/attentions/cross_attentions automatically.
        return BaseModelOutputWithPast(
            last_hidden_state=hidden_states,
            past_key_values=past_key_values
        )

Bir yöntemin kullandığı gizli durumları yakala

get_image_features gibi özellik çıkarma yöntemleri, görme kulesi gibi bir alt modelden genellikle bir veya birkaç gizli durumu okur. output_hidden_states=True isteği, yalnızca birkaçının kullanılacağı tüm katmanları canlı tutar. Bunun yerine yöntemi @select_hidden_states ile süsleyin. Bu, output_hidden_states değerini yöntemin kullandığı indekslere ayarlar ve bu kwargs'ları alan alt modelin @capture_outputs işlemi yalnızca bunları yakalar.

Dizinleri içeren yöntem argümanının adını iletin. Süsleyici, argümanın varsayılan değerini de dahil olmak üzere değerini okur ve bunu output_hidden_states olarak iletir.

from ...utils.output_capturing import select_hidden_states

class MyVisionLanguageModel(MyPreTrainedModel):

    @select_hidden_states("vision_feature_layer")
    def get_image_features(
        self,
        pixel_values: torch.Tensor,
        vision_feature_layer: int | list[int] = -2,
        **kwargs: Unpack[TransformersKwargs],
    ):
        # kwargs["output_hidden_states"] is now vision_feature_layer
        image_outputs = self.vision_tower(pixel_values, return_dict=True, **kwargs)
        image_features = image_outputs.hidden_states[vision_feature_layer]
        return self.multi_modal_projector(image_features)

Argüman varsayılan olarak None ise ve değerini config'ten alıyorsa, dekoratörün çözümlenmiş değeri görmesi için @merge_with_config_defaults'i @select_hidden_states'nin üzerine yerleştirin. LlavaModel, vision_feature_layer için bunu yapar.

Eğer indeksler bir argümandan değil de modelden geliyorsa, modeli alıp onları döndüren bir fonksiyon geçin. CLIPSegForImageSegmentation, gömme çıktısını atlamak için extract_layers içindeki her katmana bir ekler.

@select_hidden_states(lambda self: [i + 1 for i in self.extract_layers])

Çağıran output_hidden_states ile gizli durumları istiyorsa, bu istek önceliklidir; bu nedenle output_hidden_states=True yine tüm gizli durumları döndürür.

Patch katman sınıfları

Output tracing, _can_record_outputs'ün bir modelin katmanlarının örneklediği doğru sınıflara işaret etmesine bağlıdır. Bir katman uygulamasını özel bir dikkat çekirdeği, kuantize edilmiş bir uzman katmanı veya bir mimari varyantıyla değiştirdiğinizde, bu işaretçilerin senkronize kalması gerekir. Yama API'si, _can_record_outputs'ün tutarlılığını korumak için temiz bir küresel kayıt defteri sağlar.

register_patch_mapping, orijinal sınıf adlarını yerini alacak nn.Module alt sınıflarına eşler. Anahtarlar tam sınıf adları veya regex desenleri olabilir. Tam eşleşmeler önceliklidir. Desenler re.search() ile test edildiğinden, başlangıç ve bitiş noktası olmayan desenler sınıf adının herhangi bir yerinde eşleşir. Aynı anahtarın iki kez kaydedilmesi, overwrite=True geçirilmediği sürece ValueError hatası oluşturur.

Girdileri unregister_patch_mapping ile kaldırın.

from transformers.monkey_patching import register_patch_mapping, unregister_patch_mapping

# Exact name – replaces only Qwen2MoeExperts
register_patch_mapping({"Qwen2MoeExperts": SequentialExperts})

# Regex – replaces every class whose name ends in "Attention"
register_patch_mapping({".*Attention$": FusedAttention})

# Anchored version – only matches Llama2Attention, Llama3Attention, …
register_patch_mapping({"^Llama\\d+Attention$": CustomLlamaAttention})

# Same way, custom keys can be removed from the registry by passing the name that was registered
unregister_patch_mapping(["Qwen2MoeExperts", ".*Attention$"])

Eşlemeler kaydedildikten sonra patch_output_recorders, her alt modülü dolaşır ve her bir OutputRecorder.target_class değerini kayıtlı ikameyle günceller.

from_pretrained() metodu, patch_output_recorders fonksiyonunu otomatik olarak çağırır. Modeli doğrudan oluştururken bu fonksiyonu kendiniz çağırmanız gerekir.

from transformers.monkey_patching import patch_output_recorders
# Built manually, outside from_pretrained
model = Qwen2MoeModel(config)

# Without this, _can_record_outputs still points at the original Qwen2MoeExperts class
# and hooks will never fire on CustomExperts instances.
patch_output_recorders(model)
Update on GitHub