diff --git a/docs/zh/06-advanced/06-TDgpt/02-tutorial.md b/docs/zh/06-advanced/06-TDgpt/02-tutorial.md index ecf486290c..e6ce9413b4 100644 --- a/docs/zh/06-advanced/06-TDgpt/02-tutorial.md +++ b/docs/zh/06-advanced/06-TDgpt/02-tutorial.md @@ -6,9 +6,9 @@ sidebar_label: "安装部署" import PkgListV3 from "/components/PkgListV3"; -# 通过 Docker 快速体验 +# 使用 TDgpt Docker 镜像 -本节首先介绍如何通过 Docker 快速体验 TDgpt。 +本节首先介绍如何通过 Docker 快速使用 TDgpt。 ## 启动 TDgpt @@ -47,14 +47,16 @@ docker exec -it bash 然后就可以执行相关的 Linux 命令操作和访问 TDengine。 -# 通过云服务快速体验 +# 注册云服务使用 TDgpt TDgpt 可以在 TDengine Cloud 上进行快速体验。如果您已经有云服务账号,请在数据库集市里面找到“时序数据预测分析数据集”数据库,点击启用就可以进入这个数据库,然后按照 TDgpt 的 SQL 操作手册来执行语句,比如 `select forecast(val, 'algo=tdtsfm_1') from forecast.electricity_demand;`。 -# 通过安装包快速体验 +# 通过安装包部署 TDgpt + +## 环境准备 + +使用 TDgpt 的高级时序数据分析功能需要在 TDengine 集群中安装部署Taos AI node(Anode)。Anode 运行在 Linux 平台上,并需要 3.10 或以上版本的 Python 环境支持。 -### 环境准备 -使用 TDgpt 的高级时序数据分析功能需要在 TDengine 集群中安装部署 AI node(Anode)。Anode 运行在 Linux 平台上,并需要 3.10 或以上版本的 Python 环境支持。 > 部署 Anode 需要 TDengine 3.3.6.0 及以后版本,请首先确认搭配 Anode 使用的 TDengine 能够支持 Anode。 可以使用以下的命令在 Ubuntu Linux 上安装 Python 3.10 环境 @@ -84,7 +86,7 @@ export PATH=$PATH:~/.local/bin ``` 至此 Python 环境准备完成,可以进行 taosanode 的安装和部署。 -### 获取安装包 +## 获取安装包 1. 从列表中下载获得 tar.gz 安装包: @@ -96,13 +98,23 @@ export PATH=$PATH:~/.local/bin tar -zxvf TDengine-TDgpt--Linux-x64.tar.gz ``` -3. 解压文件后,进入相应子目录,执行其中的 `install.sh` 安装脚本: - 请将 `` 替换为下载的安装包版本 +## 执行安装脚本 + +解压文件后,进入相应子目录,执行其中的 `install.sh` 安装脚本: +请将 `` 替换为下载的安装包版本 ```bash cd TDengine-TDgpt- sudo ./install.sh ``` -对于已经安装的 Anode,执行命令 `rmtaosanode` 即可完成卸载。 为了避免影响系统已有的 Python 环境,Anode 使用虚拟环境运行。安装 Anode 会在目录 `/var/lib/taos/taosanode/venv/` 中创建默认的 Python 虚拟环境,Anode 运行所需要的库均安装在该目录下。为了避免反复安装虚拟环境带来的开销,卸载命令 `rmtaosanode` 并不会自动删除该虚拟环境,如果您确认不再需要 Python 的虚拟环境,手动删除该目录即可。 + +## 激活使用虚拟环境 + +为了避免安装操作系统的Python 环境, TDgpt 安装过程中会自动创建一个虚拟环境,该虚拟环境默认创建的路径在 `/var/lib/taos/taosanode/venv/`。创建完成该虚拟环境,该虚拟环境通过 PiPy 安装了支持 TDgpt 运行所必须的 Python 依赖库。 +该虚拟环境不会被卸载脚本 `rmtaosanode` 删除,当您确认不再需要该虚拟环境的时候,需要手动删除该虚拟环境。 +后续如果您需要开发自己的算法模型,并能够 TDgpt 正确调用,需要将新的依赖库通过虚拟环境的 Pip 正确地安装。 + +## 卸载 +卸载 TDgpt,执行 `rmtaosanode` 即可。 安装过程中自动安装的虚拟环境不会被自动删除,用户确认不再需要的时候,需要手动删除该虚拟环境。 diff --git a/docs/zh/06-advanced/06-TDgpt/07-dev/02-algo/02-forecast.md b/docs/zh/06-advanced/06-TDgpt/07-dev/02-algo/02-forecast.md index cd34e9fd21..81908fc339 100644 --- a/docs/zh/06-advanced/06-TDgpt/07-dev/02-algo/02-forecast.md +++ b/docs/zh/06-advanced/06-TDgpt/07-dev/02-algo/02-forecast.md @@ -1,10 +1,10 @@ --- -title: "预测算法" -sidebar_label: "预测算法" +title: "预测分析" +sidebar_label: "预测分析" --- ### 输入约定 -`execute` 是预测算法处理的核心方法。框架调用该方法之前,在对象属性参数 `self.list` 中已经设置完毕用于预测的历史时间序列数据。 +`execute` 是预测分析算法的核心方法。框架调用该方法之前,在对象属性参数 `self.list` 中已经设置完毕用于预测的历史时间序列数据。 ### 输出约定及父类属性说明 `execute` 方法执行完成后的返回一个如下字典对象, 预测返回结果如下: diff --git a/docs/zh/06-advanced/06-TDgpt/07-dev/04-tsfm.md b/docs/zh/06-advanced/06-TDgpt/07-dev/04-tsfm.md index 9d416f021a..087c5e806a 100644 --- a/docs/zh/06-advanced/06-TDgpt/07-dev/04-tsfm.md +++ b/docs/zh/06-advanced/06-TDgpt/07-dev/04-tsfm.md @@ -1,112 +1,77 @@ --- -title: "增加时序数据基础模型" -sidebar_label: "增加时序数据基础模型" +title: "部署时序基础模型" +sidebar_label: "部署时序基础模型" --- -### 输入约定 -`execute` 是预测算法处理的核心方法。框架调用该方法之前,在对象属性参数 `self.list` 中已经设置完毕用于预测的历史时间序列数据。 +# 准备环境运行环境 -### 输出约定及父类属性说明 -`execute` 方法执行完成后的返回一个如下字典对象, 预测返回结果如下: +为了使用时间序列基础模型,需要在本地部署环境支持其运行。首先需要准备 Python 环境。使用 PiPy 安装必要的依赖包: -```python -return { - "mse": mse, # 预测算法的拟合数据最小均方误差(minimum squared error) - "res": res # 结果数组 [时间戳数组, 预测结果数组, 预测结果执行区间下界数组,预测结果执行区间上界数组] -} +```shell +pip install torch==2.4.1+cpu -f https://download.pytorch.org/whl/torch_stable.html +pip install flask==3.0.3 +pip install transformers==4.40.0 +pip install accelerate ``` +# 设置服务端口和 URL 地址 -预测算法的父类 `AbstractForecastService` 包含的对象属性如下: +```Python +@app.route('/ds_predict', methods=['POST']) +def time_moe(): +... +``` +修改 `ds_predict` 为需要开启的 URL 服务地址,或者使用默认路径即可。 -|属性名称|说明|默认值| -|---|---|---| -|period|输入时间序列的周期性,多少个数据点表示一个完整的周期。如果没有周期性,设置为 0 即可| 0| -|start_ts|预测结果的开始时间| 0| -|time_step|预测结果的两个数据点之间时间间隔|0 | -|fc_rows|预测结果的数量| 0 | -|return_conf|预测结果中是否包含置信区间范围,如果不包含置信区间,那么上界和下界与自身相同| 1| -|conf|置信区间分位数|95| +```Python + app.run( + host='0.0.0.0', + port=5001, + threaded=True, + debug=False + ) +``` +其中的 port 修改为希望开启的端口,重启脚本即可。 +# 启动部署 Python 脚本 -### 示例代码 -下面我们开发一个示例预测算法,对于任何输入的时间序列数据,固定返回值 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) - +```shell +nohup Python time-moe.py > custom_output.out 2>&1 & ``` -将该文件保存在 `./lib/taosanalytics/algo/fc/` 目录下,然后重启 taosanode 服务。在 TDengine 命令行接口中执行 `SHOW ANODES FULL` 能够看到新加入的算法。应用就可以通过 SQL 语句调用该预测算法。 +第一次启动脚本会从 huggingface 自动加载[2亿参数时序数据基础模型](https://huggingface.co/Maple728/TimeMoE-200M)。该模型是 Time-MoE 200M参数版本,如果您需要部署参数规模更小的版本请将 `time-moe.py` 文件中 `'Maple728/TimeMoE-200M'` 修改为 `Maple728/TimeMoE-50M`,此时将加载 [0.5亿参数版本模型](https://huggingface.co/Maple728/TimeMoE-50M)。 -```SQL ---- 对 col 列进行异常检测,通过指定 algo 参数为 myfc 来调用新添加的预测类 -SELECT _flow, _fhigh, _frowts, FORECAST(col_name, "algo=myfc") -FROM foo; +如果加载失败,请尝试执行如下命令切换为国内镜像下载模型。 + +```shell +export HF_ENDPOINT=https://hf-mirror.com ``` -如果是第一次启动该 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) +再执行脚本: +```shell +nohup Python time-moe.py > custom_output.out 2>&1 & +``` + +显示如下,则说明加载成功 +```shell +Running on all addresses (0.0.0.0) +Running on http://127.0.0.1:5001 +``` + +# 验证服务是否正常 + +使用 Shell 命令可以验证服务是否正常 + +```shell +curl 127.0.0.1:5001/ds_predict +``` +如果看到如下返回表明服务正常 + +```html + + +405 Method Not Allowed +

