Transformers documentation
Autoformer
이 모델은 2021-06-24에 HF papers에 게시되었으며, 2023-05-30에 Hugging Face Transformers에 기여되었습니다.
Autoformer
개요
Autoformer 모델은 Haixu Wu, Jiehui Xu, Jianmin Wang, Mingsheng Long이 Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting에서 제안했습니다.
이 모델은 Transformer를 심층 분해(deep decomposition) 아키텍처로 확장하여, 예측 과정에서 추세 및 계절성 구성 요소를 점진적으로 분해할 수 있습니다.
해당 논문의 초록은 다음과 같습니다:
예측 시간의 확장은 극한 기상 조기 경보와 장기 에너지 소비 계획과 같은 실제 응용에서 핵심적인 요구 사항입니다. 본 논문은 시계열의 장기 예측 문제를 연구합니다. 기존의 Transformer 기반 모델들은 다양한 self-attention 메커니즘을 채택하여 장기 의존성을 발견합니다. 그러나 장기간 미래의 복잡한 시간적 패턴은 모델이 신뢰할 수 있는 의존성을 찾는 것을 방해합니다. 또한, Transformer는 긴 시계열의 효율성을 위해 point-wise self-attention의 sparse 버전을 채택해야 하며, 이로 인해 정보 활용 병목 현상이 발생합니다. Transformer를 넘어, 우리는 Auto-Correlation 메커니즘을 갖춘 새로운 분해(decomposition) 아키텍처인 Autoformer를 설계했습니다. 우리는 시계열 분해의 전처리 관례를 깨고 이를 딥 모델의 기본 내부 블록으로 재구성했습니다. 이 설계는 Autoformer에게 복잡한 시계열에 대한 점진적 분해 능력을 부여합니다. 나아가, 확률 과정 이론에 영감을 받아, 우리는 시계열의 주기성에 기반한 Auto-Correlation 메커니즘을 설계했으며, 이는 서브시계열(sub-series) 수준에서 의존성 발견과 표현 집합을 수행합니다. Auto-Correlation은 효율성과 정확성 모두에서 self-attention보다 우수한 성능을 보입니다. 장기 예측에서 Autoformer는 에너지, 교통, 경제, 기상, 질병이라는 다섯 가지 실제 응용을 포괄하는 여섯 개의 벤치마크에서 38%의 상대적 개선과 함께 최첨단(state-of-the-art) 정확도를 달성합니다.
이 모델은 elisim과 kashif가 기여했습니다. 원본 코드는 여기에서 찾을 수 있습니다.
리소스
시작을 돕기 위한 공식 Hugging Face 및 커뮤니티(🌎로 표시) 리소스 목록입니다. 여기에 리소스를 추가하고 싶으시면 Pull Request를 열어 주시면 검토하겠습니다! 기존 리소스와 중복되지 않고 새로운 것을 보여주는 것이 이상적입니다.
- HuggingFace 블로그의 Autoformer 블로그 포스트를 확인해 보세요: 네, Transformers는 시계열 예측에 효과적입니다 (+ Autoformer)
AutoformerConfig
class transformers.AutoformerConfig
< 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 = 0id2label: 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 = Noneis_encoder_decoder: bool = Trueprediction_length: int | None = Nonecontext_length: int | None = Nonedistribution_output: str = 'student_t'loss: str = 'nll'input_size: int = 1lags_sequence: list[int] | tuple[int, ...] = (1, 2, 3, 4, 5, 6, 7)scaling: bool | str = Truenum_time_features: int = 0num_dynamic_real_features: int = 0num_static_categorical_features: int = 0num_static_real_features: int = 0cardinality: list[int] | None = Noneembedding_dimension: list[int] | None = Noned_model: int = 64encoder_attention_heads: int = 2decoder_attention_heads: int = 2encoder_layers: int = 2decoder_layers: int = 2encoder_ffn_dim: int = 32decoder_ffn_dim: int = 32activation_function: str = 'gelu'dropout: float | int = 0.1encoder_layerdrop: float | int = 0.1decoder_layerdrop: float | int = 0.1attention_dropout: float | int = 0.1activation_dropout: float | int = 0.1num_parallel_samples: int = 100init_std: float = 0.02use_cache: bool = Truelabel_length: int = 10moving_average: int = 25autocorrelation_factor: int = 3 )
매개변수
- is_encoder_decoder (
bool, 선택 사항, 기본값True) — 모델이 인코더/디코더로 사용되는지 여부를 나타냅니다. - prediction_length (
int, 선택 사항) — 디코더의 예측 길이입니다. 즉, 모델의 예측 지평선(prediction horizon)입니다. - context_length (
int, 선택 사항, 기본값prediction_length) — 인코더의 컨텍스트 길이입니다. 설정하지 않으면 컨텍스트 길이는prediction_length와 동일해집니다. - distribution_output (
string, 선택 사항, 기본값"student_t") — 모델의 분포 출력 헤드입니다. “student_t”, “normal”, “negative_binomial” 중 하나를 사용할 수 있습니다. - loss (
string, 선택 사항, 기본값"nll") —distribution_output헤드에 해당하는 모델의 손실 함수입니다. 매개변수 분포의 경우 음의 로그 가능도(nll)이며, 현재 지원되는 유일한 손실 함수입니다. - input_size (
int, 선택 사항, 기본값 1) — 기본적으로 단변수 타깃의 경우 1인 대상 변수의 크기입니다. 다변수 타깃인 경우 1보다 커집니다. - lags_sequence (
list[int], 선택 사항, 기본값[1, 2, 3, 4, 5, 6, 7]) — 공변량으로 사용되는 입력 시계열의 lag 값으로, 보통 주기에 의해 결정됩니다. 기본값은[1, 2, 3, 4, 5, 6, 7]입니다. - scaling (
bool, 선택 사항, 기본값True) — 입력 타겟을 스케일링할지 여부입니다. - num_time_features (
int, 선택 사항, 기본값 0) — 입력 시계열에 포함된 시간 특성의 개수입니다. - num_dynamic_real_features (
int, 선택 사항, 기본값 0) — 동적 실수형 특징의 개수입니다. - num_static_categorical_features (
int, 선택 사항, 기본값 0) — 정적 범주형 특징의 개수입니다. - num_static_real_features (
int, 선택 사항, 기본값 0) — 정적 실수형 특징의 개수입니다. - cardinality (
list[int], 선택) — 정적 범주형 특징 각각의 카디널리티(서로 다른 값의 개수)입니다.num_static_categorical_features와 동일한 길이를 가진 정수 목록이어야 합니다.num_static_categorical_features가 0보다 크면None일 수 없습니다. - embedding_dimension (
list[int], 선택 사항) — 임베딩 및 숨겨진 상태의 차원. - d_model (
int, 선택 사항, 기본값64) — 인코더 레이어와 풀러 레이어의 크기. - encoder_attention_heads (
int, 선택 사항, 기본값2) — Transformer 인코더의 각 어텐션 레이어에 사용할 어텐션 헤드 수입니다. - decoder_attention_heads (
int, 선택 사항, 기본값2) — Transformer decoder의 각 attention layer에 사용할 attention head 수입니다. - encoder_layers (
int, 선택 사항, 기본값2) — Transformer 인코더의 숨겨진 레이어 수입니다. 설정하지 않으면num_layers와 동일한 값을 사용합니다. - decoder_layers (
int, 선택 사항, 기본값2) — Transformer decoder의 hidden layer 수입니다. 설정하지 않으면num_layers와 동일한 값을 사용합니다. - encoder_ffn_dim (
int, 선택 사항, 기본값32) — 인코더의 “중간” 레이어(일반적으로 feed-forward 레이어라고도 함)의 차원입니다. - decoder_ffn_dim (
int, 선택 사항, 기본값32) — decoder의 “intermediate”(일반적으로 feed-forward라고도 함) 레이어의 차원입니다. - activation_function (
str, 선택 사항, 기본값gelu) — 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열)입니다. 예를 들어,"gelu","relu","silu"등이 있습니다. - dropout (
Union[float, int], 선택 사항, 기본값0.1) — 모든 dropout 레이어에 적용할 비율입니다. - encoder_layerdrop (
Union[float, int], 선택 사항, 기본값0.1) — 인코더의 LayerDrop 확률입니다. 자세한 내용은 [LayerDrop 논문](https://huggingface.co/papers/1909.11556 참조)을 참고하세요. - decoder_layerdrop (
Union[float, int], 선택 사항, 기본값0.1) — 디코더의 LayerDrop 확률입니다. 자세한 내용은 [LayerDrop 논문](https://huggingface.co/papers/1909.11556 참조)을 참고하세요. - attention_dropout (
Union[float, int], 선택 사항, 기본값0.1) — Attention 확률에 적용할 dropout 비율입니다. - activation_dropout (
Union[float, int], 선택 사항, 기본값0.1) — 완전 연결 레이어 내부 활성화에 적용할 dropout 비율입니다. - num_parallel_samples (
int, 선택 사항, 기본값 100) — 추론의 각 시간 단계에서 병렬로 생성할 샘플 수입니다. - init_std (
float, 선택 사항, 기본값0.02) — 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다. - use_cache (
bool, 선택 사항, 기본값True) — 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음).config.is_decoder=True인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다. - label_length (
int, 선택 사항, 기본값 10) — 직접 다단계 예측(즉, 비자기회귀 생성)에 사용되는 Autoformer 디코더의 시작 토큰 길이입니다. - moving_average (
int, 선택 사항, 기본값 25) — 이동 평균의 윈도우 크기입니다. 실제로는 Decomposition Layer의 AvgPool1d에서 사용되는 커널 크기입니다. - autocorrelation_factor (
int, 선택 사항, 기본값 3) — “Attention”(즉, AutoCorrelation 메커니즘) 인자로, 상위 k개의 자기상관 지연을 찾는 데 사용됩니다. 논문에서는 1에서 5 사이의 값으로 설정하는 것을 권장합니다.
이것은 AutoformerModel의 설정을 저장하기 위한 설정 클래스입니다. 지정된 인수를 기반으로 Autoformer 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 설정을 인스턴스화하면 huggingface/autoformer-tourism-monthly와 유사한 설정이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
예:
>>> from transformers import AutoformerConfig, AutoformerModel
>>> # Initializing a default Autoformer configuration
>>> configuration = AutoformerConfig()
>>> # Randomly initializing a model (with random weights) from the configuration
>>> model = AutoformerModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configAutoformerModel
class transformers.AutoformerModel
< source >( config: AutoformerConfig )
매개변수
- config (AutoformerConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
특정 헤드가 위에 없는 상태의 Autoformer 모델로, 원시 hidden-states를 출력합니다.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → AutoformerModelOutput or tuple(torch.Tensor)
매개변수
- past_values (
torch.Tensor형태가(batch_size, sequence_length)) — 시계열의 과거 값으로, 미래를 예측하기 위한 컨텍스트로 사용됩니다. 이 값에는 과거의 추가 값을 “추가 컨텍스트”로 제공하기 위해 지연(lag)이 포함될 수 있습니다.past_values은 Transformer 인코더의 입력으로 사용됩니다(선택적으로 추가 기능, 예:static_categorical_features,static_real_features,past_time_features).여기서 시퀀스 길이는
context_length+max(config.lags_sequence)와 같습니다.누락된 값은 0으로 대체해야 합니다.
- past_time_features (
torch.Tensor형태가(batch_size, sequence_length, num_features), 선택 사항) — 선택적인 시간 특징으로, 모델이 내부적으로past_values. 에 추가합니다. 이는 “연도 내 월”, “월 내 일” 등을 벡터(예: Fourier features)로 인코딩한 형태일 수 있습니다. 또한 “age” 특징일 수도 있으며, 이는 기본적으로 시계열이 “생애의 어느 시점”에 있는지를 모델이 인식하도록 돕습니다. Age 특징은 과거의 먼 시간 단계에서는 작은 값을 가지며, 현재 시간 단계에 가까워질수록 단조롭게 증가합니다.이러한 기능은 입력의 위치 인코딩 역할을 합니다. 따라서 모델 내부에서 위치 인코딩을 매개변수로 처음부터 학습하는 BERT와 달리, Time Series Transformer는 추가적인 시간 특성을 제공해야 합니다.
Autoformer는
static_categorical_features에 대해서만 추가 임베딩을 학습합니다. - past_observed_mask (
torch.BoolTensorshape(batch_size, sequence_length), 선택 사항) — 어떤past_values이 관찰되었는지, 어떤 값이 누락되었는지를 나타내는 불리언 마스크입니다. 마스크 값은 [0, 1] 범위에서 선택됩니다: 관찰된 값은 1, 누락된 값(즉, 0으로 대체된 NaN)은 0입니다.[0, 1]:- 관측된 값에 대해 1
- 누락된 값(즉, 0으로 대체된 NaN)에 대해 0
- static_categorical_features (
torch.LongTensor형상이(batch_size, number of static categorical features), 선택 사항) — 모델이 임베딩을 학습하여 시계열 값에 더할 선택적 정적 범주형 특징입니다.Static categorical features는 모든 시간 단계에서 동일한 값을 가지는 특징(시간에 따라 고정된 특징)입니다.
정적 범주형 특징의 일반적인 예시로는 시계열 ID가 있습니다.
- static_real_features (
torch.Tensorshape(batch_size, number of static real features), 선택 사항) — 모델이 시계열 값에 추가할 선택적 정적 실수형 특징입니다. 정적 실수형 특징은 모든 시간 단계에서 동일한 값을 가지는 특징(시간에 따라 정적인 특징)입니다. 정적 실수형 특징의 일반적인 예로는 프로모션 정보가 있습니다.Static real features는 모든 시간 단계에서 동일한 값을 가지는(시간에 대해 정적인) 특징입니다.
정적 실수치의 일반적인 예시로는 프로모션 정보가 있습니다.
- future_values (
torch.Tensor형태가(batch_size, prediction_length)) — 시계열의 미래 값으로, 모델의 라벨로 사용됩니다.future_values은/는 Transformer가 학습하여 출력해야 하는 값이며, 주어진 조건은past_values.자세한 내용은 데모 노트북 및 코드 스니펫을 참고하세요.
누락된 값은 0으로 대체해야 합니다.
- future_time_features (
torch.Tensor형태가(batch_size, prediction_length, num_features), 선택 사항) — 모델이 내부적으로future_values. 에 추가하는 선택적 시간 특징입니다. 이는 “연도 내 월”, “월 내 일” 등을 벡터(예: Fourier features)로 인코딩한 형태일 수 있습니다. 또한 “age” 특징일 수도 있으며, 이는 기본적으로 시계열이 “생애의 어느 시점”에 있는지를 모델이 인식하도록 돕습니다. Age 특징은 과거의 먼 시간 단계에서는 작은 값을 가지며, 현재 시간 단계에 가까워질수록 단조롭게 증가합니다.이러한 특징은 입력의 위치 인코딩 역할을 합니다. 따라서 모델 내부에서 위치 인코딩을 매개변수로 처음부터 학습하는 BERT와 달리, Time Series Transformer는 추가적인 특징을 제공해야 합니다.
Autoformer는
static_categorical_features에 대해서만 추가 임베딩을 학습합니다. - decoder_attention_mask (
torch.LongTensor, shape(batch_size, target_sequence_length), 선택 사항) — 특정 토큰 인덱스에 대한 attention을 수행하지 않도록 하는 mask입니다. 기본적으로 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). 일반적으로 이는past_key_values디코딩의 이전 단계에서 모델이 반환한use_cache=True또는config.use_cache=True.입력으로 Cache 인스턴스만 허용되며, kv cache 가이드를 참고하세요.
past_key_values가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.
past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은input_ids만 입력해야 하며, 이때의 shape은(batch_size, unprocessed_length)입니다. shape이(batch_size, sequence_length)인 전체input_ids를 입력하지 않습니다. - use_cache (
bool, 선택 사항) —True로 설정하면past_key_values키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(past_key_values참조).
반환값
AutoformerModelOutput 또는 tuple(torch.Tensor)
AutoformerModelOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되거나 config.return_dict=False인 경우)로, 구성(AutoformerConfig)과 입력에 따라 다양한 요소를 포함합니다.
AutoformerModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 모델의 decoder 마지막 레이어 출력의 hidden-state 시퀀스입니다.past_key_values가 사용되면,(batch_size, 1, hidden_size)형태의 시퀀스의 마지막 hidden-state만 출력됩니다.trend (
torch.Tensor, shape(batch_size, sequence_length, hidden_size)) — 각 시계열에 대한 Trend 텐서.past_key_values (
Cache, 선택 사항,use_cache=True가 전달되었거나config.use_cache=True인 경우 반환됨) — Cache 인스턴스입니다. 자세한 내용은 kv cache 가이드를 참고하세요.순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)를 포함합니다(입력
past_key_values참조).decoder_hidden_states (
tuple[torch.Tensor], 선택 사항,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], 선택 사항,output_attentions=True가 전달되거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 decoder의 attention 가중치입니다.
cross_attentions (
tuple[torch.Tensor], 선택 사항,output_attentions=True가 전달되거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.decoder의 cross-attention 레이어에서 attention softmax를 적용한 후, cross-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention 가중치입니다.
encoder_last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택 사항) — 모델 인코더의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.encoder_hidden_states (
tuple[torch.Tensor], 선택 사항,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인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 인코더 attention 가중치입니다.
loc (
torch.Tensor, shape(batch_size,)또는(batch_size, input_size), 선택 사항) — 각 시계열의 컨텍스트 윈도우 값을 이동시켜 모델에 동일한 크기의 입력을 제공한 후, 원래 크기로 되돌리기 위해 사용됩니다.scale (
torch.Tensor, shape(batch_size,)또는(batch_size, input_size), 선택 사항) — 각 시계열의 컨텍스트 윈도우 스케일링 값입니다. 모델에 동일한 크기의 입력을 제공하기 위해 사용되며, 추론 시 원래 크기로 되돌리기 위해 사용됩니다. static_features: (torch.Tensor, shape(batch_size, feature size), 선택 사항): 배치 내 각 시계열의 정적 특징입니다. 추론 시 공변량(covariates)에 복사됩니다.static_features (
torch.Tensor, shape(batch_size, feature size), 선택 사항) — 배치 내 각 시계열의 정적 특징으로, 추론 시점에 공변량(covariates)에 복사됩니다.
예:
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerModel
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = AutoformerModel.from_pretrained("huggingface/autoformer-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"],
... future_values=batch["future_values"],
... future_time_features=batch["future_time_features"],
... )
>>> last_hidden_state = outputs.last_hidden_stateAutoformerForPrediction
class transformers.AutoformerForPrediction
< source >( config: AutoformerConfig )
매개변수
- config (AutoformerConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
시계열 예측을 위해 상단에 분포 헤드가 있는 Autoformer 모델.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( past_values: Tensorpast_time_features: Tensorpast_observed_mask: Tensorstatic_categorical_features: typing.Optional[torch.Tensor] = Nonestatic_real_features: typing.Optional[torch.Tensor] = Nonefuture_values: typing.Optional[torch.Tensor] = Nonefuture_time_features: typing.Optional[torch.Tensor] = Nonefuture_observed_mask: typing.Optional[torch.Tensor] = Nonedecoder_attention_mask: typing.Optional[torch.LongTensor] = Noneencoder_outputs: list[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqTSPredictionOutput or tuple(torch.Tensor)
매개변수
- past_values (
torch.Tensor형태가(batch_size, sequence_length)) — 시계열의 과거 값으로, 미래를 예측하기 위한 컨텍스트로 사용됩니다. 이 값에는 과거의 추가 값을 “추가 컨텍스트”로 제공하기 위해 지연(lag)이 포함될 수 있습니다.past_values은 Transformer 인코더의 입력으로 사용됩니다(선택적으로 추가 기능, 예:static_categorical_features,static_real_features,past_time_features).여기서 시퀀스 길이는
context_length+max(config.lags_sequence)와 같습니다.누락된 값은 0으로 대체해야 합니다.
- past_time_features (
torch.Tensor형태가(batch_size, sequence_length, num_features), 선택 사항) — 선택적인 시간 특징으로, 모델이 내부적으로past_values. 에 추가합니다. 이는 “연도 내 월”, “월 내 일” 등을 벡터(예: Fourier features)로 인코딩한 형태일 수 있습니다. 또한 “age” 특징일 수도 있으며, 이는 기본적으로 시계열이 “생애의 어느 시점”에 있는지를 모델이 인식하도록 돕습니다. Age 특징은 과거의 먼 시간 단계에서는 작은 값을 가지며, 현재 시간 단계에 가까워질수록 단조롭게 증가합니다.이러한 기능은 입력의 위치 인코딩 역할을 합니다. 따라서 모델 내부에서 위치 인코딩을 매개변수로 처음부터 학습하는 BERT와 달리, Time Series Transformer는 추가적인 시간 특성을 제공해야 합니다.
Autoformer는
static_categorical_features에 대해서만 추가 임베딩을 학습합니다. - past_observed_mask (
torch.BoolTensorshape(batch_size, sequence_length), 선택 사항) — 어떤past_values이 관찰되었는지, 어떤 값이 누락되었는지를 나타내는 불리언 마스크입니다. 마스크 값은 [0, 1] 범위에서 선택됩니다: 관찰된 값은 1, 누락된 값(즉, 0으로 대체된 NaN)은 0입니다.[0, 1]:- 관측된 값에 대해 1
- 누락된 값(즉, 0으로 대체된 NaN)에 대해 0
- static_categorical_features (
torch.LongTensor형상이(batch_size, number of static categorical features), 선택 사항) — 모델이 임베딩을 학습하여 시계열 값에 더할 선택적 정적 범주형 특징입니다.Static categorical features는 모든 시간 단계에서 동일한 값을 가지는 특징(시간에 따라 고정된 특징)입니다.
정적 범주형 특징의 일반적인 예시로는 시계열 ID가 있습니다.
- static_real_features (
torch.Tensorshape(batch_size, number of static real features), 선택 사항) — 모델이 시계열 값에 추가할 선택적 정적 실수형 특징입니다. 정적 실수형 특징은 모든 시간 단계에서 동일한 값을 가지는 특징(시간에 따라 정적인 특징)입니다. 정적 실수형 특징의 일반적인 예로는 프로모션 정보가 있습니다.Static real features는 모든 시간 단계에서 동일한 값을 가지는(시간에 대해 정적인) 특징입니다.
정적 실수치의 일반적인 예시로는 프로모션 정보가 있습니다.
- future_values (
torch.Tensor형태가(batch_size, prediction_length)) — 시계열의 미래 값으로, 모델의 라벨로 사용됩니다.future_values은/는 Transformer가 학습하여 출력해야 하는 값이며, 주어진 조건은past_values.자세한 내용은 데모 노트북 및 코드 스니펫을 참고하세요.
누락된 값은 0으로 대체해야 합니다.
- future_time_features (
torch.Tensor형태가(batch_size, prediction_length, num_features), 선택 사항) — 모델이 내부적으로future_values. 에 추가하는 선택적 시간 특징입니다. 이는 “연도 내 월”, “월 내 일” 등을 벡터(예: Fourier features)로 인코딩한 형태일 수 있습니다. 또한 “age” 특징일 수도 있으며, 이는 기본적으로 시계열이 “생애의 어느 시점”에 있는지를 모델이 인식하도록 돕습니다. Age 특징은 과거의 먼 시간 단계에서는 작은 값을 가지며, 현재 시간 단계에 가까워질수록 단조롭게 증가합니다.이러한 특징은 입력의 위치 인코딩 역할을 합니다. 따라서 모델 내부에서 위치 인코딩을 매개변수로 처음부터 학습하는 BERT와 달리, Time Series Transformer는 추가적인 특징을 제공해야 합니다.
Autoformer는
static_categorical_features에 대해서만 추가 임베딩을 학습합니다. - future_observed_mask (
torch.BoolTensor형상이(batch_size, sequence_length)또는(batch_size, sequence_length, input_size), 선택 사항) — 어떤future_values값이 관측되었고 어떤 값이 누락되었는지를 나타내는 불리언 마스크입니다.[0, 1]:- 관측된 값에 대해 1
- 누락된 값(즉, 0으로 대체된 NaN)에 대해 0
이 마스크는 최종 손실 계산 시 누락된 값을 필터링하는 데 사용됩니다.
- decoder_attention_mask (
torch.LongTensor, shape(batch_size, target_sequence_length), 선택 사항) — 특정 토큰 인덱스에 대한 attention을 수행하지 않도록 하는 mask입니다. 기본적으로 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). 일반적으로 이는past_key_values디코딩의 이전 단계에서 모델이 반환한use_cache=True또는config.use_cache=True.입력으로 Cache 인스턴스만 허용되며, kv cache 가이드를 참고하세요.
past_key_values가 전달되지 않으면 기본적으로 DynamicCache가 초기화됩니다.모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다.
past_key_values를 사용하는 경우, 이 모델에 과거 키 값 상태가 제공되지 않은input_ids만 입력해야 하며, 이때의 shape은(batch_size, unprocessed_length)입니다. shape이(batch_size, sequence_length)인 전체input_ids를 입력하지 않습니다. - use_cache (
bool, 선택 사항) —True로 설정하면past_key_values키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(past_key_values참조).
반환값
Seq2SeqTSPredictionOutput 또는 tuple(torch.Tensor)
torch.Tensor의 튜플 또는 Seq2SeqTSPredictionOutput입니다. 구성(AutoformerConfig)과 입력에 따라 다양한 요소를 포함하며, return_dict=False가 전달되거나 config.return_dict=False인 경우에도 동일합니다.
AutoformerForPrediction의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
loss (
torch.Tensor, shape(1,), 선택 사항,future_values가 제공될 때 반환됨) — 분포적 손실.params (
torch.Tensor, shape(batch_size, num_samples, num_params)) — 선택된 분포의 매개변수.past_key_values (
EncoderDecoderCache, 선택 사항,use_cache=True가 전달되었거나config.use_cache=True인 경우 반환됨) — EncoderDecoderCache 인스턴스입니다. 자세한 내용은 kv 캐시 가이드를 참고하세요.순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)를 포함합니다(입력
past_key_values참조).decoder_hidden_states (
tuple(torch.Tensor), 선택 사항,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), 선택 사항,output_attentions=True가 전달되거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 decoder의 attention 가중치입니다.
cross_attentions (
tuple(torch.Tensor), 선택 사항,output_attentions=True가 전달되었거나config.output_attentions=True인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.decoder의 cross-attention 레이어에서 attention softmax를 적용한 후, cross-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention 가중치입니다.
encoder_last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택 사항) — 모델 인코더의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.encoder_hidden_states (
tuple(torch.Tensor), 선택 사항,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인 경우 반환됨) — 각 레이어마다 하나씩 포함된torch.Tensor의 튜플로, 모양은(batch_size, num_heads, sequence_length, sequence_length)입니다.self-attention 헤드에서 가중 평균을 계산하는 데 사용되는, attention softmax 이후의 인코더 attention 가중치입니다.
loc (
torch.Tensor, shape(batch_size,)또는(batch_size, input_size), 선택 사항) — 각 시계열의 컨텍스트 윈도우 값을 이동시켜 모델에 동일한 크기의 입력을 제공한 후, 원래 크기로 되돌리기 위해 사용됩니다.scale (
torch.Tensor, shape(batch_size,)또는(batch_size, input_size), 선택 사항) — 각 시계열의 컨텍스트 윈도우 스케일링 값입니다. 모델에 동일한 크기의 입력을 제공하기 위해 사용되며, 이후 원래 크기로 되돌리기 위해 사용됩니다.static_features (
torch.Tensor, shape(batch_size, feature size), 선택 사항) — 배치 내 각 시계열의 정적 특징으로, 추론 시점에 공변량(covariates)에 복사됩니다.
예:
>>> from huggingface_hub import hf_hub_download
>>> import torch
>>> from transformers import AutoformerForPrediction
>>> file = hf_hub_download(
... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset"
... )
>>> batch = torch.load(file)
>>> model = AutoformerForPrediction.from_pretrained("huggingface/autoformer-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"],
... 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"],
... future_time_features=batch["future_time_features"],
... )
>>> mean_prediction = outputs.sequences.mean(dim=1)AutoformerForPrediction는 static_real_features도 사용할 수 있습니다. 이를 위해 데이터셋에 포함된 해당 특징의 수에 따라 AutoformerConfig의 num_static_real_features를 설정합니다(tourism_monthly
1과 같을 경우), 아래에 표시된 대로 모델을 초기화하고 as를 호출합니다:
>>> from huggingface_hub import hf_hub_download >>> import torch >>> from transformers import AutoformerConfig, AutoformerForPrediction >>> file = hf_hub_download( ... repo_id="hf-internal-testing/tourism-monthly-batch", filename="train-batch.pt", repo_type="dataset" ... ) >>> batch = torch.load(file) >>> # check number of static real features >>> num_static_real_features = batch["static_real_features"].shape[-1] >>> # load configuration of pretrained model and override num_static_real_features >>> configuration = AutoformerConfig.from_pretrained( ... "huggingface/autoformer-tourism-monthly", ... num_static_real_features=num_static_real_features, ... ) >>> # we also need to update feature_size as it is not recalculated >>> configuration.feature_size += num_static_real_features >>> model = AutoformerForPrediction(configuration) >>> 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"], ... )