企业官网建设流程全解析

TDengine TDgpt 模型评估工具 analytics_compare 实战：预测与异常检测模型回测指南

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

analytics_compare是 TDgpt（TDengine 的时序数据分析智能体）提供的模型有效性评估工具，它使用 TDengine 中真实存储的时序数据作为回测依据，以量化指标对比不同预测模型、异常检测模型的表现。本文以 TDgpt 企业版内置的该工具为主线，完整讲解其配置文件（analytics.ini）、预测模型回测、异常检测模型回测的端到端操作流程，并结合仓库中对应的算法源码与样例数据，说明每个配置项、每个参数背后的实现细节，帮助你在接入或自研算法时快速建立一套可复用的模型选型基准。

注意：该工具仅在TDgpt 企业版中提供，开源版本（TDgpt OSS）不可用。仓库 tools/tdgpt 中保留了完整的算法实现与样例数据，可用于理解其评估对象与评估逻辑。

工具定位与评估原理

TDgpt 面向时序数据提供预测（forecast）、异常检测（anomaly detection）、数据补全（imputation）等分析能力，其算法库既包括 statsmodels 等经典统计模型，也包括 PyTorch、Keras 等机器学习/深度学习框架，详见 TDgpt 简介。面对同一个数据集，不同算法、不同参数组合的效果差异很大，analytics_compare正是为此设计的"离线评测台"：

• 预测模型：用均方误差（MSE）衡量预测值与真实值的偏差，后续还将增加 MAPE、MAE 指标；
• 异常检测模型：用查准率（precision）与查全率（recall）衡量检出结果与人工标注（annotation）的吻合度。

它的工作方式是"读库 → 跑模型 → 出报告"：从 TDengine 中读取指定表的时间序列数据，按照analytics.ini中配置的算法清单逐一执行回测，最后输出 Excel 报告（预测为fc_result.xlsx，异常检测为ad_result.xlsx）。报告首个工作表列出每个算法的名称、调用参数、指标与耗时，若开启绘图开关，后续工作表还会为每个模型附上可视化结果图。

一、环境准备与基础配置

评估工具通过 shell 调用 TDgpt 安装路径下misc目录中的analytics_compare.py，并读取同目录（或指定位置）的analytics.ini配置文件。执行时必须使用 TDgpt 虚拟环境中的 Python，否则会因缺少依赖库而启动失败。

1.1 配置 TDengine 连接

analytics.ini的第一部分是[taosd]段，用于指定评估工具访问的 TDengine 服务：

[taosd] host = 127.0.0.1 user = root password = taosdata conf = /etc/taos/taos.cfg

1.2 配置评估输入数据

[input_data]段指定回测所用的数据来源：

[input_data] db_name = test table_name = passengers column_name = val, _c0

_c0是 TDengine 内置的时间戳主列名，评估工具需要同时拿到"时间戳 + 数值"两列才能构造出完整的时间序列。

二、评估预测分析模型

预测模型评估的完整流程是：加载样例数据 → 配置[forecast]段 → 调用工具 → 检查fc_result.xlsx。

2.1 加载样例数据

仓库在 tools/tdgpt/resource/sample-fc.sql 提供了预测评估样例数据。该文件创建数据库test，并在其中建立passengers表（ts timestamp, val int），写入从 1949-01-01 到 1960-12-01 共 144 条月度数据，这是经典的 AirPassengers 航空公司旅客量数据集——具有明显的年度周期性和增长趋势，非常适合检验周期类预测算法的能力。

在 TDgpt 安装目录的resource目录下执行：

taos -f sample-fc.sql

2.2 配置预测评估参数

在analytics.ini中追加[forecast]段：

[forecast] period = 12 rows = 10 start_time = 1949-01-01T00:00:00 end_time = 1960-12-01T00:00:00 res_start_time = 1730000000000 gen_figure = true [forecast.algos] holtwinters={"trend":"add", "seasonal":"add"} arima={"time_step": 3600000, "start_p": 0, "max_p": 5, "start_q": 0, "max_q": 5}

各配置项含义：

2.3 调用评估工具

python3 ./analytics_compare.py forecast

2.4 解读结果

执行完成后，程序目录下生成fc_result.xlsx。第一个工作表为模型运行结果，包含 4 个指标：模型名称（algorithm）、执行调用参数（params）、均方误差（MSE）、执行时间（elapsed_time）。参考输出如下：

MSE 越小表示预测越接近真实值，但同时也需要结合执行耗时综合判断：上例中 holtwinters 不仅 MSE 更低，耗时也远小于 arima。若gen_figure为true，后续工作表会为每个模型单独绘制"真实值 vs 预测值"对比图，便于直观观察趋势与周期是否拟合良好：

2.5 从源码理解预测算法参数

[forecast.algos]中列出的算法与 TDgpt 算法库一一对应。以 holtwinters 为例，其实现位于 tools/tdgpt/taosanalytics/algo/fc/holtwinters.py，底层封装了 statsmodels 的ExponentialSmoothing与SimpleExpSmoothing：

