diff --git a/docs/zh/06-advanced/06-TDgpt/03-preprocess.md b/docs/zh/06-advanced/06-TDgpt/03-preprocess.md index b63cae0740..8cc207943a 100644 --- a/docs/zh/06-advanced/06-TDgpt/03-preprocess.md +++ b/docs/zh/06-advanced/06-TDgpt/03-preprocess.md @@ -9,14 +9,14 @@ import wndata from './pic/white-noise-data.png' ### 分析流程 时序数据分析之前需要有预处理的过程，为减轻分析算法的负担，TDgpt 在将时序数据发给具体分析算法进行分析时，已经对数据做了预处理，整体的流程如下图所示。 -预处理流程 +预处理流程 TDgpt 首先对输入数据进行白噪声检查（White Noise Data check）, 检查通过以后针对预测分析，还要进行输入（历史）数据的重采样和时间戳对齐处理（异常检测跳过数据重采样和时间戳对齐步骤）。 预处理完成以后，再进行预测或异常检测操作。预处理过程不属于预测或异常检测处理逻辑的一部分。 ### 白噪声检查 -white-noise-data +white-noise-data 白噪声时序数据可以简单地认为是随机数构成的时间数据序列（如上图所示的正态分布随机数序列），随机数构成的时间序列没有分析的价值，因此会直接返回。白噪声检查采用经典的 `Ljung-Box` 统计量检验，计算 `Ljung-Box` 统计量需遍历整个输入时间序列。如果用户能够明确输入序列一定不是白噪声序列，那么可以在参数列表中增加参数 `wncheck=0` 强制要求分析平台忽略白噪声检查，从而节省计算资源。 TDgpt 暂不提供独立的时间序列白噪声检测功能。 diff --git a/docs/zh/06-advanced/06-TDgpt/04-forecast/index.md b/docs/zh/06-advanced/06-TDgpt/04-forecast/index.md index 560e6cdcc0..e0f6f238cf 100644 --- a/docs/zh/06-advanced/06-TDgpt/04-forecast/index.md +++ b/docs/zh/06-advanced/06-TDgpt/04-forecast/index.md @@ -3,19 +3,18 @@ title: 预测算法 description: 预测算法 --- -import fc_result from '../pic/fc.png'; -import fc_result_figure from '../pic/fc-result.png'; +import fc_result from '../pic/fc-result.png'; 时序数据预测处理以持续一个时间段的时序数据作为输入，预测接下来一个连续时间区间内时间序列数据趋势。用户可以指定输出的（预测）时间序列数据点的数量，因此其输出的结果行数不确定。为此，TDengine 使用新 SQL 函数 `FORECAST` 提供时序数据预测服务。基础数据（用于预测的历史时间序列数据）是该函数的输入，预测结果是该函数的输出。用户可以通过 `FORECAST` 函数调用 Anode 提供的预测算法提供的服务。 -在后续章节中，使用时序数据表`foo`作为示例，介绍预测和异常检测算法的使用方式，`foo` 表的模式如下： +在后续章节中，使用时序数据表 `foo` 作为示例，介绍预测和异常检测算法的使用方式，`foo` 表的模式如下： -|列名称|类型|说明| -|---|---|---| -|ts| timestamp| 主时间戳列| -|i32| int32| 4字节整数，设备测量值 metric| +| 列名称 | 类型 | 说明 | +| ------ | --------- | ---------------------------- | +| ts | timestamp | 主时间戳列 | +| i32 | int32 | 4字节整数，设备测量值 metric | -```bash +```sql taos> select * from foo; ts | i32 | ======================================== @@ -30,6 +29,7 @@ taos> select * from foo; ``` ### 语法 + ```SQL FORECAST(column_expr, option_expr) @@ -42,21 +42,21 @@ algo=expr1 [,start=start_ts_val] [,expr2] "} - ``` + 1. `column_expr`：预测的时序数据列，只支持数值类型列输入。 2. `options`：预测函数的参数。字符串类型，其中使用 K=V 方式调用算法及相关参数。采用逗号分隔的 K=V 字符串表示，其中的字符串不需要使用单引号、双引号、或转义号等符号，不能使用中文及其他宽字符。预测支持 `conf`, `every`, `rows`, `start`, `rows` 几个控制参数，其含义如下： ### 参数说明 -|参数|含义|默认值| -|---|---|---| -|algo|预测分析使用的算法|holtwinters| -|wncheck|白噪声（white noise data）检查|默认值为 1，0 表示不进行检查| -|conf|预测数据的置信区间范围 ，取值范围 [0, 100]|95| -|every|预测数据的采样间隔|输入数据的采样间隔| -|start|预测结果的开始时间戳|输入数据最后一个时间戳加上一个采样间隔时间区间| -|rows|预测结果的记录数|10| +| 参数 | 含义 | 默认值 | +| ------- | ------------------------------------------ | ---------------------------------------------- | +| algo | 预测分析使用的算法 | holtwinters | +| wncheck | 白噪声（white noise data）检查 | 默认值为 1，0 表示不进行检查 | +| conf | 预测数据的置信区间范围 ，取值范围 [0, 100] | 95 | +| every | 预测数据的采样间隔 | 输入数据的采样间隔 | +| start | 预测结果的开始时间戳 | 输入数据最后一个时间戳加上一个采样间隔时间区间 | +| rows | 预测结果的记录数 | 10 | 1. 预测查询结果新增三个伪列，具体如下：`_FROWTS`：预测结果的时间戳、`_FLOW`：置信区间下界、`_FHIGH`：置信区间上界, 对于没有置信区间的预测算法，其置信区间同预测结果 2. 更改参数 `START`：返回预测结果的起始时间，改变起始时间不会影响返回的预测数值，只影响起始时间。 @@ -74,7 +74,8 @@ FROM foo; SELECT _flow, _fhigh, _frowts, FORECAST(i32, "algo=arima,alpha=95,period=10,wncheck=0") FROM foo; ``` -``` + +```sql taos> select _flow, _fhigh, _frowts, forecast(i32) from foo; _flow | _fhigh | _frowts | forecast(i32) | ======================================================================================== @@ -90,8 +91,8 @@ taos> select _flow, _fhigh, _frowts, forecast(i32) from foo; -1076.1566162 | 1214.4498291 | 2020-01-01 00:01:44.000 | 69 | ``` - ## 内置预测算法 + - [arima](./02-arima.md) - [holtwinters](./03-holtwinters.md) - CES (Complex Exponential Smoothing) @@ -111,6 +112,7 @@ taos> select _flow, _fhigh, _frowts, forecast(i32) from foo; - TimesNet ## 算法有效性评估工具 + TDgpt 提供预测分析算法有效性评估工具 `analytics_compare`，调用该工具并设置合适的参数，能够使用 TDengine 中的数据作为回测依据，评估不同预测算法或相同的预测算法在不同的参数或训练模型的下的预测有效性。预测有效性的评估使用 `MSE` 和 `MAE` 指标作为依据，后续还将增加 `MAPE`指标。 ```ini @@ -134,12 +136,13 @@ res_start_time = 1730000000000 gen_figure = true ``` -算法对比分析运行完成以后，生成 fc-results.xlsx 文件，其中包含了调用算法的预测分析误差、执行时间、调用参数等信息。如下图所示： - -预测对比结果 +算法对比分析运行完成以后，生成 fc-results.xlsx 文件，其中包含了调用算法的预测分析误差、执行时间、调用参数等信息，如下表： +| algorithm | params | MSE | elapsed_time(ms.) | +| ----------- | ------------------------------------------------------------------------- | ------- | ----------------- | +| holtwinters | `{"trend":"add", "seasonal":"add"}` | 351.622 | 125.1721 | +| arima | `{"time_step":3600000, "start_p":0, "max_p":10, "start_q":0, "max_q":10}` | 433.709 | 45577.9187 | 如果设置了 `gen_figure` 为 true，分析结果中还会有绘制的分析预测结果图（如下图所示）。 -预测对比结果 - +预测对比结果 diff --git a/docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/index.md b/docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/index.md index 4802fa2e4f..9b7a5d2834 100644 --- a/docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/index.md +++ b/docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/index.md @@ -5,7 +5,6 @@ description: 异常检测算法 import ad from '../pic/anomaly-detection.png'; import ad_result from '../pic/ad-result.png'; -import ad_result_figure from '../pic/ad-result-figure.png'; TDengine 中定义了异常（状态）窗口来提供异常检测服务。异常窗口可以视为一种特殊的**事件窗口（Event Window）**，即异常检测算法确定的连续异常时间序列数据所在的时间窗口。与普通事件窗口区别在于——时间窗口的起始时间和结束时间均是分析算法识别确定，不是用户给定的表达式进行判定。因此，在 `WHERE` 子句中使用 `ANOMALY_WINDOW` 关键词即可调用时序数据异常检测服务，同时窗口伪列（`_WSTART`, `_WEND`, `_WDURATION`）也能够像其他时间窗口一样用于描述异常窗口的起始时间(`_WSTART`)、结束时间(`_WEND`)、持续时间(`_WDURATION`)。例如： @@ -40,13 +39,15 @@ algo=expr1 4. 输入数据默认进行白噪声检查，如果输入数据是白噪声，将不会有任何（异常）窗口信息返回。 ### 参数说明 -|参数|含义|默认值| -|---|---|---| -|algo|异常检测调用的算法|iqr| -|wncheck|对输入数据列是否进行白噪声检查，取值为0或1|1| + +| 参数 | 含义 | 默认值 | +| ------- | ------------------------------------------ | ------ | +| algo | 异常检测调用的算法 | iqr | +| wncheck | 对输入数据列是否进行白噪声检查，取值为0或1 | 1 | ### 示例 + ```SQL --- 使用 iqr 算法进行异常检测，检测列 i32 列。 SELECT _wstart, _wend, SUM(i32) @@ -65,11 +66,12 @@ taos> SELECT _wstart, _wend, count(*) FROM foo ANOMAYL_WINDOW(i32); Query OK, 1 row(s) in set (0.028946s) ``` - ### 内置异常检测算法 + 分析平台内置了6个异常检查模型，分为3个类别，分别是[基于统计学的算法](./02-statistics-approach.md)、[基于数据密度的算法](./03-data-density.md)、以及[基于机器学习的算法](./04-machine-learning.md)。在不指定异常检测使用的方法的情况下，默认调用 IQR 进行异常检测。 ### 异常检测算法有效性比较工具 + TDgpt 提供自动化的工具对比不同数据集的不同算法监测有效性，针对异常检测算法提供查全率（recall）和查准率（precision）两个指标衡量不同算法的有效性。 通过在配置文件中(analysis.ini)设置以下的选项可以调用需要使用的异常检测算法，异常检测算法测试用数据的时间范围、是否生成标注结果的图片、调用的异常检测算法以及相应的参数。 调用异常检测算法比较之前，需要人工手动标注异常监测数据集的结果，即设置[anno_res]选项的数值，第几个数值是异常点，需要标注在数组中，如下测试集中，第 9 个点是异常点，我们就标注异常结果为 [9]. @@ -93,14 +95,18 @@ anno_res = [9] ksigma={"k": 2} iqr={} grubbs={} -lof={"algo":"auto", "n_neighbor": 3} +lof={"algorithm":"auto", "n_neighbor": 3} ``` 对比程序执行完成以后，会自动生成名称为`ad_result.xlsx` 的文件，第一个卡片是算法运行结果（如下图所示），分别包含了算法名称、执行调用参数、查全率、查准率、执行时间 5 个指标。 -异常检测对比结果 +| algorithm | params | precision(%) | recall(%) | elapsed_time(ms.) | +| --------- | -------------------------------------- | ------------ | --------- | ----------------- | +| ksigma | `{"k":2}` | 100 | 100 | 0.453 | +| iqr | `{}` | 100 | 100 | 2.727 | +| grubbs | `{}` | 100 | 100 | 2.811 | +| lof | `{"algorithm":"auto", "n_neighbor":3}` | 0 | 0 | 4.660 | 如果设置了 `gen_figure` 为 `true`，比较程序会自动将每个参与比较的算法分析结果采用图片方式呈现出来（如下图所示为 ksigma 的异常检测结果标注）。 -异常检测标注图 - +异常检测标注图 diff --git a/docs/zh/06-advanced/06-TDgpt/pic/ad-result-figure.png b/docs/zh/06-advanced/06-TDgpt/pic/ad-result-figure.png deleted file mode 100644 index b1bf231786..0000000000 Binary files a/docs/zh/06-advanced/06-TDgpt/pic/ad-result-figure.png and /dev/null differ diff --git a/docs/zh/06-advanced/06-TDgpt/pic/ad-result.png b/docs/zh/06-advanced/06-TDgpt/pic/ad-result.png old mode 100644 new mode 100755 index 80667c5733..40b9bb4435 Binary files a/docs/zh/06-advanced/06-TDgpt/pic/ad-result.png and b/docs/zh/06-advanced/06-TDgpt/pic/ad-result.png differ diff --git a/docs/zh/06-advanced/06-TDgpt/pic/fc.png b/docs/zh/06-advanced/06-TDgpt/pic/fc.png deleted file mode 100644 index ff11a5dc48..0000000000 Binary files a/docs/zh/06-advanced/06-TDgpt/pic/fc.png and /dev/null differ