Hugging Face's logo

Transformers documentation

NemotronH

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

Este modelo se publicó en HF papers el 2025-04-04 y se contribuyó a Hugging Face Transformers el 2026-03-03.

FlashAttention SDPA

NemotronH

NemotronH es una arquitectura híbrida que combina capas de atención y de espacio de estados para un modelado de lenguaje de contexto largo eficiente. Alterna bloques Mamba2 y de transformador, utilizando una proporción fija para equilibrar la expresividad con el procesamiento de secuencias en tiempo lineal.

El siguiente ejemplo demuestra cómo generar texto con Pipeline o la clase AutoModelForCausalLM.

Pipeline
AutoModelForCausalLM
from transformers import pipeline


pipe = pipeline(
    task="text-generation",
    model="nvidia/Nemotron-H-8B-Reasoning-128K",
)
pipe("Plants create energy through a process known as")

Notas

  • Use padding izquierdo para la generación por lotes. Consulte Lado de relleno.

NemotronHConfig

clase transformers.NemotronHConfig

< >

( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 131072hidden_size: int = 4096layers_block_type: list[str] | None = Nonetie_word_embeddings: bool = Falseuse_cache: bool = Truenum_logits_to_keep: int = 1pad_token_id: int | None = 0bos_token_id: int | None = 1eos_token_id: int | list[int] | None = 2num_attention_heads: int = 32num_key_value_heads: int = 8head_dim: int = 128max_position_embeddings: int = 4096attention_bias: bool = Falseattention_dropout: float | int = 0.0sliding_window: int | None = Noneintermediate_size: int = 21504mlp_hidden_act: str = 'relu2'mlp_bias: bool = Falseuse_mamba_kernels: bool = Truessm_state_size: int = 128mamba_num_heads: int = 128mamba_head_dim: int = 64mamba_hidden_act: str = 'silu'n_groups: int = 8conv_kernel: int = 4expand: int = 2time_step_min: float = 0.001time_step_max: float = 0.1time_step_limit: list[float] | tuple[float, ...] = (0.0, inf)time_step_floor: float = 0.0001use_conv_bias: bool = Truechunk_size: int = 128mamba_proj_bias: bool = Falsemamba_ssm_cache_dtype: str = 'float32'n_routed_experts: int = 8output_router_logits: bool = Falsen_shared_experts: int = 1moe_intermediate_size: int = 7688moe_shared_expert_intermediate_size: int = 7688moe_latent_size: int | None = Nonemoe_shared_expert_overlap: bool = Truenum_experts_per_tok: int = 2routed_scaling_factor: float | int = 1.0n_group: int = 1topk_group: int = 1norm_topk_prob: bool = Truenum_nextn_predict_layers: int = 0mtp_layers_block_type: list[str] | None = Noneuse_bias: bool = Falseinitializer_range: float = 0.02layer_norm_epsilon: float = 1e-05residual_in_fp32: bool = Falsehidden_dropout: float | int = 0.0rescale_prenorm_residual: bool = True )

