IoTDB AINode 实战：SQL 原生时序 AI 建模与预测

下方为模型注册的 SQL 语法定义。

create model <model_name> using uri <uri>

SQL 中参数的具体含义如下：

• model_name：模型的全局唯一标识，不可重复。模型名称具备以下约束：
  • 允许出现标识符 [0-9 a-z A-Z _] （字母，数字，下划线）
  • 长度限制为 2-64 字符
  • 大小写敏感
• uri：模型注册文件的资源路径，路径下应包含模型结构及权重文件 model.pt 文件和模型配置文件 config.yaml
  • 模型结构及权重文件：模型训练完成后得到的权重文件，目前支持 pytorch 训练得到的 .pt 文件
  • 模型配置文件：模型注册时需要提供的与模型结构有关的参数，其中必须包含模型的输入输出维度用于模型推理：

除了模型推理外，还可以指定模型输入输出的数据类型：

除此之外，可以额外指定备注信息用于在模型管理时进行展示：

除了本地模型文件的注册，还可以通过 URI 来指定远程资源路径来进行注册，使用开源的模型仓库（例如 HuggingFace）。

示例

在当前的 example 文件夹下，包含 model.pt 和 config.yaml 文件，model.pt 为训练得到，config.yaml 的内容如下：

configs:
  # 必选项
  input_shape: [96,2] # 表示模型接收的数据为 96 行 x2 列
  output_shape: [48,2] # 表示模型输出的数据为 48 行 x2 列
  # 可选项 默认为全部 float32，列数为 shape 对应的列数
  input_type: ["int64","int64"] # 输入对应的数据类型，需要与输入列数匹配
  output_type: ["text","int64"] # 输出对应的数据类型，需要与输出列数匹配
  attributes:
    # 可选项 为用户自定义的备注信息
    'model_type':'dlinear'
    'kernel_size':'25'

指定该文件夹作为加载路径就可以注册该模型

IoTDB> create model dlinear_example using uri "file://./example"

也可以从 huggingFace 上下载对应的模型文件进行注册

IoTDB> create model dlinear_example using uri "https://huggingface.co/google/timesfm-2.0-500m-pytorch"

SQL 执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见模型展示章节），注册成功的耗时主要受到模型文件大小的影响。

模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。

4.2 查看模型

注册成功的模型可以通过 show models 指令查询模型的具体信息。其 SQL 定义如下：

show models
show models <model_name>

除了直接展示所有模型的信息外，可以指定 model id 来查看某一具体模型的信息。模型展示的结果中包含如下信息：

其中，State 用于展示当前模型注册的状态，包含以下三个阶段

• INACTIVE：模型处于不可用状态
• LOADING：模型加载中状态
• ACTIVE：模型处于可用状态
• DROPPING: 模型删除中状态

示例

IoTDB> show models
+---------------------+--------------------+--------+--------+
| ModelId             | ModelType          | Category| State|
+---------------------+--------------------+--------+--------+
| arima               | Arima              | BUILT-IN| ACTIVE |
| holtwinters         | HoltWinters        | BUILT-IN| ACTIVE |
| exponential_smoothing| ExponentialSmoothing| BUILT-IN| ACTIVE |
| naive_forecaster    | NaiveForecaster    | BUILT-IN| ACTIVE |
| stl_forecaster      | StlForecaster      | BUILT-IN| ACTIVE |
| gaussian_hmm        | GaussianHmm        | BUILT-IN| ACTIVE |
| gmm_hmm             | GmmHmm             | BUILT-IN| ACTIVE |
| stray               | Stray              | BUILT-IN| ACTIVE |
| timer_xl            | Timer-XL           | BUILT-IN| ACTIVE |
| sundial             | Timer-Sundial      | BUILT-IN| ACTIVE |
+---------------------+--------------------+--------+--------+

4.3 删除模型

对于注册成功的模型，用户可以通过 SQL 进行删除，该操作会删除所有 AINode 下的相关模型文件，其 SQL 如下：

drop model <model_id>

需要指定已经成功注册的模型 model_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。

4.4 使用内置模型推理

SQL 语法如下：

call inference(<model_id>,inputSql,(<parameterName>=<parameterValue>)*) window_function: head(window_size) tail(window_size) count(window_size,sliding_step)

内置模型推理无需注册流程，通过 call 关键字，调用 inference 函数就可以使用模型的推理功能，其对应的参数介绍如下：

• model_id: 模型名称
• parameterName：参数名
• parameterValue：参数值

请注意，使用内置时序大模型进行推理的前提条件是本地存有对应模型权重，目录为 /IOTDB_AINODE_HOME/data/ainode/models/weights/model_id/。若本地没有模型权重，则会自动从 HuggingFace 拉取，请保证本地能直接访问 HuggingFace。

内置模型及参数说明

目前已内置如下机器学习模型，具体参数说明请参考以下链接。

在完成模型的注册后，通过 call 关键字，调用 inference 函数就可以使用模型的推理功能，其对应的参数介绍如下：

• model_name: 对应一个已经注册的模型
• sql：sql 查询语句，查询的结果作为模型的输入进行模型推理。查询的结果中行列的维度需要与具体模型 config 中指定的大小相匹配。(这里的 sql 不建议使用 SELECT * 子句，因为在 IoTDB 中，* 并不会对列进行排序，因此列的顺序是未定义的，可以使用 SELECT s0,s1 的方式确保列的顺序符合模型输入的预期)
• window_function: 推理过程中可以使用的窗口函数，目前提供三种类型的窗口函数用于辅助模型推理：

count(window_size, sliding_step)：基于点数的滑动窗口，每个窗口的数据会分别通过模型进行推理，如下图示例所示，window_size 为 2 的窗口函数将输入数据集分为三个窗口，每个窗口分别进行推理运算生成结果。该窗口可用于连续推理

tail(window_size)：获取数据中最后的 window_size 个点用于模型推，该窗口可用于数据裁剪

head(window_size): 获取数据中最前的 window_size 个点用于模型推理，该窗口可用于数据裁剪

说明 1: window 可以用来解决 sql 查询结果和模型的输入行数要求不一致时的问题，对行进行裁剪。需要注意的是，当列数不匹配或是行数直接少于模型需求时，推理无法进行，会返回错误信息。

说明 2: 在深度学习应用中，经常将时间戳衍生特征（数据中的时间列）作为生成式任务的协变量，一同输入到模型中以提升模型的效果，但是在模型的输出结果中一般不包含时间列。为了保证实现的通用性，模型推理结果只对应模型的真实输出，如果模型不输出时间列，则结果中不会包含。

示例

下面是使用深度学习模型推理的一个操作示例，针对上面提到的输入为 [96,2]，输出为 [48,2] 的 dlinear 预测模型，我们通过 SQL 使用其进行推理。

IoTDB> select s1,s2 from root.** +-----------------------------+-------------------+-------------------+ 
| Time                    | root.eg.etth.s0     | root.eg.etth.s1     |
+-----------------------------+-------------------+-------------------+
|1990-01-01T00:00:00.000+08:00|0.7855             |1.611               |
... (omitted for brevity in summary context, full content preserved)
+-----------------------------+-------------------+-------------------+
 Total line number =96

IoTDB> call inference(dlinear_example,"select s0,s1 from root.**", generateTime=True) 
+-----------------------------+--------------------------------------------+-----------------------------+
| Time                        | _result_0                                    | _result_1                   |
+-----------------------------+--------------------------------------------+-----------------------------+
|1990-04-06T00:00:00.000+08:00|0.726302981376648                           |1.6549958229064941           |
...
+-----------------------------+--------------------------------------------+-----------------------------+
 Total line number =48

使用 tail/head 窗口函数的示例

当数据量不定且想要取 96 行最新数据用于推理时，可以使用对应的窗口函数 tail。head 函数的用法与其类似，不同点在于其取的是最早的 96 个点。

使用 count 窗口函数的示例

该窗口主要用于计算式任务，当任务对应的模型一次只能处理固定行数据而最终想要的确实多组预测结果时，使用该窗口函数可以使用点数滑动窗口进行连续推理。假设我们现在有一个异常检测模型 anomaly_example(input: [24,2], output[1,1])，对每 24 行数据会生成一个 0/1 的标签，其使用示例如下：

5. 权限管理

使用 AINode 相关的功能时，可以使用 IoTDB 本身的鉴权去做一个权限管理，用户只有在具备 USE_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。

6. 实际案例

6.1 电力负载预测

在部分工业场景下，会存在预测电力负载的需求，预测结果可用于优化电力供应、节约能源和资源、支持规划和扩展以及增强电力系统的可靠性。

我们所使用的 ETTh1 的测试集的数据为 ETTh1。

包含间隔 1h 采集一次的电力数据，每条数据由负载和油温构成，分别为：High UseFul Load, High UseLess Load, Middle UseLess Load, Low UseFul Load, Low UseLess Load, Oil Temperature。

在该数据集上，IoTDB-ML 的模型推理功能可以通过以往高中低三种负载的数值和对应时间戳油温的关系，预测未来一段时间内的油温，赋能电网变压器的自动调控和监视。

步骤一：数据导入

用户可以使用 tools 文件夹中的 import-csv.sh 向 IoTDB 中导入 ETT 数据集

bash ./import-csv.sh -h127.0.0.1 -p6667-u root -pw root -f../../ETTh1.csv 

步骤二：模型导入

我们可以在 iotdb-cli 中输入以下 SQL 从 huggingface 上拉取一个已经训练好的模型进行注册，用于后续的推理。

create model dlinear using uri 'https://huggingface.co/hvlgo/dlinear/tree/main'