• trend与seasonal参数仅接受"add"（加法）或"mul"（乘法）两种取值（见源码第 26-35 行的合法性校验）；
• 当两者均为空时退化为简单指数平滑SimpleExpSmoothing；
• 存在季节成分时，算法会把配置中的period作为seasonal_periods传入ExponentialSmoothing（第 53-58 行），因此period的取值会直接影响季节项拟合质量。

ARIMA 算法则位于 tools/tdgpt/taosanalytics/algo/fc/arima.py，time_step指定数据点的时间间隔（毫秒），start_p/max_p与start_q/max_q控制自回归阶数与移动平均阶数的搜索范围。除这两个示例算法外，TDgpt 的预测算法库还包含ces、ets、prophet、theta以及chronos、gpt、moirai、timemoe、timesfm等模型（见 tools/tdgpt/taosanalytics/algo/fc），均可作为[forecast.algos]的候选对象。

三、评估异常检测模型

异常检测评估使用**查全率（recall）与查准率（precision）**两个指标衡量模型有效性，前提是先用人工标注（anno_res）给出数据集中真实的异常点位置。

3.1 加载样例数据

仓库在 tools/tdgpt/resource/sample-ad.sql 提供了异常检测样例数据，创建表ad_sample(ts timestamp, val int)并写入 17 个数据点。执行：

taos -f sample-ad.sql

3.2 配置异常检测评估参数

在analytics.ini中追加[ad]段：

[ad] start_time = 2021-01-01T01:01:01 end_time = 2021-01-01T01:01:11 gen_figure = true anno_res = [9] [ad.algos] ksigma={"k": 2} iqr={} grubbs={} lof={"algorithm":"auto", "neighbors": 3}

提示：仓库中 tools/tdgpt/resource/sample-ad.sql 样例数据的时间戳从1577808000000（毫秒）开始，实际使用时请将start_time/end_time设置为覆盖你数据真实时间范围的取值，保证读取到完整序列。

3.3 标注异常点

anno_res是异常检测评估的关键输入：必须人工确认测试数据中哪些位置是异常，再按零基位置填入。例如样例数据中第 10 个数据点（下标为 9）为异常点，则标注[9]；若第 1 个点（下标 0）和第 10 个点（下标 9）都是异常点，则标注[0, 9]。标注错误会直接导致 precision/recall 失真。

3.4 调用评估工具

python3 ./analytics_compare.py anomaly-detection

3.5 解读结果

执行完成后生成ad_result.xlsx，第一个工作表包含 5 个指标：模型名称、执行调用参数、查准率（precision）、查全率（recall）、执行时间。参考输出如下：

该结果清晰地展示了模型选择的必要性：同样是默认参数，ksigma/iqr/grubbs 对样例数据完全命中，而 lof 在该小样本上的 precision 与 recall 均为 0。若gen_figure为true，后续工作表会绘制每个模型的检测标注图，直观对比哪些点被识别为异常（下图为 ksigma 的检测结果标注）：

3.6 从源码理解异常检测算法参数

四个示例算法在仓库中均有对应实现，位于 tools/tdgpt/taosanalytics/algo/ad：

• ksigma（ksigma.py）：即 k-σ（3σ）准则，计算序列的均值与标准差后得到[mean - k*std, mean + k*std]区间，落在区间外的点判定为异常。源码第 17 行默认k_val=3，配置文件传入{"k": 2}即收紧阈值、检出更多点；
• iqr（iqr.py）：四分位距法，基于数据分布的分位数构造异常区间，无需额外参数；
• grubbs（grubbs.py）：Grubbs 检验，适用于单变量数据中单个离群点的检测；
• lof（lof.py）：局部离群因子（Local Outlier Factor），通过密度比较识别局部异常，neighbors控制近邻数量，algorithm指定近邻搜索算法。

TDgpt 的异常检测算法库还内置了shesd（shesd.py）以及基于 pyod 的ecod、hbos、copod、iforest、pca（见 pyod_stat.py），均可加入[ad.algos]参与横向对比。

四、使用建议与注意事项

• 务必使用虚拟环境的 Python：TDgpt 依赖 statsmodels、pmdarima、pyod 等库，直接调用系统 Python 会因缺少依赖而启动失败；进入虚拟环境后调用其python3执行analytics_compare.py；
• 评估数据需真实覆盖算法场景：[input_data]的数据范围、周期数与[forecast]中的period、start_time/end_time必须与数据实际形态匹配，否则季节项与预测起点都会失真；
• 人工标注是异常检测评估的基准：anno_res采用零基位置，务必基于对业务数据的确认填写，它是计算 precision/recall 的"标准答案"；
• 指标要结合耗时一起看：MSE 或 precision/recall 反映准确性，elapsed_time 反映计算成本，两者需综合权衡，这也正是analytics_compare把两类指标放在同一张表里的用意；
• 适用范围说明：analytics_compare.py本体仅随 TDgpt 企业版分发，本开源仓库不包含该脚本；但评估对象——预测与异常检测算法、样例数据（sample-fc.sql、sample-ad.sql）——均可在 tools/tdgpt 中查看，你可以基于同样的数据集和算法参数，在企业版环境中复现本文的全部评估结果。

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