# Switch Transformers [Switch Transformers](https://huggingface.co/papers/2101.03961)は、MLP層がMixture-of-Experts (MoE)に置き換えられたスパースなT5モデルです。ルーティング機構によって各トークンが特定のエキスパートに関連付けられ、各エキスパートはデンスなMLPです。スパース性によりスケーリングが向上し、ルーティング機構によりモデルが実行時に関連する重みを動的に選択できるため、モデルの容量が増大します。 すべてのオリジナルのSwitch Transformersチェックポイントは、[Switch Transformer](https://huggingface.co/collections/google/switch-transformers-release-6548c35c6507968374b56d1f)コレクション内で確認できます。 > [!TIP] > このモデルは、[ybelkada](https://huggingface.co/ybelkada) と [ArthurZ](https://huggingface.co/ArthurZ) によって提供されました。 > > 右側のサイドバーにあるSwitch Transformersモデルをクリックすると、Switch Transformersをさまざまな自然言語タスクに適用する方法の例をさらに確認できます。 以下の例では、[Pipeline](/docs/transformers/main/ja/main_classes/pipelines#transformers.Pipeline)、[AutoModel](/docs/transformers/main/ja/model_doc/auto#transformers.AutoModel)、およびコマンドラインからマスクされたトークンを予測する方法を示しています。 ```python from transformers import AutoModelForSeq2SeqLM, AutoTokenizer tokenizer = AutoTokenizer.from_pretrained("google/switch-base-8") model = AutoModelForSeq2SeqLM.from_pretrained("google/switch-base-8", device_map="auto") input_text = "The capital of France is ." input_ids = tokenizer(input_text, return_tensors="pt").input_ids.to(0) outputs = model.generate(input_ids) print(tokenizer.decode(outputs[0])) ``` Quantization は、重みを低精度で表現することで、大規模モデルのメモリ負荷を軽減します。利用可能な Quantization バックエンドの詳細については、[Quantization](../quantization/overview) の概要を参照してください。 以下の例では、[bitsandbytes](../quantization/bitsandbytes) を使用して、重みを 8 ビットにのみ量子化しています。 ```python # pip install bitsandbytes from transformers import AutoModelForSeq2SeqLM, AutoTokenizer, BitsAndBytesConfig tokenizer = AutoTokenizer.from_pretrained("google/switch-base-8") quantization_config = BitsAndBytesConfig(load_in_8bit=True) model = AutoModelForSeq2SeqLM.from_pretrained("google/switch-base-8", device_map="auto", quantization_config=quantization_config) input_text = "The capital of France is ." input_ids = tokenizer(input_text, return_tensors="pt").input_ids.to(0) outputs = model.generate(input_ids) print(tokenizer.decode(outputs[0])) ``` ## SwitchTransformersConfig[[transformers.SwitchTransformersConfig]] #### transformers.SwitchTransformersConfig[[transformers.SwitchTransformersConfig]] ```python transformers.SwitchTransformersConfig(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, 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, is_encoder_decoder: bool = True, vocab_size: int = 32128, d_model: int = 768, d_kv: int = 64, d_ff: int = 2048, expert_capacity: int = 64, num_layers: int = 12, num_sparse_encoder_layers: int = 3, num_decoder_layers: int | None = 12, num_sparse_decoder_layers: int = 3, num_heads: int = 12, num_experts: int = 8, router_bias: bool = False, router_jitter_noise: int | float = 0.01, router_dtype: typing.Literal['float32', 'float16', 'bfloat16'] = 'float32', router_ignore_padding_tokens: bool = False, relative_attention_num_buckets: int = 32, relative_attention_max_distance: int = 128, dropout_rate: float | int = 0.1, layer_norm_epsilon: float = 1e-06, router_z_loss_coef: float = 0.001, router_aux_loss_coef: float = 0.001, initializer_factor: float = 1.0, dense_act_fn: str = 'relu', add_router_probs: bool = False, use_cache: bool = True, pad_token_id: int | None = 0, eos_token_id: int | list[int] | None = 1, bos_token_id: int | None = None, tie_word_embeddings: bool = True, is_decoder: bool = False, add_cross_attention: bool = False) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/configuration_switch_transformers.py#L26) **パラメータ:** is_encoder_decoder (`bool`、*任意*、デフォルトは`True`) : モデルがエンコーダー/デコーダーとして使用されるかどうかを示します。 vocab_size (`int`、*任意*、デフォルトは `32128`) : モデルの語彙サイズ。`input_ids` で表現できるトークンの種類数を定義します。 d_model (`int`、*任意*、デフォルトは`768`) : エンコーダ層とプーラー層のサイズ。 d_kv (`int`、*任意*、デフォルトは`64`) : アテンションヘッドごとのキー、クエリ、バリューの射影サイズ。射影層の`inner_dim`は`num_heads * d_kv`として定義されます。 d_ff (`int`、*任意*、デフォルトは`2048`) : MLP 表現の次元数。 expert_capacity (`int`、*任意*、デフォルトは`64`) : 各エキスパートが処理できるトークンの数です。`None`の場合、`expert_capacity`は`(sequence_length / num_experts) * capacity_factor`に設定されます。 num_layers (`int`, *任意*, デフォルトは `12`) : Transformer デコーダーの隠れ層の数。 num_sparse_encoder_layers (`int`、*optional*、デフォルトは 3) : Transformer エンコーダー層におけるスパース（MoE）な dense hidden 層の数。注： `num_layers=1` とともに 0 に設定した場合、スパースステップの計算により、現在の実装ではスパース層が作成される可能性があります。このエッジケースは、既存のチェックポイントでは発生しません。 num_decoder_layers (`int`、*任意*、デフォルトは`12`) : Transformer デコーダーの隠れ層の数。設定されていない場合は、`num_layers` と同じ値が使用されます。 num_sparse_decoder_layers (`int`、*optional*、デフォルト値は 3) : Transformer デコーダー層におけるスパース（MoE）な dense hidden layer の数です。注意: `num_decoder_layers=1` とともに 0 に設定した場合、スパースステップの計算により、現在の実装ではスパース層が作成される可能性があります。このエッジケースは、既存のチェックポイントでは発生しません。 num_heads (`int`、*任意*、デフォルトは `12`) : Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。 num_experts (`int`、*optional*、デフォルトは`8`) : MoE層におけるルーティング対象のエクスパートの数。 router_bias (`bool`、*任意*、デフォルトは`False`) : ルーターにバイアスを追加するかどうか。 router_jitter_noise (`Union[int, float]`、*任意*、デフォルトは`0.01`) : 学習中にルーターのロジットに追加するノイズの量。より良いロードバランスのために使用されます。 router_dtype (`str`、*任意*、デフォルトは`"float32"`) : ルーターに使用される`dtype`です。[論文](https://huggingface.co/papers/2101.03961)の*選択的精度*に関する議論で指定されている通り、`dtype`は`"float32"`のままにしておくことが望ましいです。 router_ignore_padding_tokens (`bool`、*任意*、デフォルトは`False`) : ルーティング時にパディングトークンを無視するかどうか。 relative_attention_num_buckets (`int`、*optional*、デフォルトは 32) : 各アテンション層で使用するバケット数。 relative_attention_max_distance (`int`、*optional*、デフォルトは 128) : バケット分離における、長いシーケンスの最大距離。 dropout_rate (`Union[float, int]`、*任意*、デフォルトは`0.1`) : すべての dropout 層の比率。 layer_norm_epsilon (`float`、*任意*、デフォルトは`1e-06`) : Layer Normalization 層で使用する epsilon です。 router_z_loss_coef (`float`、*任意*、デフォルトは`0.001`) : ルーターのz-lossの係数です。大きなルーターのlogitsをペナルティすることで、トレーニングの安定性を向上させます。 router_aux_loss_coef (`float`、*任意*、デフォルトは `0.001`) : 補助的なロードバランシング損失の係数です。MoE モデルにおける不均一なエキスパートルーティングをペナルティするために使用されます。 initializer_factor (`float`、*任意*、デフォルトは`1.0`) : すべての重み行列を初期化する係数です（1に保つ必要があります。初期化テスト用に内部で使用されます）。 dense_act_fn (`string`、*任意*、デフォルトは`"relu"`) : 使用するフィードフォワード層の種類。`"relu"`または`"gated-gelu"`のいずれかである必要があります。SwitchTransformersv1.1は`"gated-gelu"`フィードフォワード投影を使用しています。元のSwitchTransformersは`"relu"`を使用しています。 add_router_probs (`bool`、*任意*、デフォルトは`False`) : ルーターの補助損失を計算するために、ルーターの確率を出力するかどうか。 use_cache (`bool`、*任意*、デフォルトは `True`) : モデルが最後のキー/バリューアテンションを返すかどうか（すべてのモデルで利用されるわけではありません）。`config.is_decoder=True` の場合、またはモデルがデコーダー専用の生成モデルである場合にのみ関連します。 pad_token_id (`int`, *任意*, デフォルトは `0`) : 語彙内でパディングに使用されるトークン ID。 eos_token_id (`Union[int, list[int]]`、*任意*、デフォルトは `1`) : 語彙内でストリーム終了に使用されるトークン ID。 bos_token_id (`int`, *任意*) : 語彙内でストリームの開始に使用されるトークン ID。 tie_word_embeddings (`bool`、*任意*、デフォルトは`True`) : モデルの`tied_weights_keys`マッピングに従って重み埋め込みを共有するかどうか。 is_decoder (`bool`, *任意*, デフォルトは `False`) : モデルがデコーダーとして使用されるかどうかを指定します。`False` の場合、モデルはエンコーダーとして使用されます。 add_cross_attention (`bool`、*任意*、デフォルトは`False`) : モデルにクロスアテンション層を追加するかどうか。 これはSwitchTransformersModelの設定を保存するための設定クラスです。指定された引数に基づいてSwitch Transformersモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[google/switch-base-8](https://huggingface.co/google/switch-base-8)と類似した設定が得られます。 設定オブジェクトは [PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/main/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。 ## SwitchTransformersTop1Router[[transformers.SwitchTransformersTop1Router]] #### transformers.SwitchTransformersTop1Router[[transformers.SwitchTransformersTop1Router]] ```python transformers.SwitchTransformersTop1Router(config: SwitchTransformersConfig) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L52) トークンを用いたルーターは、トップ1のエキスパート割り当てを選択します。 このルーターは、Switch Transformer (https://huggingface.co/papers/2101.03961) と V-MoE (https://huggingface.co/papers/2106.05974) と同じメカニズムを使用しています。トークンは上位のエキスパートを選択します。アイテムは router_probs でソートされ、その後、選択したエキスパートにルーティングされますが、そのエキスパートの expert_capacity に達するまでです。**各トークンがエキスパートによって処理される保証はありません**。また、各エキスパートが少なくとも1つのトークンを受け取る保証もありません。 #### forward[[transformers.SwitchTransformersTop1Router.forward]] ```python forward(hidden_states: Tensor) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L72) **パラメータ:** hidden_states (`torch.Tensor`) : (batch_size, sequence_length, hidden_dim) の形状のテンソル。ルーターの確率がこのテンソルから計算されます。 **戻り値:** expert_index (`torch.Tensor`) 形状 (batch_size, sequence_length, num_experts) の One-hot dispatch mask。容量を超えてエキスパートにルーティングされたトークンはマスクされます。router_probs (`torch.Tensor`): 各トークンについて選択されたエキスパートの確率を保持する、形状 (batch_size, sequence_length, 1) のテンソル。エキスパートの出力をスケーリングするために使用されます。router_logits (`torch.Tensor`): 生のルーターロジットに対応する、形状 (batch_size, sequence_length, num_experts) のロジットテンソル。後でルーターの z-loss を計算するために使用されます。 入力された隠れ状態からルーターの確率を計算します。 ## SwitchTransformersSparseMLP[[transformers.SwitchTransformersSparseMLP]] #### transformers.SwitchTransformersSparseMLP[[transformers.SwitchTransformersSparseMLP]] ```python transformers.SwitchTransformersSparseMLP(config: SwitchTransformersConfig) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L182) #### forward[[transformers.SwitchTransformersSparseMLP.forward]] ```python forward(hidden_states: Tensor) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L188) ## SwitchTransformersModel[[transformers.SwitchTransformersModel]] #### transformers.SwitchTransformersModel[[transformers.SwitchTransformersModel]] ```python transformers.SwitchTransformersModel(config: SwitchTransformersConfig) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L802) **パラメータ:** config ([SwitchTransformersConfig](/docs/transformers/main/ja/model_doc/switch_transformers#transformers.SwitchTransformersConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを参照してください。 特定のヘッドを付加せずに生の隠れ状態を出力する、素のSwitch Transformers Model。 このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。 このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。 #### forward[[transformers.SwitchTransformersModel.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.FloatTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, encoder_outputs: tuple[tuple[torch.FloatTensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, **kwargs: *) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L830) **パラメータ:** input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids) attention_mask (`torch.FloatTensor`、形状 `(batch_size, sequence_length)`、*任意*) : パディングトークンのインデックスに対してアテンションを実行しないためのマスク。`[0, 1]` から選択されるマスクの値: - **マスクされない**トークンは 1、**マスクされる**トークンは 0。 [アテンションマスクとは?](../glossary#attention-mask) decoder_input_ids (`torch.LongTensor`、shape `(batch_size, target_sequence_length)`、*任意*) : 語彙におけるデコーダー入力シーケンスのトークンインデックス。[AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用してインデックスを取得できます。詳細は [PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。[デコーダー入力 ID とは？](../glossary#decoder-input-ids) decoder_attention_mask (`torch.BoolTensor`、形状 `(batch_size, target_sequence_length)`、*任意*) : 特定のトークンインデックスに対するアテンションの実行を回避するためのマスク。デフォルトでは、モデルが未来を予測するために過去の入力のみを参照できるようにするため、因果マスクが使用されます。 encoder_outputs (`tuple[tuple[torch.FloatTensor]]`, *任意*) : (`last_hidden_state`, *任意*: `hidden_states`, *任意*: `attentions`) のタプルです。`last_hidden_state` は形状 `(batch_size, sequence_length, hidden_size)` を持ち、エンコーダーの最終層の出力における隠れ状態のシーケンスです。*任意*) デコーダーのクロスアテンションで使用されます。 past_key_values (`~cache_utils.Cache`, *任意*) : 逐次デコードを高速化するために使用できる、事前計算された hidden-states（self-attention ブロックおよび cross-attention ブロック内の key と value）です。通常、`use_cache=True` または `config.use_cache=True` の場合、モデルがデコードの以前の段階で返した `past_key_values` で構成されます。入力として許可されるのは [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/main/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。 inputs_embeds (`torch.Tensor`、shape `(batch_size, sequence_length, hidden_size)`、*任意*) : `input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、`input_ids` のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 decoder_inputs_embeds (`torch.Tensor`、shape `(batch_size, target_sequence_length, hidden_size)`、*任意*) : `decoder_input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。`past_key_values` を使用する場合、`decoder_inputs_embeds` の最後の部分のみを入力すればよい場合があります（`past_key_values` を参照）。`decoder_input_ids` のインデックスを関連するベクトルに変換する方法を、モデル内部の埋め込みルックアップ行列よりも細かく制御したい場合に便利です。 `decoder_input_ids` と `decoder_inputs_embeds` の両方が設定されていない場合、`decoder_inputs_embeds` は `inputs_embeds` の値を採ります。 **戻り値:** `Seq2SeqMoEModelOutput` または `tuple(torch.FloatTensor)` `None` や入力に応じて、さまざまな要素で構成される`Seq2SeqMoEModelOutput`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。 [SwitchTransformersModel](/docs/transformers/main/ja/model_doc/switch_transformers#transformers.SwitchTransformersModel) の forward メソッドは、`__call__` という特殊メソッドをオーバーライドします。 この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。 - **last_hidden_state** (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`) -- モデルのデコーダーの最終層の出力における、隠れ状態のシーケンス。 `past_key_values`が使用されている場合、出力されるのは、形状`(batch_size, 1, hidden_size)`のシーケンスの最後の隠れ状態のみです。 - **past_key_values** (`EncoderDecoderCache`、*任意*、`use_cache=True` が渡された場合または `config.use_cache=True` の場合に返されます) -- [EncoderDecoderCache](/docs/transformers/main/ja/internal/generation_utils#transformers.EncoderDecoderCache) のインスタンスです。詳細については、[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。 逐次デコーディングを高速化するために使用できる（`past_key_values` 入力参照）、事前計算済みの隠れ状態（自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー）が含まれます。 - **decoder_hidden_states** (`tuple(torch.FloatTensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返される) -- `torch.FloatTensor` のタプル（モデルに埋め込み層がある場合はその出力用 + 各層の出力用）で、形状は `(batch_size, sequence_length, hidden_size)` です。 各層の出力におけるデコーダーのHidden-states、および任意の初期埋め込み出力。 - **decoder_attentions** (`tuple(torch.FloatTensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.FloatTensor` のタプル（各レイヤーごとに1つ）で、形状は `(batch_size, num_heads, sequence_length, sequence_length)` です。 自己アテンションヘッドにおける加重平均を計算するために使用される、アテンションのsoftmax後のデコーダーのアテンション重み。 - **decoder_router_logits** (`tuple(torch.FloatTensor)`、*optional*、`output_router_logits=True` が渡された場合、または `config.add_router_probs=True` の場合に返されます) -- 各層に対応する `torch.FloatTensor` のタプルで、形状は `(batch_size, sequence_length, num_experts)` です。 デコーダーモデルのルーターロジット。Mixture of Expertsモデルの補助損失を計算するために使用されます。 - **cross_attentions** (`tuple(torch.FloatTensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.FloatTensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。 クロスアテンション層のアテンション重みは、アテンションのsoftmax適用後に計算され、クロスアテンションヘッドにおける加重平均の計算に使用されます。 - **encoder_last_hidden_state** (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*optional*) -- モデルのエンコーダーの最終層の出力における、隠れ状態のシーケンス。 - **encoder_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、および任意の初期埋め込み出力。 - **encoder_attentions** (`tuple(torch.FloatTensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.FloatTensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。 アテンションのsoftmaxを適用した後のエンコーダーのアテンション重み。自己アテンションヘッドにおける加重平均の計算に使用されます。 - **encoder_router_logits** (`tuple(torch.FloatTensor)`、*optional*、`output_router_logits=True` が渡された場合、または `config.add_router_probs=True` の場合に返されます) -- 各層に対応する `torch.FloatTensor` のタプルで、形状は `(batch_size, sequence_length, num_experts)` です。 エンコーダーモデルのルーターロジット。スパースモジュールの補助損失およびz_lossの計算に使用されます。 ## SwitchTransformersForConditionalGeneration[[transformers.SwitchTransformersForConditionalGeneration]] #### transformers.SwitchTransformersForConditionalGeneration[[transformers.SwitchTransformersForConditionalGeneration]] ```python transformers.SwitchTransformersForConditionalGeneration(config: SwitchTransformersConfig) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L944) **パラメータ:** config ([SwitchTransformersConfig](/docs/transformers/main/ja/model_doc/switch_transformers#transformers.SwitchTransformersConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを参照してください。 `language modeling`ヘッドを上部に備えたSWITCH_TRANSFORMERSモデル。 このモデルは [PreTrainedModel](/docs/transformers/main/ja/main_classes/model#transformers.PreTrainedModel) を継承しています。ライブラリがすべてのモデルに対して実装している汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。 このモデルは、PyTorchの[torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)のサブクラスでもあります。通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。 #### forward[[transformers.SwitchTransformersForConditionalGeneration.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.FloatTensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.FloatTensor] = None, decoder_inputs_embeds: typing.Optional[torch.FloatTensor] = None, labels: typing.Optional[torch.LongTensor] = None, output_router_logits: bool | None = False, **kwargs: *) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L981) **パラメータ:** input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids) attention_mask (`torch.FloatTensor`、形状 `(batch_size, sequence_length)`、*任意*) : パディングトークンのインデックスに対してアテンションを実行しないためのマスク。`[0, 1]` から選択されるマスクの値: - **マスクされない**トークンは 1、**マスクされる**トークンは 0。 [アテンションマスクとは?](../glossary#attention-mask) decoder_input_ids (`torch.LongTensor`、shape `(batch_size, target_sequence_length)`、*任意*) : 語彙におけるデコーダー入力シーケンスのトークンインデックス。[AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用してインデックスを取得できます。詳細は [PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。[デコーダー入力 ID とは？](../glossary#decoder-input-ids) decoder_attention_mask (`torch.BoolTensor`、形状 `(batch_size, target_sequence_length)`、*任意*) : 特定のトークンインデックスに対するアテンションの実行を回避するためのマスク。デフォルトでは、モデルが未来を予測するために過去の入力のみを参照できるようにするため、因果マスクが使用されます。 encoder_outputs (`tuple[tuple[torch.Tensor]]`, *任意*) : (`last_hidden_state`, *任意*: `hidden_states`, *任意*: `attentions`) のタプルです。`last_hidden_state` は形状 `(batch_size, sequence_length, hidden_size)` を持ち、*任意* です。エンコーダーの最終層の出力における隠れ状態のシーケンスです。デコーダーのクロスアテンションで使用されます。 past_key_values (`~cache_utils.Cache`, *任意*) : 逐次デコードを高速化するために使用できる、事前計算された hidden-states（self-attention ブロックおよび cross-attention ブロック内の key と value）です。通常、`use_cache=True` または `config.use_cache=True` の場合、モデルがデコードの以前の段階で返した `past_key_values` で構成されます。入力として許可されるのは [Cache](/docs/transformers/main/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/main/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。 inputs_embeds (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*任意*) : `input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、`input_ids` のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 decoder_inputs_embeds (`torch.FloatTensor`、shape `(batch_size, target_sequence_length, hidden_size)`、*任意*) : `decoder_input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。`past_key_values` を使用する場合、`decoder_inputs_embeds` の最後の部分のみを入力すれば十分です（`past_key_values` を参照）。モデル内部の埋め込みルックアップ行列よりも、`decoder_input_ids` のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 `decoder_input_ids` と `decoder_inputs_embeds` の両方が設定されていない場合、`decoder_inputs_embeds` は `inputs_embeds` の値を採ります。 labels (`torch.LongTensor`、形状 `(batch_size, sequence_length)`、*任意*) : マスク言語モデリング損失を計算するためのラベル。インデックスは `[0, ..., config.vocab_size]` の範囲内であるか、-100 である必要があります（`input_ids` のドキュメント文字列を参照）。インデックスが `-100` に設定されたトークンは無視（マスク）され、損失は `[0, ..., config.vocab_size]` の範囲内のラベルを持つトークンに対してのみ計算されます。 output_router_logits (`bool`, *任意*, デフォルトは `False`) : すべてのルーターの logits を返すかどうか。ルーター損失の計算に有用であり、推論時には返すべきではありません。 **戻り値:** `Seq2SeqMoEOutput` または `tuple(torch.FloatTensor)` `Seq2SeqMoEOutput`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（`None`）や入力に応じて、さまざまな要素で構成されます。 [SwitchTransformersForConditionalGeneration](/docs/transformers/main/ja/model_doc/switch_transformers#transformers.SwitchTransformersForConditionalGeneration) の forward メソッドは、`__call__` という特殊メソッドをオーバーライドします。 この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。 - **loss** (`torch.FloatTensor`、shape `(1,)`、*optional*、`labels` が指定された場合に返されます) -- 言語モデリングの損失。 - **logits** (`torch.FloatTensor`、shape `(batch_size, sequence_length, config.vocab_size)`) -- 言語モデリングヘッドの予測スコア（SoftMax 適用前の各語彙トークンのスコア）。 - **past_key_values** (`EncoderDecoderCache`、*任意*、`use_cache=True` が渡された場合または `config.use_cache=True` の場合に返されます) -- [EncoderDecoderCache](/docs/transformers/main/ja/internal/generation_utils#transformers.EncoderDecoderCache) のインスタンスです。詳細については、[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。 逐次デコーディングを高速化するために使用できる（`past_key_values` 入力参照）、事前計算済みの隠れ状態（自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー）が含まれます。 - **decoder_hidden_states** (`tuple(torch.FloatTensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返される) -- `torch.FloatTensor` のタプル（モデルに埋め込み層がある場合はその出力用 + 各層の出力用）で、形状は `(batch_size, sequence_length, hidden_size)` です。 各層の出力および初期埋め込み出力における、デコーダーの隠れ状態。 - **decoder_attentions** (`tuple(torch.FloatTensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.FloatTensor` のタプル（各レイヤーごとに1つ）で、形状は `(batch_size, num_heads, sequence_length, sequence_length)` です。 自己アテンションヘッドにおける加重平均を計算するために使用される、アテンションのsoftmax後のデコーダーのアテンション重み。 - **decoder_router_logits** (`tuple(torch.FloatTensor)`、*optional*、`output_router_logits=True` が渡された場合、または `config.add_router_probs=True` の場合に返されます) -- 各層に対応する `torch.FloatTensor` のタプルで、形状は `(batch_size, sequence_length, num_experts)` です。 デコーダーモデルのルーターロジット。Mixture of Expertsモデルの補助損失を計算するために使用されます。 - **cross_attentions** (`tuple(torch.FloatTensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.FloatTensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。 クロスアテンション層のアテンション重みは、アテンションのsoftmax適用後に計算され、クロスアテンションヘッドにおける加重平均の計算に使用されます。 - **encoder_last_hidden_state** (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*optional*) -- モデルのエンコーダーの最終層の出力における、隠れ状態のシーケンス。 - **encoder_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)` です。 各層の出力および初期埋め込み出力におけるエンコーダーの隠れ状態。 - **encoder_attentions** (`tuple(torch.FloatTensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.FloatTensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。 アテンションのsoftmaxを適用した後のエンコーダーのアテンション重み。自己アテンションヘッドにおける加重平均の計算に使用されます。 - **encoder_router_logits** (`tuple(torch.FloatTensor)`、*optional*、`output_router_logits=True` が渡された場合、または `config.add_router_probs=True` の場合に返されます) -- 各層に対応する `torch.FloatTensor` のタプルで、形状は `(batch_size, sequence_length, num_experts)` です。 エンコーダーモデルのルーターロジット。Mixture of Expertsモデルにおいて、補助損失およびz_lossを計算するために使用されます。 ## SwitchTransformersEncoderModel[[transformers.SwitchTransformersEncoderModel]] #### transformers.SwitchTransformersEncoderModel[[transformers.SwitchTransformersEncoderModel]] ```python transformers.SwitchTransformersEncoderModel(config: SwitchTransformersConfig) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L1098) #### forward[[transformers.SwitchTransformersEncoderModel.forward]] ```python forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.FloatTensor] = None, inputs_embeds: typing.Optional[torch.FloatTensor] = None, use_cache: bool | None = None, **kwargs: *) ``` [ソース](https://github.com/huggingface/transformers/blob/main/src/transformers/models/switch_transformers/modeling_switch_transformers.py#L1120) **パラメータ:** input_ids (`torch.LongTensor`、shape `(batch_size, sequence_length)`、*任意*) : 語彙における入力シーケンスのトークンインデックスです。デフォルトでは、パディングは無視されます。インデックスは [AutoTokenizer](/docs/transformers/main/ja/model_doc/auto#transformers.AutoTokenizer) を使用して取得できます。詳細については、[PreTrainedTokenizer.encode()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) および [PreTrainedTokenizer.__call__()](/docs/transformers/main/ja/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) を参照してください。 [入力IDとは何ですか？](../glossary#input-ids) attention_mask (`torch.FloatTensor`、形状 `(batch_size, sequence_length)`、*任意*) : パディングトークンのインデックスに対してアテンションを実行しないためのマスク。`[0, 1]` から選択されるマスクの値: - **マスクされない**トークンは 1、**マスクされる**トークンは 0。 [アテンションマスクとは?](../glossary#attention-mask) inputs_embeds (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`、*任意*) : `input_ids` を渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込み参照行列よりも、`input_ids` のインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 use_cache (`bool`, *任意*) : `True`に設定すると、`past_key_values`のキーバリュー状態が返され、デコーディングの高速化に利用できます（`past_key_values`を参照）。 **戻り値:** `MoEModelOutput` または `tuple(torch.FloatTensor)` `MoEModelOutput`、または`torch.FloatTensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（`None`）や入力に応じて、さまざまな要素で構成されます。 [SwitchTransformersEncoderModel](/docs/transformers/main/ja/model_doc/switch_transformers#transformers.SwitchTransformersEncoderModel) の forward メソッドは、`__call__` という特殊メソッドをオーバーライドします。 この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。 - **last_hidden_state** (`torch.FloatTensor`、shape `(batch_size, sequence_length, hidden_size)`) -- モデルの最終層の出力における隠れ状態のシーケンス。 - **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後のアテンション重み。自己アテンションヘッド内で加重平均を計算するために使用されます。 - **router_probs** (`tuple(torch.FloatTensor)`、*optional*、`output_router_probs=True` と `config.add_router_probs=True` が渡された場合、または `config.output_router_probs=True` の場合に返されます) -- 各層に対応する `torch.FloatTensor` のタプルで、形状は `(batch_size, sequence_length, num_experts)` です。 Raw router probabilities that are computed by MoE routers, these terms are used to compute the auxiliary loss and the z_loss for Mixture of Experts models.