Skip to content

update ainode deployment #832

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
StefanieZhao7 merged 1 commit into from
Jul 21, 2025
Merged

update ainode deployment #832

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 45 additions & 81 deletions src/UserGuide/Master/Table/Deployment-and-Maintenance/AINode_Deployment_apache.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,10 +24,10 @@

### 1.1 Capability Introduction

AINode is the third type of endogenous node provided by IoTDB after the Configurable Node and DataNode. This node extends its ability to perform machine learning analysis on time series by interacting with the DataNode and Configurable Node of the IoTDB cluster. It supports the introduction of existing machine learning models from external sources for registration and the use of registered models to complete time series analysis tasks on specified time series data through simple SQL statements. The creation, management, and inference of models are integrated into the database engine. Currently, machine learning algorithms or self-developed models are available for common time series analysis scenarios, such as prediction and anomaly detection.
AINode is the third type of endogenous node provided by IoTDB after the Configurable Node and DataNode. This node extends its ability to perform machine learning analysis on time series by interacting with the DataNode and Configurable Node of the IoTDB cluster. It supports the introduction of existing machine learning models from external sources for registration and the use of registered models to complete time series analysis tasks on specified time series data through simple SQL statements. The creation, management, and inference of models are integrated into the database engine. Currently, machine learning algorithms or self-developed models are available for common time series analysis scenarios, such as prediction and anomaly detection.

### 1.2 Delivery Method
It is an additional package outside the IoTDB cluster, with independent installation.
AINode is an additional package outside the IoTDB cluster, with independent installation.

### 1.3 Deployment mode
<div >
Expand All @@ -39,62 +39,47 @@

### 2.1 Get installation package

Unzip and install the package
`(apache-iotdb-<version>-ainode-bin.zip)`， The directory structure after unpacking the installation package is as follows:
| **Catalogue** | **Type** | **Explain** |
| ------------ | -------- | ------------------------------------------------ |
| lib | folder | AINode compiled binary executable files and related code dependencies |
| sbin | folder | The running script of AINode can start, remove, and stop AINode |
| conf | folder | Contains configuration items for AINode, specifically including the following configuration items |
| LICENSE | file | Certificate |
| NOTICE | file | Tips |
| README_ZH.md | file | Explanation of the Chinese version of the markdown format |
| `README.md` | file | Instructions |
Unzip and install the package
`(apache-iotdb-<version>-ainode-bin.zip)`， The directory structure after unpacking the installation package is as follows:

| **Catalogue** | **Type** | **Explain** |
| ------------ | -------- |-----------------------------------------------------------------------|
| lib | folder | Python package files for AINode |
| sbin | folder | The running script of AINode can start, remove, and stop AINode |
| conf | folder | Configuration files for AINode, and runtime environment setup scripts |
| LICENSE | file | Certificate |
| NOTICE | file | Tips |
| README_ZH.md | file | Explanation of the Chinese version of the markdown format |
| README.md | file | Instructions |

### 2.2 Environmental Preparation

1. Recommended operating systems: Ubuntu, CentOS, MacOS
1. Recommended operating systems: Ubuntu, MacOS
2. IoTDB version: >= V 2.0.5.1
3. Runtime environment
- Python version between 3.9 and 3.12, with pip and venv tools installed;
- Python version between 3.9 and 3.12, with pip and venv tools installed;

## 3. Installation steps

### 3.1 Install AINode


1. Ensure Python version is between 3.9 and 3.12:
1. Ensure Python version is between 3.9 and 3.12:
```shell
python --version
python --version
# or
python3 --version
```

2. Download and import AINode into a dedicated folder, switch to the folder, and unzip the package:
2. Download and import AINode into a dedicated folder, switch to the folder, and unzip the package:
```shell
unzip timechodb-2.0.5.1-ainode-bin.zip
```
3. Create a virtual environment (execute in the ainode directory):

```shell
python3 -m venv venv
```

4. Activate the virtual environment:

```shell
source venv/bin/activate
```
5. Update pip and install AINode dependencies:
```shell
python -m pip install --upgrade pip
poetry lock
poetry install
```
unzip apache-iotdb-<version>-ainode-bin.zip
```

### 3.2 Configuration item modification

AINode supports modifying some necessary parameters. You can find the following parameters in the `conf/iotdb-ainode.properties` file and make persistent modifications to them:

| **Name** | **Description** | **Type** | **Default Value** |
| ------------------------------ | ------------------------------------------------------------ | -------- | ------------------ |
| cluster_name | Identifier of the cluster AINode joins | string | defaultCluster |
Expand All @@ -110,13 +95,19 @@ AINode supports modifying some necessary parameters. You can find the following
| ain_models_dir | Path to store model files for AINode (relative path starts from OS-dependent directory; absolute path is recommended) | String | data/AINode/models |
| ain_thrift_compression_enabled | Whether to enable Thrift compression for AINode (0=disabled, 1=enabled) | Boolean | 0 |

### 3.3 Start AINode
### 3.3 Importing Weight Files

> Offline environment only (Online environments can skip this step)
>
Contact Timecho team to obtain the model weight files, then place them in the /IOTDB_AINODE_HOME/data/ainode/models/weights/ directory.

### 3.4 Start AINode

After completing the deployment of Seed Config Node, the registration and inference functions of the model can be supported by adding AINode nodes. After specifying the information of the IoTDB cluster in the configuration file, the corresponding instruction can be executed to start AINode and join the IoTDB cluster。
After completing the deployment of Seed Config Node, the registration and inference functions of the model can be supported by adding AINode nodes. After specifying the information of the IoTDB cluster in the configuration file, the corresponding instruction can be executed to start AINode and join the IoTDB cluster。

#### Networking environment startup
- Networking environment startup

##### Start command
Start command

```shell
# Start command
Expand All @@ -134,25 +125,7 @@ AINode supports modifying some necessary parameters. You can find the following
nohup bash sbin\start-ainode.bat > myout.file 2>& 1 &
```


#### Example

```shell
# Start command
# Linux and MacOS systems
bash sbin/start-ainode.sh
# Windows systems
sbin\start-ainode.bat


