Transformers documentation
Melacak output antara model
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_outputsmenyelesaikan flag output, mengumpulkan nilai perantara, dan menangani konversireturn_dict.@merge_with_config_defaultsmenyelesaikanuse_cachedari 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 mendefinisikannum_hidden_layers, indeks negatif akan memicuValueError. Gunakan indeks positif untuk model-model tersebut. - Indeks di luar rentang diabaikan tanpa error, dan tidak memilih apa pun.
config.output_hidden_states=Truemasih menangkap setiap hidden state.
Dari v5.17 hingga v5.22, indeks daftar
kmemilih keluaran dari lapisankdan mengabaikan keluaran embedding. Sekarang, indeks tersebut memilihhidden_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
ModelOutputyang dikembalikan. - Konversi dataclass menjadi tuple biasa ketika
return_dict=False. - Selesaikan
output_attentionsdanoutput_hidden_statesdari kwargs atauself.configketikaNone.
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, sehinggaoutput_hidden_states=Truetetap 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_recorderssecara 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)