TDengine TDgpt 机器学习异常检测：基于自编码器（Autoencoder）的 sample_ad_model 使用指南

• 数据库
• 时序数据库
• 物联网
• 大数据
• 实时分析
• 云原生

TDgpt（TDengine 高级分析引擎）内置了一套基于**自编码器（Autoencoder）**深度神经网络的时序异常检测模型sample_ad_model，该模型已在 NAB 公开数据集上完成预训练，可通过 SQL 中的ANOMALY_WINDOW窗口函数直接调用。本文以官方文档为基础，结合仓库内模型文件与 Python 源码，完整讲解该模型的原理、文件结构、部署加载流程与 SQL 使用方式，帮助你掌握在 TDengine 集群中接入 Keras 预训练异常检测模型的完整实操路径。

一、机器学习异常检测在 TDgpt 中的定位

TDgpt 将异常检测能力划分为三类算法族：统计算法（如grubbs、ksigma、shesd、iqr）、数据密度算法（如lof）以及机器学习算法（如自编码器）。机器学习算法通过ANOMALY_WINDOW关键字在 SQL 的WHERE子句中调用，例如：

SELECT _wstart, _wend, SUM(col) FROM foo ANOMALY_WINDOW(col_val, "algo=iqr");

ANOMALY_WINDOW是一种特殊的事件窗口：窗口的打开与关闭不是由用户表达式决定，而是由异常检测算法在运行期自行判定，窗口伪列_WSTART、_WEND、_WDURATION分别记录窗口的开始、结束与持续时间。完整语法与参数说明可参考 Anomaly Detection 总览，其核心语法如下：

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

其中algo指定检测算法，wncheck控制是否对输入数据做白噪声预检查（默认开启，输入为白噪声时直接不返回结果）。本文的主角——自编码器模型，在algo参数中注册为sample_ad_model。

二、自编码器模型的原理与训练方式

自编码器是一类"以输出还原输入"的神经网络：网络先通过编码器（Encoder）将输入压缩为低维隐向量，再通过解码器（Decoder）还原出与输入同维度的重建结果。训练完成后，模型对"正常"样本的重建误差很小，而对"异常"样本（训练分布之外的形态）重建误差显著增大，据此即可用重建误差（Reconstruction Error）判定异常。

仓库中提供了完整的训练脚本 train_ad_model.py，其训练数据来自 NAB（Numenta Anomaly Benchmark）的art_daily_small_noise数据集（无异常的人工日常小噪声序列）。核心训练逻辑如下：

df_small_noise = get_training_data() time_steps = 288 # 滑动窗口长度 = 一天的 5 分钟采样点数 training_mean = df_small_noise.mean() training_std = df_small_noise.std() # 以 z-score 方式归一化训练数据 df_training_value = (df_small_noise - training_mean) / training_std x_train = create_sequences(df_training_value.values, time_steps)

模型采用一维卷积（Conv1D）搭建的卷积自编码器：

model = keras.Sequential([ layers.Input(shape=(x_train.shape[1], x_train.shape[2])), layers.Conv1D(filters=32, kernel_size=7, padding="same", strides=2, activation="relu"), layers.Dropout(rate=0.2), layers.Conv1D(filters=16, kernel_size=7, padding="same", strides=2, activation="relu"), layers.Conv1DTranspose(filters=16, kernel_size=7, padding="same", strides=2, activation="relu"), layers.Dropout(rate=0.2), layers.Conv1DTranspose(filters=32, kernel_size=7, padding="same", strides=2, activation="relu"), layers.Conv1DTranspose(filters=1, kernel_size=7, padding="same"), ]) model.compile(optimizer=keras.optimizers.Adam(learning_rate=0.001), loss="mse")

训练时以x_train同时作为输入和标签，使用 MSE 损失与 Adam 优化器，最多训练 50 个 epoch，并通过EarlyStopping（监控val_loss，patience=5）防止过拟合。训练完成后，脚本统计训练集上的平均绝对误差（MAE）：