Parámetros

  • vocab_size (int, opcional, valor predeterminado 131072) — Tamaño del vocabulario del modelo. Define el número de tokens diferentes que pueden representarse mediante input_ids.
  • hidden_size (int, opcional, valor predeterminado 4096) — Dimensión de las representaciones ocultas.
  • layers_block_type (list, opcional) — Lista explícita de tipos de capa para cada capa. Cada elemento debe ser uno de: “mlp”, “linear_attention”, “full_attention” o “moe”. El número de capas se determina por la longitud de esta lista.
  • tie_word_embeddings (bool, opcional, valor predeterminado False) — Si se deben vincular las matrices de pesos de embeddings según el mapeo tied_weights_keys del modelo.
  • use_cache (bool, opcional, valor predeterminado True) — Indica si el modelo debe devolver las últimas claves/valores de atención (no utilizado por todos los modelos). Solo es relevante si config.is_decoder=True o cuando el modelo es un modelo generativo solo de decodificador.
  • num_logits_to_keep (int, opcional, valor predeterminado 1) — Número de logits del prompt que se calcularán durante la generación. Si es None, se calcularán todos los logits.
  • pad_token_id (int, opcional, valor predeterminado 0) — Id del token utilizado para el relleno en el vocabulario.
  • bos_token_id (int, opcional, valor predeterminado 1) — Id del token utilizado para el inicio de la secuencia en el vocabulario.
  • eos_token_id (Union[int, list[int]], opcional, valor predeterminado 2) — Identificador de token utilizado para el fin de secuencia en el vocabulario.
  • num_attention_heads (int, opcional, valor predeterminado 32) — Número de cabezas de atención para cada capa de atención en el decodificador Transformer.
  • num_key_value_heads (int, opcional, valor predeterminado 8) — Este es el número de cabezas key_value que se deben utilizar para implementar Grouped Query Attention. Si num_key_value_heads=num_attention_heads, el modelo utilizará Multi Head Attention (MHA); si num_key_value_heads=1, el modelo utilizará Multi Query Attention (MQA); en caso contrario, se utilizará GQA. Al convertir un checkpoint multi-head en un checkpoint GQA, cada cabeza de clave y valor del grupo debe construirse mediante el promediado (meanpooling) de todas las cabezas originales dentro de ese grupo. Para más detalles, consulta este artículo. Si no se especifica, el valor predeterminado será num_attention_heads.
  • head_dim (int, opcional, valor predeterminado 128) — La dimensión de la cabeza de atención. Si es None, se establecerá en hidden_size // num_attention_heads
  • max_position_embeddings (int, opcional, valor predeterminado 4096) — La longitud máxima de secuencia con la que se podría utilizar este modelo.
  • attention_bias (bool, opcional, valor predeterminado False) — Si se debe usar un sesgo en las capas de proyección de consulta, clave, valor y salida durante la autoatención.
  • attention_dropout (Union[float, int], opcional, valor predeterminado 0.0) — La proporción de dropout para las probabilidades de atención.
  • sliding_window (int, opcional) — Tamaño de la ventana de atención deslizante. Si es None, no se aplica ninguna ventana deslizante.
  • intermediate_size (int, opcional, valor predeterminado 21504) — Dimensión de las representaciones del MLP.
  • mlp_hidden_act (str, opcional, valor predeterminado relu2) — La función de activación no lineal (función o cadena) en el decodificador. Por ejemplo, "gelu", "relu", "silu", etc.
  • mlp_bias (bool, opcional, valor predeterminado False) — Si se debe usar un sesgo en las capas up_proj, down_proj y gate_proj de las capas MLP.
  • use_mamba_kernels (bool, opcional, valor predeterminado True) — Obsoleto y sin efecto. Los kernels rápidos de Mamba se utilizan automáticamente cuando están disponibles.
  • ssm_state_size (int, opcional, valor predeterminado 128) — La dimensión de los latentes del espacio de estados de mamba.
  • mamba_num_heads (int, opcional, valor predeterminado 128) — El número de cabezas mamba utilizadas en la implementación v2.
  • mamba_head_dim (int, opcional, valor predeterminado 64) — Tamaño de la dimensión de incrustación de la cabeza
  • mamba_hidden_act (str, opcional, valor predeterminado "silu") — La función de activación no lineal en las capas Mamba.
  • n_groups (int, opcional, valor predeterminado 8) — Número de grupos para las matrices de evolución de las capas Mamba.
  • conv_kernel (int, opcional, valor predeterminado 4) — El tamaño del kernel de convolución.
  • expand (int, opcional, valor predeterminado 2) — Factor de expansión utilizado para determinar el tamaño intermedio en las capas Mamba.
  • time_step_min (float, opcional, valor predeterminado 0.001) — time_step mínimo utilizado para acotar dt_proj.bias.
  • time_step_max (float, opcional, valor predeterminado 0.1) — time_step máximo utilizado para acotar dt_proj.bias.
  • time_step_limit (Union[list[float], tuple[float, ...]], opcional, valor predeterminado (0.0, inf)) — Rango aceptado de valores de paso de tiempo para el recorte.
  • time_step_floor (float, opcional, valor predeterminado 0.0001) — Valor mínimo permitido para el delta del paso de tiempo discreto tras la activación softplus.
  • use_conv_bias (bool, opcional, valor predeterminado True) — Indica si se debe usar sesgo en la capa de convolución del bloque mezclador Mamba.
  • chunk_size (int, opcional, valor predeterminado 128) — Tamaño de los fragmentos que componen la secuencia en las capas Mamba.
  • mamba_proj_bias (bool, opcional, valor predeterminado False) — Indica si se debe usar sesgo en las proyecciones de entrada y salida ([“in_proj”, “out_proj”]) del bloque mezclador mamba
  • mamba_ssm_cache_dtype (str, opcional, valor predeterminado "float32") — Tipo de datos para los estados de caché de Mamba SSM.
  • n_routed_experts (int, opcional, valor predeterminado 8) — Número de expertos enrutados.
  • output_router_logits (bool, opcional, valor predeterminado False) — Indica si el modelo debe devolver los logits del router. Habilitar esta opción también permite que el modelo devuelva la pérdida auxiliar, que incluye la pérdida de equilibrio de carga y la pérdida z del router.
  • n_shared_experts (int, opcional, valor predeterminado 1) — Número de expertos compartidos.
  • moe_intermediate_size (int, opcional, valor predeterminado 7688) — Tamaño intermedio de los MLP de los expertos enrutados.
  • moe_shared_expert_intermediate_size (int, opcional, valor predeterminado 7688) — Dimensión de las representaciones MLP en los expertos compartidos.
  • moe_latent_size (int, opcional) — Tamaño latente para las proyecciones de expertos de MoE. Si es None, usa hidden_size.
  • moe_shared_expert_overlap (bool, opcional, valor predeterminado True) — Si los expertos compartidos se superponen con los expertos enrutados.
  • num_experts_per_tok (int, opcional, valor predeterminado 2) — Número de expertos a los que enrutar cada token. Este es el valor top-k para el enrutamiento de selección de tokens.
  • routed_scaling_factor (Union[float, int], opcional, valor predeterminado 1.0) — Factor de escala de los expertos enrutados.
  • n_group (int, opcional, valor predeterminado 1) — Número de grupos para el enrutamiento de expertos.
  • topk_group (int, opcional, valor predeterminado 1) — Número de grupos seleccionados para cada token (para cada token, garantizando que los expertos seleccionados estén solo dentro de topk_group grupos).
  • norm_topk_prob (bool, opcional, valor predeterminado True) — Si se normalizan los pesos de los expertos enrutados.
  • num_nextn_predict_layers (int, opcional, valor predeterminado 0) — Número de capas adicionales para la predicción de múltiples tokens. Si es 0, la predicción de múltiples tokens se desactiva.
  • mtp_layers_block_type (list, opcional, valor predeterminado ['full_attention', 'moe']) — Lista explícita de tipos de capa para las capas de predicción de múltiples tokens cuando num_nextn_predict_layers > 0.
  • use_bias (bool, opcional, valor predeterminado False) — Si se usa sesgo en el modelo.
  • initializer_range (float, opcional, valor predeterminado 0.02) — La desviación estándar del truncated_normal_initializer para inicializar todas las matrices de pesos.
  • layer_norm_epsilon (float, opcional, valor predeterminado 1e-05) — El epsilon utilizado por las capas de normalización de capa.
  • residual_in_fp32 (bool, opcional, valor predeterminado False) — Indica si los residuales deben estar en float32.
  • hidden_dropout (Union[float, int], opcional, valor predeterminado 0.0) — La probabilidad de dropout para todas las capas totalmente conectadas en las incrustaciones, el codificador y el pooler.
  • rescale_prenorm_residual (bool, opcional, valor predeterminado True) — Si se deben reescalar las conexiones residuales de prenormalización.

Esta es la clase de configuración para almacenar la configuración de un NemotronHModel. Se utiliza para instanciar un modelo Nemotron H según los argumentos especificados, definiendo la arquitectura del modelo. Instanciar una configuración con los valores predeterminados producirá una configuración similar a la de nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16

Los objetos de configuración heredan de PreTrainedConfig y se pueden usar para controlar las salidas del modelo. Lea la documentación de PreTrainedConfig para obtener más información.

>>> from transformers import NemotronHModel, NemotronHConfig

>>> # Initializing a NemotronH configuration
>>> configuration = NemotronHConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = NemotronHModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

validate_layer_type

< >

( )

Validar la lista layers_block_type.

NemotronHModel

clase transformers.NemotronHModel

< >

( config: NemotronHConfig )

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.LongTensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = Noneattention_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> )

NemotronHForCausalLM

clase transformers.NemotronHForCausalLM

< >

( config: NemotronHConfig )

forward

< >

( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneposition_ids: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs ) → MoeCausalLMOutputWithPast or tuple(torch.Tensor)

Parámetros

  • input_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de los tokens de la secuencia de entrada en el vocabulario. El relleno se ignorará de forma predeterminada.

    Los índices se pueden obtener usando AutoTokenizer. Consulte PreTrainedTokenizer.encode() y PreTrainedTokenizer.call() para más detalles.

    ¿Qué son los IDs de entrada?

  • attention_mask (torch.Tensor de forma (batch_size, sequence_length), opcional) — Máscara para evitar realizar atención en los índices de tokens de relleno. Valores de máscara seleccionados en [0, 1]:
    • 1 para los tokens que no están enmascarados,
    • 0 para los tokens que están enmascarados.

    ¿Qué son las máscaras de atención?

  • position_ids (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Índices de las posiciones de los tokens de cada secuencia de entrada en los embeddings de posición. Seleccionados en el rango [0, config.n_positions - 1].

    ¿Qué son los IDs de posición?

  • past_key_values (~cache_utils.Cache, opcional) — Estados ocultos precalculados (claves y valores en los bloques de autoatención y en los bloques de atención cruzada) que se pueden usar para acelerar la decodificación secuencial. Esto generalmente consiste en la past_key_values devuelta por el modelo en una etapa anterior de la decodificación, cuando use_cache=True o config.use_cache=True.

    Solo se permite una instancia de Cache como entrada, consulte nuestra guía de caché kv. Si no se pasan past_key_values, DynamicCache se inicializará de forma predeterminada.

    El modelo generará el mismo formato de caché que se proporciona como entrada.

    Si se utilizan past_key_values, se espera que el usuario introduzca únicamente los input_ids no procesados (aquellos que no tienen sus estados de clave y valor pasados proporcionados a este modelo) con forma (batch_size, unprocessed_length) en lugar de todos los input_ids con forma (batch_size, sequence_length).

  • inputs_embeds (torch.Tensor de forma (batch_size, sequence_length, hidden_size), opcional) — Opcionalmente, en lugar de pasar input_ids, puedes elegir pasar directamente una representación incrustada. Esto es útil si deseas tener más control sobre cómo convertir los índices de input_ids en los vectores asociados que en la matriz de búsqueda de incrustaciones interna del modelo.
  • labels (torch.LongTensor de forma (batch_size, sequence_length), opcional) — Etiquetas para calcular la pérdida de modelado de lenguaje enmascarado. Los índices deben estar en [0, ..., config.vocab_size] o ser -100 (ver la docstring de input_ids). Los tokens con índices establecidos en -100 se ignoran (enmascarados); la pérdida solo se calcula para los tokens con etiquetas en [0, ..., config.vocab_size].
  • use_cache (bool, opcional) — Si se establece en True, se devuelven los estados de clave-valor de past_key_values y pueden usarse para acelerar la decodificación (ver past_key_values).
  • logits_to_keep (Union[int, torch.Tensor], opcional, valor predeterminado 0) — Si es un int, calcula los logits para los últimos logits_to_keep tokens. Si es 0, calcula los logits para todos los input_ids (caso especial). Solo se necesitan los logits del último token para la generación, y calcularlos solo para ese token puede ahorrar memoria, lo cual se vuelve bastante significativo para secuencias largas o un tamaño de vocabulario grande. Si es un torch.Tensor, debe ser de 1D y corresponder a los índices a conservar en la dimensión de longitud de secuencia. Esto es útil al usar el formato de tensor empaquetado (una sola dimensión para el lote y la longitud de secuencia).

Devuelve

MoeCausalLMOutputWithPast o tuple(torch.Tensor)

Un MoeCausalLMOutputWithPast o una tupla de torch.Tensor (si se pasa return_dict=False o cuando config.return_dict=False) que comprende varios elementos según la configuración (NemotronHConfig) y las entradas.

El método forward de NemotronHForCausalLM sobrescribe el método especial __call__.

Aunque la receta para la pasada hacia adelante debe definirse dentro de esta función, se debe llamar a la instancia de Module después en lugar de a esta, ya que la primera se encarga de ejecutar los pasos de pre y postprocesamiento, mientras que la segunda los ignora silenciosamente.

  • loss (torch.Tensor de forma (1,), opcional, se devuelve cuando se proporciona labels) — Pérdida de modelado de lenguaje (para la predicción del siguiente token).

  • logits (torch.Tensor de forma (batch_size, sequence_length, config.vocab_size)) — Puntuaciones de predicción de la cabeza de modelado de lenguaje (puntuaciones para cada token del vocabulario antes de SoftMax).

  • aux_loss (torch.Tensor, opcional, se devuelve cuando se pasa output_router_logits=True o cuando config.output_router_logits=True, y el modelo entrena su router con una pérdida de equilibrio de carga) — Pérdida auxiliar de equilibrio de carga para los módulos dispersos. Los modelos que equilibran sus expertos con un sesgo del router en su lugar (DeepSeek-V3 y las arquitecturas derivadas de él) devuelven None aquí, aunque siguen devolviendo router_logits.

  • router_logits (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_router_logits=True o cuando config.output_router_logits=True) — Tupla de torch.Tensor (una por cada capa dispersa) de forma (batch_size * sequence_length, num_experts).

    Logits crudos del router calculados por los routers de MoE. Se pueden utilizar para calcular una pérdida de equilibrado de carga o para inspeccionar cómo se distribuyen los tokens entre los expertos.

  • past_key_values (Cache, opcional, se devuelve cuando se pasa use_cache=True o cuando config.use_cache=True) — Es una instancia de Cache. Para más detalles, consulta nuestra guía de caché kv.

    Contiene estados ocultos precalculados (claves y valores en los bloques de autoatención) que pueden utilizarse (véase la entrada past_key_values) para acelerar la decodificación secuencial.

  • hidden_states (tuple(torch.Tensor), opcional, devuelto cuando se pasa output_hidden_states=True o cuando config.output_hidden_states=True) — Tupla de torch.Tensor (una para la salida de las incrustaciones, si el modelo tiene una capa de incrustaciones, + una para la salida de cada capa) de forma (batch_size, sequence_length, hidden_size).

    Estados ocultos del modelo en la salida de cada capa más las salidas opcionales de la incrustación inicial.

  • attentions (tuple(torch.Tensor), opcional, se devuelve cuando se pasa output_attentions=True o cuando config.output_attentions=True) — Tupla de torch.Tensor (una por cada capa) de forma (batch_size, num_heads, sequence_length, sequence_length).

    Pesos de atención tras el softmax de atención, utilizados para calcular la media ponderada en las cabezas de autoatención.

Ejemplo:

>>> from transformers import AutoTokenizer, NemotronHForCausalLM

>>> model = NemotronHForCausalLM.from_pretrained("Zyphra/NemotronH-7B-v1")
>>> tokenizer = AutoTokenizer.from_pretrained("Zyphra/NemotronH-7B-v1")

>>> prompt = "Hey, are you conscious? Can you talk to me?"
>>> inputs = tokenizer(prompt, return_tensors="pt")

>>> # Generate
>>> generate_ids = model.generate(inputs.input_ids, max_length=30)
>>> tokenizer.batch_decode(generate_ids, skip_special_tokens=True, clean_up_tokenization_spaces=False)[0]
"Hey, are you conscious? Can you talk to me?\nI'm not conscious, but I can talk to you."
Update on GitHub

←Nemotron NemotronH Omni→