Transformers documentation
NemotronH
このモデルは2025年4月4日にHF papersで公開され、2026年3月3日にHugging Face Transformersに貢献されました。
NemotronH
NemotronHは、効率的な長文脈言語モデリングのために、アテンション層と状態空間層を組み合わせるハイブリッドアーキテクチャです。Mamba2ブロックとtransformerブロックを交互に配置し、固定比率を用いて表現力と線形時間でのシーケンス処理のバランスを取ります。
以下の例では、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))注記
- バッチ生成には左パディングを使用します。Padding sideを参照してください。
NemotronHConfig
class 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)— 生成中に計算するプロンプトの logits の数。Noneの場合、すべての logits が計算されます。 - pad_token_id (
int、任意、デフォルトは0) — 語彙内でパディングに使用されるトークン ID。 - bos_token_id (
int、任意、デフォルトは1) — 語彙におけるストリーム開始に使用されるトークン ID。 - eos_token_id (
Union[int, list[int]]、任意、デフォルトは2) — 語彙内でストリーム終了に使用されるトークン ID。 - num_attention_heads (
int、任意、デフォルトは32) — Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。 - num_key_value_heads (
int、任意、デフォルトは8) — Grouped Query Attention の実装に使用する key_value ヘッドの数を指定します。num_key_value_heads=num_attention_headsの場合、モデルは Multi Head Attention (MHA) を使用し、num_key_value_heads=1の場合は Multi Query Attention (MQA) を使用し、それ以外の場合は GQA が使用されます。 マルチヘッドのチェックポイントを GQA のチェックポイントに変換する際は、各グループの key ヘッドと value ヘッドを、そのグループ内の元のすべてのヘッドの平均プーリングによって構築する必要があります。詳細については、この論文を参照してください。指定しない場合、デフォルトでnum_attention_headsが使用されます。 - head_dim (
int、任意、デフォルトは128) — アテンションヘッドの次元です。None の場合、hidden_size // num_attention_heads がデフォルトとして使用されます。 - max_position_embeddings (
int、任意、デフォルトは4096) — このモデルが使用される可能性のある最大シーケンス長です。 - attention_bias (
bool、任意、デフォルトはFalse) — 自己注意機構において、クエリ、キー、バリュー、出力の投影層にバイアスを使用するかどうかを指定します。 - attention_dropout (
Union[float, int]、任意、デフォルトは0.0) — アテンション確率のドロップアウト率です。 - sliding_window (
int, 省略可) — スライディングウィンドウアテンションのウィンドウサイズ。Noneの場合、スライディングウィンドウは適用されません。 - intermediate_size (
int、任意、デフォルトは21504) — MLP 表現の次元数。 - mlp_hidden_act (
str、任意、デフォルトはrelu2) — デコーダー内で使用される非線形活性化関数（関数または文字列）です。例えば、"gelu"、"relu"、"silu"などです。 - mlp_bias (
bool、任意、デフォルトはFalse) — MLP層のup_proj、down_proj、gate_proj層でバイアスを使用するかどうかを指定します。 - use_mamba_kernels (
bool、任意、デフォルトはTrue) — 非推奨であり、効果はありません。利用可能な場合、高速な Mamba カーネルが自動的に使用されます。 - ssm_state_size (
int、任意、デフォルト値は 128)— Mamba の状態空間潜在変数の次元です。 - mamba_num_heads (
int、任意、デフォルトは128) — v2実装で使用するmambaヘッドの数です。 - 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) —dt_proj.biasを制限するために使用される最小のtime_step。 - time_step_max (
float、任意、デフォルトは0.1) —dt_proj.biasを制限するために使用されるtime_stepの最大値。 - time_step_limit (
Union[list[float], tuple[float, ...]]、省略可、デフォルトは(0.0, inf)) — クランプに使用するタイムステップ値の許容範囲。 - time_step_floor (
float、任意、デフォルトは0.0001) — softplus 活性化後の離散タイムステップのデルタに許可される最小値です。 - use_conv_bias (
bool、任意、デフォルトはTrue) — Mamba mixer ブロックの畳み込み層でバイアスを使用するかどうか。 - chunk_size (
int、任意、デフォルトは 128) — Mamba レイヤー内でシーケンスを構成するチャンクのサイズ。 - mamba_proj_bias (
bool、任意、デフォルトはFalse) — mamba mixer ブロックの入力および出力投影（[“in_proj”, “out_proj”]）でバイアスを使用するかどうかを示すフラグ - mamba_ssm_cache_dtype (
str, 省略可、デフォルトは"float32") — Mamba SSM キャッシュ状態のデータ型です。 - 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) — モデルでバイアスを使用するかどうか。 - initializer_range (
float、任意、デフォルトは0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。 - layer_norm_epsilon (
float、任意、デフォルトは1e-05) — レイヤーノーマル層で使用する epsilon です。 - residual_in_fp32 (
bool、省略可、デフォルトはFalse) — residualsをfloat32で保持するかどうかを指定します。 - hidden_dropout (
Union[float, int]、任意、デフォルト値は0.0) — embeddings、encoder、pooler 内のすべての全結合層における 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.configlayers_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.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Nonelogits_to_keep: typing.Union[int, torch.Tensor] = 0**kwargs ) → MoeCausalLMOutputWithPast or tuple(torch.FloatTensor)
パラメータ
- input_ids (
torch.LongTensorの形状(batch_size, sequence_length), 、省略可) — 語彙における入力シーケンスのトークンインデックスです。デフォルトではパディングは無視されます。インデックスは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 cache ガイドを参照してください。
past_key_valuesが渡されない場合、デフォルトで DynamicCache が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。
past_key_valuesを使用する場合、すべてのinput_ids（形状(batch_size, sequence_length)）ではなく、このモデルに過去のキー・バリュー状態が与えられていない未処理のinput_ids（形状(batch_size, unprocessed_length)）のみを入力することになります。 - inputs_embeds (
torch.FloatTensor、形状(batch_size, sequence_length, hidden_size)、任意) —input_idsを渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込みルックアップ行列よりも、input_idsのインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 - labels (
torch.LongTensor、shape(batch_size, sequence_length)、任意) — マスク言語モデリング損失を計算するためのラベルです。インデックスは[0, ..., config.vocab_size]の範囲内であるか、-100 である必要があります（input_idsの docstring を参照）。インデックスが-100に設定されたトークンは無視（マスク）され、損失は[0, ..., config.vocab_size]の範囲内のラベルを持つトークンに対してのみ計算されます。 - use_cache (
bool、任意) —Trueに設定すると、past_key_valuesのキーバリュー状態が返され、デコーディングの高速化に利用できます（past_key_valuesを参照）。 - logits_to_keep (
Union[int, torch.Tensor]、省略可、デフォルトは0) —intの場合、最後のlogits_to_keepトークンについて logits を計算します。0の場合、すべてのinput_idsについて logits を計算します（特殊ケース）。生成には最後のトークンの logits だけで十分であり、そのトークンのみについて計算することでメモリを節約できます。これは、長いシーケンスや大規模な語彙サイズの場合に特に顕著な効果があります。torch.Tensorの場合、シーケンス長次元で保持するインデックスに対応する 1 次元テンソルである必要があります。これは、パックされたテンソル形式（バッチとシーケンス長を単一の次元にまとめた形式）を使用する場合に有用です。
戻り値
MoeCausalLMOutputWithPast または tuple(torch.FloatTensor)
MoeCausalLMOutputWithPast、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（NemotronHConfig）や入力に応じて、さまざまな要素で構成されます。
NemotronHForCausalLMのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
loss (
torch.FloatTensor、shape(1,)、optional、labelsが指定された場合に返されます) — 言語モデリングの損失（次のトークン予測用）。logits (
torch.FloatTensor、shape(batch_size, sequence_length, config.vocab_size)) — 言語モデリングヘッドの予測スコア（SoftMax 適用前の各語彙トークンのスコア）。aux_loss (
torch.FloatTensor、optional、output_router_logits=Trueが渡された場合、またはconfig.output_router_logits=Trueの場合、かつモデルがロードバランシング損失でルーターを学習する場合に返されます) — スパースモジュールのロードバランシング用の補助損失。ルーターバイアスによってエキスパートをバランスさせるモデル（DeepSeek-V3 とそこから派生したアーキテクチャ）は、router_logitsを返しながらも、ここではNoneを返します。router_logits (
tuple(torch.FloatTensor)、任意、output_router_logits=Trueが渡された場合またはconfig.output_router_logits=Trueの場合に返されます) — 各スパース層に対応するtorch.FloatTensorのタプルで、形状は(batch_size * sequence_length, num_experts)です。MoEルーターによって計算される生のルーターロジットです。ロードバランシング損失の計算や、トークンがどのようにエキスパートにディスパッチされるかの確認に使用できます。
past_key_values (
Cache、任意、use_cache=Trueが渡された場合またはconfig.use_cache=Trueの場合に返されます) — Cache のインスタンスです。詳細については、kv cache ガイドを参照してください。逐次デコーディングを高速化するために使用できる（
past_key_values入力参照）、事前計算済みの隠れ状態（自己注意ブロックのキーとバリュー）が含まれます。hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返されます)—torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力におけるモデルのHidden-states、および任意の初期埋め込み出力。
attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます)—torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(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."