# Backend startup command (recommended for long-term running)
# Linux and MacOS systems
nohup bash sbin/start-ainode.sh > myout.file 2>& 1 &
# Windows systems
nohup bash sbin\start-ainode.bat > myout.file 2>& 1 &
```

### 3.4 Detecting the status of AINode nodes
### 3.5 Detecting the status of AINode nodes

During the startup process of AINode, the new AINode will be automatically added to the IoTDB cluster. After starting AINode, you can enter SQL in the command line to query. If you see an AINode node in the cluster and its running status is Running (as shown below), it indicates successful joining.

Expand All @@ -168,11 +141,11 @@ IoTDB> show cluster
+------+----------+-------+---------------+------------+-------+-----------+
```

### 3.5 Stop AINode
### 3.6 Stop AINode

If you need to stop a running AINode node, execute the corresponding shutdown script.

#### Stop command
Stop command

```shell
# Linux / MacOS
Expand All @@ -182,15 +155,6 @@ If you need to stop a running AINode node, execute the corresponding shutdown sc
sbin\stop-ainode.bat
```

#### Example

```shell
# Linux / MacOS
bash sbin/stop-ainode.sh

# Windows
sbin\stop-ainode.bat
```
After stopping AINode, you can still see AINode nodes in the cluster, whose running status is UNKNOWN (as shown below), and the AINode function cannot be used at this time.

```shell
Expand All @@ -209,9 +173,9 @@ If you need to restart the node, you need to execute the startup script again.

### 4.1 An error occurs when starting AINode stating that the venv module cannot be found

When starting AINode using the default method, a Python virtual environment will be created in the installation package directory and dependencies will be installed, so it is required to install the venv module. Generally speaking, Python 3.10 and above versions come with built-in VenV, but for some systems with built-in Python environments, this requirement may not be met. There are two solutions when this error occurs (choose one or the other):
When starting AINode using the default method, a Python virtual environment will be created in the installation package directory and dependencies will be installed, so it is required to install the venv module. Generally speaking, Python 3.10 and above versions come with built-in VenV, but for some systems with built-in Python environments, this requirement may not be met. There are two solutions when this error occurs (choose one or the other):

To install the Venv module locally, taking Ubuntu as an example, you can run the following command to install the built-in Venv module in Python. Or install a Python version with built-in Venv from the Python official website.
To install the Venv module locally, taking Ubuntu as an example, you can run the following command to install the built-in Venv module in Python. Or install a Python version with built-in Venv from the Python official website.

```shell
apt-get install python3.10-venv
Expand All @@ -221,14 +185,14 @@ Install version 3.10.0 of venv into AINode in the AINode path.
```shell
../Python-3.10.0/python -m venv venv(Folder Name）
```
When running the startup script, use ` -i ` to specify an existing Python interpreter path as the running environment for AINode, eliminating the need to create a new virtual environment.
When running the startup script, use ` -i ` to specify an existing Python interpreter path as the running environment for AINode, eliminating the need to create a new virtual environment.

### 4.2 The SSL module in Python is not properly installed and configured to handle HTTPS resources
### 4.2 The SSL module in Python is not properly installed and configured to handle HTTPS resources
WARNING: pip is configured with locations that require TLS/SSL, however the ssl module in Python is not available.
You can install OpenSSLS and then rebuild Python to solve this problem
> Currently Python versions 3.6 to 3.9 are compatible with OpenSSL 1.0.2, 1.1.0, and 1.1.1.

Python requires OpenSSL to be installed on our system, the specific installation method can be found in [link](https://stackoverflow.com/questions/56552390/how-to-fix-ssl-module-in-python-is-not-available-in-centos)
Python requires OpenSSL to be installed on our system, the specific installation method can be found in [link](https://stackoverflow.com/questions/56552390/how-to-fix-ssl-module-in-python-is-not-available-in-centos)

```shell
sudo apt-get install build-essential libssl-dev zlib1g-dev libbz2-dev libreadline-dev libsqlite3-dev wget curl llvm libncurses5-dev libncursesw5-dev xz-utils tk-dev libffi-dev liblzma-dev uuid-dev lzma-dev liblzma-dev
Expand All @@ -237,9 +201,9 @@ make
sudo make install
```

### 4.3 Pip version is lower
### 4.3 Pip version is lower

A compilation issue similar to "error: Microsoft Visual C++14.0 or greater is required..." appears on Windows
A compilation issue similar to "error: Microsoft Visual C++14.0 or greater is required..." appears on Windows

The corresponding error occurs during installation and compilation, usually due to insufficient C++version or Setup tools version. You can check it in

Expand All @@ -249,14 +213,14 @@ The corresponding error occurs during installation and compilation, usually due
```


### 4.4 Install and compile Python
### 4.4 Install and compile Python

Use the following instructions to download the installation package from the official website and extract it:
Use the following instructions to download the installation package from the official website and extract it:
```shell
.wget https://www.python.org/ftp/python/3.10.0/Python-3.10.0.tar.xz
tar Jxf Python-3.10.0.tar.xz
```
Compile and install the corresponding Python package:
Compile and install the corresponding Python package:
```shell
cd Python-3.10.0
./configure prefix=/usr/local/python3
Expand Down
Loading