Transformers documentation
Autoformer
Mô hình này được công bố trên HF papers vào ngày 2021-06-24 và được đóng góp cho Hugging Face Transformers vào ngày 2023-05-30.
Autoformer
Tổng quan
Mô hình Autoformer được đề xuất trong Autoformer: Decomposition Transformers with Auto-Correlation for Long-Term Series Forecasting bởi Haixu Wu, Jiehui Xu, Jianmin Wang, Mingsheng Long.
Mô hình này mở rộng Transformer như một kiến trúc phân rã sâu, có khả năng phân rã dần các thành phần xu hướng và mùa trong quá trình dự báo.
Tóm tắt từ bài báo như sau:
Việc mở rộng khoảng thời gian dự báo là một yêu cầu quan trọng đối với các ứng dụng thực tế, chẳng hạn như cảnh báo sớm thời tiết cực đoan và lập kế hoạch tiêu thụ năng lượng dài hạn. Bài báo này nghiên cứu bài toán dự báo dài hạn cho chuỗi thời gian. Các mô hình dựa trên Transformer trước đây đã áp dụng nhiều cơ chế tự chú ý khác nhau để khám phá các phụ thuộc tầm xa. Tuy nhiên, các mẫu thời gian phức tạp của tương lai dài hạn ngăn cản mô hình tìm ra các phụ thuộc đáng tin cậy. Ngoài ra, để đạt hiệu quả với chuỗi dài, Transformer phải sử dụng các phiên bản thưa của tự chú ý điểm, dẫn đến nút cổ chai trong việc khai thác thông tin. Vượt ra ngoài phạm vi của Transformer, chúng tôi thiết kế Autoformer như một kiến trúc phân rã mới với cơ chế Auto-Correlation. Chúng tôi phá vỡ quy ước tiền xử lý về phân rã chuỗi và cải tiến nó thành một khối nội bộ cơ bản của các mô hình sâu. Thiết kế này trang bị cho Autoformer khả năng phân rã tiến bộ cho các chuỗi thời gian phức tạp. Hơn nữa, lấy cảm hứng từ lý thuyết quá trình ngẫu nhiên, chúng tôi thiết kế cơ chế Auto-Correlation dựa trên tính tuần hoàn của chuỗi, thực hiện việc khám phá phụ thuộc và tổng hợp biểu diễn ở cấp độ chuỗi con. Auto-Correlation vượt trội hơn tự chú ý về cả hiệu quả lẫn độ chính xác. Trong dự báo dài hạn, Autoformer đạt độ chính xác tiên tiến, với mức cải thiện tương đối 38% trên sáu bộ chuẩn, bao phủ năm ứng dụng thực tế: năng lượng, giao thông, kinh tế, thời tiết và dịch bệnh.
Mô hình này được đóng góp bởi elisim và kashif. Mã nguồn gốc có thể được tìm thấy tại đây.
Tài nguyên
Danh sách các tài nguyên chính thức của Hugging Face và cộng đồng (được đánh dấu bằng 🌎) để giúp bạn bắt đầu. Nếu bạn quan tâm đến việc gửi tài nguyên để được đưa vào đây, hãy thoải mái mở một Pull Request và chúng tôi sẽ xem xét! Tài nguyên lý tưởng nên minh họa điều gì đó mới thay vì sao chép một tài nguyên hiện có.
- Xem bài viết Autoformer trên blog HuggingFace: Có, Transformers hiệu quả cho dự báo chuỗi thời gian (+ Autoformer)
AutoformerConfig
lớp 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 )
Tham số
- is_encoder_decoder (
bool, tùy chọn, mặc định làTrue) — Xác định xem mô hình có được sử dụng như một encoder/decoder hay không. - prediction_length (
int, tùy chọn) — Chiều dài dự đoán cho bộ giải mã. Nói cách khác, là chân trời dự đoán của mô hình. - context_length (
int, tùy chọn, mặc định làprediction_length) — Độ dài ngữ cảnh cho bộ mã hóa. Nếu không được đặt, độ dài ngữ cảnh sẽ giống vớiprediction_length. - distribution_output (
string, tuỳ chọn, mặc định là"student_t") — Đầu phát phân phối (distribution emission head) của mô hình. Có thể là “student_t”, “normal” hoặc “negative_binomial”. - loss (
string, tùy chọn, mặc định là"nll") — Hàm mất mát cho mô hình tương ứng với đầu radistribution_output. Đối với các phân phối tham số, đây là log-likelihood âm (nll) - hiện là hàm duy nhất được hỗ trợ. - input_size (
int, tuỳ chọn, mặc định là 1) — Kích thước của biến mục tiêu, mặc định là 1 đối với các mục tiêu đơn biến. Sẽ > 1 trong trường hợp các mục tiêu đa biến. - lags_sequence (
list[int], tuỳ chọn, mặc định là[1, 2, 3, 4, 5, 6, 7]) — Các độ trễ của chuỗi thời gian đầu vào được dùng làm biến ngoại sinh, thường được xác định bởi tần suất. Mặc định là[1, 2, 3, 4, 5, 6, 7]. - scaling (
bool, tùy chọn, mặc định làTrue) — Có nên mở rộng các mục tiêu đầu vào hay không. - num_time_features (
int, tùy chọn, mặc định là 0) — Số lượng đặc trưng thời gian trong chuỗi thời gian đầu vào. - num_dynamic_real_features (
int, tùy chọn, mặc định là 0) — Số lượng đặc trưng có giá trị thực động. - num_static_categorical_features (
int, tuỳ chọn, mặc định là 0) — Số lượng các đặc trưng phân loại tĩnh. - num_static_real_features (
int, tuỳ chọn, mặc định là 0) — Số lượng đặc trưng tĩnh có giá trị thực. - cardinality (
list[int], tuỳ chọn) — Độ lớn (số lượng giá trị khác nhau) của từng đặc trưng phân loại tĩnh. Phải là một danh sách các số nguyên, có cùng độ dài vớinum_static_categorical_features. Không thể làNonenếunum_static_categorical_features> 0. - embedding_dimension (
list[int], tùy chọn) — Số chiều của các embedding và hidden states. - d_model (
int, tùy chọn, mặc định là64) — Kích thước của các lớp encoder và lớp pooler. - encoder_attention_heads (
int, tùy chọn, mặc định là2) — Số lượng đầu chú ý cho mỗi lớp chú ý trong bộ mã hóa Transformer. - decoder_attention_heads (
int, tùy chọn, mặc định là2) — Số lượng đầu chú ý cho mỗi lớp chú ý trong bộ giải mã Transformer. - encoder_layers (
int, tùy chọn, mặc định là2) — Số lượng lớp ẩn trong bộ mã hóa Transformer. Nếu không được đặt, giá trị này sẽ giống vớinum_layers. - decoder_layers (
int, tùy chọn, mặc định là2) — Số lượng lớp ẩn trong bộ giải mã Transformer. Nếu không được đặt, giá trị này sẽ giống vớinum_layers. - encoder_ffn_dim (
int, tùy chọn, mặc định là32) — Kích thước của lớp “trung gian” (thường được gọi là feed-forward) trong encoder. - decoder_ffn_dim (
int, tùy chọn, mặc định là32) — Kích thước của lớp “trung gian” (thường được gọi là lớp feed-forward) trong decoder. - activation_function (
str, tùy chọn, mặc định làgelu) — Hàm kích hoạt phi tuyến (hàm hoặc chuỗi) trong bộ giải mã. Ví dụ,"gelu","relu","silu", v.v. - dropout (
Union[float, int], tùy chọn, mặc định là0.1) — Tỷ lệ cho tất cả các lớp dropout. - encoder_layerdrop (
Union[float, int], tùy chọn, mặc định là0.1) — Xác suất LayerDrop cho encoder. Xem [bài báo LayerDrop](xem https://huggingface.co/papers/1909.11556) để biết thêm chi tiết. - decoder_layerdrop (
Union[float, int], tùy chọn, mặc định là0.1) — Xác suất LayerDrop cho bộ giải mã. Xem [bài báo LayerDrop](xem https://huggingface.co/papers/1909.11556) để biết thêm chi tiết. - attention_dropout (
Union[float, int], tùy chọn, mặc định là0.1) — Tỷ lệ dropout cho các xác suất chú ý. - activation_dropout (
Union[float, int], tùy chọn, mặc định là0.1) — Tỷ lệ dropout cho các kích hoạt bên trong lớp liên kết đầy đủ. - num_parallel_samples (
int, tùy chọn, mặc định là 100) — Số lượng mẫu được tạo song song cho mỗi bước thời gian của suy luận. - init_std (
float, tùy chọn, mặc định là0.02) — Độ lệch chuẩn của truncated_normal_initializer để khởi tạo tất cả các ma trận trọng số. - use_cache (
bool, tùy chọn, mặc định làTrue) — Xác định xem mô hình có nên trả về các chú ý key/values cuối cùng hay không (không được sử dụng bởi tất cả các mô hình). Chỉ liên quan nếuconfig.is_decoder=Truehoặc khi mô hình là mô hình sinh chỉ có decoder. - label_length (
int, tùy chọn, mặc định là 10) — Độ dài token bắt đầu của bộ giải mã Autoformer, được sử dụng cho dự đoán đa bước trực tiếp (tức là sinh phi tự hồi quy). - moving_average (
int, tùy chọn, mặc định là 25) — Kích thước cửa sổ của trung bình trượt. Trên thực tế, đây là kích thước nhân trong AvgPool1d của lớp Phân rã (Decomposition Layer). - autocorrelation_factor (
int, tùy chọn, mặc định là 3) — Hệ số “Attention” (tức là cơ chế AutoCorrelation) được sử dụng để tìm các độ trễ tự tương quan hàng đầu k. Giấy nghiên cứu khuyến nghị đặt giá trị này trong khoảng từ 1 đến 5.
Đây là lớp cấu hình để lưu trữ cấu hình của một AutoformerModel. Nó được sử dụng để khởi tạo một mô hình Autoformer theo các đối số được chỉ định, xác định kiến trúc của mô hình. Khởi tạo một cấu hình với các giá trị mặc định sẽ tạo ra một cấu hình tương tự như cấu hình của huggingface/autoformer-tourism-monthly
Các đối tượng cấu hình kế thừa từ PreTrainedConfig và có thể được sử dụng để kiểm soát đầu ra của mô hình. Đọc tài liệu từ PreTrainedConfig để biết thêm thông tin.
Ví dụ:
>>> 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
lớp transformers.AutoformerModel
< source >( config: AutoformerConfig )
Tham số
- config (AutoformerConfig) — Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức from_pretrained() để tải trọng số của mô hình.
Mô hình Autoformer cơ bản, xuất ra các hidden-state thô mà không có bất kỳ head cụ thể nào ở phía trên.
Mô hình này kế thừa từ PreTrainedModel. Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu, v.v.)
Mô hình này cũng là một lớp con của torch.nn.Module trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.
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)
Tham số
- past_values (
torch.Tensorcó hình dạng(batch_size, sequence_length)) — Các giá trị quá khứ của chuỗi thời gian, đóng vai trò là ngữ cảnh để dự đoán tương lai. Các giá trị này có thể chứa các độ trễ (lags), tức là các giá trị bổ sung từ quá khứ được thêm vào để phục vụ như “ngữ cảnh bổ sung”.past_valueslà phần đầu vào mà bộ mã hóa Transformer nhận được (kèm theo các đặc trưng bổ sung tùy chọn, chẳng hạn nhưstatic_categorical_features,static_real_features,past_time_features).Chiều dài chuỗi ở đây bằng
context_length+max(config.lags_sequence).Các giá trị thiếu cần được thay thế bằng số không.
- past_time_features (
torch.Tensorcó hình dạng(batch_size, sequence_length, num_features), tùy chọn) — Các đặc trưng thời gian tùy chọn, mà mô hình sẽ tự động thêm vàopast_values. Các đặc trưng này có thể là những thứ như “tháng trong năm”, “ngày trong tháng”, v.v. được mã hóa dưới dạng vector (ví dụ như Fourier features). Chúng cũng có thể là các đặc trưng “tuổi” (age features), về cơ bản giúp mô hình biết “điểm nào trong vòng đời” của một chuỗi thời gian. Các đặc trưng tuổi có giá trị nhỏ cho các bước thời gian ở quá khứ xa và tăng đơn điệu khi chúng ta tiến gần hơn đến bước thời gian hiện tại.Các đặc trưng này đóng vai trò là “mã hóa vị trí” của các đầu vào. Do đó, trái ngược với một mô hình như BERT, trong đó các mã hóa vị trí được học từ đầu bên trong như các tham số của mô hình, Time Series Transformer yêu cầu phải cung cấp các đặc trưng thời gian bổ sung.
Autoformer chỉ học các embedding bổ sung cho
static_categorical_features. - past_observed_mask (
torch.BoolTensorcó hình dạng(batch_size, sequence_length), tùy chọn) — Mặt nạ Boolean để chỉ ra nhữngpast_valuesnào đã được quan sát và những cái nào bị thiếu. Giá trị mặt nạ được chọn trong[0, 1]:- 1 cho các giá trị được quan sát,
- 0 cho các giá trị thiếu (tức là các NaN đã được thay thế bằng số 0).
- static_categorical_features (
torch.LongTensorcó hình dạng(batch_size, number of static categorical features), tùy chọn) — Các đặc trưng phân loại tĩnh tùy chọn mà mô hình sẽ học một embedding, sau đó cộng vào các giá trị của chuỗi thời gian.Các đặc trưng phân loại tĩnh là các đặc trưng có cùng giá trị cho tất cả các bước thời gian (tĩnh theo thời gian).
Một ví dụ điển hình về đặc trưng phân loại tĩnh là ID của chuỗi thời gian.
- static_real_features (
torch.Tensorcó hình dạng(batch_size, number of static real features), tùy chọn) — Các đặc trưng thực tĩnh tùy chọn mà mô hình sẽ thêm vào giá trị của chuỗi thời gian.Các đặc trưng thực tĩnh là các đặc trưng có cùng giá trị cho tất cả các bước thời gian (tĩnh theo thời gian).
Một ví dụ điển hình về đặc trưng thực tĩnh là thông tin khuyến mãi.
- future_values (
torch.Tensorcó hình dạng(batch_size, prediction_length)) — Các giá trị tương lai của chuỗi thời gian, đóng vai trò là nhãn cho mô hình.future_valueslà thứ mà Transformer cần học để xuất ra, dựa trênpast_values.Xem notebook demo và các đoạn mã để biết thêm chi tiết.
Các giá trị thiếu cần được thay thế bằng số không.
- future_time_features (
torch.Tensorcó hình dạng(batch_size, prediction_length, num_features), không bắt buộc) — Các đặc trưng thời gian tùy chọn, mà mô hình sẽ tự động thêm vàofuture_values. Các đặc trưng này có thể là những thứ như “tháng trong năm”, “ngày trong tháng”, v.v. được mã hóa dưới dạng vector (ví dụ như Fourier features). Chúng cũng có thể là các đặc trưng “tuổi” (age features), về cơ bản giúp mô hình biết “điểm nào trong vòng đời” của một chuỗi thời gian. Các đặc trưng tuổi có giá trị nhỏ ở các bước thời gian xa trong quá khứ và tăng đơn điệu khi chúng ta tiến gần hơn đến bước thời gian hiện tại.Các đặc trưng này đóng vai trò là “mã hóa vị trí” của các đầu vào. Do đó, trái ngược với một mô hình như BERT, trong đó các mã hóa vị trí được học từ đầu bên trong như các tham số của mô hình, Time Series Transformer yêu cầu phải cung cấp các đặc trưng bổ sung.
Autoformer chỉ học các embedding bổ sung cho
static_categorical_features. - decoder_attention_mask (
torch.LongTensorcó shape(batch_size, target_sequence_length), tùy chọn) — Mặt nạ để tránh thực hiện chú ý trên một số chỉ số token nhất định. Mặc định, một mặt nạ nhân quả sẽ được sử dụng để đảm bảo mô hình chỉ có thể nhìn vào các đầu vào trước đó nhằm dự đoán tương lai. - encoder_outputs (
tuple(tuple(torch.Tensor), optional) — Tuple bao gồmlast_hidden_state,hidden_states(optional) vàattentions(optional)last_hidden_statecó shape(batch_size, sequence_length, hidden_size)(optional) là một chuỗi các hidden-states tại đầu ra của lớp cuối cùng của encoder. Được sử dụng trong cross-attention của decoder. - past_key_values (
~cache_utils.Cache, tuỳ chọn) — Các hidden-state đã tính trước (key và value trong các khối self-attention và cross-attention) có thể được sử dụng để tăng tốc giải mã tuần tự. Điều này thường bao gồmpast_key_valuesđược trả về bởi mô hình ở một giai đoạn giải mã trước đó, khiuse_cache=Truehoặcconfig.use_cache=True.Chỉ cho phép Cache instance làm đầu vào, xem hướng dẫn kv cache của chúng tôi. Nếu không truyền
past_key_values, DynamicCache sẽ được khởi tạo theo mặc định.Mô hình sẽ xuất ra cùng định dạng cache được đưa vào làm đầu vào.
Nếu
past_key_valuesđược sử dụng, người dùng được kỳ vọng chỉ nhậpinput_idschưa được xử lý (những phần chưa có trạng thái key value quá khứ được cung cấp cho mô hình này) có hình dạng(batch_size, unprocessed_length)thay vì toàn bộinput_idscó hình dạng(batch_size, sequence_length). - use_cache (
bool, tùy chọn) — Nếu đặt thànhTrue, các trạng thái key value củapast_key_valuessẽ được trả về và có thể được sử dụng để tăng tốc quá trình giải mã (xempast_key_values).
Trả về
AutoformerModelOutput hoặc tuple(torch.Tensor)
Một AutoformerModelOutput hoặc một tuple của
torch.Tensor (nếu return_dict=False được truyền hoặc khi config.return_dict=False) bao gồm các
thành phần khác nhau tùy thuộc vào cấu hình (AutoformerConfig) và đầu vào.
Phương thức forward của AutoformerModel ghi đè lên phương thức đặc biệt __call__.
Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, người dùng nên gọi instance của
Modulesau đó thay vì gọi hàm này, vì instanceModulesẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ lặng lẽ bỏ qua chúng.
last_hidden_state (
torch.Tensorcó hình dạng(batch_size, sequence_length, hidden_size)) — Chuỗi các hidden-state tại đầu ra của lớp cuối cùng của bộ giải mã (decoder) của mô hình.Nếu
past_key_valuesđược sử dụng, chỉ có hidden-state cuối cùng của các chuỗi có shape(batch_size, 1, hidden_size)được xuất ra.trend (
torch.Tensorcó hình dạng(batch_size, sequence_length, hidden_size)) — Tensor xu hướng cho mỗi chuỗi thời gian.past_key_values (
Cache, tùy chọn, được trả về khiuse_cache=Trueđược truyền vào hoặc khiconfig.use_cache=True) — Đây là một instance của Cache. Để biết thêm chi tiết, hãy xem hướng dẫn về kv cache của chúng tôi.Chứa các hidden-states đã được tính trước (key và values trong các khối self-attention và trong các khối cross-attention) có thể được sử dụng (xem đầu vào
past_key_values) để tăng tốc độ giải mã tuần tự.decoder_hidden_states (
tuple[torch.Tensor], tuỳ chọn, được trả về khioutput_hidden_states=Trueđược truyền vào hoặc khiconfig.output_hidden_states=True) — Tuple củatorch.Tensor(một cho đầu ra của embeddings, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng(batch_size, sequence_length, hidden_size).Trạng thái ẩn của bộ giải mã tại đầu ra của mỗi lớp cùng với đầu ra của nhúng ban đầu.
decoder_attentions (
tuple[torch.Tensor], tùy chọn, được trả về khioutput_attentions=Trueđược truyền vào hoặc khiconfig.output_attentions=True) — Tuple củatorch.Tensor(một cho mỗi lớp) có hình dạng(batch_size, num_heads, sequence_length, sequence_length).Trọng số chú ý của bộ giải mã, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý tự (self-attention).
cross_attentions (
tuple[torch.Tensor], tuỳ chọn, được trả về khioutput_attentions=Trueđược truyền vào hoặc khiconfig.output_attentions=True) — Tuple củatorch.Tensor(một cho mỗi lớp) có hình dạng(batch_size, num_heads, sequence_length, sequence_length).Trọng số chú ý của lớp cross-attention của bộ giải mã, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý chéo.
encoder_last_hidden_state (
torch.Tensorcó hình dạng(batch_size, sequence_length, hidden_size), tùy chọn) — Chuỗi các trạng thái ẩn tại đầu ra của lớp cuối cùng của bộ mã hóa trong mô hình.encoder_hidden_states (
tuple[torch.Tensor], tuỳ chọn, được trả về khioutput_hidden_states=Trueđược truyền vào hoặc khiconfig.output_hidden_states=True) — Bộ tuple cáctorch.Tensor(một cho đầu ra của embeddings, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng(batch_size, sequence_length, hidden_size).Trạng thái ẩn của bộ mã hóa tại đầu ra của mỗi lớp cùng với đầu ra của nhúng ban đầu.
encoder_attentions (
tuple[torch.Tensor], tuỳ chọn, được trả về khioutput_attentions=Trueđược truyền vào hoặc khiconfig.output_attentions=True) — Bộ tuple củatorch.Tensor(một cho mỗi lớp) có hình dạng(batch_size, num_heads, sequence_length, sequence_length).Trọng số chú ý của bộ mã hóa, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý tự (self-attention).
loc (
torch.Tensorcó shape(batch_size,)hoặc(batch_size, input_size), optional) — Các giá trị dịch chuyển của context window cho mỗi chuỗi thời gian, được dùng để cung cấp cho mô hình các đầu vào có cùng độ lớn, sau đó dùng để dịch chuyển ngược lại về độ lớn ban đầu.scale (
torch.Tensorcó shape(batch_size,)hoặc(batch_size, input_size), optional) — Các giá trị scale của context window cho từng chuỗi thời gian, được dùng để đưa đầu vào của mô hình về cùng một bậc độ lớn, sau đó dùng để rescale ngược lại về bậc độ lớn ban đầu. static_features: (torch.Tensorcó shape(batch_size, feature size), optional): Các static features của từng chuỗi thời gian trong một batch, được sao chép sang covariates tại thời điểm inference.static_features (
torch.Tensorcó hình dạng(batch_size, feature size), tùy chọn) — Các đặc trưng tĩnh của mỗi chuỗi thời gian trong một batch, được sao chép vào các biến ngoại sinh (covariates) tại thời điểm suy luận.
Ví dụ:
>>> 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
lớp transformers.AutoformerForPrediction
< source >( config: AutoformerConfig )
Tham số
- config (AutoformerConfig) — Lớp cấu hình mô hình chứa tất cả các tham số của mô hình. Khởi tạo bằng tệp cấu hình không tải trọng số liên quan đến mô hình, chỉ tải cấu hình. Xem phương thức from_pretrained() để tải trọng số của mô hình.
Mô hình Autoformer với một đầu phân phối phía trên cho dự báo chuỗi thời gian.
Mô hình này kế thừa từ PreTrainedModel. Xem tài liệu của lớp cha để biết các phương thức chung mà thư viện triển khai cho tất cả các mô hình của nó (chẳng hạn như tải xuống hoặc lưu trữ, thay đổi kích thước các nhúng đầu vào, cắt tỉa các đầu, v.v.)
Mô hình này cũng là một lớp con của torch.nn.Module trong PyTorch. Hãy sử dụng nó như một Module PyTorch thông thường và tham khảo tài liệu PyTorch cho mọi vấn đề liên quan đến cách sử dụng và hành vi chung.
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)
Tham số
- past_values (
torch.Tensorcó hình dạng(batch_size, sequence_length)) — Các giá trị quá khứ của chuỗi thời gian, đóng vai trò là ngữ cảnh để dự đoán tương lai. Các giá trị này có thể chứa các độ trễ (lags), tức là các giá trị bổ sung từ quá khứ được thêm vào để phục vụ như “ngữ cảnh bổ sung”.past_valueslà phần đầu vào mà bộ mã hóa Transformer nhận được (kèm theo các đặc trưng bổ sung tùy chọn, chẳng hạn nhưstatic_categorical_features,static_real_features,past_time_features).Chiều dài chuỗi ở đây bằng
context_length+max(config.lags_sequence).Các giá trị thiếu cần được thay thế bằng số không.
- past_time_features (
torch.Tensorcó hình dạng(batch_size, sequence_length, num_features), tùy chọn) — Các đặc trưng thời gian tùy chọn, mà mô hình sẽ tự động thêm vàopast_values. Các đặc trưng này có thể là những thứ như “tháng trong năm”, “ngày trong tháng”, v.v. được mã hóa dưới dạng vector (ví dụ như Fourier features). Chúng cũng có thể là các đặc trưng “tuổi” (age features), về cơ bản giúp mô hình biết “điểm nào trong vòng đời” của một chuỗi thời gian. Các đặc trưng tuổi có giá trị nhỏ cho các bước thời gian ở quá khứ xa và tăng đơn điệu khi chúng ta tiến gần hơn đến bước thời gian hiện tại.Các đặc trưng này đóng vai trò là “mã hóa vị trí” của các đầu vào. Do đó, trái ngược với một mô hình như BERT, trong đó các mã hóa vị trí được học từ đầu bên trong như các tham số của mô hình, Time Series Transformer yêu cầu phải cung cấp các đặc trưng thời gian bổ sung.
Autoformer chỉ học các embedding bổ sung cho
static_categorical_features. - past_observed_mask (
torch.BoolTensorcó hình dạng(batch_size, sequence_length), tùy chọn) — Mặt nạ Boolean để chỉ ra nhữngpast_valuesnào đã được quan sát và những cái nào bị thiếu. Giá trị mặt nạ được chọn trong[0, 1]:- 1 cho các giá trị được quan sát,
- 0 cho các giá trị thiếu (tức là các NaN đã được thay thế bằng số 0).
- static_categorical_features (
torch.LongTensorcó hình dạng(batch_size, number of static categorical features), tùy chọn) — Các đặc trưng phân loại tĩnh tùy chọn mà mô hình sẽ học một embedding, sau đó cộng vào các giá trị của chuỗi thời gian.Các đặc trưng phân loại tĩnh là các đặc trưng có cùng giá trị cho tất cả các bước thời gian (tĩnh theo thời gian).
Một ví dụ điển hình về đặc trưng phân loại tĩnh là ID của chuỗi thời gian.
- static_real_features (
torch.Tensorcó hình dạng(batch_size, number of static real features), tùy chọn) — Các đặc trưng thực tĩnh tùy chọn mà mô hình sẽ thêm vào giá trị của chuỗi thời gian.Các đặc trưng thực tĩnh là các đặc trưng có cùng giá trị cho tất cả các bước thời gian (tĩnh theo thời gian).
Một ví dụ điển hình về đặc trưng thực tĩnh là thông tin khuyến mãi.
- future_values (
torch.Tensorcó hình dạng(batch_size, prediction_length)) — Các giá trị tương lai của chuỗi thời gian, đóng vai trò là nhãn cho mô hình.future_valueslà thứ mà Transformer cần học để xuất ra, dựa trênpast_values.Xem notebook demo và các đoạn mã để biết thêm chi tiết.
Các giá trị thiếu cần được thay thế bằng số không.
- future_time_features (
torch.Tensorcó hình dạng(batch_size, prediction_length, num_features), không bắt buộc) — Các đặc trưng thời gian tùy chọn, mà mô hình sẽ tự động thêm vàofuture_values. Các đặc trưng này có thể là những thứ như “tháng trong năm”, “ngày trong tháng”, v.v. được mã hóa dưới dạng vector (ví dụ như Fourier features). Chúng cũng có thể là các đặc trưng “tuổi” (age features), về cơ bản giúp mô hình biết “điểm nào trong vòng đời” của một chuỗi thời gian. Các đặc trưng tuổi có giá trị nhỏ ở các bước thời gian xa trong quá khứ và tăng đơn điệu khi chúng ta tiến gần hơn đến bước thời gian hiện tại.Các đặc trưng này đóng vai trò là “mã hóa vị trí” của các đầu vào. Do đó, trái ngược với một mô hình như BERT, trong đó các mã hóa vị trí được học từ đầu bên trong như các tham số của mô hình, Time Series Transformer yêu cầu phải cung cấp các đặc trưng bổ sung.
Autoformer chỉ học các embedding bổ sung cho
static_categorical_features. - future_observed_mask (
torch.BoolTensorcó hình dạng(batch_size, sequence_length)hoặc(batch_size, sequence_length, input_size), tuỳ chọn) — Mặt nạ Boolean để chỉ ra nhữngfuture_valuesđã được quan sát và những giá trị nào bị thiếu. Các giá trị mặt nạ được chọn trong [0, 1]: 1 cho các giá trị được quan sát, 0 cho các giá trị bị thiếu (tức là các NaN đã được thay thế bằng số không). Mặt nạ này được sử dụng để lọc bỏ các giá trị bị thiếu cho phép tính toán loss cuối cùng.[0, 1]:- 1 cho các giá trị được quan sát,
- 0 cho các giá trị thiếu (tức là các NaN đã được thay thế bằng số 0).
Mặt nạ này được sử dụng để lọc các giá trị thiếu cho việc tính toán loss cuối cùng.
- decoder_attention_mask (
torch.LongTensorcó shape(batch_size, target_sequence_length), tùy chọn) — Mặt nạ để tránh thực hiện chú ý trên một số chỉ số token nhất định. Mặc định, một mặt nạ nhân quả sẽ được sử dụng để đảm bảo mô hình chỉ có thể nhìn vào các đầu vào trước đó nhằm dự đoán tương lai. - encoder_outputs (
tuple(tuple(torch.Tensor), optional) — Tuple bao gồmlast_hidden_state,hidden_states(optional) vàattentions(optional)last_hidden_statecó shape(batch_size, sequence_length, hidden_size)(optional) là một chuỗi các hidden-states tại đầu ra của lớp cuối cùng của encoder. Được sử dụng trong cross-attention của decoder. - past_key_values (
~cache_utils.Cache, tuỳ chọn) — Các hidden-state đã tính trước (key và value trong các khối self-attention và cross-attention) có thể được sử dụng để tăng tốc giải mã tuần tự. Điều này thường bao gồmpast_key_valuesđược trả về bởi mô hình ở một giai đoạn giải mã trước đó, khiuse_cache=Truehoặcconfig.use_cache=True.Chỉ cho phép Cache instance làm đầu vào, xem hướng dẫn kv cache của chúng tôi. Nếu không truyền
past_key_values, DynamicCache sẽ được khởi tạo theo mặc định.Mô hình sẽ xuất ra cùng định dạng cache được đưa vào làm đầu vào.
Nếu
past_key_valuesđược sử dụng, người dùng được kỳ vọng chỉ nhậpinput_idschưa được xử lý (những phần chưa có trạng thái key value quá khứ được cung cấp cho mô hình này) có hình dạng(batch_size, unprocessed_length)thay vì toàn bộinput_idscó hình dạng(batch_size, sequence_length). - use_cache (
bool, tùy chọn) — Nếu đặt thànhTrue, các trạng thái key value củapast_key_valuessẽ được trả về và có thể được sử dụng để tăng tốc quá trình giải mã (xempast_key_values).
Trả về
Seq2SeqTSPredictionOutput hoặc tuple(torch.Tensor)
Một Seq2SeqTSPredictionOutput hoặc một tuple của
torch.Tensor (nếu return_dict=False được truyền hoặc khi config.return_dict=False) bao gồm các
thành phần khác nhau tùy thuộc vào cấu hình (AutoformerConfig) và đầu vào.
Phương thức forward của AutoformerForPrediction ghi đè lên phương thức đặc biệt __call__.
Mặc dù công thức cho bước truyền tiến cần được định nghĩa bên trong hàm này, người dùng nên gọi instance của
Modulesau đó thay vì gọi hàm này, vì instanceModulesẽ đảm nhận việc thực hiện các bước tiền xử lý và hậu xử lý, trong khi hàm này sẽ lặng lẽ bỏ qua chúng.
loss (
torch.Tensorcó shape(1,), tùy chọn, được trả về khi cung cấpfuture_values) — Loss phân phối.params (
torch.Tensorcó hình dạng(batch_size, num_samples, num_params)) — Tham số của phân phối được chọn.past_key_values (
EncoderDecoderCache, tùy chọn, được trả về khiuse_cache=Trueđược truyền vào hoặc khiconfig.use_cache=True) — Đây là một instance của EncoderDecoderCache. Để biết thêm chi tiết, hãy xem hướng dẫn về kv cache của chúng tôi.Chứa các hidden-states đã được tính trước (key và values trong các khối self-attention và trong các khối cross-attention) có thể được sử dụng (xem đầu vào
past_key_values) để tăng tốc độ giải mã tuần tự.decoder_hidden_states (
tuple(torch.Tensor), tuỳ chọn, được trả về khioutput_hidden_states=Trueđược truyền vào hoặc khiconfig.output_hidden_states=True) — Tuple củatorch.Tensor(một cho đầu ra của embeddings, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng(batch_size, sequence_length, hidden_size).Trạng thái ẩn của bộ giải mã tại đầu ra của mỗi lớp cùng với đầu ra của nhúng ban đầu.
decoder_attentions (
tuple(torch.Tensor), tùy chọn, được trả về khi truyềnoutput_attentions=Truehoặc khiconfig.output_attentions=True) — Tuple củatorch.Tensor(một cho mỗi lớp) có hình dạng(batch_size, num_heads, sequence_length, sequence_length).Trọng số chú ý của bộ giải mã, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý tự (self-attention).
cross_attentions (
tuple(torch.Tensor), tuỳ chọn, được trả về khioutput_attentions=Trueđược truyền vào hoặc khiconfig.output_attentions=True) — Bộ tuple củatorch.Tensor(một cho mỗi lớp) có hình dạng(batch_size, num_heads, sequence_length, sequence_length).Trọng số chú ý của lớp cross-attention của bộ giải mã, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý chéo.
encoder_last_hidden_state (
torch.Tensorcó hình dạng(batch_size, sequence_length, hidden_size), tùy chọn) — Chuỗi các trạng thái ẩn tại đầu ra của lớp cuối cùng của bộ mã hóa trong mô hình.encoder_hidden_states (
tuple(torch.Tensor), tuỳ chọn, được trả về khioutput_hidden_states=Trueđược truyền vào hoặc khiconfig.output_hidden_states=True) — Bộ tuple củatorch.Tensor(một cho đầu ra của embeddings, nếu mô hình có lớp embedding, + một cho đầu ra của mỗi lớp) có hình dạng(batch_size, sequence_length, hidden_size).Trạng thái ẩn của bộ mã hóa tại đầu ra của mỗi lớp cùng với đầu ra của nhúng ban đầu.
encoder_attentions (
tuple(torch.Tensor), tùy chọn, được trả về khi truyềnoutput_attentions=Truehoặc khiconfig.output_attentions=True) — Tuple củatorch.Tensor(một cho mỗi lớp) có hình dạng(batch_size, num_heads, sequence_length, sequence_length).Trọng số chú ý của bộ mã hóa, sau softmax chú ý, được sử dụng để tính trung bình có trọng số trong các đầu chú ý tự (self-attention).
loc (
torch.Tensorcó shape(batch_size,)hoặc(batch_size, input_size), optional) — Các giá trị dịch chuyển của context window cho mỗi chuỗi thời gian, được dùng để cung cấp cho mô hình các đầu vào có cùng độ lớn, sau đó dùng để dịch chuyển ngược lại về độ lớn ban đầu.scale (
torch.Tensorcó shape(batch_size,)hoặc(batch_size, input_size), optional) — Các giá trị scale của context window cho từng chuỗi thời gian, được dùng để đưa đầu vào của mô hình về cùng một bậc độ lớn, sau đó dùng để rescale ngược lại về độ lớn gốc.static_features (
torch.Tensorcó hình dạng(batch_size, feature size), tùy chọn) — Các đặc trưng tĩnh của mỗi chuỗi thời gian trong một batch, được sao chép vào các biến ngoại sinh (covariates) tại thời điểm suy luận.
Ví dụ:
>>> 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 cũng có thể sử dụng static_real_features. Để làm điều này, hãy đặt num_static_real_features trong AutoformerConfig dựa trên số lượng các đặc trưng như vậy trong bộ dữ liệu (trong trường hợp của bộ dữ liệu tourism_monthly thì
bằng 1), khởi tạo mô hình và gọi như bên dưới:
>>> 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"], ... )