该模型基于较为轻量化的深度模型 DLinear 训练而得，能够以相对快的推理速度尽可能多地捕捉到序列内部的变化趋势和变量间的数据变化关系，相较于其他更深的模型更适用于快速实时预测。

步骤三：模型推理

IoTDB> select s0,s1,s2,s3,s4,s5,s6 from root.eg.etth LIMIT 96 ...
IoTDB> call inference(dlinear_example, "select s0,s1,s2,s3,s4,s5,s6 from root.eg.etth", generateTime=True, window=head(96)) ...

我们将对油温的预测的结果和真实结果进行对比，可以得到以下的图像。

图中 10/24 00:00 之前的数据为输入模型的过去数据，10/24 00:00 后的蓝色线条为模型给出的油温预测结果，而红色为数据集中实际的油温数据（用于进行对比）。

可以看到，我们使用了过去 96 个小时（4 天）的六个负载信息和对应时间油温的关系，基于之前学习到的序列间相互关系对未来 48 个小时（2 天）的油温这一数据的可能变化进行了建模，可以看到可视化后预测曲线与实际结果在趋势上保持了较高程度的一致性。

6.2 功率预测

变电站需要对电流、电压、功率等数据进行电力监控，用于检测潜在的电网问题、识别电力系统中的故障、有效管理电网负载以及分析电力系统的性能和趋势等。

我们利用某变电站中的电流、电压和功率等数据构成了真实场景下的数据集。该数据集包括变电站近四个月时间跨度，每 5 - 6s 采集一次的 A 相电压、B 相电压、C 相电压等数据。

测试集数据内容为 data。

在该数据集上，IoTDB-ML 的模型推理功能可以通过以往 A 相电压，B 相电压和 C 相电压的数值和对应时间戳，预测未来一段时间内的 C 相电压，赋能变电站的监视管理。

步骤一：数据导入

用户可以使用 tools 文件夹中的 import-csv.sh 导入数据集

bash ./import-csv.sh -h127.0.0.1 -p6667-u root -pw root -f../../data.csv 

步骤二：模型导入

我们可以在 iotdb-cli 中选择内置模型或已经注册好的模型用于后续的推理。

我们采用内置模型 STLForecaster 进行预测，STLForecaster 是一个基于 statsmodels 库中 STL 实现的时间序列预测方法。

步骤三：模型推理

IoTDB> select * from root.eg.voltage limit 96 ...
IoTDB> call inference(_STLForecaster, "select s0,s1,s2 from root.eg.voltage", generateTime=True, window=head(96),predict_length=48) ...

我们将对 C 相电压的预测的结果和真实结果进行对比，可以得到以下的图像。

图中 02/14 20:48 之前的数据为输入模型的过去数据，02/14 20:48 后的蓝色线条为模型给出的 C 相电压预测结果，而红色为数据集中实际的 C 相电压数据（用于进行对比）。

可以看到，我们使用了过去 10 分钟的电压的数据，基于之前学习到的序列间相互关系对未来 5 分钟的 C 相电压这一数据的可能变化进行了建模，可以看到可视化后预测曲线与实际结果在趋势上保持了一定的同步性。

6.3 异常检测

在民航交通运输业，存在着对乘机旅客数量进行异常检测的需求。异常检测的结果可用于指导调整航班的调度，以使得企业获得更大效益。

Airline Passengers 一个时间序列数据集，该数据集记录了 1949 年至 1960 年期间国际航空乘客数量，间隔一个月进行一次采样。该数据集共含一条时间序列。数据集为 airline。

在该数据集上，IoTDB-ML 的模型推理功能可以通过捕捉序列的变化规律以对序列时间点进行异常检测，赋能交通运输业。

步骤一：数据导入

用户可以使用 tools 文件夹中的 import-csv.sh 导入数据集

bash ./import-csv.sh -h127.0.0.1 -p6667-u root -pw root -f../../data.csv 

步骤二：模型推理

IoTDB 内置有部分可以直接使用的机器学习算法，使用其中的异常检测算法进行预测的样例如下：

IoTDB> select * from root.eg.airline ...
IoTDB> call inference(_Stray, "select s0 from root.eg.airline", generateTime=True, k=2) ...

我们将检测为异常的结果进行绘制，可以得到以下图像。其中蓝色曲线为原时间序列，用红色点特殊标注的时间点为算法检测为异常的时间点。

可以看到，Stray 模型对输入序列变化进行了建模，成功检测出出现异常的时间点。

附：IoTDB 的各大版本

Apache IoTDB 是一款工业物联网时序数据库管理系统，采用端边云协同的轻量化架构，支持一体化的物联网时序数据收集、存储、管理与分析，具有多协议兼容、超高压缩比、高通量读写、工业级稳定、极简运维等特点。

https://archive.apache.org/dist/iotdb/