# Informer

## 概要

Informerモデルは、Haoyi Zhou、Shanghang Zhang、Jieqi Peng、Shuai Zhang、Jianxin Li、Hui Xiong、Wancai Zhang による [Informer: Beyond Efficient Transformer for Long Sequence Time-Series Forecasting](https://huggingface.co/papers/2012.07436) で提案されました。

このメソッドは、Probabilistic Attentionメカニズムを導入し、「lazy」クエリではなく「active」クエリを選択することで、スパースなTransformerを提供します。これにより、vanilla attentionの二次的な計算量とメモリ要件を軽減します。

論文の抄録は以下の通りです。

*電力消費計画などのように、長系列の時間系列の予測を必要とする実世界のアプリケーションは多く存在します。長系列時間系列予測（LSTF）では、出力と入力間の精密な長距離依存性の結合を効率的に捉える能力、すなわちモデルの高い予測能力が求められます。最近の研究では、Transformer が予測能力を向上させる可能性が示されています。しかしながら、Transformer には、二次的な時間計算量、高いメモリ使用量、エンコーダー・デコーダーアーキテクチャに内在する制約など、LSTF に直接適用することを妨げるいくつかの深刻な問題があります。これらの問題に対処するため、LSTF 用の効率的な Transformer ベースのモデルである Informer を設計しました。Informer には、3 つの特徴的な特性があります。(i) ProbSparse 自己注意メカニズムは、時間計算量とメモリ使用量において O(L logL) を達成し、系列の依存性アライメントにおいて同等の性能を示します。(ii) 自己注意蒸留は、カスケード層の入力を半分にすることで支配的な注意を強調し、極端に長い入力系列を効率的に処理します。(iii) 生成スタイルのデコーダーは、概念的には単純ですが、ステップバイステップの方式ではなく、1 回のフォワード操作で長い時間系列を予測するため、長系列予測の推論速度を大幅に向上させます。4 つの大規模データセットでの広範な実験により、Informer が既存の手法を大幅に上回り、LSTF 問題に対する新たなソリューションを提供することが示されました。*

このモデルは [elisim](https://huggingface.co/elisim) と [kashif](https://huggingface.co/kashif) によって提供されました。元のコードは [こちら](https://github.com/zhouhaoyi/Informer2020) で確認できます。

## リソース

Hugging Face 公式およびコミュニティ（🌎で示されています）の、はじめるのに役立つリソースのリストです。ここにリソースを掲載していただくことを希望される場合は、Pull Request を開いてください。レビューいたします。リソースは、既存のリソースと重複するのではなく、新しいことを示すものであることが望ましいです。

- HuggingFaceブログのInformerに関するブログ記事[Multivariate Probabilistic Time Series Forecasting with Informer](https://huggingface.co/blog/informer)をご覧ください。

## InformerConfig[[transformers.InformerConfig]]

#### transformers.InformerConfig[[transformers.InformerConfig]]

```python
transformers.InformerConfig(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, prediction_length: int | None = None, context_length: int | None = None, distribution_output: str = 'student_t', loss: str = 'nll', input_size: int = 1, lags_sequence: list[int] | None = None, scaling: str | bool | None = 'mean', num_dynamic_real_features: int = 0, num_static_real_features: int = 0, num_static_categorical_features: int = 0, num_time_features: int = 0, cardinality: list[int] | None = None, embedding_dimension: list[int] | None = None, d_model: int = 64, encoder_ffn_dim: int = 32, decoder_ffn_dim: int = 32, encoder_attention_heads: int = 2, decoder_attention_heads: int = 2, encoder_layers: int = 2, decoder_layers: int = 2, activation_function: str = 'gelu', dropout: float | int = 0.05, encoder_layerdrop: float | int = 0.1, decoder_layerdrop: float | int = 0.1, attention_dropout: float | int = 0.1, activation_dropout: float | int = 0.1, num_parallel_samples: int = 100, init_std: float = 0.02, use_cache: bool = True, attention_type: str = 'prob', sampling_factor: int = 5, distil: bool = True)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/informer/configuration_informer.py#L24)

**パラメータ:**

is_encoder_decoder (`bool`、*任意*、デフォルトは`True`) : モデルがエンコーダー/デコーダーとして使用されるかどうかを示します。

prediction_length (`int`、*optional*) : デコーダーの予測長です。つまり、モデルの予測ホライズンです。この値は通常、データセットによって決まるため、適切に設定することをお勧めします。

context_length (`int`、*任意*、デフォルトは`prediction_length`) : エンコーダーのコンテキスト長。`None`の場合、コンテキスト長は`prediction_length`と同じになります。

distribution_output (`string`、*任意*、デフォルトは`"student_t"`) : モデルの分布エミッションヘッドです。"student_t"、"normal"、"negative_binomial"のいずれかを指定できます。

loss (`string`、*任意*、デフォルトは `"nll"`) : `distribution_output` ヘッドに対応するモデルの損失関数です。パラメトリックな分布の場合、負の対数尤度 (nll) となり、現在サポートされているのはこれのみです。

input_size (`int`、*optional*、デフォルトは 1) : 対象変数のサイズです。単変量ターゲットの場合はデフォルトで 1 になります。多変量ターゲットの場合は 1 より大きくなります。

lags_sequence (`list[int]`、*optional*、デフォルトは`[1, 2, 3, 4, 5, 6, 7]`) : 入力時系列のラグを共変量として使用します。これはデータの頻度によって決まる場合が多いです。デフォルトは`[1, 2, 3, 4, 5, 6, 7]`ですが、データセットに応じて適切に変更することをお勧めします。

scaling (`string` または `bool`、*省略可能*、デフォルトは `"mean"`) : `None` の場合はスケーラーを適用せず、それ以外の場合は "mean" スケーラー、"std" スケーラー、またはスケーラーなしで入力ターゲットをスケーリングするかどうかを指定します。`True` の場合、スケーラーは "mean" に設定されます。

num_dynamic_real_features (`int`, *任意*, デフォルトは 0) : 動的な実数値特徴量の数。

num_static_real_features (`int`、*任意*、デフォルトは 0) : 静的な実数値特徴量の数。

num_static_categorical_features (`int`、*任意*、デフォルトは 0) : 静的カテゴリカル特徴の数を指定します。

num_time_features (`int`、*任意*、デフォルトは 0) : 入力時系列に含まれる時間特徴量の数。

cardinality (`list[int]`, *任意*) : 静的カテゴリカル特徴量それぞれの基数（異なる値の数）。`num_static_categorical_features` と同じ長さの整数のリストである必要があります。`num_static_categorical_features` が 0 より大きい場合、`None` にすることはできません。

embedding_dimension (`list[int]`, *任意*) : 静的カテゴリカル特徴のそれぞれに対する埋め込みの次元。整数のリストであり、`num_static_categorical_features` と同じ長さである必要があります。`num_static_categorical_features` が 0 より大きい場合、`None` にすることはできません。

d_model (`int`、*任意*、デフォルトは`64`) : エンコーダ層とプーラ層のサイズ。

encoder_ffn_dim (`int`、*任意*、デフォルトは`32`) : エンコーダー内の「中間」層（feed-forward層と呼ばれることが多い）の次元数。

decoder_ffn_dim (`int`、*任意*、デフォルトは `32`) : デコーダー内の「intermediate」（feed-forward と呼ばれることが多い）層の次元数。

encoder_attention_heads (`int`、*optional*、デフォルトは `2`) : Transformer エンコーダーの各アテンション層におけるアテンションヘッドの数。

decoder_attention_heads (`int`、*任意*、デフォルトは `2`) : Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。

encoder_layers (`int`、*任意*、デフォルトは `2`) : Transformer エンコーダーの隠れ層の数。設定されていない場合は、`num_layers` と同じ値が使用されます。

decoder_layers (`int`、*任意*、デフォルトは`2`) : Transformer デコーダーの隠れ層数。設定されていない場合は、`num_layers` と同じ値が使用されます。

activation_function (`str`、*任意*、デフォルトは`gelu`) : デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、`"gelu"`、`"relu"`、`"silu"`など。

dropout (`Union[float, int]`、*任意*、デフォルトは`0.05`) : すべての dropout 層の比率。

encoder_layerdrop (`Union[float, int]`、*任意*、デフォルトは`0.1`) : エンコーダーの LayerDrop 確率です。詳細については、[LayerDrop の論文](see https://huggingface.co/papers/1909.11556)を参照してください。

decoder_layerdrop (`Union[float, int]`、*任意*、デフォルトは`0.1`) : デコーダーの LayerDrop 確率です。詳細については、[LayerDrop の論文](see https://huggingface.co/papers/1909.11556)を参照してください。

attention_dropout (`Union[float, int]`、*任意*、デフォルトは`0.1`) : 注意確率のドロップアウト率。

activation_dropout (`float`、*任意*、デフォルト値は 0.1) : フィードフォワードネットワークの2つの層の間で使用される dropout の確率。

num_parallel_samples (`int`、*optional*、デフォルトは 100) : 推論の各タイムステップで並列に生成するサンプル数。

init_std (`float`、*任意*、デフォルトは`0.02`) : すべての重み行列を初期化するためのtruncated_normal_initializerの標準偏差です。

use_cache (`bool`、*任意*、デフォルトは `True`) : モデルが最後のキー/バリューアテンションを返すかどうか（すべてのモデルで利用されるわけではありません）。`config.is_decoder=True` の場合、またはモデルがデコーダー専用の生成モデルである場合にのみ関連します。

attention_type (`str`、*任意*、デフォルトは "prob") : エンコーダーで使用されるアテンション。"prob"（Informer の ProbAttention）または "full"（バニラ Transformer の標準的な自己アテンション）に設定できます。

sampling_factor (`int`、*optional*、デフォルト値は 5) : ProbSparse サンプリング係数（`attention_type`="prob" の場合のみ有効）。削減されたクエリ行列（Q_reduce）の入力長を制御するために使用されます。

distil (`bool`、*任意*、デフォルトは`True`) : エンコーダーで蒸留を使用するかどうか。

これはInformerModelの設定を保存するための設定クラスです。指定された引数に基づいてInformerモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、[huggingface/informer-tourism-monthly](https://huggingface.co/huggingface/informer-tourism-monthly) と同様の設定が得られます。

設定オブジェクトは [PreTrainedConfig](/docs/transformers/v5.23.0/ja/main_classes/configuration#transformers.PreTrainedConfig) を継承し、モデルの出力を制御するために使用できます。詳細については、[PreTrainedConfig](/docs/transformers/v5.23.0/ja/main_classes/configuration#transformers.PreTrainedConfig) のドキュメントを参照してください。

例:

```python
>>> from transformers import InformerConfig, InformerModel

>>> # Initializing an Informer configuration with 12 time steps for prediction
>>> configuration = InformerConfig(prediction_length=12)

>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = InformerModel(configuration)

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

## InformerModel[[transformers.InformerModel]]

#### transformers.InformerModel[[transformers.InformerModel]]

```python
transformers.InformerModel(config: InformerConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/informer/modeling_informer.py#L994)

**パラメータ:**

config ([InformerConfig](/docs/transformers/v5.23.0/ja/model_doc/informer#transformers.InformerConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/v5.23.0/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

特定のヘッドを付加せず、生の隠れ状態を出力する素のInformer Model。

このモデルは [PreTrainedModel](/docs/transformers/v5.23.0/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.InformerModel.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/informer/modeling_informer.py#L1132)

**パラメータ:**

past_values (`torch.Tensor`、shape は `(batch_size, sequence_length)` または `(batch_size, sequence_length, input_size)`) : 時系列の過去の値です。将来を予測するためのコンテキストとして機能します。このテンソルのシーケンスサイズは、モデルがラグ特徴量（つまり、追加のコンテキストとして機能するために追加される過去の追加の値）を構築するために大きなサイズを使用するため、モデルの `context_length` より大きくなければなりません。 这里的 `sequence_length` は `config.context_length` + `max(config.lags_sequence)` に等しく、`lags_sequence` が設定されていない場合は、`config.context_length` + 7 に等しくなります（デフォルトでは、`config.lags_sequence` の最大のルックバックインデックスは 7 です）。プロパティ `_past_length` は、過去の実際の長さを返します。 `past_values` は、Transformer エンコーダーが受け取る入力です（`static_categorical_features`、`static_real_features`、`past_time_features` およびラグなどの任意の追加特徴量を含む）。 任意ですが、欠損値はゼロに置き換え、`past_observed_mask` によって示す必要があります。 多次元時系列の場合、`input_size` > 1 の次元が必要であり、これはタイムステップごとの時系列の変数の数に対応します。

past_time_features (`torch.Tensor`、形状 `(batch_size, sequence_length, num_features)`) : 必須の時間特徴です。モデルは内部でこれらを `past_values` に追加します。これには、ベクトルとしてエンコードされた（例えば Fourier 特徴として）「年内の月」や「月内の日」などが含まれます。また、いわゆる「年齢」特徴も該当します。これは基本的に、時系列が「人生のどの時点にあるか」をモデルに認識させるのに役立ちます。年齢特徴は、過去の遠いタイムステップでは値が小さく、現在のタイムステップに近づくにつれて単調に増加します。祝日の特徴も、時間特徴の良い例です。これらの特徴は、入力に対する「位置エンコーディング」の役割を果たします。したがって、BERT のようなモデル（位置エンコーディングがモデルのパラメータとして内部からゼロから学習される）とは異なり、Time Series Transformer では追加の時間特徴を提供する必要があります。Time Series Transformer が追加の埋め込みを学習するのは、`static_categorical_features` に対してのみです。追加の動的実数共変量は、予測時にこれらの特徴が既知であるという条件付きで、このテンソルに連結できます。ここでの `num_features` は、`config.`num_time_features` + `config.num_dynamic_real_features` に等しくなります。

past_observed_mask (`torch.BoolTensor`、shape `(batch_size, sequence_length)` または `(batch_size, sequence_length, input_size)`、*任意*) : `past_values` のどの値が観測され、どの値が欠損しているかを示すブールマスク。`[0, 1]` から選択されるマスクの値: - **観測**された値は 1、- **欠損**している値（ゼロに置き換えられた NaN など）は 0。

static_categorical_features (`torch.LongTensor`、shape `(batch_size, number of static categorical features)`、*任意*) : モデルが埋め込みを学習し、その埋め込みを時系列の値に加算する、任意の静的カテゴリ特徴量です。静的カテゴリ特徴量とは、すべてのタイムステップで同じ値を持つ（時間に対して静的な）特徴量です。静的カテゴリ特徴量の典型的な例として、時系列 ID があります。

static_real_features (`torch.Tensor`、形状 `(batch_size, number of static real features)`、*任意*) : モデルが時系列の値に追加する、任意の静的実数特徴量です。静的実数特徴量とは、すべてのタイムステップで同じ値を持つ（時間に対して静的な）特徴量です。静的実数特徴量の典型的な例としては、プロモーション情報が挙げられます。

future_values (`torch.Tensor`、形状は`(batch_size, prediction_length)`または`(batch_size, prediction_length, input_size)`、*optional*) : 時系列の将来の値であり、モデルのラベルとして機能します。`future_values`は、`past_values`が与えられた際に出力すべきものとして、Transformerが学習中に必要とするものです。 这里的シーケンス長は`prediction_length`と等しくなります。 詳細については、デモノートブックとコードスニペットを参照してください。 任意ですが、学習中は欠損値をゼロで置き換え、`future_observed_mask`で示す必要があります。 多次元時系列の場合、`input_size` > 1の次元が必須であり、これは各タイムステップにおける時系列の変数の数に対応します。

future_time_features (`torch.Tensor`、shape は `(batch_size, prediction_length, num_features)`) : 予測ウィンドウに必要な時間特徴です。モデルは内部でこれらを `future_values` に追加します。これには、ベクトルとしてエンコードされた（例えば Fourier features として）「年内の月」や「月内の日」などが含まれます。また、いわゆる「age」特徴も該当します。これは基本的に、時系列が「ライフサイクルのどの時点にあるか」をモデルに認識させるのに役立ちます。Age 特徴は、過去の遠いタイムステップでは値が小さく、現在のタイムステップに近づくにつれて単調に増加します。祝日の特徴も、時間特徴の良い例です。これらの特徴は、入力に対する「位置エンコーディング」の役割を果たします。したがって、BERT のようなモデル（位置エンコーディングがモデルのパラメータとして内部からゼロから学習される）とは異なり、Time Series Transformer では追加の時間特徴を指定する必要があります。Time Series Transformer が追加の埋め込みを学習するのは、`static_categorical_features` に対してのみです。追加の動的な実数共変量は、予測時にこれらの特徴が既知であるという条件のもとで、このテンソルに連結できます。ここでの `num_features` は、`config.num_time_features` + `config.num_dynamic_real_features` に等しくなります。

decoder_attention_mask (`torch.LongTensor`、shape `(batch_size, target_sequence_length)`、*optional*) : 特定のトークンインデックスに対するアテンションの実行を回避するためのマスク。デフォルトでは、モデルが未来を予測する際に過去の入力のみを参照できるようにするため、causal mask が使用されます。

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : `last_hidden_state`、`hidden_states` (*optional*)、`attentions` (*optional*) からなるタプル。`last_hidden_state` は形状 `(batch_size, sequence_length, hidden_size)` (*optional*) を持ち、エンコーダーの最終層の出力における隠れ状態のシーケンスです。デコーダーのクロスアテンションで使用されます。

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/v5.23.0/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/v5.23.0/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。

use_cache (`bool`, *任意*) : `True`に設定すると、`past_key_values`のキーバリュー状態が返され、デコーディングの高速化に利用できます（`past_key_values`を参照）。

**戻り値:** [Seq2SeqTSModelOutput](/docs/transformers/v5.23.0/ja/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) または `tuple(torch.Tensor)`

[Seq2SeqTSModelOutput](/docs/transformers/v5.23.0/ja/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput)、または`torch.Tensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[InformerConfig](/docs/transformers/v5.23.0/ja/model_doc/informer#transformers.InformerConfig)）と入力に応じて、さまざまな要素で構成されます。

[InformerModel](/docs/transformers/v5.23.0/ja/model_doc/informer#transformers.InformerModel)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **last_hidden_state** (`torch.Tensor`、形状 `(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/v5.23.0/ja/internal/generation_utils#transformers.EncoderDecoderCache) のインスタンスです。詳細については、[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。

  逐次デコーディングを高速化するために使用できる（`past_key_values` 入力参照）、事前計算済みの隠れ状態（自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー）が含まれます。
- **decoder_hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用 1 つ + 各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるデコーダーのHidden-states、および任意の初期埋め込み出力。
- **decoder_attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  自己アテンションヘッドにおける加重平均を計算するために使用される、アテンションのsoftmax後のデコーダーのアテンション重み。
- **cross_attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  クロスアテンション層のアテンション重みは、アテンションのsoftmax適用後に計算され、クロスアテンションヘッドにおける加重平均の計算に使用されます。
- **encoder_last_hidden_state** (`torch.Tensor`、形状 `(batch_size, sequence_length, hidden_size)`、*任意*) -- モデルのエンコーダーの最終層の出力における隠れ状態のシーケンス。
- **encoder_hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用 1 つ + 各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるエンコーダーのHidden-states、および任意の初期埋め込み出力。
- **encoder_attentions** (`tuple(torch.Tensor)`、*任意*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- 各レイヤーごとに 1 つの `torch.Tensor` からなるタプルで、形状は `(batch_size, num_heads, sequence_length, sequence_length)` です。

  アテンションのsoftmaxを適用した後のエンコーダーのアテンション重み。自己アテンションヘッドにおける加重平均の計算に使用されます。
- **loc** (`torch.Tensor`、形状 `(batch_size,)` または `(batch_size, input_size)`、*任意*) -- 各時系列のコンテキストウィンドウの値をシフトするために使用されます。これにより、モデルへの入力が同じ大きさになり、その後元の大きさにシフトバックされます。
- **scale** (`torch.Tensor`、形状 `(batch_size,)` または `(batch_size, input_size)`、*任意*) -- 各時系列のコンテキストウィンドウのスケーリング値。モデルへの入力値を同じ大きさ（magnitude）に揃えるために使用し、その後、元の大きさに戻すために使用されます。
- **static_features** (`torch.Tensor`、形状 `(batch_size, feature size)`、*任意*) -- バッチ内の各時系列の静的特徴量です。推論時に共変量にコピーされます。

例:

```python
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import InformerModel

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = InformerModel.from_pretrained("huggingface/informer-tourism-monthly")

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> last_hidden_state = outputs.last_hidden_state
```

## InformerForPrediction[[transformers.InformerForPrediction]]

#### transformers.InformerForPrediction[[transformers.InformerForPrediction]]

```python
transformers.InformerForPrediction(config: InformerConfig)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/informer/modeling_informer.py#L1357)

**パラメータ:**

config ([InformerConfig](/docs/transformers/v5.23.0/ja/model_doc/informer#transformers.InformerConfig)) : モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、[from_pretrained()](/docs/transformers/v5.23.0/ja/main_classes/model#transformers.PreTrainedModel.from_pretrained) メソッドを確認してください。

時系列予測用に分布ヘッドを上部に備えたInformerモデル。

このモデルは [PreTrainedModel](/docs/transformers/v5.23.0/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.InformerForPrediction.forward]]

```python
forward(past_values: Tensor, past_time_features: Tensor, past_observed_mask: Tensor, static_categorical_features: typing.Optional[torch.Tensor] = None, static_real_features: typing.Optional[torch.Tensor] = None, future_values: typing.Optional[torch.Tensor] = None, future_time_features: typing.Optional[torch.Tensor] = None, future_observed_mask: typing.Optional[torch.Tensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: list[torch.Tensor] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[ソース](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/informer/modeling_informer.py#L1392)

**パラメータ:**

past_values (`torch.Tensor`、shape は `(batch_size, sequence_length)` または `(batch_size, sequence_length, input_size)`) : 時系列の過去の値です。将来を予測するためのコンテキストとして機能します。このテンソルのシーケンスサイズは、モデルがラグ特徴量（つまり、追加のコンテキストとして機能するために追加される過去の追加の値）を構築するために大きなサイズを使用するため、モデルの `context_length` より大きくなければなりません。 这里的 `sequence_length` は `config.context_length` + `max(config.lags_sequence)` に等しく、`lags_sequence` が設定されていない場合は、`config.context_length` + 7 に等しくなります（デフォルトでは、`config.lags_sequence` の最大のルックバックインデックスは 7 です）。プロパティ `_past_length` は、過去の実際の長さを返します。 `past_values` は、Transformer エンコーダーが受け取る入力です（`static_categorical_features`、`static_real_features`、`past_time_features` およびラグなどの任意の追加特徴量を含む）。 任意ですが、欠損値はゼロに置き換え、`past_observed_mask` によって示す必要があります。 多次元時系列の場合、`input_size` > 1 の次元が必要であり、これはタイムステップごとの時系列の変数の数に対応します。

past_time_features (`torch.Tensor`、形状 `(batch_size, sequence_length, num_features)`) : 必須の時間特徴です。モデルは内部でこれらを `past_values` に追加します。これには、ベクトルとしてエンコードされた（例えば Fourier 特徴として）「年内の月」や「月内の日」などが含まれます。また、いわゆる「年齢」特徴も該当します。これは基本的に、時系列が「人生のどの時点にあるか」をモデルに認識させるのに役立ちます。年齢特徴は、過去の遠いタイムステップでは値が小さく、現在のタイムステップに近づくにつれて単調に増加します。祝日の特徴も、時間特徴の良い例です。これらの特徴は、入力に対する「位置エンコーディング」の役割を果たします。したがって、BERT のようなモデル（位置エンコーディングがモデルのパラメータとして内部からゼロから学習される）とは異なり、Time Series Transformer では追加の時間特徴を提供する必要があります。Time Series Transformer が追加の埋め込みを学習するのは、`static_categorical_features` に対してのみです。追加の動的実数共変量は、予測時にこれらの特徴が既知であるという条件付きで、このテンソルに連結できます。ここでの `num_features` は、`config.`num_time_features` + `config.num_dynamic_real_features` に等しくなります。

past_observed_mask (`torch.BoolTensor`、shape `(batch_size, sequence_length)` または `(batch_size, sequence_length, input_size)`、*任意*) : `past_values` のどの値が観測され、どの値が欠損しているかを示すブールマスク。`[0, 1]` から選択されるマスクの値: - **観測**された値は 1、- **欠損**している値（ゼロに置き換えられた NaN など）は 0。

static_categorical_features (`torch.LongTensor`、shape `(batch_size, number of static categorical features)`、*任意*) : モデルが埋め込みを学習し、その埋め込みを時系列の値に加算する、任意の静的カテゴリ特徴量です。静的カテゴリ特徴量とは、すべてのタイムステップで同じ値を持つ（時間に対して静的な）特徴量です。静的カテゴリ特徴量の典型的な例として、時系列 ID があります。

static_real_features (`torch.Tensor`、形状 `(batch_size, number of static real features)`、*任意*) : モデルが時系列の値に追加する、任意の静的実数特徴量です。静的実数特徴量とは、すべてのタイムステップで同じ値を持つ（時間に対して静的な）特徴量です。静的実数特徴量の典型的な例としては、プロモーション情報が挙げられます。

future_values (`torch.Tensor`、形状は`(batch_size, prediction_length)`または`(batch_size, prediction_length, input_size)`、*optional*) : 時系列の将来の値であり、モデルのラベルとして機能します。`future_values`は、`past_values`が与えられた際に出力すべきものとして、Transformerが学習中に必要とするものです。 这里的シーケンス長は`prediction_length`と等しくなります。 詳細については、デモノートブックとコードスニペットを参照してください。 任意ですが、学習中は欠損値をゼロで置き換え、`future_observed_mask`で示す必要があります。 多次元時系列の場合、`input_size` > 1の次元が必須であり、これは各タイムステップにおける時系列の変数の数に対応します。

future_time_features (`torch.Tensor`、shape は `(batch_size, prediction_length, num_features)`) : 予測ウィンドウに必要な時間特徴です。モデルは内部でこれらを `future_values` に追加します。これには、ベクトルとしてエンコードされた（例えば Fourier features として）「年内の月」や「月内の日」などが含まれます。また、いわゆる「age」特徴も該当します。これは基本的に、時系列が「ライフサイクルのどの時点にあるか」をモデルに認識させるのに役立ちます。Age 特徴は、過去の遠いタイムステップでは値が小さく、現在のタイムステップに近づくにつれて単調に増加します。祝日の特徴も、時間特徴の良い例です。これらの特徴は、入力に対する「位置エンコーディング」の役割を果たします。したがって、BERT のようなモデル（位置エンコーディングがモデルのパラメータとして内部からゼロから学習される）とは異なり、Time Series Transformer では追加の時間特徴を指定する必要があります。Time Series Transformer が追加の埋め込みを学習するのは、`static_categorical_features` に対してのみです。追加の動的な実数共変量は、予測時にこれらの特徴が既知であるという条件のもとで、このテンソルに連結できます。ここでの `num_features` は、`config.num_time_features` + `config.num_dynamic_real_features` に等しくなります。

future_observed_mask (`torch.BoolTensor`、shape `(batch_size, sequence_length)` または `(batch_size, sequence_length, input_size)`、*任意*) : `future_values` のうち、観測された値と欠損値を区別するためのブールマスク。マスクの値は `[0, 1]` から選択します:  - **観測された** 値には 1、 - **欠損** 値には 0（ゼロに置き換えられた NaN）を指定します。 このマスクは、最終的な損失計算において欠損値を除外するために使用されます。

decoder_attention_mask (`torch.LongTensor`、shape `(batch_size, target_sequence_length)`、*optional*) : 特定のトークンインデックスに対するアテンションの実行を回避するためのマスク。デフォルトでは、モデルが未来を予測する際に過去の入力のみを参照できるようにするため、causal mask が使用されます。

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : `last_hidden_state`、`hidden_states` (*optional*)、`attentions` (*optional*) からなるタプル。`last_hidden_state` は形状 `(batch_size, sequence_length, hidden_size)` (*optional*) を持ち、エンコーダーの最終層の出力における隠れ状態のシーケンスです。デコーダーのクロスアテンションで使用されます。

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/v5.23.0/ja/internal/generation_utils#transformers.Cache) インスタンスのみです。[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。`past_key_values` が渡されない場合、デフォルトで [DynamicCache](/docs/transformers/v5.23.0/ja/internal/generation_utils#transformers.DynamicCache) が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。`past_key_values` を使用する場合は、すべての `input_ids`（形状 `(batch_size, sequence_length)`）の代わりに、このモデルに過去の key value 状態が与えられていない未処理の `input_ids`（形状 `(batch_size, unprocessed_length)`）のみを入力する必要があります。

use_cache (`bool`, *任意*) : `True`に設定すると、`past_key_values`のキーバリュー状態が返され、デコーディングの高速化に利用できます（`past_key_values`を参照）。

**戻り値:** [Seq2SeqTSModelOutput](/docs/transformers/v5.23.0/ja/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput) または `tuple(torch.Tensor)`

[Seq2SeqTSModelOutput](/docs/transformers/v5.23.0/ja/main_classes/output#transformers.modeling_outputs.Seq2SeqTSModelOutput)、または`torch.Tensor`のタプル（`return_dict=False`が渡された場合、または`config.return_dict=False`の場合）。設定（[InformerConfig](/docs/transformers/v5.23.0/ja/model_doc/informer#transformers.InformerConfig)）と入力に応じて、さまざまな要素で構成されます。

[InformerForPrediction](/docs/transformers/v5.23.0/ja/model_doc/informer#transformers.InformerForPrediction)のforwardメソッドは、`__call__`特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく`Module`インスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを無視してしまいます。

- **last_hidden_state** (`torch.Tensor`、形状 `(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/v5.23.0/ja/internal/generation_utils#transformers.EncoderDecoderCache) のインスタンスです。詳細については、[kv cache ガイド](https://huggingface.co/docs/transformers/en/kv_cache)を参照してください。

  逐次デコーディングを高速化するために使用できる（`past_key_values` 入力参照）、事前計算済みの隠れ状態（自己アテンションブロックおよびクロスアテンションブロックのキーとバリュー）が含まれます。
- **decoder_hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用 1 つ + 各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるデコーダーのHidden-states、および任意の初期埋め込み出力。
- **decoder_attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  自己アテンションヘッドにおける加重平均を計算するために使用される、アテンションのsoftmax後のデコーダーのアテンション重み。
- **cross_attentions** (`tuple(torch.Tensor)`、*optional*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- `torch.Tensor` のタプル（各レイヤーごとに1つ）、形状は `(batch_size, num_heads, sequence_length, sequence_length)`。

  クロスアテンション層のアテンション重みは、アテンションのsoftmax適用後に計算され、クロスアテンションヘッドにおける加重平均の計算に使用されます。
- **encoder_last_hidden_state** (`torch.Tensor`、形状 `(batch_size, sequence_length, hidden_size)`、*任意*) -- モデルのエンコーダーの最終層の出力における隠れ状態のシーケンス。
- **encoder_hidden_states** (`tuple(torch.Tensor)`、*optional*、`output_hidden_states=True` が渡された場合または `config.output_hidden_states=True` の場合に返されます) -- `torch.Tensor` のタプル（埋め込み層を持つモデルの場合、埋め込みの出力用 1 つ + 各層の出力用 1 つずつ）で、形状は `(batch_size, sequence_length, hidden_size)` です。

  各層の出力におけるエンコーダーのHidden-states、および任意の初期埋め込み出力。
- **encoder_attentions** (`tuple(torch.Tensor)`、*任意*、`output_attentions=True` が渡された場合または `config.output_attentions=True` の場合に返されます) -- 各レイヤーごとに 1 つの `torch.Tensor` からなるタプルで、形状は `(batch_size, num_heads, sequence_length, sequence_length)` です。

  アテンションのsoftmaxを適用した後のエンコーダーのアテンション重み。自己アテンションヘッドにおける加重平均の計算に使用されます。
- **loc** (`torch.Tensor`、形状 `(batch_size,)` または `(batch_size, input_size)`、*任意*) -- 各時系列のコンテキストウィンドウの値をシフトするために使用されます。これにより、モデルへの入力が同じ大きさになり、その後元の大きさにシフトバックされます。
- **scale** (`torch.Tensor`、形状 `(batch_size,)` または `(batch_size, input_size)`、*任意*) -- 各時系列のコンテキストウィンドウのスケーリング値。モデルへの入力値を同じ大きさ（magnitude）に揃えるために使用し、その後、元の大きさに戻すために使用されます。
- **static_features** (`torch.Tensor`、形状 `(batch_size, feature size)`、*任意*) -- バッチ内の各時系列の静的特徴量です。推論時に共変量にコピーされます。

例:

```python
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import InformerForPrediction

>>> file = hf_hub_download(
...     repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)

>>> model = InformerForPrediction.from_pretrained(
...     "huggingface/informer-tourism-monthly"
... )

>>> # during training, one provides both past and future values
>>> # as well as possible additional features
>>> outputs = model(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_values=batch["future_values"],
...     future_time_features=batch["future_time_features"],
... )

>>> loss = outputs.loss
>>> loss.backward()

>>> # during inference, one only provides past values
>>> # as well as possible additional features
>>> # the model autoregressively generates future values
>>> outputs = model.generate(
...     past_values=batch["past_values"],
...     past_time_features=batch["past_time_features"],
...     past_observed_mask=batch["past_observed_mask"],
...     static_categorical_features=batch["static_categorical_features"],
...     static_real_features=batch["static_real_features"],
...     future_time_features=batch["future_time_features"],
... )

>>> mean_prediction = outputs.sequences.mean(dim=1)
```