x_train_pred = model.predict(x_train) train_mae_loss = np.mean(np.abs(x_train_pred - x_train), axis=1) threshold = np.max(train_mae_loss) # 以训练集最大 MAE 作为异常阈值

即：阈值取训练集重建 MAE 的最大值，推理时 MAE 超过该阈值的样本即判为异常。训练好的模型与统计信息分别以.keras与.info两种格式保存。

三、模型文件结构：.keras 与 .info

预训练模型的文件存放在仓库的 tools/tdgpt/model/sample-ad-autoencoder/ 目录下，官方目录结构如下：

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

两个文件的分工：

• sample-ad-autoencoder.keras：Keras 格式的模型权重与网络结构文件，由keras.saving.load_model加载（参见 autoencoder.py）；
• sample-ad-autoencoder.info：joblib 格式的模型附属参数，加载后供推理逻辑使用。通过读取该文件可得到模型的真实超参数：

推理时，模型会按(value - mean) / std对输入做与训练一致的归一化，再以timesteps=288为窗口切分序列（create_sequences的实现见 util.py），计算每个窗口的重建 MAE 并与阈值比较。

四、部署加载：三步接入预训练模型

文档明确说明，示例模型及其适配器默认不会被加载。要启用该模型，需要完成以下三个步骤：

1. 下载模型文件：将sample-ad-autoencoder目录下的两个文件放置到 anode 的模型目录/var/lib/taos/taosanode/model/sample-ad-autoencoder/。该目录与 TDgpt 配置中的模型根目录相对应（管理文档中model_dir默认为/usr/local/taos/taosanode/model/，并链接到/var/lib/taos/taosanode/model，详见 TDgpt 管理）。
2. 复制适配器：将仓库中的适配器 misc/autoencoder.py 复制到 anode 的taosanalytics/algo/ad/目录下。该目录是 TDgpt 扫描异常检测算法类的注册目录，内置算法grubbs、iqr、ksigma、shesd、lof等均位于此。
3. 重启并刷新：重启 taosanode 服务，然后在taos客户端执行UPDATE ALL ANODES刷新算法缓存。之后运行SHOW ANODES FULL，若列表中出现sample_ad_model即表示模型加载成功：

taos> show anodes full; id | type | algo | ============================================================================ 1 | anomaly-detection | grubbs | 1 | anomaly-detection | lof | 1 | anomaly-detection | shesd | 1 | anomaly-detection | ksigma | 1 | anomaly-detection | iqr | 1 | anomaly-detection | sample_ad_model | 1 | forecast | arima | ...

SHOW ANODES用于查看 anode 的 FQDN 与运行状态，SHOW ANODES FULL用于列出 anode 上可用的分析与预测服务；执行UPDATE ANODE {anode_id}可只刷新单个 anode 的算法缓存。这些管理命令的完整说明见 TDgpt 管理文档。

五、适配器源码解析：算法如何被调度执行

复制到taosanalytics/algo/ad/的适配器定义了一个继承自AbstractAnomalyDetectionService的服务类（基类定义见 base.py）：

class _AutoEncoderDetectionService(AbstractAnomalyDetectionService): name = "sample_ad_model" # SQL 中 algo 参数使用的名称 desc = "sample anomaly detection model based on auto encoder"

name属性即 SQL 中algo=sample_ad_model的注册名。类构造时通过单例ModelFileManager按需加载磁盘上的模型文件（加载与缓存机制见 model_file_mgt.py）：

ModelFileManager.get_instance().load_model_file( _AutoEncoderDetectionService.name, os.path.join( Configure.get_instance().get_model_directory(), "sample-ad-autoencoder/sample-ad-autoencoder", ), _AutoEncoderDetectionService.do_load_model, _AutoEncoderDetectionService.name, )

