Merge pull request #28733 from taosdata/doc/analysis

doc: refactor analysis docs.

docs/zh/06-advanced/06-TDgpt/02-management.md

@@ -4,10 +4,10 @@ sidebar_label: "安装部署"
 ---
 
 ### 环境准备
-ANode 要求节点上准备有 Python 3.10 及以上版本，以及相应的 Python 包自动安装组件 Pip，同时请确保能够正常连接互联网。
+ANode 可以运行在 Linux/Windows/Mac 操作系统之上，要求部署 Anode 的节点安装有 3.10 及以上版本的Python环境，以及相应的 Python 包自动安装组件 Pip。
 
 ### 安装及卸载
-使用专门的 ANode 安装包 TDengine-enterprise-anode-1.x.x.tar.gz 进行 ANode 的安装部署工作，安装过程与 TDengine 的安装流程一致。
+不同操作系统上安装及部署操作有差异，主要包括安装/卸载操作、安装路径、Anode服务的启停等几个方面。本小节以 Linux 系统为例，说明安装部署的整个流程。使用Linux环境下的安装包 TDengine-enterprise-anode-1.x.x.tar.gz 可进行 ANode 的安装部署工作，使用如下命令：
 
 ```bash
 tar -xzvf TDengine-enterprise-anode-1.0.0.tar.gz
@@ -15,13 +15,11 @@ cd TDengine-enterprise-anode-1.0.0
 sudo ./install.sh
 ```
 
-卸载 ANode，执行命令 `rmtaosanode` 即可。
+在安装完成 ANode 之后，执行命令 `rmtaosanode` 即可。
+ANode 使用 Python 虚拟环境运行，避免影响安装环境中现有的 Python 库。安装后的默认 Python 虚拟环境目录位于 `/var/lib/taos/taosanode/venv/`。为了避免反复安装虚拟环境带来的开销，卸载 ANode 执行的命令 `rmtaosanode` 并不会自动删除该虚拟环境，如果您确认不需要 Python 的虚拟环境，手动删除即可。
 
-### 其他
-为了避免 ANode 安装后影响目标节点现有的 Python 库。 ANode 使用 Python 虚拟环境运行，安装后的默认 Python 目录处于 `/var/lib/taos/taosanode/venv/`。为了避免反复安装虚拟环境带来的开销，卸载 ANode 并不会自动删除该虚拟环境，如果您确认不需要 Python 的虚拟环境，可以手动删除。
-
-## 启动及停止服务
-安装 ANode 以后，可以使用 `systemctl` 来管理 ANode 的服务。使用如下命令可以启动/停止/检查状态。
+### 启停服务
+在 Linux 系统中，安装 ANode 以后可以使用 `systemd` 来管理 ANode 服务。使用如下命令可以启动/停止/检查状态。
 
 ```bash
 systemctl start  taosanoded
@@ -29,7 +27,7 @@ systemctl stop   taosanoded
 systemctl status taosanoded
 ```
 
-## 目录及配置说明
+### 目录及配置说明
 |目录/文件|说明|
 |---------------|------|
 |/usr/local/taos/taosanode/bin|可执行文件目录|
@@ -39,64 +37,25 @@ systemctl status taosanoded
 |/var/log/taos/taosanode/|日志文件目录|
 |/etc/taos/taosanode.ini|配置文件|
 
-### 配置说明
+#### 配置说明
 