Method Not Allowed

+

The method is not allowed for the requested URL.

``` diff --git a/docs/zh/06-advanced/06-TDgpt/07-dev/index.md b/docs/zh/06-advanced/06-TDgpt/07-dev/index.md index bcd972df8e..d41a360f89 100644 --- a/docs/zh/06-advanced/06-TDgpt/07-dev/index.md +++ b/docs/zh/06-advanced/06-TDgpt/07-dev/index.md @@ -1,6 +1,6 @@ --- -title: "算法开发者指南" -sidebar_label: "算法开发者指南" +title: "开发者指南" +sidebar_label: "开发者指南" --- TDgpt 是一个可扩展的时序数据高级分析平台,用户遵循简易的步骤就能将自己开发的分析算法添加到分析平台, 各种应用就可以通过SQL语句直接调用, 让高级分析算法的使用门槛降到几乎为零。目前 TDpgt 平台只支持使用 Python 语言开发的分析算法。 Anode 采用类动态加载模式,在启动的时候扫描特定目录内满足约定条件的所有代码文件,并将其加载到系统中。因此,开发者只需要遵循以下几步就能完成新算法的添加工作: @@ -67,30 +67,3 @@ Anode采用算法自动加载模式,因此只识别符合命名约定的 Pytho SELECT COUNT(*) FROM foo ANOMALY_WINDOW(col_name, 'algo=name') ``` - -## 添加具有模型的分析算法 - -基于统计学的分析算法可以直接针对输入时间序列数据进行分析,但是某些深度学习算法对于输入数据需要较长的时间训练,并且生成相应的模型。这种情况下,同一个分析算法对应不同的输入数据集有不同的分析模型。 -将具有模型的分析算法添加到 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'); -```