企业官网建设流程全解析

TDgpt 机器学习异常检测实战：Autoencoder 深度学习模型的加载、部署与 SQL 调用

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine

TDgpt 是 TDengine 的智能分析平台，其 Anode（分析节点）内置了基于自编码器（Autoencoder）的深度学习异常检测模型，并通过ANOMALY_WINDOW异常窗口将模型推理能力无缝嵌入 SQL 查询。本文将围绕 TDgpt 的机器学习异常检测算法，讲解其模型原理、预训练来源、部署加载的完整流程，并结合仓库源码剖析适配器的推理实现，最终给出可直接运行的 SQL 示例与开发自有模型的扩展指南。读完本文，你将掌握如何在 TDengine 集群中启用并调用sample_ad_model模型进行工业时序数据的异常检测。

一、异常检测服务与机器学习算法在 TDgpt 中的定位

TDgpt 的异常检测服务通过 TDengine 引入的**异常窗口（Anomaly Window）**提供。异常窗口是一种特殊的事件窗口，区别在于窗口的打开与关闭由异常检测算法自行判定，而非用户输入表达式。在 SQL 中使用ANOMALY_WINDOW关键字即可调用该服务，窗口伪列_WSTART、_WEND、_WDURATION分别记录异常窗口的起始时间、结束时间与持续时间：

-- 使用 IQR 算法检测 col_val 列的异常，同时返回异常窗口起止时间与窗口内 col 列的求和 SELECT _wstart, _wend, SUM(col) FROM foo ANOMALY_WINDOW(col_val, "algo=iqr");

如下所示，Anode 返回异常窗口[10:51:30, 10:53:40]，应用层可在此基础上继续对窗口内数据进行查询、聚合或其他操作。

异常检测的完整语法如下：

ANOMALY_WINDOW(column_expr [, column_expr ...] [, option_expr]) option_expr: {" algo=expr1 [,wncheck=1|0] [,expr2] "}

• column_expr：数值类型的输入列或表达式，不支持NCHAR、VARCHAR、VARBINARY等字符类型，不支持标签与非数值结果；v3.4.1.0起支持多列输入，仅接受单列的模型取第一列并忽略其余列。
• option_expr：以逗号分隔的key=value参数对，仅支持 ASCII 字符，例如algo=ksigma,k=2。
• 异常检测结果可作为嵌套查询的内层，与其他窗口查询支持相同的函数。
• 默认会对输入数据执行白噪声检查，若输入为白噪声则不返回结果，可通过wncheck=0关闭。

异常检测还引入伪列_ANOMALYMARK用于标记异常类型，默认所有内置算法对异常点输出-1。内置异常检测算法分为统计算法（k-sigma、IQR、Grubbs、S-H-ESD）、数据密度算法与机器学习算法三类；未指定算法时默认使用 IQR。Anode 上实际可用的算法可通过SHOW ANODES FULL查看。本文重点介绍其中基于自编码器的机器学习算法sample_ad_model。

二、自编码器（Autoencoder）异常检测模型原理

自编码器是一种无监督学习的神经网络，由编码器（Encoder）与解码器（Decoder）组成：编码器将输入压缩为低维潜在表示，解码器再从潜在表示重建原始输入。模型训练目标是让重建误差（Reconstruction Error）最小化。当训练数据以正常样本为主时，模型对"正常模式"的重建误差很小；而偏离训练数据分布的异常样本经过压缩-重建后误差会显著放大。因此，重建误差（通常以 MAE 度量）超过阈值即判定为异常，这正是 autoencoder.py 的判别核心。

TDgpt 内置的该模型基于 art_daily_small_noise 数据集（来自 NAB 基准测试的合成日常小噪声数据）预训练，模型推理所需的均值（mean）、标准差（std）、阈值（threshold）与时间步长（timesteps）等参数随模型一起打包在 info 文件中。

三、模型与适配器的仓库形态

当前仓库中，该模型的完整形态包含三部分：

• 模型文件：sample-ad-autoencoder.keras，Keras 格式的已训练模型；
• 模型元信息：sample-ad-autoencoder.info，joblib 格式，保存mean、std、threshold、timesteps等推理参数；
• Python 适配器：autoencoder.py，实现AbstractAnomalyDetectionService接口，将模型接入 TDgpt 的算法服务注册与调度框架。

model目录结构如下：

. └── model └── sample-ad-autoencoder ├── sample-ad-autoencoder.keras └── sample-ad-autoencoder.info

从源码结构看（见 conf.py 的_get_default_conf_linux），Linux 下 taosanode 的默认模型目录为/usr/local/taos/taosanode/model/，动态模型目录为/usr/local/taos/taosanode/model/dynamic/；Windows 下默认基础路径为c:/TDengine/taosanode。不同安装方式下模型目录可能有所差异（例如部分文档描述为/var/lib/taos/taosanode/model/），请以实际部署环境中的model_dir配置为准。

四、三步部署：加载 Autoencoder 模型

模型与其适配器默认不会被加载。要启用该模型，按以下步骤操作：

第一步：放置模型文件。将sample-ad-autoencoder目录（含.keras与.info两个文件）下载/复制到 Anode 的模型目录下，即model/sample-ad-autoencoder/（对应默认路径/usr/local/taos/taosanode/model/sample-ad-autoencoder/）。

第二步：安装 Python 适配器。将 autoencoder.py 复制到taosanalytics/algo/ad/目录。TDgpt 的算法注册框架会扫描该目录下的服务类，适配器类_AutoEncoderDetectionService通过类属性声明算法名：

class _AutoEncoderDetectionService(AbstractAnomalyDetectionService): name = "sample_ad_model" # SHOW 语句展示的算法名 desc = "sample anomaly detection model based on auto encoder"

