# NemotronH

[NemotronH](https://huggingface.co/papers/2504.03624) é uma arquitetura híbrida que combina camadas de atenção e de espaço de estado para modelagem de linguagem de contexto longo eficiente. Ela intercala blocos Mamba2 e de transformer, usando uma proporção fixa para equilibrar expressividade com processamento de sequências em tempo linear.

O exemplo abaixo demonstra como gerar texto com [Pipeline](/docs/transformers/main/pt/main_classes/pipelines#transformers.Pipeline) ou a classe [AutoModelForCausalLM](/docs/transformers/main/pt/model_doc/auto#transformers.AutoModelForCausalLM).

```python
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")
```

```python
from transformers import AutoModelForCausalLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("nvidia/Nemotron-H-8B-Reasoning-128K")
model = AutoModelForCausalLM.from_pretrained(
    "nvidia/Nemotron-H-8B-Reasoning-128K",
    device_map="auto",
)
input_ids = tokenizer("Plants create energy through a process known as", return_tensors="pt").to(model.device)

output = model.generate(**input_ids, max_new_tokens=50)
print(tokenizer.decode(output[0], skip_special_tokens=True))
```

## Observações

- Use padding à esquerda para geração em lote. Consulte [Lado do padding](../llm_tutorial#padding-side).

## NemotronHConfig[[transformers.NemotronHConfig]]

#### transformers.NemotronHConfig[[transformers.NemotronHConfig]]

```python
transformers.NemotronHConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 131072, hidden_size: int = 4096, layers_block_type: list[str] | None = None, tie_word_embeddings: bool = False, use_cache: bool = True, num_logits_to_keep: int = 1, pad_token_id: int | None = 0, bos_token_id: int | None = 1, eos_token_id: int | list[int] | None = 2, num_attention_heads: int = 32, num_key_value_heads: int = 8, head_dim: int = 128, max_position_embeddings: int = 4096, attention_bias: bool = False, attention_dropout: float | int = 0.0, sliding_window: int | None = None, intermediate_size: int = 21504, mlp_hidden_act: str = 'relu2', mlp_bias: bool = False, use_mamba_kernels: bool = True, ssm_state_size: int = 128, mamba_num_heads: int = 128, mamba_head_dim: int = 64, mamba_hidden_act: str = 'silu', n_groups: int = 8, conv_kernel: int = 4, expand: int = 2, time_step_min: float = 0.001, time_step_max: float = 0.1, time_step_limit: list[float] | tuple[float, ...] = (0.0, inf), time_step_floor: float = 0.0001, use_conv_bias: bool = True, chunk_size: int = 128, mamba_proj_bias: bool = False, mamba_ssm_cache_dtype: str = 'float32', n_routed_experts: int = 8, output_router_logits: bool = False, n_shared_experts: int = 1, moe_intermediate_size: int = 7688, moe_shared_expert_intermediate_size: int = 7688, moe_latent_size: int | None = None, moe_shared_expert_overlap: bool = True, num_experts_per_tok: int = 2, routed_scaling_factor: float | int = 1.0, n_group: int = 1, topk_group: int = 1, norm_topk_prob: bool = True, num_nextn_predict_layers: int = 0, mtp_layers_block_type: list[str] | None = None, use_bias: bool = False, initializer_range: float = 0.02, layer_norm_epsilon: float = 1e-05, residual_in_fp32: bool = False, hidden_dropout: float | int = 0.0, rescale_prenorm_residual: bool = True)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nemotron_h/configuration_nemotron_h.py#L27)

**Parâmetros:**

vocab_size (`int`, *opcional*, padrão `131072`) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`.

hidden_size (`int`, *opcional*, padrão `4096`) : Dimensão das representações ocultas.

layers_block_type (`list`, *opcional*) : Lista explícita dos tipos de camada para cada camada. Cada elemento deve ser um dos seguintes: "mlp", "linear_attention", "full_attention" ou "moe". O número de camadas é determinado pelo comprimento desta lista.

tie_word_embeddings (`bool`, *opcional*, padrão `False`) : Se deve vincular as embeddings de pesos de acordo com o mapeamento `tied_weights_keys` do modelo.

use_cache (`bool`, *opcional*, padrão `True`) : Indica se o modelo deve retornar as últimas atenções de chave/valor (não utilizado por todos os modelos). Relevante apenas se `config.is_decoder=True` ou quando o modelo for um modelo generativo somente de decodificador.

num_logits_to_keep (`int`, *opcional*, padrão 1) : Número de logits de prompt a serem calculados durante a geração. Se `None`, todos os logits serão calculados.

pad_token_id (`int`, *opcional*, padrão `0`) : ID do token usado para preenchimento no vocabulário.

bos_token_id (`int`, *opcional*, padrão `1`) : ID do token usado para o início do fluxo no vocabulário.

eos_token_id (`Union[int, list[int]]`, *opcional*, padrão `2`) : ID do token usado para o fim do fluxo no vocabulário.

num_attention_heads (`int`, *opcional*, padrão `32`) : Número de cabeças de atenção para cada camada de atenção no decodificador do Transformer.

num_key_value_heads (`int`, *opcional*, padrão `8`) : Este é o número de cabeças de key_value que devem ser usadas para implementar Grouped Query Attention. Se `num_key_value_heads=num_attention_heads`, o modelo usará Multi Head Attention (MHA); se `num_key_value_heads=1`, o modelo usará Multi Query Attention (MQA); caso contrário, será usado GQA. Ao converter um checkpoint multi-head para um checkpoint GQA, cada cabeça de chave e valor do grupo deve ser construída pela média (meanpooling) de todas as cabeças originais dentro desse grupo. Para mais detalhes, consulte [este artigo](https://huggingface.co/papers/2305.13245). Se não for especificado, o valor padrão será `num_attention_heads`.

head_dim (`int`, *opcional*, padrão `128`) : A dimensão da cabeça de atenção. Se for None, o valor padrão será hidden_size // num_attention_heads

max_position_embeddings (`int`, *opcional*, padrão `4096`) : O comprimento máximo de sequência com o qual este modelo pode ser utilizado.

attention_bias (`bool`, *opcional*, padrão `False`) : Se deve usar um viés nas camadas de projeção de query, key, value e output durante a autoatenção.

attention_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A taxa de dropout para as probabilidades de atenção.

sliding_window (`int`, *opcional*) : Tamanho da janela de atenção deslizante. Se `None`, nenhuma janela deslizante é aplicada.

intermediate_size (`int`, *opcional*, padrão `21504`) : Dimensão das representações do MLP.

mlp_hidden_act (`str`, *opcional*, padrão `relu2`) : A função de ativação não linear (função ou string) no decodificador. Por exemplo, `"gelu"`, `"relu"`, `"silu"`, etc.

mlp_bias (`bool`, *opcional*, padrão `False`) : Se deve usar um viés nas camadas up_proj, down_proj e gate_proj das camadas MLP.

use_mamba_kernels (`bool`, *opcional*, padrão `True`) : Obsoleto e sem efeito. Os kernels rápidos do Mamba são usados automaticamente quando disponíveis.

ssm_state_size (`int`, *opcional*, padrão 128) : A dimensão dos latentes do espaço de estado do mamba.

mamba_num_heads (`int`, *opcional*, padrão `128`) : O número de cabeças mamba usadas na implementação v2.

mamba_head_dim (`int`, *opcional*, padrão `64`) : Tamanho da dimensão do embedding da cabeça

mamba_hidden_act (`str`, *opcional*, padrão `"silu"`) : A função de ativação não linear nas camadas Mamba.

n_groups (`int`, *opcional*, padrão 8) : Número de grupos para as matrizes de evolução das camadas Mamba.

conv_kernel (`int`, *opcional*, padrão `4`) : O tamanho do kernel de convolução.

expand (`int`, *opcional*, padrão 2) : Fator de expansão usado para determinar o tamanho intermediário nas camadas Mamba.

time_step_min (`float`, *opcional*, padrão `0.001`) : `time_step` mínimo usado para limitar `dt_proj.bias`.

time_step_max (`float`, *opcional*, padrão `0.1`) : `time_step` máximo usado para limitar `dt_proj.bias`.

time_step_limit (`Union[list[float], tuple[float, ...]]`, *opcional*, padrão `(0.0, inf)`) : Intervalo aceito de valores de passo de tempo para clamping.

time_step_floor (`float`, *opcional*, padrão `0.0001`) : Valor mínimo permitido para o passo de tempo discreto delta após a ativação softplus.

use_conv_bias (`bool`, *opcional*, padrão `True`) : Se deve ou não usar viés na camada de convolução do bloco misturador Mamba.

chunk_size (`int`, *opcional*, padrão 128) : Tamanho dos blocos que comporão a sequência nas camadas Mamba.

mamba_proj_bias (`bool`, *opcional*, padrão `False`) : Indica se deve ou não usar viés nas projeções de entrada e saída (["in_proj", "out_proj"]) do bloco mamba mixer

mamba_ssm_cache_dtype (`str`, *opcional*, padrão `"float32"`) : Tipo de dados para os estados de cache do SSM do Mamba.

n_routed_experts (`int`, *opcional*, padrão `8`) : Número de especialistas roteados.

output_router_logits (`bool`, *opcional*, padrão `False`) : Indica se os logits do roteador devem ser retornados pelo modelo. Ativar essa opção também permite que o modelo outpute a perda auxiliar, incluindo a perda de balanceamento de carga e a perda z do roteador.

n_shared_experts (`int`, *opcional*, padrão `1`) : Número de especialistas compartilhados.

moe_intermediate_size (`int`, *opcional*, padrão `7688`) : Tamanho intermediário dos MLPs dos especialistas roteados.

moe_shared_expert_intermediate_size (`int`, *opcional*, padrão 7688) : Dimensão das representações do MLP nos especialistas compartilhados.

moe_latent_size (`int`, *opcional*) : Tamanho latente para as projeções de especialistas do MoE. Se `None`, usa `hidden_size`.

moe_shared_expert_overlap (`bool`, *opcional*, padrão `True`) : Se os especialistas compartilhados se sobrepõem aos especialistas roteados.

num_experts_per_tok (`int`, *opcional*, padrão `2`) : Número de especialistas para os quais cada token será roteado. Este é o valor top-k para o roteamento de escolha de token.

routed_scaling_factor (`Union[float, int]`, *opcional*, padrão `1.0`) : Fator de escala ou especialistas roteados.

n_group (`int`, *opcional*, padrão 1) : Número de grupos para roteamento de especialistas.

topk_group (`int`, *opcional*, padrão `1`) : Número de grupos selecionados para cada token (para cada token, garantindo que os especialistas selecionados estejam apenas dentro de `topk_group` grupos).

norm_topk_prob (`bool`, *opcional*, padrão `True`) : Se as pesos dos especialistas roteados devem ser normalizados.

num_nextn_predict_layers (`int`, *opcional*, padrão 0) : Número de camadas adicionais para previsão de múltiplos tokens. Se for 0, a previsão de múltiplos tokens é desativada.

mtp_layers_block_type (`list`, *opcional*, padrão `['full_attention', 'moe']`) : Lista explícita de tipos de camada para as camadas de previsão de múltiplos tokens quando `num_nextn_predict_layers` > 0.

use_bias (`bool`, *opcional*, padrão `False`) : Se deve usar viés no modelo.

initializer_range (`float`, *opcional*, padrão `0.02`) : O desvio padrão do truncated_normal_initializer para inicializar todas as matrizes de pesos.

layer_norm_epsilon (`float`, *opcional*, padrão `1e-05`) : O epsilon usado pelas camadas de normalização de camada.

residual_in_fp32 (`bool`, *opcional*, padrão `False`) : Se os resíduos devem estar em `float32` ou não.

hidden_dropout (`Union[float, int]`, *opcional*, padrão `0.0`) : A probabilidade de dropout para todas as camadas totalmente conectadas nos embeddings, no encoder e no pooler.

rescale_prenorm_residual (`bool`, *opcional*, padrão `True`) : Se deve reescalar as conexões residuais de pré-normalização.

Esta é a classe de configuração para armazenar a configuração de um NemotronHModel. Ela é usada para instanciar um modelo Nemotron H de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16](https://huggingface.co/nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16)

Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações.

```python
>>> 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[[transformers.NemotronHConfig.validate_layer_type]]

```python
validate_layer_type()
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nemotron_h/configuration_nemotron_h.py#L207)

Valide a lista layers_block_type.

## NemotronHModel[[transformers.NemotronHModel]]

#### transformers.NemotronHModel[[transformers.NemotronHModel]]

```python
transformers.NemotronHModel(config: NemotronHConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nemotron_h/modeling_nemotron_h.py#L1076)

#### forward[[transformers.NemotronHModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.LongTensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, attention_mask: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nemotron_h/modeling_nemotron_h.py#L1093)

## NemotronHForCausalLM[[transformers.NemotronHForCausalLM]]

#### transformers.NemotronHForCausalLM[[transformers.NemotronHForCausalLM]]

```python
transformers.NemotronHForCausalLM(config: NemotronHConfig)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nemotron_h/modeling_nemotron_h.py#L1157)

#### forward[[transformers.NemotronHForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs)
```

[Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/nemotron_h/modeling_nemotron_h.py#L1169)

**Parâmetros:**

input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada no vocabulário. O preenchimento (padding) será ignorado por padrão. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada?](../glossary#input-ids)

attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`:  - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**.  [O que são máscaras de atenção?](../glossary#attention-mask)

position_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Índices das posições dos tokens de cada sequência de entrada nos embeddings de posição. Selecionados no intervalo `[0, config.n_positions - 1]`.  [O que são IDs de posição?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`.  Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão.  O modelo sairá no mesmo formato de cache que foi fornecido como entrada.  Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Opcionalmente, em vez de passar `input_ids`, você pode escolher passar diretamente uma representação incorporada. Isso é útil se você quiser ter mais controle sobre como converter os índices de `input_ids` nos vetores associados do que a matriz de busca de incorporação interna do modelo.

labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`.

use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`).

logits_to_keep (`Union[int, torch.Tensor]`, *opcional*, padrão `0`) : Se for um `int`, calcula os logits para os últimos `logits_to_keep` tokens. Se for `0`, calcula os logits para todos os `input_ids` (caso especial). Apenas os logits do último token são necessários para a geração, e calculá-los apenas para esse token pode economizar memória, o que se torna bastante significativo para sequências longas ou tamanho de vocabulário grande. Se for um `torch.Tensor`, deve ser 1D, correspondendo aos índices a serem mantidos na dimensão de comprimento da sequência. Isso é útil ao usar o formato de tensor empacotado (uma única dimensão para lote e comprimento da sequência).

**Retorna:** `MoeCausalLMOutputWithPast` ou `tuple(torch.Tensor)`

Um `MoeCausalLMOutputWithPast` ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([NemotronHConfig](/docs/transformers/main/pt/model_doc/nemotron_h#transformers.NemotronHConfig)) e das entradas.

O método forward de [NemotronHForCausalLM](/docs/transformers/main/pt/model_doc/nemotron_h#transformers.NemotronHForCausalLM) sobrescreve o método especial `__call__`.

Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente.

- **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem (para previsão do próximo token).
- **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem (pontuações para cada token do vocabulário antes do SoftMax).
- **aux_loss** (`torch.Tensor`, *opcional*, retornado quando `output_router_logits=True` é passado ou quando `config.output_router_logits=True`, e o modelo treina seu roteador com uma perda de balanceamento de carga) -- Perda auxiliar de balanceamento de carga para os módulos esparsos. Modelos que equilibram seus especialistas com um viés de roteador em vez disso (DeepSeek-V3 e as arquiteturas derivadas dele) retornam `None` aqui, mas ainda retornam `router_logits`.
- **router_logits** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_router_logits=True` é passado ou quando `config.output_router_logits=True`) -- Tupla de `torch.Tensor` (um para cada camada esparsa) com forma `(batch_size * sequence_length, num_experts)`.

  Logits brutos do roteador calculados pelos roteadores MoE. Podem ser usados para calcular uma perda de balanceamento de carga ou para inspecionar como os tokens são distribuídos entre os especialistas.
- **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Contém estados ocultos pré-computados (chaves e valores nos blocos de autoatenção) que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial.
- **hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings, se o modelo tiver uma camada de embedding, + um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`.

  Estados ocultos do modelo na saída de cada camada, além das saídas opcionais do embedding inicial.
- **attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`.

  Pesos de atenção após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção.

Exemplo:

```python
>>> 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."
```