-Anode 提供的 RestFul 服务使用 uWSGI 驱动，因此 ANode 和 uWSGI 的配置信息存放在同一个配置文件中，具体如下：
+Anode 提供的服务使用 uWSGI 驱动，因此 ANode 和 uWSGI 的配置信息共同存放在相同的配置文件 `taosanode.ini`，该配置文件默认位于 `/etc/taos/`目录下，其具体内容及说明如下：
 
 ```ini
 [uwsgi]
-# charset
-env = LC_ALL = en_US.UTF-8
 
-# ip:port
+# Anode HTTP service ip:port
 http = 127.0.0.1:6050
 
-# the local unix socket file than communicate to Nginx
-#socket = 127.0.0.1:8001
-#socket-timeout = 10
-
-# base directory
+# base directory for Anode python files， do NOT modified this
 chdir = /usr/local/taos/taosanode/lib
 
-# initialize python file
+# initialize Anode python file
 wsgi-file = /usr/local/taos/taosanode/lib/taos/app.py
 
-# call module of uWSGI
-callable = app
-
-# auto remove unix Socket and pid file when stopping
-vacuum = true
-
-# socket exec model
-#chmod-socket = 664
-
-# uWSGI pid
-uid = root
-
-# uWSGI gid
-gid = root
-
-# main process
-master = true
-
-# the number of worker processes
-processes = 2
-
 # pid file
 pidfile = /usr/local/taos/taosanode/taosanode.pid
 
-# enable threads
-enable-threads = true
-
-# the number of threads for each process
-threads = 4
-
-# memory useage report
-memory-report = true
-
-# smooth restart
-reload-mercy = 10
-
 # conflict with systemctl, so do NOT uncomment this
 # daemonize = /var/log/taos/taosanode/taosanode.log
 
@@ -106,7 +65,7 @@ logto = /var/log/taos/taosanode/taosanode.log
 # wWSGI monitor port
 stats = 127.0.0.1:8387
 
-# python virtual environment directory
+# python virtual environment directory, used by Anode
 virtualenv = /usr/local/taos/taosanode/venv/
 
 [taosanode]
@@ -119,16 +78,18 @@ model-dir = /usr/local/taos/taosanode/model/
 # default log level
 log-level = DEBUG
 
-# draw the query results
-draw-result = 0
 ```
 
 **提示**
 请勿设置 `daemonize` 参数，该参数会导致 uWSGI 与 systemctl 冲突，从而无法正常启动。
