doc: update gpt doc. (#30428)

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

@@ -0,0 +1,108 @@
+---
+title: "安装部署"
+sidebar_label: "安装部署"
+---
+
+import PkgListV3 from "/components/PkgListV3";
+
+
+# 通过 Docker 快速体验
+
+本节首先介绍如何通过 Docker 快速体验 TDgpt。
+
+## 启动 TDgpt
+
+如果已经安装了 Docker，首先拉取最新的 TDengine 容器镜像：
+
+```shell
+docker pull tdengine/tdengine:latest
+```
+
+或者指定版本的容器镜像：
+
+```shell
+docker pull tdengine/tdengine:3.3.3.0
+```
+
+然后只需执行下面的命令：
+
+```shell
+docker run -d -p 6030:6030 -p 6041:6041 -p 6043:6043 -p 6044-6049:6044-6049 -p 6044-6045:6044-6045/udp -p 6060:6060 tdengine/tdengine
+```
+
+注意：TDgpt 服务端使用  6090 TCP 端口。TDgpt 是一个无状态时序数据分析智能体，并不会在本地持久化保存数据，仅根据配置可能在本地生成运行日志。
+
+确定该容器已经启动并且在正常运行。
+
+```shell
+docker ps
+```
+
+进入该容器并执行 `bash`
+
+```shell
+docker exec -it <container name> bash
+```
+
+然后就可以执行相关的 Linux 命令操作和访问 TDengine。
+
+
+# 通过云服务快速体验
+
+TDgpt 可以在 TDengine Cloud 上进行快速体验。如果您已经有云服务账号，请在数据库集市里面找到“时序数据预测分析数据集”数据库，点击启用就可以进入这个数据库，然后按照 TDgpt 的 SQL 操作手册来执行语句，比如 `select forecast(val, 'algo=tdtsfm_1') from forecast.electricity_demand;`。
+
+# 通过安装包快速体验
+
+### 环境准备
+使用 TDgpt 的高级时序数据分析功能需要在 TDengine 集群中安装部署 AI node（Anode）。Anode 运行在 Linux 平台上，并需要 3.10 或以上版本的 Python 环境支持。
+> 部署 Anode 需要 TDengine 3.3.6.0 及以后版本，请首先确认搭配 Anode 使用的 TDengine 能够支持 Anode。
+
+可以使用以下的命令在 Ubuntu Linux 上安装 Python 3.10 环境
+
+### 安装 Python
+
+```shell
+sudo apt-get install software-properties-common
+sudo add-apt-repository ppa:deadsnakes/ppa
+sudo apt update
+sudo apt install python3.10
+sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 2
+sudo update-alternatives --config python3
+sudo apt install python3.10-venv
+sudo apt install python3.10-dev
+```
+
+### 安装 PiPy
+
+```shell
+curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10
+```
+
+将 `~/.local/bin` 路径添加到环境变量中 `~/.bashrc or ~/.bash_profile`
+```shell
+export PATH=$PATH:~/.local/bin
+```
+至此 Python 环境准备完成，可以进行 taosanode 的安装和部署。
+
+### 获取安装包
+1. 从列表中下载获得 tar.gz 安装包：
+
+   <PkgListV3 type={9}/>
+
+2. 进入到安装包所在目录，使用 tar 解压安装包；
+> 请将 `<version>` 替换为下载的安装包版本
+
+```bash
+tar -zxvf TDengine-anode-<version>-Linux-x64.tar.gz
+```
+
+3. 解压文件后，进入相应子目录，执行其中的 `install.sh` 安装脚本：
+   请将 `<version>` 替换为下载的安装包版本
+
+```bash
+cd TDengine-anode-<version>
+sudo ./install.sh
+```
+
+对于已经安装的 Anode，执行命令 `rmtaosanode` 即可完成卸载。
+为了避免影响系统已有的 Python 环境，Anode 使用虚拟环境运行。安装 Anode 会在目录 `/var/lib/taos/taosanode/venv/` 中创建默认的 Python 虚拟环境，Anode 运行所需要的库均安装在该目录下。为了避免反复安装虚拟环境带来的开销，卸载命令 `rmtaosanode` 并不会自动删除该虚拟环境，如果您确认不再需要 Python 的虚拟环境，手动删除该目录即可。

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

@@ -1,62 +1,10 @@
 ---
-title: "安装部署"
-sidebar_label: "安装部署"
+title: "运维管理指南"
+sidebar_label: "运维管理指南"
 ---
 
 import PkgListV3 from "/components/PkgListV3";
 
-### 环境准备
-使用 TDgpt 的高级时序数据分析功能需要在 TDengine 集群中安装部署 AI node（Anode）。Anode 运行在 Linux 平台上，并需要 3.10 或以上版本的 Python 环境支持。
-> 部署 Anode 需要 TDengine 3.3.6.0 及以后版本，请首先确认搭配 Anode 使用的 TDengine 能够支持 Anode。
-
-可以使用以下的命令在 Ubuntu Linux 上安装 Python 3.10 环境
-
-#### 安装 Python
-
-```shell
-sudo apt-get install software-properties-common
-sudo add-apt-repository ppa:deadsnakes/ppa
-sudo apt update
-sudo apt install python3.10
-sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 2
-sudo update-alternatives --config python3
-sudo apt install python3.10-venv
-sudo apt install python3.10-dev
-```
-
-#### 安装 Pip
-```shell
-curl -sS https://bootstrap.pypa.io/get-pip.py | python3.10
-```
-
-####
-将 `~/.local/bin` 路径添加到环境变量中 `~/.bashrc or ~/.bash_profile`
-```shell
-export PATH=$PATH:~/.local/bin
-```
-至此 Python 环境准备完成，可以进行 taosanode 的安装和部署。
-
-### 安装及卸载
-1. 从列表中下载获得 tar.gz 安装包：
-   <PkgListV3 type={9}/>
-
-2. 进入到安装包所在目录，使用 tar 解压安装包；
-> 请将 `<version>` 替换为下载的安装包版本
-```bash
-tar -zxvf TDengine-anode-<version>-Linux-x64.tar.gz
-```
-
-3. 解压文件后，进入相应子目录，执行其中的 `install.sh` 安装脚本：
-请将 `<version>` 替换为下载的安装包版本
-
-```bash
-cd TDengine-anode-<version>
-sudo ./install.sh
-```
-
-对于已经安装的 Anode，执行命令 `rmtaosanode` 即可完成卸载。
-为了避免影响系统已有的 Python 环境，Anode 使用虚拟环境运行。安装 Anode 会在目录 `/var/lib/taos/taosanode/venv/` 中创建默认的 Python 虚拟环境，Anode 运行所需要的库均安装在该目录下。为了避免反复安装虚拟环境带来的开销，卸载命令 `rmtaosanode` 并不会自动删除该虚拟环境，如果您确认不再需要 Python 的虚拟环境，手动删除该目录即可。
-
 ### 启停服务
 在 Linux 系统中，安装 Anode 以后会自动创建 `taosanoded` 服务。可以使用 `systemd` 来管理 Anode 服务，使用如下命令启动/停止/检查 Anode。
 

docs/zh/06-advanced/06-TDgpt/07-dev/03-ml/index.md

@@ -0,0 +1,31 @@
+---
+title: "添加机器学习模型"
+sidebar_label: "添加机器学习模型"
+---
+
+## 添加具有模型的分析算法
+
+基于统计学的分析算法可以直接针对输入时间序列数据进行分析，但是某些深度学习算法对于输入数据需要较长的时间训练，并且生成相应的模型。这种情况下，同一个分析算法对应不同的输入数据集有不同的分析模型。
+将具有模型的分析算法添加到 Anode 中，首先需要在 `model` 目录中建立该算法对应的目录（目录名称可自拟），将采用该算法针对不同的输入时间序列数据生成的训练模型均需要保存在该目录下，同时目录名称要在分析算法中确定，以便能够固定加载该目录下的分析模型。为了确保模型能够正常读取加载，存储的模型使用`joblib`库进行序列化保存。
+
+下面以自编码器（Autoencoder）为例，说明如何添加要预先训练的模型进行异常检测。
+首先我们在 `model `目录中创建一个目录 -- `ad_autoencoder` (见上图目录结构)，该目录将用来保存所有使用自编码器训练的模型。然后，我们使用自编码器对 foo 表的时间序列数据进行训练，得到模型 针对 foo 表的模型，我们将其命名为 `ad_autoencoder_foo`，使用 `joblib`序列化该模型以后保存在 `ad_autoencoder` 目录中。如下图所示，ad_autoencoder_foo 由两个文件构成，分别是模型文件 (ad_autoencoder_foo.dat) 和模型文件描述文件 (ad_autoencoder_foo.info)。
+
+```bash
+.
+└── model
+    └── ad_autoencoder
+        ├── ad_autoencoder_foo.dat
+        └── ad_autoencoder_foo.info
+
+```
+
+接下来说明如何使用 SQL 调用该模型。
+通过设置参数 `algo=ad_encoder` 告诉分析平台要调用自编码器算法训练的模型（自编码器算法在可用算法列表中），因此直接指定即可。此外还需要指定自编码器针对某数据集训练的确定的模型，此时我们需要使用已经保存的模型 `ad_autoencoder_foo` ，因此需要添加参数 `model=ad_autoencoder_foo` 以便能够调用该模型。
+
+```SQL
+--- 在 options 中增加 model 的名称，ad_autoencoder_foo， 针对 foo 数据集（表）训练的采用自编码器的异常检测模型进行异常检测
+SELECT COUNT(*), _WSTART
+FROM foo
+ANOMALY_WINDOW(col1, 'algo=ad_encoder, model=ad_autoencoder_foo');
+```

docs/zh/06-advanced/06-TDgpt/07-dev/04-tsfm.md

@@ -0,0 +1,112 @@
+---
+title: "增加时序数据基础模型"
+sidebar_label: "增加时序数据基础模型"
+---
+
+### 输入约定
+`execute` 是预测算法处理的核心方法。框架调用该方法之前，在对象属性参数 `self.list` 中已经设置完毕用于预测的历史时间序列数据。
+
+### 输出约定及父类属性说明
+`execute` 方法执行完成后的返回一个如下字典对象， 预测返回结果如下：
+
+```python
+return {
+    "mse": mse, # 预测算法的拟合数据最小均方误差(minimum squared error)
+    "res": res  # 结果数组 [时间戳数组, 预测结果数组, 预测结果执行区间下界数组，预测结果执行区间上界数组]
+}
+```
+
+
+预测算法的父类 `AbstractForecastService` 包含的对象属性如下：
+
+|属性名称|说明|默认值|
+|---|---|---|
+|period|输入时间序列的周期性，多少个数据点表示一个完整的周期。如果没有周期性，设置为 0 即可|	0|
+|start_ts|预测结果的开始时间|	0|
+|time_step|预测结果的两个数据点之间时间间隔|0	|
+|fc_rows|预测结果的数量|	0	|
+|return_conf|预测结果中是否包含置信区间范围，如果不包含置信区间，那么上界和下界与自身相同|	1|	
+|conf|置信区间分位数|95|
+
+
+
+### 示例代码
+下面我们开发一个示例预测算法，对于任何输入的时间序列数据，固定返回值 1 作为预测结果。
+
+```python
+import numpy as np
+from taosanalytics.service import AbstractForecastService
+
+
+# 算法实现类名称 需要以下划线 "_" 开始，并以 Service 结束
+class _MyForecastService(AbstractForecastService):
+    """ 定义类，从 AbstractForecastService 继承并实现其定义的抽象方法 execute  """
+
+    # 定义算法调用关键词，全小写ASCII码
+    name = 'myfc'
+
+    # 该算法的描述信息(建议添加)
+    desc = """return the forecast time series data"""
+
+    def __init__(self):
+        """类初始化方法"""
+        super().__init__()
+
+    def execute(self):
+        """ 算法逻辑的核心实现"""
+        res = []
+
+        """这个预测算法固定返回 1 作为预测值，预测值的数量是用户通过 self.fc_rows 指定"""
+        ts_list = [self.start_ts + i * self.time_step for i in range(self.fc_rows)]
+        res.append(ts_list)  # 设置预测结果时间戳列
+
+        """生成全部为 1 的预测结果 """
+        res_list = [1] * self.fc_rows
+        res.append(res_list)
+
+        """检查用户输入，是否要求返回预测置信区间上下界"""
+        if self.return_conf:
+            """对于没有计算预测置信区间上下界的算法，直接返回预测值作为上下界即可"""
+            bound_list = [1] * self.fc_rows
+            res.append(bound_list)  # 预测结果置信区间下界
+            res.append(bound_list)  # 预测结果执行区间上界
+
+        """返回结果"""
+        return {"res": res, "mse": 0}
+
+    def set_params(self, params):
+        """该算法无需任何输入参数，直接调用父类函数，不处理算法参数设置逻辑"""
+        return super().set_params(params)
+
+```
+
+将该文件保存在 `./lib/taosanalytics/algo/fc/` 目录下，然后重启 taosanode 服务。在 TDengine 命令行接口中执行 `SHOW ANODES FULL` 能够看到新加入的算法。应用就可以通过 SQL 语句调用该预测算法。
+
+```SQL
+--- 对 col 列进行异常检测，通过指定 algo 参数为 myfc 来调用新添加的预测类
+SELECT  _flow, _fhigh, _frowts, FORECAST(col_name, "algo=myfc")
+FROM foo;
+```
+
+如果是第一次启动该 Anode, 请按照 [TDgpt 安装部署](../../management/) 里的步骤先将该 Anode 添加到 TDengine 系统中。
+
+### 单元测试
+
+在测试目录`taosanalytics/test`中的 forecast_test.py 中增加单元测试用例或添加新的测试文件。单元测试依赖 Python Unit test 包。
+
+```python
+def test_myfc(self):
+    """ 测试 myfc 类 """
+    s = loader.get_service("myfc")
+
+    # 设置用于预测分析的数据
+    s.set_input_list(self.get_input_list(), None)
+    # 检查预测结果应该全部为 1
+    r = s.set_params(
+        {"fc_rows": 10, "start_ts": 171000000, "time_step": 86400 * 30, "start_p": 0}
+    )
+    r = s.execute()
+
+    expected_list = [1] * 10
+    self.assertEqlist(r["res"][0], expected_list)
+```

docs/zh/06-advanced/06-TDgpt/09-tutorial.md

@@ -1,73 +0,0 @@
----
-title: "快速体验"
-sidebar_label: "快速体验"
----
-
-# 通过 Docker 快速体验
-
-本节首先介绍如何通过 Docker 快速体验 TDgpt。
-
-## 启动 TDgpt
-
-如果已经安装了 Docker，首先拉取最新的 TDengine 容器镜像：
-
-```shell
-docker pull tdengine/tdengine:latest
-```
-
-或者指定版本的容器镜像：
-
-```shell
-docker pull tdengine/tdengine:3.3.3.0
-```
-
-然后只需执行下面的命令：
-
-```shell
-docker run -d -p 6030:6030 -p 6041:6041 -p 6043:6043 -p 6044-6049:6044-6049 -p 6044-6045:6044-6045/udp -p 6060:6060 tdengine/tdengine
-```
-
-注意：TDgpt 服务端使用  6090 TCP 端口。TDgpt 是一个无状态时序数据分析智能体，并不会在本地持久化保存数据，仅根据配置可能在本地生成运行日志。
-
-确定该容器已经启动并且在正常运行。
-
-```shell
-docker ps
-```
-
-进入该容器并执行 `bash`
-
-```shell
-docker exec -it <container name> bash
-```
-
-然后就可以执行相关的 Linux 命令操作和访问 TDengine。
-
-# 通过安装包快速体验
-
-## 获取安装包
-
-1. 从列表中下载获得 tar.gz 安装包：
-
-2. 进入到安装包所在目录，使用 `tar` 解压安装包；
-3. 进入到安装包所在目录，先解压文件后，进入子目录，执行其中的 install.sh 安装脚本。
-
-> 请将 `<version>` 替换为下载的安装包版本
-
-```bash
-tar -zxvf TDengine-anode-<version>-Linux-x64.tar.gz
-```
-
-解压文件后，进入相应子目录，执行其中的 `install.sh` 安装脚本：
-
-```bash
-sudo ./install.sh
-```
-
-## 安装部署使用
-
-请参考[安装部署指南](./management) 准备环境，并安装部署 TDgpt。
-
-# 通过云服务快速体验
-
-TDgpt 可以在 TDengine Cloud 上进行快速体验。如果您已经有云服务账号，请在数据库集市里面找到“时序数据预测分析数据集”数据库，点击启用就可以进入这个数据库，然后按照 TDgpt 的 SQL 操作手册来执行语句，比如 `select forecast(val, 'algo=tdtsfm_1') from forecast.electricity_demand;`。

tools/tdgpt/requirements.txt

@@ -47,6 +47,7 @@ threadpoolctl==3.5.0
 torch==2.4.1+cpu
 typing_extensions==4.9.0
 urllib3==2.2.3
+transformers==4.40.0
 uWSGI==2.0.27
 Werkzeug==3.0.4
 Flask-Testing==0.8.1

tools/tdgpt/script/install.sh

@@ -410,6 +410,7 @@ function install_anode_venv() {
   ${csudo}${venvDir}/bin/pip3 install --upgrade keras
   ${csudo}${venvDir}/bin/pip3 install requests
   ${csudo}${venvDir}/bin/pip3 install taospy
+  ${csudo}${venvDir}/bin/pip3 install transformers
 
   echo -e "Install python library for venv completed!"
 }

tools/tdgpt/taosanalytics/time-moe.py

@@ -0,0 +1,61 @@
+import torch
+from flask import Flask, request, jsonify
+from transformers import AutoModelForCausalLM
+
+app = Flask(__name__)
+device = 'cpu'
+
+model = AutoModelForCausalLM.from_pretrained(
+    'Maple728/TimeMoE-200M',
+    device_map=device,  # use "cpu" for CPU inference, and "cuda" for GPU inference.
+    trust_remote_code=True,
+)
+
+@app.route('/ds_predict', methods=['POST'])
+def time_moe():
+    try:
+        data = request.get_json()
+        if not data or 'input' not in data:
+            return jsonify({
+                'status':'error',
+                'error': 'Invalid input, please provide "input" field in JSON'
+            }), 400
+
+        input_data = data['input']
+        prediction_length = data['next_len']
+
+        seqs = torch.tensor(input_data).unsqueeze(0).float().to(device)
+        mean, std = seqs.mean(dim=-1, keepdim=True), seqs.std(dim=-1, keepdim=True)
+        normed_seqs = (seqs - mean) / std
+        seqs = normed_seqs
+
+        pred_y = model.generate(seqs, max_new_tokens=prediction_length)
+
+        normed_predictions = pred_y[:, -prediction_length:] 
+        # inverse normalize
+        predictions = normed_predictions * std + mean
+        print(predictions)
+        pred_y = predictions[0].numpy().tolist()
+
+        response = {
+            'status': 'success',
+            'output': pred_y
+        }
+        return jsonify(response), 200
+    except Exception as e:
+        return jsonify({
+            'error': f'Prediction failed: {str(e)}'
+        }), 500
+
+def main():
+    app.run(
+            host='0.0.0.0',
+            port=5001,
+            threaded=True,  
+            debug=False     
+        )
+
+
+if __name__ == "__main__":
+    main()
+