AINode 部署
AINode 部署
1. AINode 介绍
1.1 能力介绍
AINode 是 IoTDB 在 ConfigNode、DataNode 后提供的第三种内生节点，该节点通过与 IoTDB 集群的 DataNode、ConfigNode 交互，扩展了对时间序列进行机器学习分析的能力。AINode 将模型的管理、训练及推理融合在数据库引擎中，支持使用注册的模型在指定时序数据上通过简单 SQL 语句完成时序分析任务，还支持注册并使用自定义机器学习模型。AINode 目前已集成常见时序分析场景（例如预测）的机器学习算法和自研模型。
1.2 交付方式
AINode 是 IoTDB 集群外的额外套件，独立安装包。
1.3 部署模式
2. 安装准备
2.1 安装包获取
AINode 安装包（apache-iotdb-<version>-ainode-bin.zip）解压后关键目录结构如下：
| 目录 | 类型 | 说明 |
|---|---|---|
| lib | 文件夹 | AINode 的可执行程序及依赖 |
| sbin | 文件夹 | AINode 的运行脚本，用于启动或停止 AINode |
| conf | 文件夹 | AINode 的配置文件和版本声明文件 |
说明：AINode 支持通过源码编译的方式构建安装包，具体操作步骤可参考AINode 构建小节。
2.2 前置检查
为确保您获取的 AINode 安装包完整且正确，在执行安装部署前建议您进行 SHA512 校验。
准备工作：
- 获取官方发布的 SHA512 校验码：请联系天谋工作人员获取
校验步骤（以 linux 为例）：
- 打开终端，进入安装包所在目录（如
/data/ainode）：cd /data/ainode - 执行以下命令计算哈希值：
sha512sum apache-iotdb-<version>-ainode-bin.zip - 终端输出结果（左侧为SHA512 校验码，右侧为文件名）：
(base) root@hadoop@1:/data/ainode (0.664s)
sha512sum apache-iotdb-2.0.5-ainode-bin.zip
b39039a1235a86bc3ce3df0a102efa215e281b5839683ccaf47883b390af4e686f99e6980a24a9d41348325f3518bd55ebb1c61a123495cbdc575dad8c695f28 apache-iotdb-2.0.5-ainode-bin.zip- 对比输出结果与官方 SHA512 校验码，确认一致后，即可按照下方流程执行 AINode 的安装部署操作。
注意事项：
- 若校验结果不一致，请联系天谋工作人员重新获取安装包
- 校验过程中若出现"文件不存在"提示，需检查文件路径是否正确或安装包是否完整下载
2.3 环境要求
- 建议操作环境: Linux, MacOS；
- IoTDB 版本：>= V 2.0.8-beta；
3. 安装部署及使用
3.1 安装 AINode
下载导入 AINode 到专用文件夹，切换到专用文件夹并解压安装包；
unzip apache-iotdb-<version>-ainode-bin.zip3.2 配置项修改
AINode 支持修改一些必要的参数。可以在 /IOTDB_AINODE_HOME/conf/iotdb-ainode.properties 文件中找到下列参数并进行持久化的修改：
| 名称 | 描述 | 类型 | 默认值 |
|---|---|---|---|
| cluster_name | AINode 要加入的集群标识 | string | defaultCluster |
| ain_seed_config_node | AINode 启动时注册的 ConfigNode 地址 | String | 127.0.0.1:10710 |
| ain_cluster_ingress_address | AINode 拉取数据的 DataNode 的 rpc 地址 | String | 127.0.0.1 |
| ain_cluster_ingress_port | AINode 拉取数据的 DataNode 的 rpc 端口 | Integer | 6667 |
| ain_cluster_ingress_username | AINode 拉取数据的 DataNode 的客户端用户名 | String | root |
| ain_cluster_ingress_password | AINode 拉取数据的 DataNode 的客户端密码 | String | root |
| ain_rpc_address | AINode 提供服务与通信的地址 ，内部服务通讯接口 | String | 127.0.0.1 |
| ain_rpc_port | AINode 提供服务与通信的端口 | String | 10810 |
| ain_system_dir | AINode 元数据存储路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/system |
| ain_models_dir | AINode 存储模型文件的路径，相对路径的起始目录与操作系统相关，建议使用绝对路径 | String | data/AINode/models |
| ain_thrift_compression_enabled | AINode 是否启用 thrift 的压缩机制，0-不启动、1-启动 | Boolean | 0 |
3.3 导入内置权重文件
若部署环境可联网且能连通 HuggingFace 环境，系统会自动拉取内置模型权重文件，可忽略本步骤。
若为离线环境，联系天谋工作人员获取模型权重文件夹，并放置到/IOTDB_AINODE_HOME/data/ainode/models/builtin 目录下。
NOTE：注意目录层级，最终所有内置模型权重的父目录都是 builtin 。
3.4 启动 AINode
在完成 ConfigNode 的部署后，可以通过添加 AINode 来支持时序模型的管理和推理功能。在配置项中指定 IoTDB 集群的信息后，可以执行相应的指令来启动 AINode，加入 IoTDB 集群。
# 启动命令
# Linux 和 MacOS 系统
bash sbin/start-ainode.sh
# Windows 系统
sbin\start-ainode.bat
# 后台启动命令（长期运行推荐）
# Linux 和 MacOS 系统
bash sbin/start-ainode.sh -d
# Windows 系统
bash sbin\start-ainode.bat -d3.5 检测 AINode 节点状态
AINode 启动过程中会自动将新的 AINode 加入 IoTDB 集群。启动 AINode 后可以在命令行中输入 SQL 来查询，集群中看到 AINode 节点，其运行状态为 Running（如下展示）表示加入成功。
IoTDB> show cluster
+------+----------+-------+---------------+------------+-------+-----------+
|NodeID| NodeType| Status|InternalAddress|InternalPort|Version| BuildInfo|
+------+----------+-------+---------------+------------+-------+-----------+
| 0|ConfigNode|Running| 127.0.0.1| 10710|UNKNOWN|190e303-dev|
| 1| DataNode|Running| 127.0.0.1| 10730|UNKNOWN|190e303-dev|
| 2| AINode|Running| 127.0.0.1| 10810|UNKNOWN|190e303-dev|
+------+----------+-------+---------------+------------+-------+-----------+除此之外，还可以通过 show models 命令来查看模型状态。如果模型状态不对，请检查权重文件路径是否正确。
IoTDB> show models
+---------------------+---------+--------+--------+
| ModelId|ModelType|Category| State|
+---------------------+---------+--------+--------+
| arima| sktime| builtin| active|
| holtwinters| sktime| builtin| active|
|exponential_smoothing| sktime| builtin| active|
| naive_forecaster| sktime| builtin| active|
| stl_forecaster| sktime| builtin| active|
| gaussian_hmm| sktime| builtin| active|
| gmm_hmm| sktime| builtin| active|
| stray| sktime| builtin| active|
| timer_xl| timer| builtin| active|
| sundial| sundial| builtin| active|
| chronos2| t5| builtin| active|
+---------------------+---------+--------+--------+3.6 停止 AINode
如果需要停止正在运行的 AINode 节点，则执行相应的关停脚本，且支持通过参数 -p 指定端口，该端口为配置项中的 ain_rpc_port。
# Linux / MacOS
bash sbin/stop-ainode.sh
bash sbin/stop-ainode.sh -p <port_id> # 指定端口
#Windows
sbin\stop-ainode.bat
sbin\stop-ainode.bat -p <port_id> # 指定端口停止 AINode 后，还可以在集群中看到 AINode 节点，其运行状态为 UNKNOWN（如下展示），此时无法使用 AINode 功能。
IoTDB> show cluster
+------+----------+-------+---------------+------------+-------+-----------+
|NodeID| NodeType| Status|InternalAddress|InternalPort|Version| BuildInfo|
+------+----------+-------+---------------+------------+-------+-----------+
| 0|ConfigNode|Running| 127.0.0.1| 10710|UNKNOWN|190e303-dev|
| 1| DataNode|Running| 127.0.0.1| 10730|UNKNOWN|190e303-dev|
| 2| AINode|UNKNOWN| 127.0.0.1| 10790|UNKNOWN|190e303-dev|
+------+----------+-------+---------------+------------+-------+-----------+如果需要重新启动该节点，需重新执行启动脚本。
4. AINode 构建
AINode 支持通过如下方式构建安装包。
4.1 环境要求
- python： >=3.11.0,❤️.12.0
- Maven ：>= 3.6；
- Java：>= 1.8（已验证支持 1.8、11 至 17 版本，请确保环境变量路径已正确配置）。
4.2 操作步骤
- 支持通过如下两种 maven 命令构建 AINode。
# 同时构建 IoTDB 和 AINode 的指令
mvn clean package -pl distribution -P with-ainode -am -DskipTests
# 只构建 AINode 的指令
mvn clean package -pl iotdb-core/ainode -P with-ainode -am -DskipTests注意：
- 首次编译前请注意 pip 和 poetry 源可访问。
- 在当前操作系统、架构下构建的 AINode，构建后可部署在对应系统及更新的版本上。例如，在 Ubuntu20 x86 构建的 AINode 可直接部署于 Ubuntu20、Ubuntu24 等。
- 构建成功后，AINode 安装包的目录结构大致如下。
.
├── conf
│ ├── git.properties
│ ├── iotdb-ainode.properties # AINode 配置文件
│ └── pom.properties
├── lib # 采用文件夹形式打包 AINode，有助于提升启动效率
│ ├── _internal # 内含 Python 解释器及全量 python 依赖，解决离线启动问题
│ └── ainode # AINode 可执行程序
├── LICENSE
├── licenses
│ ├── 'CDDL License 1.1'
│ ├── 'Eclipse Public License 1.0 (EPL-1.0)'
│ ├── 'Eclipse Public License version 2.0 (EPL-2.0)'
│ ├── 'The 2-Clause BSD License'
│ ├── 'The 3-Clause BSD License'
│ ├── 'The MIT License (progressbar)'
│ └── 'The MIT License (QOS.ch)'
├── NOTICE
├── README.md
├── README_ZH.md
├── RELEASE_NOTES.md
└── sbin # 部署脚本
├── start-ainode.sh
├── stop-ainode.sh
└── windows