do_load_model依次加载.keras（Keras 模型）与.info（joblib 附属信息）。值得注意的实现细节：当环境中缺少 TensorFlow 时，适配器会通过KERAS_BACKEND=torch回退到以 PyTorch 为后端的独立 Keras，实现"惰性导入"以免拖慢服务启动。

模型推理发生在execute()方法中，完整流程为：

1. 输入为空时直接返回[]；模型未加载时抛出failed_load_model_except；
2. 将一维输入 reshape 为(len(list), 1)并用mean/std做 z-score 归一化；
3. 输入长度不足time_interval（288）时抛出input data is too short；
4. 按 288 的窗口切分序列，调用model.predict得到重建结果，计算逐窗口 MAE；
5. 将 MAE 与阈值比较得到逐窗口异常标记；
6. 按"连续窗口全为异常"的规则聚合出异常点索引：数据点i当且仅当窗口[(i - timesteps + 1), i]内全部为异常时才被标记为异常点；
7. 输出-1（异常）或1（正常）组成的标签列表，供上层窗口聚合使用。

六、SQL 实战：在异常窗口中调用预训练模型

模型与适配器就绪后，即可在 SQL 中通过algo与model两个参数组合调用：

-- 在异常窗口中，将算法设为 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告诉 TDgpt 使用注册名为sample_ad_model的自编码器算法；
• model=sample-ad-autoencoder指定加载的预训练模型文件名（对应模型目录下的sample-ad-autoencoder.keras/.info）；
• 查询结果按异常窗口分组，_wstart为异常窗口起始时间，count(*)为窗口内数据点数；配合_wend、_wduration、_anomalymark等伪列可进一步聚合分析（伪列说明见 Anomaly Detection 总览）。

在现有algo/ad/目录中，其他内置算法（如ksigma、iqr等）的适配器同样位于 tools/tdgpt/taosanalytics/algo/ad/ 目录，可作为编写自定义适配器的参照。

七、使用限制与注意事项

文档对自编码器模型的使用边界给出了明确提醒，使用时务必注意：

1. 预训练前提：该模型只在预训练数据分布上表现良好。它针对 NABart_daily_small_noise这类"小噪声、无异常"的日常数据训练，若直接用于分布差异很大的数据集，检测效果很可能不理想；跨场景使用前应使用你自己的数据重新训练。
2. 窗口长度约束：推理输入长度需达到timesteps=288（约一天 5 分钟粒度的数据量），不足时适配器会直接抛出input data is too short，因此需保证输入窗口内的数据量充足。
3. 默认不启用：模型与适配器默认未加载，必须完成"放置模型文件 + 复制适配器 + 重启 +UPDATE ALL ANODES"的完整流程才能被 SQL 调用。
4. 单列输入：自编码器适配器按单列数据处理，多列输入场景下取第一列参与计算（与总览文档中"仅接受单列的模型使用第一列并忽略其余列"的说明一致）。

八、规划中的机器学习算法

除自编码器外，TDgpt 正在开发两类经典机器学习异常检测算法，后续版本将陆续引入：

• Isolation Forest（孤立森林）：通过随机划分特征空间、以"隔离所需路径长度"衡量样本离群程度，适合高维与大规模数据的快速异常检测；
• One-Class SVM（单类支持向量机）：在核空间中学习正常数据的决策边界，将边界外的样本判定为异常，适合样本量适中的场景。

九、进一步学习

• 完整接入流程与适配器代码示例：Add Machine Learning Models to TDgpt
• 训练脚本：train_ad_model.py
• 推理适配器实现：misc/autoencoder.py
• 预训练模型文件：tools/tdgpt/model/sample-ad-autoencoder/
• 算法抽象基类与调度框架：base.py、model_file_mgt.py
• 异常检测窗口语法与伪列：Anomaly Detection 总览
• TDgpt 安装、anode 管理与UPDATE ALL ANODES命令：TDgpt 管理文档

• 数据库
• 时序数据库
• 物联网
• 大数据
• 实时分析
• 云原生