带有注意力机制的多变量时间序列LSTM自编码器

本仓库包含一个用于多变量时间序列预测的自编码器。它采用了论文 基于双阶段注意力机制的循环神经网络用于时间序列预测 中描述的两种注意力机制，并受到 Seanny123 的仓库 的启发。

下载与依赖

要克隆该仓库，请运行：

git clone https://github.com/JulesBelveze/time-series-autoencoder.git

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh  # Linux/macOS
# 或
brew install uv  # macOS 上使用 Homebrew

cd time-series-autoencoder
uv venv
uv pip sync pyproject.toml

pip install -r requirements.txt

使用方法

该项目使用 Hydra 作为配置解析器。您可以直接在 .yaml 文件中修改参数，也可以通过命令行标志来覆盖或设置参数（完整指南请参阅文档）。

python3 main.py -cn=[配置文件夹路径] -cp=[配置文件名]

可选参数：

  -h, --help            显示帮助信息并退出
  --batch-size BATCH_SIZE
                        批量大小
  --output-size OUTPUT_SIZE
                        输出大小：默认值为1，用于预测
  --label-col LABEL_COL
                        目标列名称
  --input-att INPUT_ATT
                        是否启用输入注意力机制
  --temporal-att TEMPORAL_ATT
                        是否启用时间注意力机制
  --seq-len SEQ_LEN     用于预测的窗口长度
  --hidden-size-encoder HIDDEN_SIZE_ENCODER
                        编码器隐藏状态的大小
  --hidden-size-decoder HIDDEN_SIZE_DECODER
                        解码器隐藏状态的大小
  --reg-factor1 REG_FACTOR1
                        如果使用稀疏自编码器，L1正则化的贡献因子
  --reg-factor2 REG_FACTOR2
                        如果使用稀疏自编码器，L2正则化的贡献因子
  --reg1 REG1           启用/禁用 L1 正则化
  --reg2 REG2           启用/禁用 L2 正则化
  --denoising DENOISING
                        是否使用去噪自编码器
  --do-train DO_TRAIN   是否训练模型
  --do-eval DO_EVAL     是否评估模型
  --data-path DATA_PATH
                        数据文件路径
  --output-dir OUTPUT_DIR
                        输出文件夹名称
  --ckpt CKPT           用于评估的检查点路径 

特性

• 处理多变量时间序列
• 注意力机制
• 去噪自编码器
• 稀疏自编码器

示例

您可以在 examples 目录下找到用于训练模型的脚本，分别适用于以下两种情况：

• 重构：数据集可在 这里 获取
• 预测：数据集可在 这里 获取

time-series-autoencoder 快速上手指南

本项目是一个基于 LSTM 和双重注意力机制的多变量时间序列自编码器，适用于时间序列预测、重构、去噪及稀疏编码任务。

环境准备

• 操作系统: Linux 或 macOS (Windows 用户建议使用 WSL)
• Python 版本: 建议 Python 3.8+
• 前置依赖:
  • git: 用于克隆代码库
  • pip 或 uv (推荐): 用于管理依赖包。uv 是一个极速的 Python 包安装器。

国内加速建议：在使用 pip 或 uv 安装依赖时，建议指定清华或阿里镜像源以提升下载速度。

安装步骤

1. 克隆项目

git clone https://github.com/JulesBelveze/time-series-autoencoder.git
cd time-series-autoencoder

2. 安装依赖

方案 A：使用 uv（推荐，速度更快）

首先安装 uv 工具：

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者 macOS (Homebrew)
brew install uv

创建虚拟环境并同步依赖（推荐添加国内镜像源）：

uv venv
# 使用阿里云镜像源加速安装
uv pip sync pyproject.toml --index-url https://mirrors.aliyun.com/pypi/simple/

方案 B：直接使用 pip

# 使用清华镜像源加速安装
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

本项目使用 Hydra 进行配置管理。你可以通过修改 .yaml 配置文件或直接使用命令行参数来运行模型。

最简单的运行示例

假设你已经准备好了数据文件，并且使用了默认的配置文件（通常位于 conf 目录下，具体文件名需查看项目结构，此处以通用方式演示）：

python3 main.py -cn=config -cp=conf

常用命令行参数示例

你可以直接通过旗帜（flags）覆盖默认配置。以下是一个典型的训练与评估命令示例：

python3 main.py \
  --data-path ./data/your_dataset.csv \
  --label-col target_column_name \
  --seq-len 10 \
  --batch-size 32 \
  --input-att true \
  --temporal-att true \
  --do-train true \
  --do-eval true \
  --output-dir ./results

关键参数说明：

• --data-path: 数据文件路径。
• --label-col: 目标列名（预测目标）。
• --seq-len: 用于预测的时间窗口长度。
• --input-att / --temporal-att: 是否启用输入注意力机制或时间注意力机制。
• --do-train / --do-eval: 控制是否执行训练或评估。
• --denoising: 设置为 true 可启用去噪自编码器模式。

数据集参考

项目提供了两个示例场景的数据集链接，可用于测试：

• 重构任务 (Reconstruction): 下载链接
• 预测任务 (Forecasting): 下载链接

更多详细配置请参考项目根目录下的 .yaml 配置文件或使用 python3 main.py --help 查看完整参数列表。