iotdb-ai 0.1.0__tar.gz

iotdb_ai-0.1.0/MANIFEST.in

@@ -0,0 +1,8 @@
+include README.md
+include QUICKSTART.md
+include ARCHITECTURE.md
+include LICENSE
+include requirements.txt
+recursive-include examples *.py
+recursive-include tests *.py
+

iotdb_ai-0.1.0/PKG-INFO

@@ -0,0 +1,424 @@
+Metadata-Version: 2.4
+Name: iotdb-ai
+Version: 0.1.0
+Summary: IoTDB AI Toolkit - High-performance time series machine learning toolkit
+Home-page: https://github.com/ycycse/IoTDB-AI
+Author: ycycse
+Author-email: dev@iotdb.apache.org
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.7
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.7
+Description-Content-Type: text/markdown
+Requires-Dist: torch>=1.7.0
+Requires-Dist: numpy>=1.19.0
+Requires-Dist: tsfile>=2.2.1
+Provides-Extra: dev
+Requires-Dist: pytest>=6.0; extra == "dev"
+Requires-Dist: black>=21.0; extra == "dev"
+Requires-Dist: flake8>=3.9; extra == "dev"
+Provides-Extra: iotdb
+Requires-Dist: apache-iotdb>=1.0.0; extra == "iotdb"
+Dynamic: author
+Dynamic: author-email
+Dynamic: classifier
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: provides-extra
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+# IoTDB AI Toolkit
+
+高性能时间序列机器学习工具包，为 IoTDB 和时间序列分析提供强大的 AI/ML 支持。
+
+## 🚀 特性
+
+### TsFileDataset - 高性能 PyTorch 数据集
+
+直接从 TsFile 文件读取数据用于深度学习模型训练，无需运行 IoTDB 服务器。
+
+**核心优势：**
+- 🔥 **高性能**：O(log n) 索引查找，使用官方 tsfile 包优化读取
+- 💾 **内存高效**：支持懒加载和预加载两种模式
+- 🎯 **简洁易用**：最少的参数配置，开箱即用
+- 🔧 **独立部署**：不依赖 IoTDB 服务器运行
+- 📦 **多文件支持**：自动处理多个 TsFile 文件
+- ✨ **官方支持**：使用 Apache TsFile 官方 Python 包，兼容性最佳
+
+### TsFileDataFrame - 懒加载时序数据分析视图
+
+对多个 TsFile 文件提供统一的 DataFrame 式访问接口，支持数组式索引和时间对齐查询。
+
+**核心优势：**
+- 📂 **多文件统一视图**：自动合并多个 TsFile 中的同名序列，透明处理跨文件数据
+- ⚡ **懒加载**：仅在查询时读取数据，大幅减少内存占用
+- 🔗 **多文件并行加载**：多文件场景下自动并行读取元数据，加速初始化
+- 🎯 **灵活索引**：支持按序号、名称、切片、列表等多种方式访问序列
+- 📊 **时间对齐查询**：通过 `.loc` 实现多序列时间对齐，自动填充 NaN
+- 🖨️ **友好展示**：内置格式化打印，支持截断展示和全量展示
+
+## 📦 安装
+
+```bash
+# 从源码安装
+git clone https://github.com/your-repo/IoTDB-AI.git
+cd IoTDB-AI
+pip install -e .
+
+# 或者使用 pip（如果已发布）
+pip install iotdb-ai
+```
+
+**依赖说明：**
+- `torch>=1.7.0` - PyTorch 深度学习框架
+- `numpy>=1.19.0` - 数值计算库
+- `tsfile>=2.0.0` - Apache TsFile 官方 Python 包（自动安装）
+
+## 🎯 快速开始
+
+### 基本使用
+
+```python
+from iotdb_ai import TsFileDataset
+from torch.utils.data import DataLoader
+
+# 创建数据集
+dataset = TsFileDataset(
+    tsfile_paths="data/sensor_data.tsfile",  # 单个文件或文件列表
+    seq_len=96,      # 输入序列长度（lookback window）
+    pred_len=24,     # 预测长度（forecast horizon）
+    window_stride=1  # 滑动窗口步长（默认1）
+)
+
+# 使用 PyTorch DataLoader
+dataloader = DataLoader(
+    dataset,
+    batch_size=32,
+    shuffle=True,
+    num_workers=4
+)
+
+# 训练模型
+for input_seq, target_seq in dataloader:
+    # input_seq: (batch_size, seq_len)
+    # target_seq: (batch_size, pred_len)
+    ...
+```
+
+### 多文件支持
+
+```python
+# 同时处理多个 TsFile 文件
+dataset = TsFileDataset(
+    tsfile_paths=[
+        "data/2024-01.tsfile",
+        "data/2024-02.tsfile",
+        "data/2024-03.tsfile",
+    ],
+    seq_len=168,     # 一周数据
+    pred_len=24,     # 预测未来一天
+)
+```
+
+### 预加载模式（小数据集）
+
+```python
+# 内存充足时，一次性加载所有数据获得最佳性能
+dataset = TsFileDataset(
+    tsfile_paths="data/small_dataset.tsfile",
+    seq_len=96,
+    pred_len=24,
+    preload=True  # 启用预加载
+)
+```
+
+## 📊 性能优化
+
+### 推荐配置
+
+根据数据集大小选择合适的配置：
+
+| 数据集大小 | 推荐配置 | 说明 |
+|-----------|---------|------|
+| < 1GB | `preload=True` | 全部加载到内存，极速访问 |
+| 1-10GB | `num_workers=4-8` | 多进程懒加载，平衡性能和内存 |
+| > 10GB | `window_stride=8+` | 增大步长减少样本数 |
+
+### DataLoader 优化
+
+```python
+dataloader = DataLoader(
+    dataset,
+    batch_size=32,
+    shuffle=True,
+    num_workers=4,           # 多进程并行加载
+    pin_memory=True,         # 加速 GPU 传输
+    persistent_workers=True  # 保持工作进程
+)
+```
+
+## 📚 API 文档
+
+### TsFileDataset
+
+```python
+TsFileDataset(
+    tsfile_paths: Union[str, List[str]],  # TsFile 文件路径
+    seq_len: int,                         # 输入序列长度
+    pred_len: int,                        # 预测序列长度
+    window_stride: int = 1,               # 滑动窗口步长
+    preload: bool = False,                # 是否预加载到内存
+)
+```
+
+**方法：**
+- `__len__()`: 返回数据集样本总数
+- `__getitem__(index)`: 获取指定索引的样本
+- `get_series_count()`: 返回时间序列数量
+- `get_info()`: 返回数据集详细信息
+
+**返回值：**
+- `(input_seq, target_seq)` 元组
+  - `input_seq`: torch.Tensor, shape `(seq_len,)`
+  - `target_seq`: torch.Tensor, shape `(pred_len,)`
+
+### TsFileDataFrame
+
+```python
+TsFileDataFrame(
+    paths: Union[str, List[str]],  # TsFile 文件路径、路径列表或目录路径
+    show_progress: bool = True,    # 是否显示加载进度
+)
+```
+
+**属性：**
+- `timeseries` -> `List[dict]`: 所有序列的元信息列表，每项包含 `ts_name`、`start_time`、`end_time`、`count`
+- `loc` -> `_LocIndexer`: 时间对齐查询索引器
+
+**方法：**
+- `__len__()`: 返回序列总数
+- `__getitem__(key)`: 按索引(int)、名称(str)、切片(slice)或列表(list)访问序列
+- `list_timeseries(path_prefix="")`: 按前缀过滤序列名称
+- `close()`: 关闭所有底层文件句柄
+- 支持 `with` 上下文管理器
+
+### Timeseries
+
+由 `TsFileDataFrame[...]` 返回的单条时间序列对象。
+
+**属性：**
+- `name` -> `str`: 序列完整路径
+- `timestamps` -> `np.ndarray`: 毫秒时间戳数组
+- `stats` -> `dict`: 包含 `start_time`、`end_time`、`count`
+
+**方法：**
+- `__len__()`: 返回数据点数量
+- `__getitem__(key)`: 行索引访问，支持 `ts[20]`（单值）和 `ts[20:100]`（切片，返回 np.ndarray）
+
+### AlignedTimeseries
+
+由 `.loc[...]` 返回的时间对齐查询结果。
+
+**属性：**
+- `timestamps` -> `np.ndarray`: 对齐后的毫秒时间戳
+- `values` -> `np.ndarray`: shape `(rows, cols)` 的值矩阵，缺失值为 NaN
+- `series_names` -> `List[str]`: 列对应的序列名称
+- `shape` -> `tuple`: values 的形状
+
+**方法：**
+- `__len__()`: 返回行数
+- `__getitem__(key)`: 索引访问 values，支持 `result[i]` 和 `result[i, j]`
+- `show(max_rows=None)`: 格式化打印表格，可指定最大行数
+
+### TsFileDataFrame 使用
+
+#### 基本使用
+
+```python
+from iotdb_ai import TsFileDataFrame
+
+# 从单个文件创建
+df = TsFileDataFrame("data/sensor_data.tsfile")
+
+# 从多个文件创建（同名序列自动合并）
+df = TsFileDataFrame([
+    "data/2024-01.tsfile",
+    "data/2024-02.tsfile",
+])
+
+# 从目录创建（自动扫描目录下所有 .tsfile 文件）
+df = TsFileDataFrame("data/")
+
+# 查看概览
+print(df)
+# TsFileDataFrame(5 time series, 2 files)
+#      ts_name            start_time              end_time  count
+#  0   weather.Beijing.temperature   2024-01-01 00:00:00   2024-06-30 23:00:00   4344
+#  1   weather.Beijing.humidity      2024-01-01 00:00:00   2024-06-30 23:00:00   4344
+#  ...
+```
+
+#### 访问单条时间序列
+
+```python
+# 按索引访问
+ts = df[0]              # 第一条序列
+ts = df[-1]             # 最后一条序列
+
+# 按名称访问
+ts = df['weather.Beijing.humidity']
+
+# 查看序列信息
+print(ts)               # Timeseries('weather.Beijing.humidity', count=4344, ...)
+print(len(ts))          # 4344
+print(ts.stats)         # {'start_time': ..., 'end_time': ..., 'count': 4344}
+
+# 行索引访问数据
+val = ts[0]             # 第一个值
+vals = ts[100:200]      # 第 100~199 行的值（返回 np.ndarray）
+```
+
+#### 批量访问序列
+
+```python
+# 切片
+series_list = df[1:3]       # 返回 List[Timeseries]
+
+# 列表索引
+series_list = df[[0, 2, 4]] # 返回 List[Timeseries]
+
+# 列出满足前缀的序列名
+names = df.list_timeseries("weather.Beijing")
+```
+
+#### 时间对齐查询 (.loc)
+
+```python
+# 按时间范围 + 序列名查询，返回 AlignedTimeseries
+result = df.loc[
+    1704067200000:1704153600000,       # 时间范围（毫秒时间戳）
+    ['weather.Beijing.temperature',
+     'weather.Beijing.humidity']
+]
+
+# 也支持按序列索引号
+result = df.loc[1704067200000:1704153600000, [0, 1]]
+
+print(result)
+# AlignedTimeseries(24 rows, 2 series)
+#            timestamp  weather.Beijing.temperature  weather.Beijing.humidity
+#  2024-01-01 00:00:00                        -2.50                    45.00
+#  2024-01-01 01:00:00                        -3.10                    47.20
+#  ...
+
+# 访问底层数据
+result.timestamps   # np.ndarray, 毫秒时间戳
+result.values       # np.ndarray, shape (rows, cols)
+result.series_names # ['weather.Beijing.temperature', 'weather.Beijing.humidity']
+result[0]           # 第一行所有列的值
+result[0, 1]        # 第一行第二列的值
+
+# 控制显示行数
+result.show()       # 显示全部行
+result.show(50)     # 显示前 50 行
+```
+
+#### 上下文管理器
+
+```python
+with TsFileDataFrame("data/sensor_data.tsfile") as df:
+    ts = df[0]
+    vals = ts[:100]
+# 自动关闭文件句柄
+```
+
+## 🎓 示例
+
+查看 `examples/` 目录获取更多示例：
+
+- `tsfile_basic_usage.py` - 基本使用方法
+- 更多示例即将推出...
+
+## 🏗️ 架构设计
+
+### 核心组件
+
+1. **TsFileDataset** (`iotdb_ai/tsfile/dataset.py`)
+   - 主数据集类，实现 PyTorch Dataset 接口
+   - 高效的索引结构（二分查找 + 前缀和）
+   - 支持懒加载和预加载模式
+
+2. **TsFileDataFrame** (`iotdb_ai/tsfile/dataframe.py`)
+   - 多文件统一视图，DataFrame 式访问接口
+   - 时间对齐查询（`.loc`），自动填充 NaN
+   - 跨文件同名序列自动合并
+
+3. **TsFileReader** (`iotdb_ai/tsfile/reader.py`)
+   - 底层 TsFile 读取器
+   - 双模式：快速解析 + IoTDB 官方库回退
+   - 优化的批量读取
+
+### 性能特性
+
+- **O(log n) 查找**：使用二分查找快速定位时间序列
+- **批量读取**：一次读取完整序列，减少 I/O 次数
+- **多进程支持**：与 PyTorch DataLoader 无缝集成
+- **内存优化**：按需加载，可选预加载
+
+## 🔧 开发
+
+### 安装开发依赖
+
+```bash
+pip install -e ".[dev]"
+```
+
+### 运行测试
+
+```bash
+pytest tests/ -v
+```
+
+### 代码格式化
+
+```bash
+black iotdb_ai/
+flake8 iotdb_ai/
+```
+
+## 📝 未来规划
+
+- [x] 多变量时间序列支持
+- [x] 时间范围过滤
+- [x] 序列名称/模式过滤
+- [ ] 数据增强功能
+- [ ] 更多预训练模型
+- [ ] 分布式训练支持
+
+## 🤝 贡献
+
+欢迎提交 Issue 和 Pull Request！
+
+## 📄 License
+
+Apache License 2.0
+
+## 📮 联系
+
+- 项目主页: https://iotdb.apache.org/
+- 问题反馈: [GitHub Issues](https://github.com/apache/iotdb/issues)
+
+---
+
+**注意：** 这是一个早期版本，API 可能会有变化。欢迎反馈和建议！

iotdb_ai-0.1.0/QUICKSTART.md

@@ -0,0 +1,281 @@
+# IoTDB AI - 快速入门指南
+
+本指南将帮助你快速开始使用 IoTDB AI Toolkit 进行时间序列模型训练。
+
+## 前置要求
+
+- Python >= 3.7
+- PyTorch >= 1.7.0
+- NumPy >= 1.19.0
+
+## 安装
+
+```bash
+cd IoTDB-AI
+pip install -e .
+```
+
+## 准备数据
+
+### 方式1：从 IoTDB 导出 TsFile
+
+如果你已经有 IoTDB 实例运行：
+
+```bash
+# 使用 IoTDB CLI 导出数据
+./sbin/export-tsfile.sh -h 127.0.0.1 -p 6667 -u root -pw root \
+  -s "root.sg1.**" -t "2024-01-01" -e "2024-12-31" -o "data.tsfile"
+```
+
+### 方式2：使用已有的 TsFile 文件
+
+如果你已经有 TsFile 文件，可以直接使用。
+
+## 第一个例子
+
+创建 `train.py`：
+
+```python
+import torch
+import torch.nn as nn
+from torch.utils.data import DataLoader
+from iotdb_ai import TsFileDataset
+
+# 1. 创建数据集
+dataset = TsFileDataset(
+    tsfile_paths="data.tsfile",
+    seq_len=96,      # 使用过去96个时间点
+    pred_len=24,     # 预测未来24个时间点
+    window_stride=1  # 每次移动1个时间点
+)
+
+print(f"数据集信息: {dataset.get_info()}")
+
+# 2. 创建 DataLoader
+train_loader = DataLoader(
+    dataset,
+    batch_size=32,
+    shuffle=True,
+    num_workers=4
+)
+
+# 3. 定义一个简单的模型
+class SimpleForecaster(nn.Module):
+    def __init__(self, seq_len, pred_len, hidden_size=128):
+        super().__init__()
+        self.lstm = nn.LSTM(1, hidden_size, batch_first=True)
+        self.linear = nn.Linear(hidden_size, pred_len)
+    
+    def forward(self, x):
+        # x shape: (batch, seq_len)
+        x = x.unsqueeze(-1)  # (batch, seq_len, 1)
+        out, _ = self.lstm(x)
+        out = out[:, -1, :]  # 取最后一个时间步
+        pred = self.linear(out)
+        return pred
+
+model = SimpleForecaster(seq_len=96, pred_len=24)
+criterion = nn.MSELoss()
+optimizer = torch.optim.Adam(model.parameters(), lr=0.001)
+
+# 4. 训练循环
+print("开始训练...")
+for epoch in range(10):
+    total_loss = 0
+    for batch_idx, (inputs, targets) in enumerate(train_loader):
+        # 前向传播
+        outputs = model(inputs)
+        loss = criterion(outputs, targets)
+        
+        # 反向传播
+        optimizer.zero_grad()
+        loss.backward()
+        optimizer.step()
+        
+        total_loss += loss.item()
+    
+    avg_loss = total_loss / len(train_loader)
+    print(f"Epoch {epoch+1}/10, Loss: {avg_loss:.4f}")
+
+print("训练完成！")
+
+# 5. 保存模型
+torch.save(model.state_dict(), "forecaster.pth")
+```
+
+运行：
+
+```bash
+python train.py
+```
+
+## 常见使用场景
+
+### 场景1：长序列预测
+
+```python
+# 使用7天数据预测未来1天
+dataset = TsFileDataset(
+    tsfile_paths="data.tsfile",
+    seq_len=168,    # 7天 * 24小时
+    pred_len=24,    # 1天
+    window_stride=24  # 每次跳过1天，减少样本重叠
+)
+```
+
+### 场景2：多文件训练
+
+```python
+# 训练集使用多个月份的数据
+dataset = TsFileDataset(
+    tsfile_paths=[
+        "data/2024-01.tsfile",
+        "data/2024-02.tsfile",
+        "data/2024-03.tsfile",
+    ],
+    seq_len=96,
+    pred_len=24,
+)
+```
+
+### 场景3：小数据集快速训练
+
+```python
+# 小数据集全部加载到内存
+dataset = TsFileDataset(
+    tsfile_paths="data.tsfile",
+    seq_len=96,
+    pred_len=24,
+    preload=True  # 关键：预加载
+)
+
+# 可以使用更多 workers
+dataloader = DataLoader(dataset, batch_size=32, num_workers=8)
+```
+
+### 场景4：GPU 训练优化
+
+```python
+# GPU 训练配置
+device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
+model = model.to(device)
+
+dataloader = DataLoader(
+    dataset,
+    batch_size=64,
+    shuffle=True,
+    num_workers=4,
+    pin_memory=True,  # 关键：加速 GPU 传输
+    persistent_workers=True
+)
+
+for inputs, targets in dataloader:
+    inputs = inputs.to(device)
+    targets = targets.to(device)
+    # ... 训练代码
+```
+
+## 性能调优
+
+### 1. 选择合适的 batch_size
+
+```python
+# 测试不同的 batch_size
+for batch_size in [16, 32, 64, 128]:
+    dataloader = DataLoader(dataset, batch_size=batch_size)
+    # 测试训练速度
+```
+
+### 2. 调整 num_workers
+
+```python
+# CPU 核心数的 2-4 倍通常效果最好
+import multiprocessing
+optimal_workers = min(multiprocessing.cpu_count() * 2, 8)
+
+dataloader = DataLoader(dataset, num_workers=optimal_workers)
+```
+
+### 3. 使用合适的 window_stride
+
+```python
+# 大数据集：增大 stride 减少样本数
+dataset = TsFileDataset(
+    tsfile_paths="large_data.tsfile",
+    seq_len=96,
+    pred_len=24,
+    window_stride=8  # 每次跳8个点
+)
+```
+
+## 常见问题
+
+### Q1: 找不到 TsFile 文件
+
+**A:** 确保文件路径正确，使用绝对路径或相对于运行目录的路径。
+
+```python
+import os
+file_path = os.path.abspath("data.tsfile")
+dataset = TsFileDataset(tsfile_paths=file_path, ...)
+```
+
+### Q2: 内存不足
+
+**A:** 使用懒加载模式（默认），不要设置 `preload=True`。
+
+```python
+# 默认懒加载，内存占用小
+dataset = TsFileDataset(
+    tsfile_paths="data.tsfile",
+    seq_len=96,
+    pred_len=24,
+    window_stride=8  # 增大步长也可以减少内存
+)
+```
+
+### Q3: 训练速度慢
+
+**A:** 尝试以下优化：
+
+1. 增加 `num_workers`
+2. 使用 `pin_memory=True`（GPU训练）
+3. 增大 `batch_size`
+4. 小数据集使用 `preload=True`
+
+```python
+dataloader = DataLoader(
+    dataset,
+    batch_size=64,        # 增大
+    num_workers=8,        # 增大
+    pin_memory=True,      # GPU加速
+    persistent_workers=True
+)
+```
+
+### Q4: 如何查看数据集信息
+
+**A:** 使用 `get_info()` 方法：
+
+```python
+dataset = TsFileDataset(...)
+info = dataset.get_info()
+print(f"时间序列数: {info['series_count']}")
+print(f"总样本数: {info['total_windows']}")
+print(f"文件列表: {info['files']}")
+```
+
+## 下一步
+
+- 查看 `examples/` 目录获取更多示例
+- 阅读 API 文档了解详细参数
+- 参考架构文档理解实现细节
+
+## 获取帮助
+
+- 查看 [README.md](README.md) 了解更多功能
+- 提交 Issue: https://github.com/apache/iotdb/issues
+- 访问社区: https://iotdb.apache.org/
+
+祝你使用愉快！🚀
+