Transformers documentation

Rastreamento das saídas intermediárias do modelo

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Rastreamento das saídas intermediárias do modelo

O método forward() de cada modelo costumava resolver manualmente as bandeiras None, como output_attentions, a partir dos padrões de configuração, acumular os pesos de atenção e os estados ocultos por camada em tuplas e converter os dataclasses ModelOutput em tuplas simples quando return_dict=False. Dois decoradores substituem toda essa boilerplate.

  • @capture_outputs resolve as flags de saída, coleta valores intermediários e trata a conversão de return_dict.
  • @merge_with_config_defaults resolve use_cache a partir da config. Omita-o para modelos que não fazem cache, como CLIPModel.

Você encontrará esses decoradores principalmente ao integrar um novo modelo. Consulte adicionando um modelo ao 🤗 Transformers para um guia passo a passo.

Capture apenas os estados ocultos de que você precisa

output_hidden_states=True mantém o estado oculto de cada camada na memória até o final da passagem para frente. Se você precisar de apenas um ou alguns, passe um índice ou uma lista de índices no lugar. Os índices selecionam a partir da tupla que output_hidden_states=True retorna, em que o índice 0 é a saída do embedding e os índices negativos contam a partir do final.

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]

A tupla retornada mantém seu comprimento total, portanto hidden_states[k] aponta para a mesma camada que com output_hidden_states=True. Os estados ocultos que você não selecionou são None, e os que você selecionou são idênticos a uma captura completa.

  • Índices negativos são resolvidos antes da passagem direta a partir de config.num_hidden_layers, mais um para a saída de incorporação. Se a configuração não definir num_hidden_layers, um índice negativo gera um ValueError. Use índices positivos para esses modelos.
  • Índices fora do intervalo são descartados sem erro e não selecionam nada.
  • config.output_hidden_states=True ainda captura todos os estados ocultos.

Da v5.17 à v5.22, um índice de lista k selecionava a saída da camada k e excluía a saída do embedding. Agora ele seleciona hidden_states[k], então adicione um a qualquer índice positivo escrito para aquelas versões.

Declare quais submódulos capturar

Aplique @capture_outputs ao método forward() do modelo base. Ele anexa hooks de forward que:

  • Intercepta as saídas de classes de submódulos especificados durante a passagem de frente, sem que esses submódulos precisem saber que estão sendo observados.
  • Colete os pesos de atenção e os estados ocultos por camada em tuplas.
  • Injete os valores coletados na dataclass ModelOutput retornada.
  • Converta o dataclass em uma tupla simples quando return_dict=False.
  • Resolve output_attentions e output_hidden_states a partir de kwargs ou self.config quando None.

Mapear campos de saída para submódulos

@capture_outputs precisa saber qual submódulo produz qual saída. Declare um dicionário de nível de classe _can_record_outputs em sua subclasse de PreTrainedModel. Cada chave é um nome de campo de saída ("hidden_states", "attentions", "cross_attentions") e cada valor é uma classe de módulo, uma string com o nome da classe, uma instância de OutputRecorder ou uma lista desses para registrar vários tipos de módulo sob uma única chave.

Controle fino com OutputRecorder

OutputRecorder aceita um target_class (uma subclasse de nn.Module cujas saídas devem ser coletadas) e um index opcional para selecionar qual elemento da tupla de saída do módulo deve ser obtido. Passe layer_name para anexar hooks apenas a módulos com um nome de atributo específico. Use layer_name quando duas camadas compartilham a mesma classe, por exemplo, autoatenção versus atenção cruzada. Se a configuração armazena a contagem de camadas sob um nome diferente de num_hidden_layers, defina num_hidden_layers_key para esse atributo para que os índices negativos de output_hidden_states sejam resolvidos corretamente.

O exemplo abaixo mostra os dois decoradores em prática, com diferentes níveis de controle de saída. Consulte LlamaModel para uma referência do mundo real.

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
        )

Capture apenas os estados ocultos que um método usa

Métodos de extração de recursos, como get_image_features, frequentemente leem um ou poucos estados ocultos de um submodelo, como a torre de visão. Solicitar output_hidden_states=True mantém todas as camadas ativas para usar apenas algumas delas. Em vez disso, decore o método com @select_hidden_states. Ele define output_hidden_states para os índices que o método usa, e o @capture_outputs do submodelo que recebe os kwargs captura apenas aqueles.

Passe o nome do argumento do método que contém os índices. O decorador lê o valor do argumento, incluindo seu valor padrão, e o encaminha como 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)

Se o argumento tem None como valor padrão e obtém seu valor da configuração, coloque @merge_with_config_defaults acima de @select_hidden_states para que o decorador veja o valor resolvido. LlavaModel faz isso para vision_feature_layer.

Se os índices vierem do modelo em vez de um argumento, passe uma função que recebe o modelo e os retorna. CLIPSegForImageSegmentation adiciona um a cada camada em extract_layers para pular a saída do embedding.

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

Se o chamador solicitar estados ocultos com output_hidden_states, essa solicitação tem precedência, portanto output_hidden_states=True ainda retorna todos os estados ocultos.

Classes de camadas de patch

O rastreamento de saída depende de _can_record_outputs apontar para as classes exatas que as camadas de um modelo instanciam. Se você substituir uma implementação de camada por um kernel de atenção personalizado, uma camada de especialista quantizada ou uma variante de arquitetura, esses ponteiros precisam permanecer sincronizados. A API de patching fornece um registro global limpo para manter _can_record_outputs consistente.

register_patch_mapping mapeia nomes de classes originais para subclasses de nn.Module de substituição. As chaves podem ser nomes de classes exatos ou padrões de expressão regular. Os correspondentes exatos têm prioridade. Os padrões são testados com re.search(), portanto, padrões sem âncora correspondem em qualquer parte do nome da classe. Registrar a mesma chave duas vezes levanta ValueError, a menos que você passe overwrite=True.

Remova as entradas com 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$"])

Quando os mapeamentos são registrados, patch_output_recorders percorre todos os submódulos e atualiza cada OutputRecorder.target_class para o substituto registrado.

O método from_pretrained() chama patch_output_recorders automaticamente. Você só precisa chamá-lo manualmente ao construir um modelo diretamente.

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