Transformers documentation
NemotronH
Эта модель была опубликована в HF papers 04.04.2025 и добавлена в Hugging Face Transformers 03.03.2026.
NemotronH
NemotronH — это гибридная архитектура, сочетающая слои внимания и слои пространства состояний для эффективного моделирования языка с длинным контекстом. Она чередует блоки Mamba2 и трансформерные блоки, используя фиксированное соотношение для баланса между выразительностью и обработкой последовательностей за линейное время.
Приведённый ниже пример показывает, как генерировать текст с помощью 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")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))Примечания
- Используйте левое выравнивание (left padding) для пакетной генерации. См. Сторона выравнивания.
NemotronHConfig
класс transformers.NemotronHConfig
< source >( 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 )
Параметры
- vocab_size (
int, необязательный, по умолчанию131072) — Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены вinput_ids. - hidden_size (
int, необязательный, по умолчанию4096) — Размерность скрытых представлений. - layers_block_type (
list, необязательный) — Явный список типов слоёв для каждого слоя. Каждый элемент должен быть одним из: “mlp”, “linear_attention”, “full_attention” или “moe”. Количество слоёв определяется длиной этого списка. - tie_word_embeddings (
bool, необязательный, по умолчаниюFalse) — Определяет, следует ли связывать веса эмбеддингов согласно маппингуtied_weights_keysмодели. - use_cache (
bool, необязательный, по умолчаниюTrue) — Указывает, должен ли модель возвращать последние ключи/значения внимания (не используется во всех моделях). Актуально только еслиconfig.is_decoder=Trueили если модель является генеративной моделью только с декодером. - num_logits_to_keep (
int, необязательный, по умолчанию 1) — Количество логитов промпта, которые вычисляются во время генерации. ЕслиNone, вычисляются все логиты. - pad_token_id (
int, необязательный, по умолчанию0) — Идентификатор токена, используемого для дополнения (padding) в словаре. - bos_token_id (
int, необязательный, по умолчанию1) — Идентификатор токена, используемого для обозначения начала потока в словаре. - eos_token_id (
Union[int, list[int]], необязательный, по умолчанию2) — Идентификатор токена, используемого для обозначения конца потока в словаре. - num_attention_heads (
int, необязательный, по умолчанию32) — Количество головок внимания в каждом слое внимания декодера Transformer. - num_key_value_heads (
int, необязательный, по умолчанию8) — Это количество ключевых и value-голов, используемых для реализации Grouped Query Attention. Еслиnum_key_value_heads=num_attention_heads, модель использует Multi Head Attention (MHA); еслиnum_key_value_heads=1— Multi Query Attention (MQA); в остальных случаях применяется GQA. При конвертации мультиголовного чекпоинта в GQA-чекпоинт каждая групповая ключевая и value-голова должна конструироваться путем усреднения (meanpooling) всех исходных голов в этой группе. Дополнительные подробности — в этой статье. Если значение не указано, по умолчанию используетсяnum_attention_heads. - head_dim (
int, необязательный, по умолчанию128) — Размерность головы внимания. Если значение равно None, по умолчанию используется hidden_size // num_attention_heads - max_position_embeddings (
int, необязательный, по умолчанию4096) — Максимальная длина последовательности, с которой может использоваться эта модель. - attention_bias (
bool, необязательный, по умолчаниюFalse) — Использовать ли смещение (bias) в слоях проекции query, key, value и output при само-внимании. - attention_dropout (
Union[float, int], необязательный, по умолчанию0.0) — Коэффициент dropout для вероятностей внимания. - sliding_window (
int, необязательный) — Размер окна скользящего внимания. ЕслиNone, скользящее окно не применяется. - intermediate_size (
int, необязательный, по умолчанию21504) — Размерность представлений MLP. - mlp_hidden_act (
str, необязательный, по умолчаниюrelu2) — Нелинейная функция активации (функция или строка) в декодере. Например,"gelu","relu","silu"и т. д. - mlp_bias (
bool, необязательный, по умолчаниюFalse) — Использовать ли смещение (bias) в слоях up_proj, down_proj и gate_proj внутри MLP-слоёв. - use_mamba_kernels (
bool, необязательный, по умолчаниюTrue) — Устарел и не оказывает влияния. Быстрые ядра Mamba используются автоматически, когда доступны. - ssm_state_size (
int, необязательный, по умолчанию 128) — Размерность латентов пространства состояний mamba. - mamba_num_heads (
int, необязательный, по умолчанию128) — Количество mamba-голов, используемых в реализации v2. - mamba_head_dim (
int, необязательный, по умолчанию64) — Размер размерности встраивания головы - mamba_hidden_act (
str, необязательный, по умолчанию"silu") — Нелинейная функция активации в слоях Mamba. - n_groups (
int, необязательный, по умолчанию 8) — Количество групп для матриц эволюции в слоях Mamba. - conv_kernel (
int, необязательный, по умолчанию4) — Размер свёрточного ядра. - expand (
int, необязательный, по умолчанию 2) — Коэффициент расширения, используемый для определения промежуточного размера в слоях Mamba. - time_step_min (
float, необязательный, по умолчанию0.001) — Минимальное значениеtime_step, используемое для ограниченияdt_proj.bias. - time_step_max (
float, необязательный, по умолчанию0.1) — Максимальное значениеtime_step, используемое для ограниченияdt_proj.bias. - time_step_limit (
Union[list[float], tuple[float, ...]], необязательный, по умолчанию(0.0, inf)) — Допустимый диапазон значений шага времени для ограничения. - time_step_floor (
float, необязательный, по умолчанию0.0001) — Минимально допустимое значение дискретного шага времени delta после активации softplus. - use_conv_bias (
bool, необязательный, по умолчаниюTrue) — Использовать ли смещение (bias) в слое свёртки блока Mamba mixer. - chunk_size (
int, необязательный, по умолчанию 128) — Размер блоков, из которых будет состоять последовательность в слоях Mamba. - mamba_proj_bias (
bool, необязательный, по умолчаниюFalse) — Флаг, указывающий, следует ли использовать смещение (bias) во входных и выходных проекциях ([“in_proj”, “out_proj”]) блока mamba mixer - mamba_ssm_cache_dtype (
str, необязательный, по умолчанию"float32") — Тип данных для состояний кэша SSM в Mamba. - n_routed_experts (
int, необязательный, по умолчанию8) — Количество маршрутизируемых экспертов. - output_router_logits (
bool, необязательный, по умолчаниюFalse) — Определяет, следует ли модели возвращать логиты роутера. Включение этого параметра также позволит модели выводить вспомогательную потерю, включая потерю балансировки нагрузки и z-потерю роутера. - n_shared_experts (
int, необязательный, по умолчанию1) — Количество общих экспертов. - moe_intermediate_size (
int, необязательный, по умолчанию7688) — Промежуточный размер MLP маршрутизированных экспертов. - moe_shared_expert_intermediate_size (
int, необязательный, по умолчанию 7688) — Размерность представлений MLP в общих экспертах. - moe_latent_size (
int, необязательный) — Размер латентного пространства для проекций экспертов MoE. ЕслиNone, используетсяhidden_size. - moe_shared_expert_overlap (
bool, необязательный, по умолчаниюTrue) — Указывает, перекрываются ли общие эксперты с маршрутизируемыми экспертами. - num_experts_per_tok (
int, необязательный, по умолчанию2) — Количество экспертов, к которым маршрутизируется каждый токен. Это значение top-k для маршрутизации по выбору токена. - routed_scaling_factor (
Union[float, int], необязательный, по умолчанию1.0) — Коэффициент масштабирования для маршрутизированных экспертов. - n_group (
int, необязательный, по умолчанию 1) — Количество групп для маршрутизации экспертов. - topk_group (
int, необязательный, по умолчанию1) — Количество выбранных групп для каждого токена (для каждого токена, чтобы выбранные эксперты находились только в пределахtopk_groupгрупп). - norm_topk_prob (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли нормализовать веса маршрутизированных экспертов. - num_nextn_predict_layers (
int, необязательный, по умолчанию 0) — Количество дополнительных слоёв для предсказания нескольких токенов. Если равно 0, предсказание нескольких токенов отключено. - mtp_layers_block_type (
list, необязательный, по умолчанию['full_attention', 'moe']) — Явный список типов слоёв для слоёв многознаковой предсказательной модели, еслиnum_nextn_predict_layers> 0. - use_bias (
bool, необязательно, по умолчаниюFalse) — Использовать ли смещение (bias) в модели. - initializer_range (
float, необязательный, по умолчанию0.02) — Стандартное отклонение truncated_normal_initializer, используемое для инициализации всех матриц весов. - layer_norm_epsilon (
float, необязательный, по умолчанию1e-05) — Значение epsilon, используемое слоями нормализации. - residual_in_fp32 (
bool, необязательный, по умолчаниюFalse) — Определяет, должны ли остаточные соединения храниться в форматеfloat32. - hidden_dropout (
Union[float, int], необязательный, по умолчанию0.0) — Вероятность dropout для всех полносвязных слоёв в эмбеддингах, энкодере и пуллере. - rescale_prenorm_residual (
bool, необязательный, по умолчаниюTrue) — Определяет, следует ли масштабировать остаточные соединения до нормализации.
Это класс конфигурации для хранения параметров модели NemotronHModel. Он используется для создания модели Nemotron H в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
>>> 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Проверьте список layers_block_type.
NemotronHModel
forward
< source >( 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
forward
< source >( 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)
Параметры
- input_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
- attention_mask (
torch.Tensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- position_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона[0, config.n_positions - 1]. - past_key_values (
~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно этоpast_key_values, возвращённые моделью на предыдущем этапе декодирования, когдаuse_cache=Trueилиconfig.use_cache=True.В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован DynamicCache.Модель будет выводить тот же формат кэша, который был передан на вход.
Если используются
past_key_values, ожидается, что пользователь передаст только необработанныеinput_ids(те, для которых в этой модели ещё не заданы состояния прошлых ключей и значений) формы(batch_size, unprocessed_length), а не всеinput_idsформы(batch_size, sequence_length). - inputs_embeds (
torch.Tensorформы(batch_size, sequence_length, hidden_size), необязательный) — При необходимости, вместо передачиinput_idsможно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексыinput_idsпреобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели. - labels (
torch.LongTensorформы(batch_size, sequence_length), необязательный) — Метки для вычисления потерь каузального языкового моделирования. Индексы должны находиться в диапазоне[-100, 0, ..., config.vocab_size](см.input_idsдокументацию к-100Токены с индексом, установленным в значение[0, ..., config.vocab_size].Метки сдвигаются внутренне, так что для предсказания
logits[..., :-1, :]используютсяlabels[..., 1:]. Передавайте несдвинутые метки, соответствующиеinput_ids(то естьlabels = input_ids). Не сдвигайте метки сами перед их передачей.Если метки уже сдвинуты (например, при последовательной параллельности), передайте их как аргумент
shift_labels, и они будут использованы как есть. Для вычисления функции потерь всё равно необходимо передатьlabels. - use_cache (
bool, необязательный) — Если установлено вTrue, возвращаются состояния ключей и значенийpast_key_values, которые можно использовать для ускорения декодирования (см.past_key_values). - logits_to_keep (
Union[int, torch.Tensor], необязательный, по умолчанию0) — Если передано значение типаint, вычисляет logits для последнихlogits_to_keepтокенов. Если указано0, logits вычисляются для всехinput_ids(особый случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типаtorch.Tensor, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (один размер для batch и длины последовательности).
Возвращает
MoeCausalLMOutputWithPast или tuple(torch.Tensor)
MoeCausalLMOutputWithPast или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (NemotronHConfig) и входных данных.
Метод NemotronHForCausalLM forward переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
loss (
torch.Tensorформы(1,), необязательный, возвращается, если заданlabels) — Потери языковой модели (для предсказания следующего токена).logits (
torch.Tensorформы(batch_size, sequence_length, config.vocab_size)) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).aux_loss (
torch.Tensor, необязательный, возвращается при передачеoutput_router_logits=Trueили приconfig.output_router_logits=True, если модель обучает свой роутер с потерей балансировки нагрузки) — вспомогательная потеря балансировки нагрузки для разреженных модулей. Модели, которые балансируют своих экспертов с помощью смещения роутера (DeepSeek-V3 и архитектуры, производные от него), возвращают здесьNone, но при этом всё равно возвращаютrouter_logits.router_logits (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_router_logits=Trueили когдаconfig.output_router_logits=True) — Кортежtorch.Tensor(по одному для каждого разреженного слоя) формы(batch_size * sequence_length, num_experts).Сырые логиты маршрутизатора, вычисленные маршрутизаторами MoE. Их можно использовать для вычисления потерь сбалансированности нагрузки или для анализа того, как токены распределяются между экспертами.
past_key_values (
Cache, необязательный, возвращается при передачеuse_cache=Trueили когдаconfig.use_cache=True) — это экземпляр Cache. Подробнее см. в нашем руководстве по кэшу kv.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания), которые можно использовать (см. вход
past_key_values) для ускорения последовательного декодирования.hidden_states (
tuple(torch.Tensor), optional, возвращается, если переданоoutput_hidden_states=Trueили еслиconfig.output_hidden_states=True) — кортеж изtorch.Tensor(один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили приconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
Пример:
>>> 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."