+该配置文件只包含了使用 Anode提供服务的最基础的配置参数，对于 uWSGI 的其他配置参数设置及其含义和说明请参考[uWSGIS官方文档](https://uwsgi-docs-zh.readthedocs.io/zh-cn/latest/Options.html)。
+对于 Anode 运行配置主要是以下几个：
+- app-log: Anode 服务运行产生的日志，用户可以调整其到需要的位置
+- model-dir: 采用算法针对已经存在的数据集的运行完成生成的模型存储位置
+- log-level: app-log文件的日志级别
 
 
-
-## ANode 基本操作
+### ANode 基本操作
 #### 创建 ANode
 ```sql 
 CREATE ANODE {node_url}
@@ -147,7 +108,7 @@ SHOW ANODES;
 SHOW ANODES FULL;
 ```
 
-#### 强制刷新集群中的分析算法缓存
+#### 刷新集群中的分析算法缓存
 ```SQL
 UPDATE ANODE {node_id}
 UPDATE ALL ANODES

docs/zh/06-advanced/06-TDgpt/03-preprocess.md

@@ -3,8 +3,6 @@ title: "数据分析预处理"
 sidebar_label: "数据分析预处理"
 ---
 
-## 时序数据分析功能
-
 在针对时序数据进行高级分析之前，首先进行数据的白噪声检查（White Noise Data check, WND）。白噪声时序数据可以简单地认为是随机数构成的时序数据序列，这种类型的序列没有分析的价值，因此会直接返回空的结果。整体的流程如下图所示。
 
 <img src="./pic/activity.png" width="560" alt="流程图" />

docs/zh/06-advanced/06-TDgpt/04-forecast/index.md

@@ -3,8 +3,7 @@ title: 预测算法
 description: 预测算法
 ---
 
-#### 时序数据预测
-数据预测以一段训练数据作为输入，预测接下来一个连续时间区间内，时序数据的趋势。
+时序数据预测处理以持续一个时间段的时序数据作为输入，预测接下来一个连续时间区间内时间序列数据分布及运行的趋势。用户可以指定输出的（预测）时间序列数据点的数量，因此其输出的结果行数不确定。为此，我们引入了 `FORECAST` 函数提供预测服务。基础数据（用于预测的历史时间序列数据）是该函数的输入，预测结果是该函数的输出。用户可以通过 `FORECASTD` 函数调用 Anode 提供的预测算法提供的服务。
 
 ##### 语法
 ```SQL
@@ -21,8 +20,8 @@ algo=expr1
 "}
 
 ```
-1. `column_expr`：预测的时序数据列。与异常检测相同，只支持数值类型输入。
-2. `options`：异常检测函数的参数，使用规则与 anomaly_window 相同。预测还支持 `conf`, `every`, `rows`, `start`, `rows` 几个参数，其含义如下：
+1. `column_expr`：预测的时序数据列。与异常检测相同，只支持数值类型列输入。
+2. `options`：异常检测函数的参数，使用规则与 anomaly_window 相同。预测支持 `conf`, `every`, `rows`, `start`, `rows` 几个控制参数，其含义如下：
 
 **参数说明**
 
@@ -35,7 +34,7 @@ algo=expr1
 |start|预测结果的开始时间戳|输入数据最后一个时间戳加上一个采样时间段|
 |rows|预测结果的记录数|10|
 
-1. 预测查询结果新增了三个伪列，具体如下：`_FROWTS`：预测结果的时间戳、`_FLOW`：置信区间下界、`_FHIGH`：置信区间上界, 对于没有置信区间的预测算法，其置信区间同预测结果
+1. 预测查询结果新增三个伪列，具体如下：`_FROWTS`：预测结果的时间戳、`_FLOW`：置信区间下界、`_FHIGH`：置信区间上界, 对于没有置信区间的预测算法，其置信区间同预测结果
 2. 更改参数 `START`：返回预测结果的起始时间，改变起始时间不会影响返回的预测数值，只影响起始时间。
 3. `EVERY`：可以与输入数据的采样频率不同。采样频率只能低于或等于输入数据采样频率，不能**高于**输入数据的采样频率。
 4. 对于某些不需要计算置信区间的算法，即使指定了置信区间，返回的结果中其上下界退化成为一个点。
@@ -45,14 +44,14 @@ algo=expr1
 ```SQL
 --- 使用 arima 算法进行预测，预测结果是 10 条记录（默认值），数据进行白噪声检查，默认置信区间 95%. 
 SELECT  _flow, _fhigh, _frowts, FORECAST(i32, "algo=arima")
-FROM ai.ftb;
+FROM foo;
 
 --- 使用 arima 算法进行预测，输入数据的是周期数据，每 10 个采样点是一个周期。返回置信区间是 95%.
 SELECT  _flow, _fhigh, _frowts, FORECAST(i32, "algo=arima,alpha=95,period=10")
-FROM ai.ftb;
+FROM foo;
 ```
 ```
-taos> select _flow, _fhigh, _frowts, forecast(i32) from ai.ftb;
+taos> select _flow, _fhigh, _frowts, forecast(i32) from foo;
         _flow         |        _fhigh        |       _frowts           | forecast(i32) |
 ========================================================================================
            10.5286684 |           41.8038254 | 2020-01-01 00:01:35.001 |            26 |

docs/zh/06-advanced/06-TDgpt/05-anomaly-detection/index.md

@@ -3,14 +3,21 @@ title: 异常检测算法
 description: 异常检测算法
 ---
 
-#### 时序数据异常检测
-异常检测是针对输入的时序数据，使用预设或用户指定的算法确定时间序列中**可能**出现异常的时间序列点，对于时间序列中若干个连续的异常点，将自动合并成为一个连续的（闭区间）异常窗口。对于只有单个点的场景，异常窗口窗口退化成为一个起始时间和结束时间相同的点。
-异常检测生成的异常窗口受检测算法和算法参数的共同影响，对于异常窗口范围内的数据，可以应用 TDengine 提供的聚合和标量函数进行查询或变换处理。
-对于输入时间序列 (1, 20), (2, 22), (3, 91), (4, 120), (5, 18), (6, 19)。系统检测到 (3, 91), (4, 120) 为异常点，那么返回的异常窗口是闭区间 [3, 4]。
+时序数据异常检测，在TDengine 查询处理中以异常窗口的形式服务。因此，可以将异常检测获得的窗口视为一种特殊的**事件窗口**，区别在于异常窗口的触发条件和结束条件不是用户指定，而是检测算法自动识别。因此，可以应用在事件窗口上的函数均可应用在异常窗口中。由于异常检测结果是一个时间窗口，因此调用异常检测的方式也与使用事件窗口的方式相同，在 `WHERE` 子句中使用 `ANOMALY_WINDOW` 关键词即可调用时序数据异常检测服务，同时窗口伪列（`_WSTART`, `_WEND`, `_WDURATION`）也能够像其他窗口函数一样使用。例如：
+
+```SQL
+SELECT _wstart, _wend, SUM(i32) 
+FROM foo
+ANOMALY_WINDOW(i32, "algo=iqr");
+```
+
+如下图所示，Anode 将返回时序数据异常窗口 [10:51:30, 10:54:40] 
 
 <img src="../pic/anomaly-detection.png" width="560" alt="异常检测" />
 
-##### 语法
+在此基础上，用户可以针对异常窗口内的时序数据进行查询聚合、变换处理等操作。
+
+### 语法
 
 ```SQL
 ANOMALY_WINDOW(column_name, option_expr)
@@ -22,7 +29,7 @@ algo=expr1
 "}
 ```
 
-1. `column`：进行时序数据异常检测的输入数据列，当前只支持单列，且只能是数值类型，不能是字符类型（例如：`NCHAR` `VARCHAR` `VARBINARY`等类型），**不支持函数表达式**。
+1. `column_name`：进行时序数据异常检测的输入数据列，当前只支持单列，且只能是数值类型，不能是字符类型（例如：`NCHAR` `VARCHAR` `VARBINARY`等类型），**不支持函数表达式**。
 2. `options`：字符串。其中使用 K=V 调用异常检测算法及与算法相关的参数。采用逗号分隔的 K=V 字符串表示，其中的字符串不需要使用单引号、双引号、或转义号等符号，不能使用中文及其他宽字符。例如：`algo=ksigma,k=2` 表示进行异常检测的算法是 ksigma，该算法接受的输入参数是 2。
 3. 异常检测的结果可以作为外层查询的子查询输入，在 `SELECT` 子句中使用的聚合函数或标量函数与其他类型的窗口查询相同。
 4. 输入数据默认进行白噪声检查，如果输入数据是白噪声，将不会有任何（异常）窗口信息返回。
@@ -33,7 +40,7 @@ algo=expr1
 |algo|异常检测调用的算法|iqr|
 |wncheck|对输入数据列是否进行白噪声检查|取值为 0 或者 1，默认值为 1，表示进行白噪声检查|
 
-异常检测的返回结果以窗口形式呈现，因此窗口查询相关的伪列在这种场景下仍然可用。可以使用的伪列如下：
+异常检测的返回结果以窗口形式呈现，因此窗口查询相关的伪列在这种场景下仍然可用。可用的伪列如下：
 1. `_WSTART`： 异常窗口开始时间戳
 2. `_WEND`：异常窗口结束时间戳
 3. `_WDURATION`：异常窗口持续时间
@@ -55,7 +62,7 @@ ANOMALY_WINDOW(i32, "algo=ksigma,k=2");
 taos> SELECT _wstart, _wend, count(*) FROM ai.atb ANOMAYL_WINDOW(i32);
          _wstart         |          _wend          |   count(*)    |
 ====================================================================
- 2020-01-01 00:00:16.000 | 2020-01-01 00:00:16.001 |             1 |
+ 2020-01-01 00:00:16.000 | 2020-01-01 00:00:17.000 |             2 |
 Query OK, 1 row(s) in set (0.028946s)
 ```
 

docs/zh/06-advanced/06-TDgpt/06-dev/02-forecast.md

@@ -0,0 +1,4 @@
+---
+title: "开发者指南"
+sidebar_label: "开发者指南"
+---

docs/zh/06-advanced/06-TDgpt/06-dev/03-ad.md

@@ -0,0 +1,4 @@
+---
+title: "开发者指南"
+sidebar_label: "开发者指南"
+---

docs/zh/06-advanced/06-TDgpt/index.md

@@ -6,17 +6,18 @@ title: TDgpt
 ## 概述
 
 TDgpt 是 TDengine Enterprise 中针对时序数据提供高级分析功能的企业级组件，能够独立于 TDengine 主进程部署和运行，不消耗和占用 TDengine 主进程的资源，通过内置接口向 TDengine 提供运行时动态扩展的高级时序数据分析功能。TDgpt 具有服务无状态、功能易扩展、快速弹性部署、应用轻量化、高安全性等特点。
-TDgpt 运行在部署于 TDengine 集群中的 Analysis Node (ANode)中。每个 TDengine 集群中可以部署一个或若干个 ANode 节点，不同的 ANode 节点之间不相关，无同步或协同的要求。ANode 注册到 TDengine 集群以后，就可以通过内部接口提供服务。TDgpt 提供的高级时序数据分析服务可分为时序数据异常检测和时序数据预测分析两个类别。
+TDgpt 运行在部署于 TDengine 集群中的 AI Node (ANode)中。每个 TDengine 集群中可以部署一个或若干个 ANode 节点，不同的 ANode 节点之间不相关，无同步或协同的要求。ANode 注册到 TDengine 集群以后，就可以通过内部接口提供服务。TDgpt 提供的高级时序数据分析服务可分为时序数据异常检测和时序数据预测分析两个类别。
 
-如下是数据分析的技术架构示意图。
+下图是部署了 TDgpt 的 TDengine 集群示意图。
 
-<img src="./pic/data-analysis.png" width="560" alt="TDgpt架构图" />
+import TDgpt from '../pic/data-analysis.png';
+<img src={TDgpt} width="560" alt="TDgpt架构图" />
 
-通过注册指令语句，将 ANode 注册到 MNode 中就加入到 TDengine 集群，查询会**按需**向其请求数据分析服务。ANode 不直接接收用户的数据分析请求。用户可通过SQL语句间接使用 ANode 提供的分析服务。
+通过注册指令将 ANode 注册到 MNode 中以后，就加入到 TDengine 集群，并可被查询引擎动态调用执行。在查询处理过程中，查询引擎根据生成的物理执行计划，**按需**向 ANode 请求高级时序数据分析服务。用户可通过SQL语句与 ANode 节点交互，并使用其提供的全部分析服务。需要注意的是 ANode 不直接接受用户的数据分析请求。同时 ANode 提供高效的动态注册机制，其注册和卸载过程完全不影响 TDengine 集群的服务，只影响提供对应的查询服务能力。
 
-TDgpt 提供的高级数据分析功能分为时序数据异常检测和时序数据预测两类。
-时序数据异常检测的结果采用异常窗口的形式提供，即分析系统自动将连续的异常数据以时间窗口的形式返回，其使用方式与 TDengine 中其他类型的时间窗口类似。特别地，可以将异常时序数据窗口视作为一种特殊的**事件窗口（Event Window）**，因此事件窗口可应用的查询操作均可应用在异常窗口上。如下图所示，分析平台将返回时序数据异常窗口 [10:51:30, 10:54:40] （红色背景部分数据）。
-时序数据预测是基于输入的时间序列数据，采用用户给定（或默认算法）输出输入数据之后的时间序列数据的预测值数据，预测产生的时序数据点需要由用户指定。
+TDgpt 提供的高级数据分析功能分为时序数据异常检测和时序数据预测。
+- 时序数据异常检测的结果采用异常窗口的形式提供，即分析系统自动将算法检测到的连续异常数据以时间窗口的形式返回，其使用方式与 TDengine 中其他类型的时间窗口（例如状态窗口、事件窗口）类似。特别地，可以将异常数据窗口视作为一种特殊的**状态窗口（State Window）**，因此状态窗口可使用的所有查询操作均可应用在异常窗口上。
+- 时序数据预测是基于输入的时间序列数据，使用指定（或默认）预测算法给出输入时序数据后续时间序列的**预测**观测值数据。因此，不同于异常检测是以窗口的形式存在，时序数据预测在 TDengine 中是一个（不确定输出）函数。