Transformers documentation
Trazado de las salidas intermedias del modelo
Trazado de las salidas intermedias del modelo
El método forward() de cada modelo solía resolver manualmente las banderas None, como output_attentions, a partir de los valores predeterminados de la configuración, acumular los pesos de atención y los estados ocultos por capa en tuplas y convertir las clases de datos ModelOutput en tuplas simples cuando return_dict=False. Dos decoradores reemplazan toda esa plantilla.
@capture_outputsresuelve las banderas de salida, recopila los valores intermedios y gestiona la conversión dereturn_dict.@merge_with_config_defaultsresuelveuse_cachea partir de la configuración. Omítelo en modelos que no usan caché, como CLIPModel.
Encontrarás estos decoradores principalmente al integrar un nuevo modelo. Consulta adding a model to 🤗 Transformers para una guía paso a paso.
Captura solo los estados ocultos que necesitas
output_hidden_states=True mantiene en memoria el estado oculto de cada capa hasta que termina la pasada hacia adelante. Si solo necesitas uno o unos pocos, pasa un índice o una lista de índices en su lugar. Los índices seleccionan elementos de la tupla que devuelve output_hidden_states=True, donde el índice 0 es la salida de la capa de incrustación y los índices negativos cuentan desde el 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]La tupla devuelta mantiene su longitud completa, por lo que hidden_states[k] apunta a la misma capa que con output_hidden_states=True. Los estados ocultos que no seleccionaste son None, y los que seleccionaste son idénticos a una captura completa.
- Los índices negativos se resuelven antes de la pasada hacia adelante a partir de
config.num_hidden_layers, más uno para la salida de la incrustación. Si la configuración no definenum_hidden_layers, un índice negativo genera unValueError. Utilice índices positivos para esos modelos. - Los índices fuera de rango se descartan sin generar un error y no seleccionan nada.
config.output_hidden_states=Truesigue capturando todos los estados ocultos.
De la v5.17 a la v5.22, un índice de lista
kseleccionaba la salida de la capaky excluía la salida del embedding. Ahora seleccionahidden_states[k], por lo que hay que sumar uno a cualquier índice positivo escrito para esas versiones.
Declarar qué submódulos capturar
Aplica @capture_outputs al método forward() del modelo base. Esto adjunta hooks de forward que:
- Intercepta las salidas de las clases de submódulos especificados durante la pasada hacia adelante, sin que esos submódulos necesiten saber que están siendo observados.
- Recopilar los pesos de atención y los estados ocultos por capa en tuplas.
- Inyecta los valores recopilados en la clase de datos
ModelOutputdevuelta. - Convierte el dataclass en una tupla simple cuando
return_dict=False. - Resuelve
output_attentionsyoutput_hidden_statesdesde kwargs oself.configcuando sonNone.
Mapear los campos de salida a submódulos
@capture_outputs necesita saber qué submódulo produce cada salida. Declara un diccionario a nivel de clase _can_record_outputs en tu subclase de PreTrainedModel. Cada clave es el nombre de un campo de salida ("hidden_states", "attentions", "cross_attentions") y cada valor es una clase de módulo, una cadena con el nombre de la clase, una instancia de OutputRecorder o una lista de estos para registrar varios tipos de módulo bajo una misma clave.
Control fino con OutputRecorder
OutputRecorder acepta un target_class (una subclase de nn.Module cuyos outputs se deben recopilar) y un index opcional para seleccionar qué elemento de la tupla de salida del módulo se debe obtener. Pasa layer_name para adjuntar hooks solo a módulos con un nombre de atributo específico. Usa layer_name cuando dos capas comparten la misma clase, por ejemplo self-attention vs. cross-attention. Si la configuración almacena la cantidad de capas bajo un nombre distinto de num_hidden_layers, establece num_hidden_layers_key en ese atributo para que los índices negativos de output_hidden_states se resuelvan correctamente.
El ejemplo siguiente muestra ambos decoradores en la práctica con distintos niveles de control de la salida. Consulte LlamaModel como referencia del 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
)Captura solo los estados ocultos que utiliza un método
Los métodos de extracción de características como get_image_features suelen leer uno o pocos estados ocultos de un submodelo, como la torre de visión. Solicitar output_hidden_states=True mantiene vivas todas las capas para usar solo unas pocas. En su lugar, decore el método con @select_hidden_states. Esto establece output_hidden_states en los índices que utiliza el método, y el @capture_outputs del submodelo que recibe los kwargs captura solo esos.
Pase el nombre del argumento del método que contiene los índices. El decorador lee el valor del argumento, incluido su valor predeterminado, y lo reenvía 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)Si el argumento tiene None como valor predeterminado y obtiene su valor de la configuración, coloque @merge_with_config_defaults por encima de @select_hidden_states para que el decorador vea el valor resuelto. LlavaModel hace esto para vision_feature_layer.
Si los índices provienen del modelo en lugar de un argumento, pase una función que reciba el modelo y los devuelva. CLIPSegForImageSegmentation añade uno a cada capa en extract_layers para omitir la salida de la incrustación.
@select_hidden_states(lambda self: [i + 1 for i in self.extract_layers])Si el llamador solicita estados ocultos con
output_hidden_states, esa solicitud tiene prioridad, por lo queoutput_hidden_states=Truesigue devolviendo todos los estados ocultos.
Clases de capas de parche
El trazado de salidas depende de que _can_record_outputs apunte a las clases exactas que instancian las capas de un modelo. Si sustituye una implementación de capa por un kernel de atención personalizado, una capa de experto cuantizada o una variante de arquitectura, esos punteros deben mantenerse sincronizados. La API de parcheo proporciona un registro global limpio para mantener _can_record_outputs de forma coherente.
register_patch_mapping asocia los nombres de clases originales a subclases de reemplazo de nn.Module. Las claves pueden ser nombres de clases exactos o patrones de expresión regular. Las coincidencias exactas tienen prioridad. Los patrones se prueban con re.search(), por lo que los patrones sin anclaje coinciden en cualquier posición del nombre de la clase. Registrar la misma clave dos veces genera un ValueError a menos que se pase overwrite=True.
Elimina las entradas con 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$"])Una vez que se registran los mapeos, patch_output_recorders recorre cada submódulo y actualiza cada OutputRecorder.target_class con el reemplazo registrado.
El método from_pretrained() llama a
patch_output_recordersautomáticamente. Solo es necesario llamarlo manualmente al construir un modelo directamente.
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)