注意：算法文件需以_开头、类名以Service结尾，name使用小写 ASCII 字符（详见 算法开发文档）。

第三步：重启并同步。重启 taosanode 服务，然后在 TDengine 中执行UPDATE ALL ANODES，使新算法与模型在集群内同步生效。执行SHOW ANODES FULL确认sample_ad_model已出现并处于可用状态。

五、在 SQL 中使用机器学习模型

完成部署后，即可通过ANOMALY_WINDOW调用。核心是在参数中同时指定算法与模型：

-- 在异常窗口中，设置算法为 sample_ad_model、模型为 sample-ad-autoencoder SELECT _wstart, count(*) FROM foo anomaly_window(val, 'algo=sample_ad_model,model=sample-ad-autoencoder');

algo=sample_ad_model指定使用自编码器算法，model=sample-ad-autoencoder指定加载预训练模型文件。适配器在set_params阶段依据model参数拼出.keras与.info文件的完整路径（root_path/{model}.keras、root_path/{model}.info）并加载。

六、源码级解析：适配器的推理链路

从 autoencoder.py 的实现可以还原完整的推理流程：

1. 输入归一化：execute将self.list（框架注入的历史时序数据）重塑为二维数组，使用模型 info 中保存的mean与std做 z-score 标准化：normalized_list = (df - self.mean.value) / self.std.value；若输入长度小于time_interval会抛出ValueError("input data is too short")。
2. 序列切分：通过create_sequences(normalized_list.values, self.time_interval)按时间步长构造滑动窗口序列，作为模型的批量输入。
3. 前向推理：调用self.model.predict(seq)得到重建序列。
4. 误差计算：按行计算 MAE 损失mae_loss = np.mean(np.abs(pred_list - seq), axis=1)，得到每个时间步的重建误差。
5. 阈值判定：anomalies = mae > self.threshold，超过阈值即为候选异常点。
6. 窗口一致性判定：数据点i只有在连续time_interval个样本均为异常（np.all(anomalies[i - time_interval + 1 : i])）时才最终标记为异常，从而抑制孤立噪声导致的误报。
7. 结果输出：返回与输入等长的数组，异常点为-1，正常点为1——这与 TDgpt 异常检测输出规范（-1表示异常）保持一致。

模型加载由ModelFileManager统一管理：__init__中通过load_model_file注册模型加载回调do_load_model，该回调使用keras.saving.load_model加载.keras文件、joblib.load加载.info文件，并将模型对象注入 info 字典；set_params再从该字典中取出mean、std、threshold、timesteps完成参数装配。值得注意的是，_import_keras实现了懒加载：当系统未安装 TensorFlow 时，自动将 Keras 后端切换为 torch（KERAS_BACKEND=torch）并清理残留导入，从而保证主服务在缺少 TensorFlow 的环境下仍能正常启动。

七、使用限制与注意事项

• 强预训练依赖性：该模型只在预训练数据（art_daily_small_noise 这类模式）上效果良好，用于其未训练过的数据集很可能会产生较差的结果。生产环境建议基于自身业务数据重新训练模型。
• 输入长度约束：输入时序长度需不小于模型的时间步长time_interval，否则适配器直接报错。
• 白噪声过滤：若输入数据为白噪声，异常窗口不返回结果，这是异常检测服务的默认行为。
• 部署一致性：模型文件目录变更时，必须同步更新适配器中的路径逻辑（get_model_directory与sample-ad-autoencoder子目录拼接），并重新执行加载流程。

八、开发中的机器学习算法

以下基于机器学习的异常检测算法正处于开发阶段：

• Isolation Forest（孤立森林）：通过随机划分特征空间构建孤立树，异常样本因路径更短而更容易被孤立出来，适合高维数据的异常检测；
• One-Class Support Vector Machines（One-Class SVM）：将数据映射到高维特征空间并寻找最优超平面，将大多数样本圈定在正常区域内，区域外的样本判定为异常。

这些算法同样会以适配器形式接入ANOMALY_WINDOW，可用列表以SHOW ANODES FULL的实时输出为准。

九、扩展：将自有 ML/DL 模型接入 TDgpt

该示例模型同时也是自定义模型接入的标准范本。TDgpt 内置对 PyTorch 与 Keras 的支持，任何基于 Torch 或 Keras 训练的模型均可无缝集成。完整流程参见 为 TDgpt 添加机器学习模型，核心要点如下：

1. 将训练好的模型保存到 Anode 模型目录（可建子目录容纳多文件）；
2. 在taosanalytics/algo/ad/下编写继承AbstractAnomalyDetectionService的适配器，实现execute（推理并返回1/-1数组）与set_params（依据model参数加载模型文件）；
3. 重启 taosanode 并执行UPDATE ALL ANODES，随后即可在 SQL 中通过algo=<你的算法名>,model=<模型名>调用。

开发者还可参照 异常检测算法开发文档 中的示例算法与单元测试模板（anomaly_test.py）快速起步，并利用 TDgpt 的模型评估工具以精确率、召回率等指标验证算法效果。

十、总结

TDgpt 的机器学习异常检测能力由"预训练自编码器模型 + Python 适配器 + 异常窗口 SQL 语法"三层构成：模型负责重建误差判别，适配器负责归一化、序列切分、阈值判定与结果映射，ANOMALY_WINDOW则将推理能力封装为类 SQL 的声明式调用。本文给出的三步部署流程与完整 SQL 示例可直接落地到 TDengine 集群，结合源码级的推理链路解析，开发者既可以开箱即用地完成异常检测，也能够以此为模板训练、注册并调度自己的深度学习模型。

参考

• 自编码器（Autoencoder）
• NAB 基准数据集 art_daily_small_noise

【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine