Transformers documentation

Melacak output antara model

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Melacak output antara model

Metode forward() setiap model sebelumnya harus secara manual menyelesaikan flag None seperti output_attentions dari nilai default konfigurasi, mengakumulasi bobot perhatian dan state tersembunyi per lapisan ke dalam tuple, serta mengonversi dataclass ModelOutput menjadi tuple biasa ketika return_dict=False. Dua dekorator menggantikan seluruh boilerplate tersebut.

  • @capture_outputs menyelesaikan flag output, mengumpulkan nilai perantara, dan menangani konversi return_dict.
  • @merge_with_config_defaults menyelesaikan use_cache dari config. Sertakan hanya untuk model yang tidak menggunakan cache, seperti CLIPModel.

Anda akan sering menemui dekorator ini saat mengintegrasikan model baru. Lihat mengambahkan model ke 🤗 Transformers untuk panduan langkah demi langkah.

Ambil hanya hidden states yang Anda butuhkan

output_hidden_states=True menyimpan hidden state dari setiap layer di memori hingga forward pass berakhir. Jika Anda hanya membutuhkan satu atau beberapa, berikan sebuah indeks atau daftar indeks sebagai gantinya. Indeks tersebut memilih dari tuple yang dikembalikan oleh output_hidden_states=True, di mana indeks 0 adalah output embedding dan indeks negatif dihitung dari akhir.

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]

Tuple yang dikembalikan mempertahankan panjang penuh, sehingga hidden_states[k] menunjuk ke lapisan yang sama seperti saat menggunakan output_hidden_states=True. Hidden states yang tidak Anda pilih adalah None, dan yang Anda pilih identik dengan tangkapan penuh.

  • Indeks negatif diselesaikan sebelum forward pass dari config.num_hidden_layers, ditambah satu untuk output embedding. Jika config tidak mendefinisikan num_hidden_layers, indeks negatif akan memicu ValueError. Gunakan indeks positif untuk model-model tersebut.
  • Indeks di luar rentang diabaikan tanpa error, dan tidak memilih apa pun.
  • config.output_hidden_states=True masih menangkap setiap hidden state.

Dari v5.17 hingga v5.22, indeks daftar k memilih keluaran dari lapisan k dan mengabaikan keluaran embedding. Sekarang, indeks tersebut memilih hidden_states[k], sehingga tambahkan satu pada setiap indeks positif yang ditulis untuk versi-versi tersebut.

Nyatakan modul mana yang akan ditangkap

Terapkan @capture_outputs pada metode forward() dari model dasar. Hal ini melampirkan forward hooks yang:

  • Intercept output dari kelas submodul yang ditentukan selama forward pass, tanpa submodul tersebut perlu mengetahui bahwa mereka sedang diamati.
  • Kumpulkan bobot perhatian dan keadaan tersembunyi per lapisan ke dalam tuple.
  • Suntikkan nilai yang dikumpulkan ke dalam dataclass ModelOutput yang dikembalikan.
  • Konversi dataclass menjadi tuple biasa ketika return_dict=False.
  • Selesaikan output_attentions dan output_hidden_states dari kwargs atau self.config ketika None.

Petakan bidang output ke submodul

@capture_outputs perlu mengetahui submodule mana yang menghasilkan output mana. Deklarasikan kamus tingkat kelas _can_record_outputs pada subclass PreTrainedModel Anda. Setiap kunci adalah nama field output ("hidden_states", "attentions", "cross_attentions"), dan setiap nilainya adalah kelas modul, string nama kelas, instance OutputRecorder, atau daftar dari hal-hal tersebut untuk merekam beberapa jenis modul di bawah satu kunci.

Kontrol terperinci dengan OutputRecorder

OutputRecorder menerima target_class (subkelas nn.Module yang outputnya akan dikumpulkan) dan index opsional untuk memilih elemen mana dari tuple output modul yang akan diambil. Sampaikan layer_name untuk melampirkan hook hanya ke modul dengan nama atribut tertentu. Gunakan layer_name ketika dua lapisan berbagi kelas yang sama, misalnya self-attention vs. cross-attention. Jika config menyimpan jumlah lapisan di bawah nama selain num_hidden_layers, atur num_hidden_layers_key ke atribut tersebut agar indeks negatif output_hidden_states dapat dipecahkan dengan benar.

Contoh di bawah ini menunjukkan kedua dekorator dalam praktik dengan tingkat kontrol output yang berbeda. Lihat LlamaModel untuk referensi dunia nyata.

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
        )

Tangkap hanya state tersembunyi yang digunakan oleh metode

Metode ekstraksi fitur seperti get_image_features sering kali membaca satu atau beberapa hidden state dari submodel, seperti vision tower. Meminta output_hidden_states=True membuat setiap layer tetap aktif hanya untuk menggunakan beberapa di antaranya. Hiasi metode tersebut dengan @select_hidden_states sebagai gantinya. Ini mengatur output_hidden_states ke indeks yang digunakan oleh metode tersebut, dan @capture_outputs dari submodel yang menerima kwargs hanya menangkap indeks tersebut.

Lewatkan nama argumen metode yang menyimpan indeks. Dekorator membaca nilai argumen tersebut, termasuk nilai defaultnya, dan meneruskannya sebagai output_hidden_states.

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)

Jika argumen secara default bernilai None dan mengambil nilainya dari config, letakkan @merge_with_config_defaults di atas @select_hidden_states agar dekorator melihat nilai yang sudah teresolusi. LlavaModel melakukan ini untuk vision_feature_layer.

Jika indeks berasal dari model alih-alih dari argumen, berikan fungsi yang menerima model dan mengembalikannya. CLIPSegForImageSegmentation menambahkan satu ke setiap lapisan di extract_layers untuk melewati output embedding.

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

Jika pemanggil meminta hidden states dengan output_hidden_states, permintaan tersebut memiliki prioritas, sehingga output_hidden_states=True tetap mengembalikan setiap hidden state.

Kelas lapisan patch

Output tracing bergantung pada _can_record_outputs yang menunjuk ke kelas tepat yang diinstansiasi oleh lapisan model. Jika Anda mengganti implementasi lapisan dengan kernel attention kustom, lapisan expert terkuantisasi, atau varian arsitektur, pointer tersebut harus tetap sinkron. patching API menyediakan registry global yang bersih untuk menjaga konsistensi _can_record_outputs.

register_patch_mapping memetakan nama kelas asli ke subkelas nn.Module pengganti. Kunci dapat berupa nama kelas persis atau pola regex. Kesesuaian persis memiliki prioritas. Pola diuji dengan re.search(), sehingga pola tanpa jangkar akan cocok di mana saja dalam nama kelas. Mendaftarkan kunci yang sama dua kali akan memicu ValueError kecuali Anda meneruskan overwrite=True.

Hapus entri dengan unregister_patch_mapping.

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$"])

Setelah pemetaan didaftarkan, patch_output_recorders akan menelusuri setiap submodul dan memperbarui setiap OutputRecorder.target_class menjadi pengganti yang telah didaftarkan.

Metode from_pretrained() memanggil patch_output_recorders secara otomatis. Anda hanya perlu memanggilnya sendiri saat membangun model secara langsung.

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