diff --git a/src/.vuepress/public/img/AINode-0-en.png b/src/.vuepress/public/img/AINode-0-en.png new file mode 100644 index 000000000..1b107d75a Binary files /dev/null and b/src/.vuepress/public/img/AINode-0-en.png differ diff --git a/src/.vuepress/public/img/AINode-0.png b/src/.vuepress/public/img/AINode-0.png new file mode 100644 index 000000000..6c72d0615 Binary files /dev/null and b/src/.vuepress/public/img/AINode-0.png differ diff --git a/src/.vuepress/public/img/AINode-en.png b/src/.vuepress/public/img/AINode-en.png new file mode 100644 index 000000000..c3252231a Binary files /dev/null and b/src/.vuepress/public/img/AINode-en.png differ diff --git a/src/.vuepress/public/img/AINode-new.png b/src/.vuepress/public/img/AINode-new.png new file mode 100644 index 000000000..3d17e9e8a Binary files /dev/null and b/src/.vuepress/public/img/AINode-new.png differ diff --git a/src/.vuepress/public/img/ETTh-tree.csv b/src/.vuepress/public/img/ETTh-tree.csv new file mode 100644 index 000000000..00378225a --- /dev/null +++ b/src/.vuepress/public/img/ETTh-tree.csv @@ -0,0 +1,97 @@ +Time,root.db.etth.HUFL,root.db.etth.OT,root.db.etth.MUFL,root.db.etth.LULL,root.db.etth.MULL,root.db.etth.LUFL,root.db.etth.HULL +2016-07-01T00:00:00.000+08:00,5.827,30.531,1.599,1.34,0.462,4.203,2.009 +2016-07-01T01:00:00.000+08:00,5.693,27.787,1.492,1.371,0.426,4.142,2.076 +2016-07-01T02:00:00.000+08:00,5.157,27.787,1.279,1.218,0.355,3.777,1.741 +2016-07-01T03:00:00.000+08:00,5.09,25.044,1.279,1.279,0.391,3.807,1.942 +2016-07-01T04:00:00.000+08:00,5.358,21.948,1.492,1.279,0.462,3.868,1.942 +2016-07-01T05:00:00.000+08:00,5.626,21.174,1.528,1.371,0.533,4.051,2.143 +2016-07-01T06:00:00.000+08:00,7.167,22.792,2.132,1.858,0.782,5.026,2.947 +2016-07-01T07:00:00.000+08:00,7.435,23.144,2.31,2.224,1.031,5.087,3.282 +2016-07-01T08:00:00.000+08:00,5.827,30.531,1.599,1.34,0.462,4.203,2.009 +2016-07-01T09:00:00.000+08:00,5.693,27.787,1.492,1.371,0.426,4.142,2.076 +2016-07-01T10:00:00.000+08:00,5.157,27.787,1.279,1.218,0.355,3.777,1.741 +2016-07-01T11:00:00.000+08:00,5.09,25.044,1.279,1.279,0.391,3.807,1.942 +2016-07-01T12:00:00.000+08:00,5.358,21.948,1.492,1.279,0.462,3.868,1.942 +2016-07-01T13:00:00.000+08:00,5.626,21.174,1.528,1.371,0.533,4.051,2.143 +2016-07-01T14:00:00.000+08:00,7.167,22.792,2.132,1.858,0.782,5.026,2.947 +2016-07-01T15:00:00.000+08:00,7.435,23.144,2.31,2.224,1.031,5.087,3.282 +2016-07-01T16:00:00.000+08:00,5.559,21.667,2.452,1.432,1.173,2.955,3.014 +2016-07-01T17:00:00.000+08:00,4.555,17.446,1.919,1.371,0.817,2.68,2.545 +2016-07-01T18:00:00.000+08:00,4.957,19.979,1.99,1.492,0.853,2.955,2.545 +2016-07-01T19:00:00.000+08:00,5.76,20.119,2.203,1.492,0.853,3.442,2.545 +2016-07-01T20:00:00.000+08:00,4.689,19.205,1.812,1.523,0.853,2.833,2.545 +2016-07-01T21:00:00.000+08:00,4.689,18.572,1.777,1.614,1.244,3.107,2.679 +2016-07-01T22:00:00.000+08:00,5.09,19.556,2.452,1.432,1.35,2.559,2.947 +2016-07-01T23:00:00.000+08:00,5.09,17.305,2.487,1.523,1.35,2.589,3.148 +2016-07-02T00:00:00.000+08:00,4.22,19.486,1.706,1.492,0.782,2.619,2.411 +2016-07-02T01:00:00.000+08:00,4.756,19.134,1.635,1.492,0.711,3.076,2.344 +2016-07-02T02:00:00.000+08:00,5.626,20.682,2.523,1.492,1.208,3.076,2.88 +2016-07-02T03:00:00.000+08:00,5.492,18.712,2.452,1.553,1.208,3.015,3.014 +2016-07-02T04:00:00.000+08:00,5.358,17.868,2.452,1.523,1.208,2.863,3.014 +2016-07-02T05:00:00.000+08:00,5.09,18.009,2.381,1.523,1.208,2.68,2.947 +2016-07-02T06:00:00.000+08:00,4.823,18.009,2.203,1.523,1.173,2.619,2.947 +2016-07-02T07:00:00.000+08:00,4.622,19.768,2.132,1.492,1.137,2.467,2.88 +2016-07-02T08:00:00.000+08:00,5.224,21.104,2.701,1.523,1.315,2.437,3.081 +2016-07-02T09:00:00.000+08:00,5.157,19.697,2.878,1.432,1.35,2.345,3.014 +2016-07-02T10:00:00.000+08:00,5.157,20.049,2.878,1.432,1.492,2.284,3.148 +2016-07-02T11:00:00.000+08:00,5.157,20.752,2.914,1.401,1.492,2.193,3.081 +2016-07-02T12:00:00.000+08:00,4.555,21.385,2.452,1.401,1.492,2.193,3.081 +2016-07-02T13:00:00.000+08:00,5.425,22.23,3.092,1.462,1.706,2.437,3.282 +2016-07-02T14:00:00.000+08:00,5.492,20.26,2.523,1.462,1.492,2.985,3.282 +2016-07-02T15:00:00.000+08:00,5.626,21.104,2.487,1.523,1.492,3.076,3.215 +2016-07-02T16:00:00.000+08:00,5.559,20.612,2.594,1.523,1.67,2.924,3.282 +2016-07-02T17:00:00.000+08:00,5.224,18.361,2.559,1.462,1.564,2.68,3.215 +2016-07-02T18:00:00.000+08:00,9.913,20.963,6.645,1.553,3.305,3.046,4.957 +2016-07-02T19:00:00.000+08:00,11.788,19.416,8.173,1.675,2.523,3.686,5.425 +2016-07-02T20:00:00.000+08:00,9.645,20.823,6.752,1.828,2.132,3.107,4.957 +2016-07-02T21:00:00.000+08:00,10.382,20.19,7.462,1.767,2.559,2.985,5.76 +2016-07-02T22:00:00.000+08:00,8.774,21.315,6.112,1.919,2.025,2.894,4.689 +2016-07-02T23:00:00.000+08:00,10.449,22.019,6.965,1.736,2.452,2.772,5.157 +2016-07-03T00:00:00.000+08:00,9.846,20.682,7.036,1.767,2.665,2.894,4.823 +2016-07-03T01:00:00.000+08:00,9.913,25.466,6.894,1.736,2.416,3.229,4.823 +2016-07-03T02:00:00.000+08:00,10.65,25.888,6.929,1.797,2.452,3.381,4.689 +2016-07-03T03:00:00.000+08:00,10.114,27.857,6.645,1.736,1.812,3.107,4.354 +2016-07-03T04:00:00.000+08:00,9.98,27.295,6.574,1.767,1.954,3.411,4.153 +2016-07-03T05:00:00.000+08:00,9.31,22.23,6.005,1.858,2.132,3.229,4.22 +2016-07-03T06:00:00.000+08:00,9.444,21.948,6.965,1.858,2.168,2.955,4.622 +2016-07-03T07:00:00.000+08:00,9.444,27.295,6.823,1.736,2.559,2.589,4.287 +2016-07-03T08:00:00.000+08:00,10.382,29.335,7.604,1.675,2.31,2.955,5.425 +2016-07-03T09:00:00.000+08:00,9.779,26.028,6.716,1.675,2.843,2.65,5.224 +2016-07-03T10:00:00.000+08:00,10.382,24.34,7.32,1.858,2.203,2.985,4.689 +2016-07-03T11:00:00.000+08:00,9.779,26.45,6.823,1.675,1.99,2.528,4.153 +2016-07-03T12:00:00.000+08:00,10.717,25.958,7.356,1.797,2.807,2.65,4.756 +2016-07-03T13:00:00.000+08:00,10.315,24.059,7.391,1.858,2.452,2.924,4.689 +2016-07-03T14:00:00.000+08:00,12.592,25.325,8.671,1.949,2.203,3.716,5.224 +2016-07-03T15:00:00.000+08:00,11.119,23.637,7.889,1.919,2.843,3.625,4.622 +2016-07-03T16:00:00.000+08:00,10.65,26.38,7.036,1.919,2.025,3.594,4.421 +2016-07-03T17:00:00.000+08:00,10.047,27.365,6.432,1.949,1.67,3.686,4.22 +2016-07-03T18:00:00.000+08:00,11.721,28.068,7.889,1.858,2.559,3.564,5.09 +2016-07-03T19:00:00.000+08:00,12.123,29.475,8.066,1.919,2.487,4.082,5.358 +2016-07-03T20:00:00.000+08:00,9.98,26.802,6.858,1.858,2.559,3.29,5.023 +2016-07-03T21:00:00.000+08:00,9.243,29.968,6.29,1.888,2.63,3.137,4.957 +2016-07-03T22:00:00.000+08:00,10.181,30.39,7.178,1.888,3.02,3.076,5.425 +2016-07-03T23:00:00.000+08:00,9.645,31.164,7.107,1.828,2.665,3.015,5.425 +2016-07-04T00:00:00.000+08:00,9.779,29.757,6.503,2.01,2.985,3.076,4.89 +2016-07-04T01:00:00.000+08:00,11.119,32.289,7.32,1.98,2.914,3.807,5.157 +2016-07-04T02:00:00.000+08:00,11.052,31.938,7.391,1.98,2.523,3.686,4.957 +2016-07-04T03:00:00.000+08:00,10.784,28.561,7.214,1.888,2.487,3.594,4.89 +2016-07-04T04:00:00.000+08:00,11.186,21.526,7.178,1.919,2.345,3.96,4.89 +2016-07-04T05:00:00.000+08:00,10.449,22.23,6.61,2.041,2.31,3.807,4.89 +2016-07-04T06:00:00.000+08:00,9.578,19.416,6.787,1.888,3.127,3.259,5.76 +2016-07-04T07:00:00.000+08:00,9.31,18.572,6.61,1.888,3.056,3.168,5.76 +2016-07-04T08:00:00.000+08:00,9.913,21.667,6.254,1.858,2.63,3.015,5.894 +2016-07-04T09:00:00.000+08:00,8.975,25.536,6.29,1.828,2.665,2.863,4.957 +2016-07-04T10:00:00.000+08:00,8.64,27.857,6.148,1.828,2.594,2.924,4.823 +2016-07-04T11:00:00.000+08:00,9.176,27.928,5.579,1.858,2.381,2.863,5.492 +2016-07-04T12:00:00.000+08:00,9.109,24.621,5.65,1.797,2.523,2.772,4.823 +2016-07-04T13:00:00.000+08:00,9.846,23.848,5.97,1.888,2.949,3.107,5.559 +2016-07-04T14:00:00.000+08:00,11.588,23.074,7.391,1.98,2.807,3.807,5.425 +2016-07-04T15:00:00.000+08:00,11.788,22.511,7.214,2.041,2.985,3.899,6.095 +2016-07-04T16:00:00.000+08:00,10.583,21.667,7.143,2.071,2.914,3.655,5.961 +2016-07-04T17:00:00.000+08:00,11.588,25.395,7.569,2.01,3.056,3.472,6.296 +2016-07-04T18:00:00.000+08:00,11.922,25.184,7.711,1.949,3.056,3.746,6.229 +2016-07-04T19:00:00.000+08:00,12.324,29.546,8.422,1.98,3.234,4.203,5.559 +2016-07-04T20:00:00.000+08:00,10.382,29.475,6.858,1.949,2.63,3.564,5.894 +2016-07-04T21:00:00.000+08:00,10.047,29.264,6.752,1.949,3.02,3.32,5.425 +2016-07-04T22:00:00.000+08:00,10.516,30.953,7.107,1.919,3.376,3.137,6.028 +2016-07-04T23:00:00.000+08:00,10.717,31.726,6.787,2.01,3.02,3.168,6.095 diff --git a/src/.vuepress/public/img/ainode-upgrade-state-apache-en.png b/src/.vuepress/public/img/ainode-upgrade-state-apache-en.png new file mode 100644 index 000000000..7db47e6fb Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-state-apache-en.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-state-apache.png b/src/.vuepress/public/img/ainode-upgrade-state-apache.png new file mode 100644 index 000000000..26691c6d9 Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-state-apache.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-state-timecho-en.png b/src/.vuepress/public/img/ainode-upgrade-state-timecho-en.png new file mode 100644 index 000000000..debbbad6b Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-state-timecho-en.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-state-timecho.png b/src/.vuepress/public/img/ainode-upgrade-state-timecho.png new file mode 100644 index 000000000..dd2c08142 Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-state-timecho.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-1-en.png b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-1-en.png new file mode 100644 index 000000000..f12236830 Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-1-en.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-1.png b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-1.png new file mode 100644 index 000000000..e421059e5 Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-1.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-2-en.png b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-2-en.png new file mode 100644 index 000000000..a6d981b53 Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-2-en.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-2.png b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-2.png new file mode 100644 index 000000000..6b570c114 Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-2.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-3-en.png b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-3-en.png new file mode 100644 index 000000000..f3c117c8b Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-3-en.png differ diff --git a/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-3.png b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-3.png new file mode 100644 index 000000000..e762d0f54 Binary files /dev/null and b/src/.vuepress/public/img/ainode-upgrade-table-forecast-timecho-3.png differ diff --git a/src/.vuepress/public/img/timeseries-large-model-chronos2.png b/src/.vuepress/public/img/timeseries-large-model-chronos2.png new file mode 100644 index 000000000..ca33f1f96 Binary files /dev/null and b/src/.vuepress/public/img/timeseries-large-model-chronos2.png differ diff --git a/src/.vuepress/sidebar/V2.0.x/en-Table.ts b/src/.vuepress/sidebar/V2.0.x/en-Table.ts index 2dd0d639e..2d0a34f8a 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Table.ts @@ -132,8 +132,10 @@ export const enSidebar = { collapsible: true, prefix: 'AI-capability/', children: [ - { text: 'AINode', link: 'AINode_apache' }, - { text: 'TimeSeries Large Model', link: 'TimeSeries-Large-Model' }, + { text: 'AINode(V2.0.5/6)', link: 'AINode_apache' }, + { text: 'AINode(V2.0.8)', link: 'AINode_Upgrade_apache' }, + { text: 'TimeSeries Large Model(V2.0.5/6)', link: 'TimeSeries-Large-Model' }, + { text: 'TimeSeries Large Model(V2.0.8)', link: 'TimeSeries-Large-Model_Upgrade_apache' }, ], }, { diff --git a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts index 71d52acc1..5a475b99c 100644 --- a/src/.vuepress/sidebar/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar/V2.0.x/en-Tree.ts @@ -148,8 +148,10 @@ export const enSidebar = { collapsible: true, prefix: 'AI-capability/', children: [ - { text: 'AINode', link: 'AINode_apache' }, - { text: 'TimeSeries Large Model', link: 'TimeSeries-Large-Model' }, + { text: 'AINode(V2.0.5/6)', link: 'AINode_apache' }, + { text: 'AINode(V2.0.8)', link: 'AINode_Upgrade_apache' }, + { text: 'TimeSeries Large Model(V2.0.5/6)', link: 'TimeSeries-Large-Model' }, + { text: 'TimeSeries Large Model(V2.0.8)', link: 'TimeSeries-Large-Model_Upgrade_apache' }, ], }, { diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts index 9b0fceeb4..f51c5590d 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Table.ts @@ -130,8 +130,10 @@ export const zhSidebar = { collapsible: true, prefix: 'AI-capability/', children: [ - { text: 'AINode', link: 'AINode_apache' }, - { text: '时序大模型', link: 'TimeSeries-Large-Model' }, + { text: 'AINode(V2.0.5/6)', link: 'AINode_apache' }, + { text: 'AINode(V2.0.8)', link: 'AINode_Upgrade_apache' }, + { text: '时序大模型(V2.0.5/6)', link: 'TimeSeries-Large-Model' }, + { text: '时序大模型(V2.0.8)', link: 'TimeSeries-Large-Model_Upgrade_apache' }, ], }, { diff --git a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts index 44bbfb781..8ef0d38a1 100644 --- a/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar/V2.0.x/zh-Tree.ts @@ -139,8 +139,10 @@ export const zhSidebar = { collapsible: true, prefix: 'AI-capability/', children: [ - { text: 'AINode', link: 'AINode_apache' }, - { text: '时序大模型', link: 'TimeSeries-Large-Model' }, + { text: 'AINode(V2.0.5/6)', link: 'AINode_apache' }, + { text: 'AINode(V2.0.8)', link: 'AINode_Upgrade_apache' }, + { text: '时序大模型(V2.0.5/6)', link: 'TimeSeries-Large-Model' }, + { text: '时序大模型(V2.0.8)', link: 'TimeSeries-Large-Model_Upgrade_apache' }, ], }, { diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts index 4074c09c9..5563b72b7 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Table.ts @@ -159,8 +159,10 @@ export const enSidebar = { collapsible: true, prefix: 'AI-capability/', children: [ - { text: 'AINode', link: 'AINode_timecho' }, - { text: 'TimeSeries Large Model', link: 'TimeSeries-Large-Model' }, + { text: 'AINode(V2.0.5/6)', link: 'AINode_timecho' }, + { text: 'AINode(V2.0.8)', link: 'AINode_Upgrade_timecho' }, + { text: 'TimeSeries Large Model(V2.0.5/6)', link: 'TimeSeries-Large-Model' }, + { text: 'TimeSeries Large Model(V2.0.8)', link: 'TimeSeries-Large-Model_Upgrade_timecho' }, ], }, { diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts index c7468c944..714e9805e 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/en-Tree.ts @@ -172,8 +172,10 @@ export const enSidebar = { collapsible: true, prefix: 'AI-capability/', children: [ - { text: 'AINode', link: 'AINode_timecho' }, - { text: 'TimeSeries Large Model', link: 'TimeSeries-Large-Model' }, + { text: 'AINode(V2.0.5/6)', link: 'AINode_timecho' }, + { text: 'AINode(V2.0.8)', link: 'AINode_Upgrade_timecho' }, + { text: 'TimeSeries Large Model(V2.0.5/6)', link: 'TimeSeries-Large-Model' }, + { text: 'TimeSeries Large Model(V2.0.8)', link: 'TimeSeries-Large-Model_Upgrade_timecho' }, ], }, { diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts index df7ad2f69..e49305509 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Table.ts @@ -150,8 +150,10 @@ export const zhSidebar = { collapsible: true, prefix: 'AI-capability/', children: [ - { text: 'AINode', link: 'AINode_timecho' }, - { text: '时序大模型', link: 'TimeSeries-Large-Model' }, + { text: 'AINode(V2.0.5/6)', link: 'AINode_timecho' }, + { text: 'AINode(V2.0.8)', link: 'AINode_Upgrade_timecho' }, + { text: '时序大模型(V2.0.5/6)', link: 'TimeSeries-Large-Model' }, + { text: '时序大模型(V2.0.8)', link: 'TimeSeries-Large-Model_Upgrade_timecho' }, ], }, { diff --git a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts index ba3900d07..128347ae2 100644 --- a/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts +++ b/src/.vuepress/sidebar_timecho/V2.0.x/zh-Tree.ts @@ -154,8 +154,10 @@ export const zhSidebar = { collapsible: true, prefix: 'AI-capability/', children: [ - { text: 'AINode', link: 'AINode_timecho' }, - { text: '时序大模型', link: 'TimeSeries-Large-Model' }, + { text: 'AINode(V2.0.5/6)', link: 'AINode_timecho' }, + { text: 'AINode(V2.0.8)', link: 'AINode_Upgrade_timecho' }, + { text: '时序大模型(V2.0.5/6)', link: 'TimeSeries-Large-Model' }, + { text: '时序大模型(V2.0.8)', link: 'TimeSeries-Large-Model_Upgrade_timecho' }, ], }, { diff --git a/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade.md b/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade.md new file mode 100644 index 000000000..6f44068b6 --- /dev/null +++ b/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: AINode_Upgrade_apache.html +--- + \ No newline at end of file diff --git a/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade_apache.md b/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade_apache.md new file mode 100644 index 000000000..548c22f69 --- /dev/null +++ b/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade_apache.md @@ -0,0 +1,540 @@ + + +# AINode + +AINode is a native IoTDB node designed for registering, managing, and invoking time series-related models. It integrates industry-leading self-developed time series large models—such as the Timer series developed by Tsinghua University—and supports millisecond-level real-time inference on time series data via standard SQL statements. It enables key application scenarios including time series trend forecasting, missing value imputation, and anomaly detection. + +System architecture is illustrated below: + +![](/img/AINode-0-en.png) + +Responsibilities of the three node types are as follows: + +* **ConfigNode**: Manages distributed nodes and handles load balancing. +* **DataNode**: Receives and parses user SQL requests; stores time series data; performs data preprocessing computations. +* **AINode**: Manages and utilizes time series models. + +## 1. Advantages and Features + +Compared to building a standalone machine learning service, AINode offers the following benefits: + +* **Ease of Use**: No Python or Java programming required. Complete model management and inference workflows are achievable via SQL statements. For example, use `CREATE MODEL` to register a model and ` SELECT * FROM FORECAST (...) ` for inference—simple and efficient. +* **Eliminates Data Migration**: IoTDB-native machine learning enables direct inference on data stored within IoTDB, avoiding data transfer to external ML platforms. This accelerates processing, enhances security, and reduces costs. + +![](/img/h1.png) + +* **Built-in Advanced Algorithms**: Integrates state-of-the-art machine learning algorithms covering typical time series analysis tasks, empowering IoTDB with native analytical capabilities: + * **Time Series Forecasting**: Learns patterns from historical sequences to predict future values based on past observations. + * **Anomaly Detection for Time Series**: Detects and identifies outliers in time series data to uncover abnormal behaviors. + +## 2. Core Concepts + +* **Model**: A machine learning model that takes time series data as input and outputs analytical results or decisions. Models are the fundamental management units in AINode, supporting creation (registration), deletion, querying, and inference. +* **Create**: Loads externally designed or trained model files/algorithms into AINode for unified management and usage. +* **Inference**: Applies a registered model to perform time series analysis tasks on specified data. +* **Built-in Capability**: AINode includes native algorithms/models for common time series scenarios (e.g., forecasting and anomaly detection). + +![](/img/AINode-en.png) + +## 3. Installation and Deployment + +Refer to the documentation [AINode Deployment](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md) for deployment instructions. + +## 4. Usage Guide + +AINode supports two core functionalities: model inference and model management (registration, viewing, deletion, loading, unloading). Details follow. + +### 4.1 Model Inference + +AINode supports forecasting inference on single target variables. Syntax, parameters, and examples are provided below. + +1. **SQL Syntax** + +```SQL +SELECT * FROM FORECAST( + MODEL_ID, + TARGETS, -- SQL to retrieve target variables + OUTPUT_START_TIME, + OUTPUT_LENGTH, + OUTPUT_INTERVAL, + TIMECOL, + PRESERVE_INPUT, + [MODEL_OPTIONS]? +) +``` + +* Built-in models require no registration. Specify `model_id` in the `forecast` function to invoke inference. +* Parameter Description + +| Parameter Name | Type | Attribute | Description | Required | Notes | +|---------------------|-----------|------------------------------------------------------|-----------------------------------------------------------------------------|----------|-----------------------------------------------------------------------| +| model_id | Scalar | String | Unique identifier of the forecasting model | Yes | | +| targets | Table | SET SEMANTIC | Input data for target variables. IoTDB automatically sorts data by time before sending to AINode | Yes | Invalid SQL in this clause triggers query errors | +| output_start_time | Scalar | Timestamp. Default: last timestamp of targets + output_interval | Start timestamp of forecast output (issue time) | No | Must be later than the maximum timestamp in targets | +| output_length | Scalar | INT32. Default: 96 | Output window size | No | Must be > 0 | +| output_interval | Scalar | Interval. Default: (last_ts - first_ts) / (n - 1) | Time interval between forecast points (units: ns, us, ms, s, m, h, d, w) | No | Must be > 0 | +| timecol | Scalar | String. Default: "time" | Name of the time column | No | Must exist in `targets` and be of TIMESTAMP type | +| preserve_input | Scalar | Boolean. Default: false | Whether to retain all original input rows in output | No | | +| model_options | Scalar | String. Default: empty string | Model-specific key-value pairs (e.g., normalization settings); separated by ';' | No | | + +Notes: +* **Default Behavior**: Forecasts all columns in `targets`. Currently supports INT32, INT64, FLOAT, DOUBLE types only. +* **Input Requirements**: + * Must include a time column. + * Row count: Errors if below minimum; truncates to latest rows if exceeding maximum. +* **Output**: + * Contains all target variable columns with original data types. + * If `preserve_input=true`, adds an `is_input` column to mark original rows. +* **Timestamp Generation**: + * Uses `OUTPUT_START_TIME` (optional) as forecast start point. + * Uses `OUTPUT_INTERVAL` (optional, defaults to input sampling interval). Timestamp of row N: `OUTPUT_START_TIME + (N - 1) * OUTPUT_INTERVAL`. + +2. **Usage Example** + +Create database `etth` and table `eg`: + +```SQL +CREATE DATABASE etth; +CREATE TABLE eg (hufl FLOAT FIELD, hull FLOAT FIELD, mufl FLOAT FIELD, mull FLOAT FIELD, lufl FLOAT FIELD, lull FLOAT FIELD, ot FLOAT FIELD) +``` + +Prepare source data [ETTh1-tab](/img/ETTh1-tab.csv) + +Forecast 96 future values of sensor `ot` using its latest 96 historical records: + +```SQL +IoTDB:etth> SELECT Time, HUFL, HULL, MUFL, MULL, LUFL, LULL, OT FROM eg LIMIT 96 ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +| Time| HUFL| HULL| MUFL| MULL| LUFL| LULL| OT| ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +|2016-07-01T00:00:00.000+08:00| 5.827|2.009|1.599|0.462|4.203| 1.34|30.531| +|2016-07-01T01:00:00.000+08:00| 5.693|2.076|1.492|0.426|4.142|1.371|27.787| +|2016-07-01T02:00:00.000+08:00| 5.157|1.741|1.279|0.355|3.777|1.218|27.787| +|2016-07-01T03:00:00.000+08:00| 5.09|1.942|1.279|0.391|3.807|1.279|25.044| +...... +Total line number = 96 +It costs 0.119s + +IoTDB:etth> SELECT * FROM forecast( + model_id => 'sundial', + targets => (SELECT Time, ot FROM etth.eg WHERE time >= 2016-08-07T18:00:00.000+08:00 LIMIT 1440) ORDER BY time, + output_length => 96 +) ++-----------------------------+---------+ +| time| ot| ++-----------------------------+---------+ +|2016-10-06T18:00:00.000+08:00|20.781654| +|2016-10-06T19:00:00.000+08:00|20.252121| +|2016-10-06T20:00:00.000+08:00|19.960138| +|2016-10-06T21:00:00.000+08:00|19.662334| +...... +Total line number = 96 +It costs 1.615s +``` + +### 4.2 Registering Custom Models + +**Transformers models meeting the following criteria can be registered to AINode:** + +1. AINode uses Transformers v4.56.2; avoid inheriting interfaces from older versions (<4.50). +2. The model must inherit an AINode inference pipeline class (currently supports forecasting pipeline): + ```python + # iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic_pipeline.py + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """Preprocess input data before inference, including shape validation and numerical conversion.""" + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """Postprocess model outputs after inference.""" + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + Preprocess and validate input data before model inference. + + Args: + inputs (list[dict]): + Input data as list of dicts containing: + - 'targets': Tensor of shape (input_length,) or (target_count, input_length). + - 'past_covariates': Optional dict of tensors, each of shape (input_length,). + - 'future_covariates': Optional dict of tensors, each of shape (input_length,). + infer_kwargs (dict, optional): Additional inference parameters, e.g.: + - `output_length` (int): Required if 'future_covariates' provided for validation. + + Raises: + ValueError: For invalid input formats (missing keys, invalid tensor shapes). + + Returns: + Preprocessed and validated input ready for model inference. + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + Perform forecasting on given inputs. + + Parameters: + inputs: Input data for forecasting (type/structure model-specific). + **infer_kwargs: Additional parameters, e.g.: + - `output_length` (int): Number of future time points to generate. + + Returns: + Forecast output (format model-specific). + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + Postprocess model outputs, validate shapes, and ensure expected dimensions. + + Args: + outputs: List of 2D tensors, each of shape `[target_count, output_length]`. + + Raises: + InferenceModelInternalException: For invalid output tensor shapes. + ValueError: For incorrect output format. + + Returns: + List of postprocessed 2D tensors. + """ + pass + ``` +3. Modify `config.json` to include: + ```json + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", + "AutoModelForCausalLM": "model.Chronos2Model" + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", + "model_type": "custom_t5" + } + ``` + * Must specify model Config and model classes via `auto_map`. + * Must implement and specify the inference pipeline class. + * `model_type` serves as a unique identifier. Must not conflict with existing model types (for both `builtin` and `user_defined` models). +4. Ensure the model directory contains: + * `config.json` (model configuration) + * `model.safetensors` (model weights) + * Other `.py` files (model code) + * *Note: Filenames for config and weights are fixed and non-customizable.* + +**SQL Syntax for Registration:** +```SQL +CREATE MODEL USING URI +``` + +**Parameter Details:** +* **model_id**: Unique identifier for the custom model (case-sensitive): + * Allowed characters: `[0-9a-zA-Z_]` (alphanumeric and underscore; cannot start with digit/underscore) + * Length: 2–64 characters +* **uri**: Local URI path containing model code and weights. + +**Registration Example:** +Upload a custom Transformers model from local path. AINode copies the folder to the `user_defined` directory. +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` +Registration proceeds asynchronously. Check status via `SHOW MODELS` (see Section 4.3). After successful registration, invoke inference via standard queries. + +### 4.3 Viewing Models + +Registered models can be queried using: +```SQL +SHOW MODELS +``` +Filter by specific model: +```SQL +SHOW MODELS -- Display specific model only +``` + +Result columns: + +| **ModelId** | **ModelType** | **Category** | **State** | +|-------------|---------------|--------------|-----------| +| Model ID | Model Type | Category | State | + +State transition diagram: + +![](/img/ainode-upgrade-state-apache-en.png) + +State Flow Explanation: +1. After AINode startup, `SHOW MODELS` displays only **system built-in (BUILTIN)** models. +2. User-uploaded models are marked as **user-defined (USER_DEFINED)**. AINode attempts to parse `ModelType` from config; displays empty if parsing fails. +3. Time series large model weights (built-in) are not bundled with AINode. Download occurs on startup: + * `ACTIVATING` during download → `ACTIVE` on success → `INACTIVE` on failure. + +**Viewing Example:** +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +**Built-in Traditional Time Series Models:** + +| Model Name | Core Concept | Applicable Scenarios | Key Features | +|-----------------------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------------------------| +| **ARIMA** (Autoregressive Integrated Moving Average) | Combines AR, differencing (I), and MA for stationary or differenced series | Univariate forecasting (stock prices, sales, economics) | 1. For linear trends with weak seasonality2. Requires (p,d,q) tuning3. Sensitive to missing values | +| **Holt-Winters** (Triple Exponential Smoothing) | Exponential smoothing with level, trend, and seasonal components | Data with clear trend & seasonality (monthly sales, power demand) | 1. Handles additive/multiplicative seasonality2. Weights recent data higher3. Simple implementation | +| **Exponential Smoothing** | Weighted average of history with exponentially decaying weights | Trending but non-seasonal data (short-term demand) | 1. Few parameters, simple computation2. Suitable for stable/slow-changing series3. Extensible to double/triple smoothing | +| **Naive Forecaster** | Uses last observation as next prediction (simplest baseline) | Benchmarking or data with no clear pattern | 1. No training needed2. Sensitive to sudden changes3. Seasonal variant uses prior season value | +| **STL Forecaster** | Decomposes series into trend, seasonal, residual; forecasts components | Complex seasonality/trends (climate, traffic) | 1. Handles non-fixed seasonality2. Robust to outliers3. Components can use other models | +| **Gaussian HMM** | Hidden states generate observations; each state follows Gaussian distribution | State sequence prediction/classification (speech, finance) | 1. Models temporal state transitions2. Observations independent per state3. Requires state count | +| **GMM HMM** | Extends Gaussian HMM; each state uses Gaussian Mixture Model | Multi-modal observation scenarios (motion recognition, biosignals) | 1. More flexible than single Gaussian2. Higher complexity3. Requires GMM component count | +| **STRAY** (Search for Outliers using Random Projection and Adaptive Thresholding) | Uses SVD to detect anomalies in high-dimensional time series | High-dimensional anomaly detection (sensor networks, IT monitoring) | 1. No distribution assumption2. Handles high dimensions3. Sensitive to global anomalies | + +**Built-in Time Series Large Models:** + +| Model Name | Core Concept | Applicable Scenarios | Key Features | +|-----------------|------------------------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------------------------| +| **Timer-XL** | Long-context time series large model pretrained on massive industrial data | Complex industrial forecasting requiring ultra-long history (energy, aerospace, transport) | 1. Supports input of tens of thousands of time points2. Covers non-stationary, multivariate, and covariate scenarios3. Pretrained on trillion-scale high-quality industrial IoT data | +| **Timer-Sundial** | Generative foundation model with "Transformer + TimeFlow" architecture | Zero-shot forecasting requiring uncertainty quantification (finance, supply chain, renewable energy) | 1. Strong zero-shot generalization; supports point & probabilistic forecasting2. Flexible analysis of any prediction distribution statistic3. Innovative flow-matching architecture for efficient non-deterministic sample generation | +| **Chronos-2** | Universal time series foundation model based on discrete tokenization | Rapid zero-shot univariate forecasting; scenarios enhanced by covariates (promotions, weather) | 1. Powerful zero-shot probabilistic forecasting2. Unified multi-variable & covariate modeling (strict input requirements):  a. Future covariate names ⊆ historical covariate names  b. Each historical covariate length = target length  c. Each future covariate length = prediction length3. Efficient encoder-only structure balancing performance and speed | + +### 4.4 Deleting Models + +Registered models can be deleted via SQL. AINode removes the corresponding folder under `user_defined`. Syntax: +```SQL +DROP MODEL +``` +* Specify a successfully registered `model_id`. +* Deletion is asynchronous; model enters `DROPPING` state (unavailable for inference during this phase). +* **Built-in models cannot be deleted.** + +### 4.5 Loading/Unloading Models + +AINode supports two loading strategies: +* **On-Demand Loading**: Load model temporarily during inference, then release resources. Suitable for testing or low-load scenarios. +* **Persistent Loading**: Keep model instances resident in CPU memory or GPU VRAM to support high-concurrency inference. Users specify load/unload targets via SQL; AINode auto-manages instance counts. Current loaded status is queryable. + +Details below: + +1. **Configuration Parameters** + Edit these settings to control persistent loading behavior: + ```properties + # Ratio of total device memory/VRAM usable by AINode for inference + # Datatype: Float + ain_inference_memory_usage_ratio=0.4 + + # Memory overhead ratio per loaded model instance (model_size * this_value) + # Datatype: Float + ain_inference_extra_memory_ratio=1.2 + ``` + +2. **List Available Devices** + ```SQL + SHOW AI_DEVICES + ``` + Example: + ```SQL + IoTDB> SHOW AI_DEVICES + +-------------+ + | DeviceId| + +-------------+ + | cpu| + | 0| + | 1| + +-------------+ + ``` + +3. **Load Model** + Manually load model; system auto-balances instance count based on resources: + ```SQL + LOAD MODEL TO DEVICES (, )* + ``` + Parameters: + * `existing_model_id`: Model ID (current version supports `timer_xl` and `sundial` only) + * `device_id`: + * `cpu`: Load into server memory + * `gpu_id`: Load into specified GPU(s), e.g., `'0,1'` for GPUs 0 and 1 + Example: + ```SQL + LOAD MODEL sundial TO DEVICES 'cpu,0,1' + ``` + +4. **Unload Model** + Unload all instances of a model; system reallocates freed resources: + ```SQL + UNLOAD MODEL FROM DEVICES (, )* + ``` + Parameters same as `LOAD MODEL`. + Example: + ```SQL + UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' + ``` + +5. **View Loaded Models** + ```SQL + SHOW LOADED MODELS + SHOW LOADED MODELS (, )* -- Filter by device + ``` + Example (sundial loaded on CPU, GPU 0, GPU 1): + ```SQL + IoTDB> SHOW LOADED MODELS + +-------------+--------------+------------------+ + | DeviceId| ModelId| Count(instances)| + +-------------+--------------+------------------+ + | cpu| sundial| 4| + | 0| sundial| 6| + | 1| sundial| 6| + +-------------+--------------+------------------+ + ``` + * `DeviceId`: Device identifier + * `ModelId`: Loaded model ID + * `Count(instances)`: Number of model instances per device (auto-assigned by system) + +### 4.6 Time Series Large Models Overview + +AINode supports multiple time series large models. For detailed introduction and deployment guidance, refer to [Time Series Large Models](../AI-capability/TimeSeries-Large-Model_Upgrade_apache.md). + +## 5. Permission Management + +AINode leverages IoTDB's native authentication system. Users require `USE_MODEL` permission to manage models. For inference, users must have access permissions to source time series referenced in the input SQL. + +| **Permission Name** | **Scope** | **Admin User (default ROOT)** | **Regular User** | +|---------------------|----------------------------------------|-------------------------------|------------------| +| USE_MODEL | CREATE MODEL / SHOW MODELS / DROP MODEL | √ | √ | +| READ_SCHEMA & READ_DATA | FORECAST | √ | √ | + +## 6. Contributing Open Source Time Series Large Models to IoTDB-AINode + +To add a new built-in custom model to AINode (using Chronos2 as example): + +* **Initiate Discussion** + Email [dev@iotdb.apache.org](mailto:dev@iotdb.apache.org) or open an issue in the main repository. + +* **Submit Pull Request to Main Branch** + 1. Verify the model's open-source license and declare it appropriately in the IoTDB repository. + 2. Create a new package for the model under `iotdb-core/ainode/iotdb/ainode/core/model/`: + * Include model configuration class + * Include model class for inference execution + * Include class inheriting AINode's inference pipeline + ```bash + root@rootMacBook-Pro model % eza --tree --level=2 . + . + ├── chronos2 + │ ├── __init__.py + │ ├── base.py + │ ├── chronos_bolt.py + │ ├── config.py + │ ├── dataset.py + │ ├── layers.py + │ ├── model.py + │ ├── pipeline_chronos2.py # Inherits AINode inference pipeline + │ └── utils.py + ├── sktime + ├── sundial + └── timer_xl + ``` + 3. Add model metadata in `iotdb-core/ainode/iotdb/ainode/core/model/model_info.py`: + ```python + BUILTIN_HF_TRANSFORMERS_MODEL_MAP = { + "chronos2": ModelInfo( + model_id="chronos2", + category=ModelCategory.BUILTIN, + state=ModelStates.INACTIVE, + model_type="t5", + pipeline_cls="pipeline_chronos2.Chronos2Pipeline", + repo_id="amazon/chronos-2", # [Optional] HuggingFace weights repo + auto_map={ + "AutoConfig": "config.Chronos2CoreConfig", + "AutoModelForCausalLM": "model.Chronos2Model", + }, + ), + } + ``` + 4. Add model entry in `integration-test/src/test/java/org/apache/iotdb/ainode/utils/AINodeTestUtils.java`: + ```java + public static final Map BUILTIN_LTSM_MAP = + Stream.of( + new AbstractMap.SimpleEntry<>( + "sundial", new FakeModelInfo("sundial", "sundial", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "timer_xl", new FakeModelInfo("timer_xl", "timer", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "chronos2", new FakeModelInfo("chronos2", "t5", "builtin", "active"))) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + ``` + 5. Submit PR; ensure CI tests pass before merging. + +* **Packaging and Deployment** + 1. Build AINode to generate installation package: + ```bash + # Build IoTDB and AINode together + mvn clean package -pl distribution -P with-ainode -am -DskipTests + # Build AINode only + mvn clean package -pl iotdb-core/ainode -P with-ainode -am -DskipTests + ``` + 2. Ensure model weights are accessible at runtime: + * If weights are fetchable from HuggingFace, confirm `repo_id` is set. + * Otherwise, manually place weights in `data/ainode/models/builtin/` before/during startup. + ```bash + root@rootMacBook-Pro models % eza --tree --level=3 . + . + ├── __init__.py + ├── builtin + │ ├── __init__.py + │ ├── chronos2 + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ ├── sundial + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ └── timer_xl + │ ├── __init__.py + │ ├── config.json + │ └── model.safetensors + └── user_defined + ``` + +* **Complete Example** + Reference implementation: https://github.com/apache/iotdb/pull/16903 \ No newline at end of file diff --git a/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade_timecho.md b/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade_timecho.md new file mode 100644 index 000000000..5467a5af3 --- /dev/null +++ b/src/UserGuide/Master/Table/AI-capability/AINode_Upgrade_timecho.md @@ -0,0 +1,714 @@ + + +# AINode + +AINode is a native IoTDB node that supports the registration, management, and invocation of time series related models. It includes industry-leading self-developed time series large models, such as the Timer series models developed by Tsinghua University. Models can be invoked using standard SQL statements, enabling millisecond-level real-time inference on time series data, and supporting application scenarios such as time series trend prediction, missing value filling, and anomaly value detection. + +The system architecture is shown in the following figure: + +![](/img/AINode-0-en.png) + +The responsibilities of the three nodes are as follows: + +* **ConfigNode**: Responsible for distributed node management and load balancing. +* **DataNode**: Responsible for receiving and parsing user SQL requests; responsible for storing time series data; responsible for data preprocessing calculations. +* **AINode**: Responsible for managing and using time series models. + +## 1. Advantages and Features + +Compared to building a machine learning service separately, it has the following advantages: + +* **Simple and Easy to Use**: No need to use Python or Java programming, you can complete the entire process of machine learning model management and inference using SQL statements. For example, creating a model can be done using the CREATE MODEL statement, and using a model for inference can be done using the `SELECT * FROM FORECAST (...)` statement, making it more simple and convenient. +* **Avoid Data Migration**: Using IoTDB-native machine learning can directly apply data stored in IoTDB to machine learning model inference without moving data to a separate machine learning service platform, thus accelerating data processing, improving security, and reducing costs. + +![](/img/h1.png) + +* **Built-in Advanced Algorithms**: Supports industry-leading machine learning analysis algorithms, covering typical time series analysis tasks, and empowering time series databases with native data analysis capabilities. For example: + * **Time Series Forecasting**: Learning change patterns from past time series data; outputting the most likely predictions for future sequences based on given past observations. + * **Time Series Anomaly Detection**: Detecting and identifying abnormal values in given time series data to help discover abnormal behavior in time series. + +## 2. Basic Concepts + +* **Model (Model)**: A machine learning model that takes time series data as input and outputs the results or decisions of the analysis task. The model is the basic management unit of AINode, supporting the creation (registration), deletion, query, modification (fine-tuning), and use (inference) of models. +* **Create (Create)**: Load the external designed or trained model file or algorithm into AINode, managed and used uniformly by IoTDB. +* **Inference (Inference)**: Use the created model to complete the time series analysis task on the specified time series data. +* **Built-in (Built-in)**: AINode comes with common time series analysis scenario (e.g., prediction and anomaly detection) machine learning algorithms or self-developed models. + +![](/img/AINode-en.png) + +## 3. Installation and Deployment + +AINode deployment can be referred to the documentation [AINode Deployment](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md). + +## 4. Usage Guide + +TimechoDB-AINode supports three major functions: model inference, model fine-tuning, and model management (registration, viewing, deletion, loading, unloading, etc.). The following sections will provide detailed explanations. + +### 4.1 Model Inference + +TimechoDB-AINode provides the following time series prediction capabilities: + +* **Univariate Prediction**: Supports prediction of a single target variable. +* **Covariate Prediction**: Can simultaneously predict multiple target variables and supports introducing covariates in prediction to improve accuracy. + +The following sections will detail the syntax definition, parameter descriptions, and usage examples of the prediction inference function. + +1. **SQL Syntax** + +```SQL +SELECT * FROM FORECAST( + MODEL_ID, + TARGETS, -- SQL to get target variables + [HISTORY_COVS, -- String, SQL to get historical covariates + FUTURE_COVS, -- String, SQL to get future covariates + OUTPUT_START_TIME, + OUTPUT_LENGTH, + OUTPUT_INTERVAL, + TIMECOL, + PRESERVE_INPUT, + MODEL_OPTIONS]? +) +``` + +* Built-in model inference does not require a registration process. By using the forecast function and specifying model_id, you can use the inference function of the model. +* Parameter description + +| Parameter Name | Parameter Type | Parameter Attributes | Description | Required | Notes | +|----------------|----------------|----------------------|-------------|----------|-------| +| model_id | Scalar parameter | String type | Unique identifier of the prediction model | Yes | | +| targets | Table parameter | SET SEMANTIC | Input data for the target variables to be predicted. IoTDB will automatically sort the data in ascending order of time before passing it to AINode. | Yes | Use SQL to describe the input data with target variables. If the input SQL is invalid, corresponding query errors will be reported. | +| history_covs | Scalar parameter | String type (valid table model query SQL), default: none | Specifies historical data of covariates for this prediction task, which are used to assist in predicting target variables. AINode will not output prediction results for historical covariates. Before passing data to the model, AINode will automatically sort the data in ascending order of time. | No | 1. Query results can only contain FIELD columns; 2. Other: Different models may have specific requirements, and errors will be thrown if not met. | +| future_covs | Scalar parameter | String type (valid table model query SQL), default: none | Specifies future data of some covariates for this prediction task, which are used to assist in predicting target variables. Before passing data to the model, AINode will automatically sort the data in ascending order of time. | No | 1. Can only be specified when history_covs is set; 2. The covariate names involved must be a subset of history_covs; 3. Query results can only contain FIELD columns; 4. Other: Different models may have specific requirements, and errors will be thrown if not met. | +| output_start_time | Scalar parameter | Timestamp type. Default value: last timestamp of target variable + output_interval | Starting timestamp of output prediction points [i.e., forecast start time] | No | Must be greater than the maximum timestamp of target variable timestamps | +| output_length | Scalar parameter | INT32 type. Default value: 96 | Output window size | No | Must be greater than 0 | +| output_interval | Scalar parameter | Time interval type. Default value: (last timestamp - first timestamp of input data) / n - 1 | Time interval between output prediction points. Supported units: ns, us, ms, s, m, h, d, w | No | Must be greater than 0 | +| timecol | Scalar parameter | String type. Default value: time | Name of time column | No | Must be a TIMESTAMP column existing in targets | +| preserve_input | Scalar parameter | Boolean type. Default value: false | Whether to retain all original rows of target variable input in the output result set | No | | +| model_options | Scalar parameter | String type. Default value: empty string | Key-value pairs related to the model, such as whether to normalize the input. Different key-value pairs are separated by ';'. | No | | + +Notes: +* **Default behavior**: Predict all columns of targets. Currently, only supports INT32, INT64, FLOAT, DOUBLE types. +* **Input data requirements**: + * Must contain a time column. + * Row count requirements: If insufficient, an error will be reported; if exceeding the maximum, the last data will be automatically truncated. + * Column count requirements: Univariate models only support single columns, multi-column will report errors; covariate models usually have no restrictions unless the model itself has clear constraints. +* **Output results**: + * Includes all target variable columns, with data types consistent with the original table. + * If `preserve_input=true` is specified, an additional `is_input` column will be added to identify original data rows. +* **Timestamp generation**: + * Uses `OUTPUT_START_TIME` (optional) as the starting time point for prediction and divides historical and future data. + * Uses `OUTPUT_INTERVAL` (optional, default is the sampling interval of input data) as the output time interval. The timestamp of the Nth row is calculated as: `OUTPUT_START_TIME + (N - 1) * OUTPUT_INTERVAL`. + +2. **Usage Examples** + +**Example 1: Univariate Prediction** + +Create database etth and table eg in advance + +```SQL +create database etth; +create table eg (hufl FLOAT FIELD, hull FLOAT FIELD, mufl FLOAT FIELD, mull FLOAT FIELD, lufl FLOAT FIELD, lull FLOAT FIELD, ot FLOAT FIELD) +``` + +Prepare original data [ETTh1-tab](/img/ETTh1-tab.csv) + +Use the first 96 rows of data from column ot in table eg to predict its future 96 rows of data. + +```SQL +IoTDB:etth> select Time, HUFL,HULL,MUFL,MULL,LUFL,LULL,OT from eg LIMIT 96 ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +| Time| HUFL| HULL| MUFL| MULL| LUFL| LULL| OT| ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +|2016-07-01T00:00:00.000+08:00| 5.827|2.009|1.599|0.462|4.203| 1.34|30.531| +|2016-07-01T01:00:00.000+08:00| 5.693|2.076|1.492|0.426|4.142|1.371|27.787| +|2016-07-01T02:00:00.000+08:00| 5.157|1.741|1.279|0.355|3.777|1.218|27.787| +|2016-07-01T03:00:00.000+08:00| 5.09|1.942|1.279|0.391|3.807|1.279|25.044| +...... +Total line number = 96 +It costs 0.119s + +IoTDB:etth> select * from forecast( + model_id => 'sundial', + targets => (select Time, ot from etth.eg where time >= 2016-08-07T18:00:00.000+08:00 limit 1440) order BY time, + output_length => 96 +) ++-----------------------------+---------+ +| time| ot| ++-----------------------------+---------+ +|2016-10-06T18:00:00.000+08:00|20.781654| +|2016-10-06T19:00:00.000+08:00|20.252121| +|2016-10-06T20:00:00.000+08:00|19.960138| +|2016-10-06T21:00:00.000+08:00|19.662334| +...... +Total line number = 96 +It costs 1.615s +``` + +**Example 2: Covariate Prediction** + +Create table tab_real (to store original real data) in advance + +```SQL +create table tab_real (target1 DOUBLE FIELD, target2 DOUBLE FIELD, cov1 DOUBLE FIELD, cov2 DOUBLE FIELD, cov3 DOUBLE FIELD); +``` + +Prepare original data + +```SQL +IoTDB:etth> SELECT * FROM tab_real ++-----------------------------+-------+-------+----+----+----+ +| time|target1|target2|cov1|cov2|cov3| ++-----------------------------+-------+-------+----+----+----+ +|1970-01-01T08:00:00.001+08:00| 1.0| 1.0| 1.0| 1.0| 1.0| +|1970-01-01T08:00:00.002+08:00| 2.0| 2.0| 2.0| 2.0| 2.0| +|1970-01-01T08:00:00.003+08:00| 3.0| 3.0| 3.0| 3.0| 3.0| +|1970-01-01T08:00:00.004+08:00| 4.0| 4.0| 4.0| 4.0| 4.0| +|1970-01-01T08:00:00.005+08:00| 5.0| 5.0| 5.0| 5.0| 5.0| +|1970-01-01T08:00:00.006+08:00| 6.0| 6.0| 6.0| 6.0| 6.0| +|1970-01-01T08:00:00.007+08:00| null| null|null|null| 7.0| +|1970-01-01T08:00:00.008+08:00| null| null|null|null| 8.0| ++-----------------------------+-------+-------+----+----+----+ + + +-- Insert statement +IoTDB:etth> INSERT INTO tab_real (time, target1, target2, cov1, cov2, cov3) VALUES +(1, 1.0, 1.0, 1.0, 1.0, 1.0), +(2, 2.0, 2.0, 2.0, 2.0, 2.0), +(3, 3.0, 3.0, 3.0, 3.0, 3.0), +(4, 4.0, 4.0, 4.0, 4.0, 4.0), +(5, 5.0, 5.0, 5.0, 5.0, 5.0), +(6, 6.0, 6.0, 6.0, 6.0, 6.0), +(7, NULL, NULL, NULL, NULL, 7.0), +(8, NULL, NULL, NULL, NULL, 8.0); +``` + +* Prediction task 1: Use historical covariates cov1, cov2, and cov3 to assist in predicting target variables target1 and target2. + + ![](/img/ainode-upgrade-table-forecast-timecho-1-en.png) + + * Use the first 6 rows of historical data from cov1, cov2, cov3, target1, target2 in table tab_real to predict the next 2 rows of target variables target1 and target2. + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.338330268859863|7.338330268859863| + |1970-01-01T08:00:00.008+08:00| 8.02529525756836| 8.02529525756836| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.315s + ``` +* Prediction task 2: Use historical covariates cov1, cov2 and known covariates cov3 in the same table to assist in predicting target variables target1 and target2. + + ![](/img/ainode-upgrade-table-forecast-timecho-2-en.png) + + * Use the first 6 rows of historical data from cov1, cov2, cov3, target1, target2 in table tab_real, and known covariate cov3 in the future 2 rows of the same table to predict the next 2 rows of target variables target1 and target2. + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + FUTURE_COVS => ' + SELECT TIME, cov3 + FROM etth.tab_real + WHERE TIME >= 7 + LIMIT 2', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.244050025939941|7.244050025939941| + |1970-01-01T08:00:00.008+08:00|7.907227516174316|7.907227516174316| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.291s + ``` +* Prediction task 3: Use historical covariates cov1, cov2 from different tables and known covariates cov3 to assist in predicting target variables target1 and target2. + + ![](/img/ainode-upgrade-table-forecast-timecho-3-en.png) + + * Create table tab_cov_forecast (to store known covariate cov3 prediction values) in advance, and prepare related data. + ```SQL + create table tab_cov_forecast (cov3 DOUBLE FIELD); + + -- Insert statement + INSERT INTO tab_cov_forecast (time, cov3) VALUES (7, 7.0),(8, 8.0); + + IoTDB:etth> SELECT * FROM tab_cov_forecast + +----+----+ + |time|cov3| + +----+----+ + | 7| 7.0| + | 8| 8.0| + +----+----+ + ``` + * Use the first 6 rows of known data from cov1, cov2, cov3, target1, target2 in table tab_real, and known covariate cov3 in the future 2 rows from table tab_cov_forecast to predict the next 2 rows of target variables target1 and target2. + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + FUTURE_COVS => ' + SELECT TIME, cov3 + FROM etth.tab_cov_forecast + WHERE TIME >= 7 + LIMIT 2', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.244050025939941|7.244050025939941| + |1970-01-01T08:00:00.008+08:00|7.907227516174316|7.907227516174316| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.351s + ``` + + +### 4.2 Model Fine-Tuning + +AINode supports model fine-tuning through SQL. + +**SQL Syntax** + +```SQL +createModelStatement + | CREATE MODEL modelId=identifier (WITH HYPERPARAMETERS '(' hparamPair (',' hparamPair)* ')')? FROM MODEL existingModelId=identifier ON DATASET '(' targetData=string ')' + ; +hparamPair + : hparamKey=identifier '=' hyparamValue=primaryExpression + ; +``` + +**Parameter Description** + +| Name | Description | +|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| modelId | Unique identifier of the fine-tuned model | +| hparamPair | Hyperparameter key-value pairs used for fine-tuning, currently supports the following:
`train_epochs`: int type, number of fine-tuning epochs
`iter_per_epoch`: int type, number of iterations per epoch
`learning_rate`: double type, learning rate | +| existingModelId | Base model used for fine-tuning | +| targetData | SQL to get the dataset used for fine-tuning | + +**Example** + +1. Select data from the ot field in the specified time range as the fine-tuning dataset, and create the model sundialv3 based on sundial. + +```SQL +IoTDB> set sql_dialect=table +Msg: The statement is executed successfully. +IoTDB> CREATE MODEL sundialv3 FROM MODEL sundial ON DATASET ('SELECT time, ot from etth.eg where 1467302400000 <= time and time < 1517468400001') +Msg: The statement is executed successfully. +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| +| sundialv2| sundial| fine_tuned| active| +| sundialv3| sundial| fine_tuned| training| ++---------------------+---------+-----------+---------+ +``` + +2. Fine-tuning tasks are started asynchronously in the background, which can be seen in the AINode process log; after fine-tuning is completed, query and use the new model. + +```SQL +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| +| sundialv2| sundial| fine_tuned| active| +| sundialv3| sundial| fine_tuned| active| ++---------------------+---------+-----------+---------+ +``` + +### 4.3 Register Custom Models + +**The following Transformers models can be registered to AINode:** + +1. AINode currently uses transformers version 4.56.2, so when building the model, avoid inheriting interfaces from lower versions (<4.50); +2. The model must inherit a pipeline for inference tasks of AINode (currently supports prediction pipeline): + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + Preprocess input data before the inference task, including shape validation and numerical conversion. + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + Postprocess output results after the inference task. + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + Preprocess input data before passing it to the model for inference, validate input data shape and type. + + Args: + inputs (list[dict]): + Input data, list of dictionaries, each dictionary contains: + - 'targets': tensor of shape (input_length,) or (target_count, input_length). + - 'past_covariates': optional, tensor dictionary, each tensor of shape (input_length,). + - 'future_covariates': optional, tensor dictionary, each tensor of shape (input_length,). + + infer_kwargs (dict, optional): Additional keyword parameters for inference, such as: + - `output_length`(int): If 'future_covariates' is provided, used to validate its validity. + + Raises: + ValueError: If input format is incorrect (e.g., missing keys, invalid tensor shapes). + + Returns: + Processed and validated input data, ready for model inference. + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + Perform prediction on given input. + + Parameters: + inputs: Input data for prediction. Type and structure depend on the model's specific implementation. + **infer_kwargs: Additional inference parameters, e.g.: + - `output_length`(int): Number of time points the model should generate. + + Returns: + Prediction output, specific form depends on the model's specific implementation. + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + Postprocess model output after inference, validate output data shape and ensure it meets expected dimensions. + + Args: + outputs: + Model output, list of 2D tensors, each tensor of shape `[target_count, output_length]`. + + Raises: + InferenceModelInternalException: If output tensor shape is invalid (e.g., dimension error). + ValueError: If output format is incorrect. + + Returns: + list[torch.Tensor]: + Postprocessed output, a list of 2D tensors. + """ + pass + ``` +3. Modify the model configuration file config.json to ensure it includes the following fields: + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // Specify the Config class of the model + "AutoModelForCausalLM": "model.Chronos2Model" // Specify the model class + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // Specify the model's inference pipeline + "model_type": "custom_t5", // Specify the model type + } + ``` + + 1. Must specify the Config class and model class through auto_map; + 2. Must integrate and specify the inference pipeline class; + 3. For built-in (builtin) and custom (user_defined) models managed by AINode, the model category (model_type) also serves as a unique identifier. That is, the model category to be registered must not duplicate any existing model types. Models created through fine-tuning will inherit the model category of the original model. +4. Ensure the model directory to be registered contains the following files, and the model configuration file name and weight file name are not customizable: + 1. Model configuration file: config.json; + 2. Model weight file: model.safetensors; + 3. Model code: other .py files. + +**The SQL syntax for registering custom models is as follows:** + +```SQL +CREATE MODEL USING URI +``` + +**Parameter Description:** + +* **model_id**: Unique identifier for the custom model; cannot be duplicated, with the following constraints: + * Allowed characters: [0-9 a-z A-Z \_ ] (letters, numbers (not at the beginning), underscore (not at the beginning)) + * Length limit: 2-64 characters + * Case-sensitive +* **uri**: Local URI address containing the model code and weights. + +**Registration Example:** + +Upload a custom Transformers model from a local path, AINode will copy the folder to the user_defined directory. + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +After executing the SQL, the registration process will be asynchronous. The registration status of the model can be viewed by checking the model display (see the "Viewing Models" section). After the model is registered successfully, it can be called using normal query methods for model inference. + +### 4.4 Viewing Models + +Registered models can be queried using the view command. + +```SQL +SHOW MODELS +``` + +In addition to displaying all model information directly, you can specify `model_id` to view the information of a specific model. + +```SQL +SHOW MODELS -- Only show specific model +``` + +The result of the model display contains the following: + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| Model ID | Model Type | Model Category | Model State | + +Where, the State model status machine flowchart is as follows: + +![](/img/ainode-upgrade-state-timecho-en.png) + +State machine flow description: + +1. After starting AINode, executing `show models` command, only **system built-in (BUILTIN)** models can be viewed. +2. Users can import their own models, which are identified as **user-defined (USER_DEFINED)**; AINode will try to parse the model type (ModelType) from the model configuration file; if parsing fails, this field will be displayed as empty. +3. Time series large models (built-in models) do not have weight files packaged with AINode, and AINode automatically downloads them when starting. + 1. During download, it is ACTIVATING, and after successful download, it becomes ACTIVE, and if failed, it becomes INACTIVE. +4. After users start a model fine-tuning task, the model state during training is TRAINING, and after successful training, it becomes ACTIVE, and if failed, it becomes FAILED. +5. If the fine-tuning task is successful, after fine-tuning, all ckpt (training files) will be statistically analyzed to find the best file and automatically renamed to the user-specified model_id. + +**Viewing Example** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| sundialx_1| sundial| fine_tuned| active| +| sundialx_4| sundial| fine_tuned| training| +| sundialx_5| sundial| fine_tuned| failed| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +**Built-in Traditional Time Series Models:** + +| Model Name | Core Concept | Applicable Scenarios | Key Features | +|-----------------------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------------------------| +| **ARIMA** (Autoregressive Integrated Moving Average) | Combines AR, differencing (I), and MA for stationary or differenced series | Univariate forecasting (stock prices, sales, economics) | 1. For linear trends with weak seasonality2. Requires (p,d,q) tuning3. Sensitive to missing values | +| **Holt-Winters** (Triple Exponential Smoothing) | Exponential smoothing with level, trend, and seasonal components | Data with clear trend & seasonality (monthly sales, power demand) | 1. Handles additive/multiplicative seasonality2. Weights recent data higher3. Simple implementation | +| **Exponential Smoothing** | Weighted average of history with exponentially decaying weights | Trending but non-seasonal data (short-term demand) | 1. Few parameters, simple computation2. Suitable for stable/slow-changing series3. Extensible to double/triple smoothing | +| **Naive Forecaster** | Uses last observation as next prediction (simplest baseline) | Benchmarking or data with no clear pattern | 1. No training needed2. Sensitive to sudden changes3. Seasonal variant uses prior season value | +| **STL Forecaster** | Decomposes series into trend, seasonal, residual; forecasts components | Complex seasonality/trends (climate, traffic) | 1. Handles non-fixed seasonality2. Robust to outliers3. Components can use other models | +| **Gaussian HMM** | Hidden states generate observations; each state follows Gaussian distribution | State sequence prediction/classification (speech, finance) | 1. Models temporal state transitions2. Observations independent per state3. Requires state count | +| **GMM HMM** | Extends Gaussian HMM; each state uses Gaussian Mixture Model | Multi-modal observation scenarios (motion recognition, biosignals) | 1. More flexible than single Gaussian2. Higher complexity3. Requires GMM component count | +| **STRAY** (Search for Outliers using Random Projection and Adaptive Thresholding) | Uses SVD to detect anomalies in high-dimensional time series | High-dimensional anomaly detection (sensor networks, IT monitoring) | 1. No distribution assumption2. Handles high dimensions3. Sensitive to global anomalies | + +**Built-in Time Series Large Models:** + +| Model Name | Core Concept | Applicable Scenarios | Key Features | +|-----------------|------------------------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------------------------| +| **Timer-XL** | Long-context time series large model pretrained on massive industrial data | Complex industrial forecasting requiring ultra-long history (energy, aerospace, transport) | 1. Supports input of tens of thousands of time points2. Covers non-stationary, multivariate, and covariate scenarios3. Pretrained on trillion-scale high-quality industrial IoT data | +| **Timer-Sundial** | Generative foundation model with "Transformer + TimeFlow" architecture | Zero-shot forecasting requiring uncertainty quantification (finance, supply chain, renewable energy) | 1. Strong zero-shot generalization; supports point & probabilistic forecasting2. Flexible analysis of any prediction distribution statistic3. Innovative flow-matching architecture for efficient non-deterministic sample generation | +| **Chronos-2** | Universal time series foundation model based on discrete tokenization | Rapid zero-shot univariate forecasting; scenarios enhanced by covariates (promotions, weather) | 1. Powerful zero-shot probabilistic forecasting2. Unified multi-variable & covariate modeling (strict input requirements):  a. Future covariate names ⊆ historical covariate names  b. Each historical covariate length = target length  c. Each future covariate length = prediction length3. Efficient encoder-only structure balancing performance and speed | + +### 4.5 Model Deletion + +Registered models can be deleted via SQL. AINode removes the corresponding model folder under `user_defined`. Syntax: +```SQL +DROP MODEL +``` +- Requires specifying an existing `model_id`. +- Deletion is asynchronous (status: `DROPPING`), during which the model cannot be used for inference. +- **Built-in models cannot be deleted.** + +### 4.6 Loading/Unloading Models + +AINode supports two loading strategies: +* **On-Demand Loading**: Load model temporarily during inference, then release resources. Suitable for testing or low-load scenarios. +* **Persistent Loading**: Keep model instances resident in CPU memory or GPU VRAM to support high-concurrency inference. Users specify load/unload targets via SQL; AINode auto-manages instance counts. Current loaded status is queryable. + +Details below: + +1. **Configuration Parameters** + Edit these settings to control persistent loading behavior: + ```properties + # Ratio of total device memory/VRAM usable by AINode for inference + # Datatype: Float + ain_inference_memory_usage_ratio=0.4 + + # Memory overhead ratio per loaded model instance (model_size * this_value) + # Datatype: Float + ain_inference_extra_memory_ratio=1.2 + ``` + +2. **List Available Devices** + ```SQL + SHOW AI_DEVICES + ``` + Example: + ```SQL + IoTDB> SHOW AI_DEVICES + +-------------+ + | DeviceId| + +-------------+ + | cpu| + | 0| + | 1| + +-------------+ + ``` + +3. **Load Model** + Manually load model; system auto-balances instance count based on resources: + ```SQL + LOAD MODEL TO DEVICES (, )* + ``` + Parameters: + * `existing_model_id`: Model ID (current version supports `timer_xl` and `sundial` only) + * `device_id`: + * `cpu`: Load into server memory + * `gpu_id`: Load into specified GPU(s), e.g., `'0,1'` for GPUs 0 and 1 + Example: + ```SQL + LOAD MODEL sundial TO DEVICES 'cpu,0,1' + ``` + +4. **Unload Model** + Unload all instances of a model; system reallocates freed resources: + ```SQL + UNLOAD MODEL FROM DEVICES (, )* + ``` + Parameters same as `LOAD MODEL`. + Example: + ```SQL + UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' + ``` + +5. **View Loaded Models** + ```SQL + SHOW LOADED MODELS + SHOW LOADED MODELS (, )* -- Filter by device + ``` + Example (sundial loaded on CPU, GPU 0, GPU 1): + ```SQL + IoTDB> SHOW LOADED MODELS + +-------------+--------------+------------------+ + | DeviceId| ModelId| Count(instances)| + +-------------+--------------+------------------+ + | cpu| sundial| 4| + | 0| sundial| 6| + | 1| sundial| 6| + +-------------+--------------+------------------+ + ``` + * `DeviceId`: Device identifier + * `ModelId`: Loaded model ID + * `Count(instances)`: Number of model instances per device (auto-assigned by system) + +### 4.7 Large Time Series Models + +AINode supports multiple large time series models. For deployment details, refer to [Time Series Large Model](../AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md) + +### 5. Permission Management + +Use IoTDB's built-in authentication for AINode permissions. Users need `USE_MODEL` permission to manage models and access input data for inference. + +| **Permission** | **Scope** | **Administrator (default ROOT)** | **Normal User** | +|---------------------|--------------------------------|----------------------------------|-----------------| +| USE_MODEL | create model / show models / drop model | √ | √ | +| READ_SCHEMA&READ_DATA | forecast | √ | √ | \ No newline at end of file diff --git a/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade.md b/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade.md new file mode 100644 index 000000000..440615354 --- /dev/null +++ b/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: TimeSeries-Large-Model_Upgrade_apache.html +--- + diff --git a/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md b/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md new file mode 100644 index 000000000..bc20138a4 --- /dev/null +++ b/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md @@ -0,0 +1,157 @@ + +# Time Series Large Models + +## 1. Introduction + +Time Series Large Models are foundational models specifically designed for time series data analysis. The IoTDB team has been developing the Timer, a self-researched foundational time series model, which is based on the Transformer architecture and pre-trained on massive multi-domain time series data, supporting downstream tasks such as time series forecasting, anomaly detection, and time series imputation. The AINode platform developed by the team also supports the integration of cutting-edge time series foundational models from the industry, providing users with diverse model options. Unlike traditional time series analysis techniques, these large models possess universal feature extraction capabilities and can serve a wide range of analytical tasks through zero-shot analysis, fine-tuning, and other services. + +All technical achievements in the field of time series large models related to this paper (including both the team's self-researched models and industry-leading directions) have been published in top international machine learning conferences, with specific details in the appendix. + +## 2. Application Scenarios + +* **Time Series Forecasting**: Providing time series data forecasting services for industrial production, natural environments, and other fields to help users understand future trends in advance. +* **Data Imputation**: Performing context-based filling for missing segments in time series to enhance the continuity and integrity of the dataset. +* **Anomaly Detection**: Using autoregressive analysis technology to monitor time series data in real-time, promptly alerting potential anomalies. + +![](/img/LargeModel10.png) + +## 3. Timer-1 Model + +The Timer model (non-built-in model) not only demonstrates excellent few-shot generalization and multi-task adaptability, but also acquires a rich knowledge base through pre-training, endowing it with universal capabilities to handle diverse downstream tasks, with the following characteristics: + +* **Generalizability**: The model can achieve industry-leading deep model prediction results through fine-tuning with only a small number of samples. +* **Universality**: The model design is flexible, capable of adapting to various different task requirements, and supports variable input and output lengths, enabling it to function effectively in various application scenarios. +* **Scalability**: As the number of model parameters increases or the scale of pre-training data expands, the model's performance will continue to improve, ensuring that the model can continuously optimize its prediction effectiveness as time and data volume grow. + +![](/img/model01.png) + +## 4. Timer-XL Model + +Timer-XL further extends and upgrades the network structure based on Timer, achieving comprehensive breakthroughs in multiple dimensions: + +* **Ultra-Long Context Support**: This model breaks through the limitations of traditional time series forecasting models, supporting the processing of inputs with thousands of Tokens (equivalent to tens of thousands of time points), effectively solving the context length bottleneck problem. +* **Coverage of Multi-Variable Forecasting Scenarios**: Supports various forecasting scenarios, including the prediction of non-stationary time series, multi-variable prediction tasks, and predictions involving covariates, meeting diversified business needs. +* **Large-Scale Industrial Time Series Dataset**: Pre-trained on a trillion-scale time series dataset from the industrial IoT field, the dataset possesses important characteristics such as massive scale, excellent quality, and rich domain coverage, covering multiple fields including energy, aerospace, steel, and transportation. + +![](/img/model02.png) + +## 5. Timer-Sundial Model + +Timer-Sundial is a series of generative foundational models focused on time series forecasting. The base version has 128 million parameters and has been pre-trained on 1 trillion time points, with the following core characteristics: + +* **Strong Generalization Performance**: Possesses zero-shot forecasting capabilities and can support both point forecasting and probabilistic forecasting simultaneously. +* **Flexible Prediction Distribution Analysis**: Not only can it predict means or quantiles, but it can also evaluate any statistical properties of the prediction distribution through the raw samples generated by the model. +* **Innovative Generative Architecture**: Employs a "Transformer + TimeFlow" collaborative architecture - the Transformer learns the autoregressive representations of time segments, while the TimeFlow module transforms random noise into diverse prediction trajectories based on the flow-matching framework (Flow-Matching), achieving efficient generation of non-deterministic samples. + +![](/img/model03.png) + +## 6. Chronos-2 Model + +Chronos-2 is a universal time series foundational model developed by the Amazon Web Services (AWS) research team, evolved from the Chronos discrete token modeling paradigm. This model is suitable for both zero-shot univariate forecasting and covariate forecasting. Its main characteristics include: + +* **Probabilistic Forecasting Capability**: The model outputs multi-step prediction results in a generative manner, supporting quantile or distribution-level forecasting to characterize future uncertainty. +* **Zero-Shot General Forecasting**: Leveraging the contextual learning ability acquired through pre-training, it can directly execute forecasting on unseen datasets without retraining or parameter updates. +* **Unified Modeling of Multi-Variable and Covariates**: Supports joint modeling of multiple related time series and their covariates under the same architecture to improve prediction performance for complex tasks. However, it has strict input requirements: + * The set of names of future covariates must be a subset of the set of names of historical covariates; + * The length of each historical covariate must equal the length of the target variable; + * The length of each future covariate must equal the prediction length; +* **Efficient Inference and Deployment**: The model adopts a compact encoder-only structure, maintaining strong generalization capabilities while ensuring inference efficiency. + +![](/img/timeseries-large-model-chronos2.png) + +## 7. Performance Showcase + +Time Series Large Models can adapt to real time series data from various different domains and scenarios, demonstrating excellent processing capabilities across various tasks. The following shows the actual performance on different datasets: + +**Time Series Forecasting:** + +Leveraging the forecasting capabilities of Time Series Large Models, future trends of time series can be accurately predicted. The blue curve in the following figure represents the predicted trend, while the red curve represents the actual trend, with both curves highly consistent. + +![](/img/LargeModel03.png) + +**Data Imputation:** + +Using Time Series Large Models to fill missing data segments through predictive imputation. + +![](/img/timeseries-large-model-data-imputation.png) + +**Anomaly Detection:** + +Using Time Series Large Models to accurately identify outliers that deviate significantly from the normal trend. + +![](/img/LargeModel05.png) + +## 8. Deployment and Usage + +1. Open the IoTDB CLI console and check that the ConfigNode, DataNode, and AINode nodes are all Running. + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. In an online environment, the first startup of the AINode node will automatically pull the Timer-XL, Sundial, and Chronos2 models. + + > Note: + > + > * The AINode installation package does not include model weight files. + > * The automatic pull feature depends on the deployment environment having HuggingFace network access capability. + > * AINode supports manual upload of model weight files. For specific operation methods, refer to [Importing Weight Files](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md#_3-3-importing-built-in-weight-files). + +3. Check if the models are available. + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### Appendix + +**[1]** Timer: Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[2]** TIMER-XL: LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING, Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[3]** Sundial: A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ Back]() + +**[4]** Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821**. [↩ Back]() \ No newline at end of file diff --git a/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md b/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md new file mode 100644 index 000000000..c7fde0bf2 --- /dev/null +++ b/src/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md @@ -0,0 +1,157 @@ + +# Time Series Large Models + +## 1. Introduction + +Time Series Large Models are foundational models specifically designed for time series data analysis. The IoTDB team has been developing the Timer, a self-researched foundational time series model, which is based on the Transformer architecture and pre-trained on massive multi-domain time series data, supporting downstream tasks such as time series forecasting, anomaly detection, and time series imputation. The AINode platform developed by the team also supports the integration of cutting-edge time series foundational models from the industry, providing users with diverse model options. Unlike traditional time series analysis techniques, these large models possess universal feature extraction capabilities and can serve a wide range of analytical tasks through zero-shot analysis, fine-tuning, and other services. + +All technical achievements in the field of time series large models related to this paper (including both the team's self-researched models and industry-leading directions) have been published in top international machine learning conferences, with specific details in the appendix. + +## 2. Application Scenarios + +* **Time Series Forecasting**: Providing time series data forecasting services for industrial production, natural environments, and other fields to help users understand future trends in advance. +* **Data Imputation**: Performing context-based filling for missing segments in time series to enhance the continuity and integrity of the dataset. +* **Anomaly Detection**: Using autoregressive analysis technology to monitor time series data in real-time, promptly alerting potential anomalies. + +![](/img/LargeModel10.png) + +## 3. Timer-1 Model + +The Timer model (non-built-in model) not only demonstrates excellent few-shot generalization and multi-task adaptability, but also acquires a rich knowledge base through pre-training, endowing it with universal capabilities to handle diverse downstream tasks, with the following characteristics: + +* **Generalizability**: The model can achieve industry-leading deep model prediction results through fine-tuning with only a small number of samples. +* **Universality**: The model design is flexible, capable of adapting to various different task requirements, and supports variable input and output lengths, enabling it to function effectively in various application scenarios. +* **Scalability**: As the number of model parameters increases or the scale of pre-training data expands, the model's performance will continue to improve, ensuring that the model can continuously optimize its prediction effectiveness as time and data volume grow. + +![](/img/model01.png) + +## 4. Timer-XL Model + +Timer-XL further extends and upgrades the network structure based on Timer, achieving comprehensive breakthroughs in multiple dimensions: + +* **Ultra-Long Context Support**: This model breaks through the limitations of traditional time series forecasting models, supporting the processing of inputs with thousands of Tokens (equivalent to tens of thousands of time points), effectively solving the context length bottleneck problem. +* **Coverage of Multi-Variable Forecasting Scenarios**: Supports various forecasting scenarios, including the prediction of non-stationary time series, multi-variable prediction tasks, and predictions involving covariates, meeting diversified business needs. +* **Large-Scale Industrial Time Series Dataset**: Pre-trained on a trillion-scale time series dataset from the industrial IoT field, the dataset possesses important characteristics such as massive scale, excellent quality, and rich domain coverage, covering multiple fields including energy, aerospace, steel, and transportation. + +![](/img/model02.png) + +## 5. Timer-Sundial Model + +Timer-Sundial is a series of generative foundational models focused on time series forecasting. The base version has 128 million parameters and has been pre-trained on 1 trillion time points, with the following core characteristics: + +* **Strong Generalization Performance**: Possesses zero-shot forecasting capabilities and can support both point forecasting and probabilistic forecasting simultaneously. +* **Flexible Prediction Distribution Analysis**: Not only can it predict means or quantiles, but it can also evaluate any statistical properties of the prediction distribution through the raw samples generated by the model. +* **Innovative Generative Architecture**: Employs a "Transformer + TimeFlow" collaborative architecture - the Transformer learns the autoregressive representations of time segments, while the TimeFlow module transforms random noise into diverse prediction trajectories based on the flow-matching framework (Flow-Matching), achieving efficient generation of non-deterministic samples. + +![](/img/model03.png) + +## 6. Chronos-2 Model + +Chronos-2 is a universal time series foundational model developed by the Amazon Web Services (AWS) research team, evolved from the Chronos discrete token modeling paradigm. This model is suitable for both zero-shot univariate forecasting and covariate forecasting. Its main characteristics include: + +* **Probabilistic Forecasting Capability**: The model outputs multi-step prediction results in a generative manner, supporting quantile or distribution-level forecasting to characterize future uncertainty. +* **Zero-Shot General Forecasting**: Leveraging the contextual learning ability acquired through pre-training, it can directly execute forecasting on unseen datasets without retraining or parameter updates. +* **Unified Modeling of Multi-Variable and Covariates**: Supports joint modeling of multiple related time series and their covariates under the same architecture to improve prediction performance for complex tasks. However, it has strict input requirements: + * The set of names of future covariates must be a subset of the set of names of historical covariates; + * The length of each historical covariate must equal the length of the target variable; + * The length of each future covariate must equal the prediction length; +* **Efficient Inference and Deployment**: The model adopts a compact encoder-only structure, maintaining strong generalization capabilities while ensuring inference efficiency. + +![](/img/timeseries-large-model-chronos2.png) + +## 7. Performance Showcase + +Time Series Large Models can adapt to real time series data from various different domains and scenarios, demonstrating excellent processing capabilities across various tasks. The following shows the actual performance on different datasets: + +**Time Series Forecasting:** + +Leveraging the forecasting capabilities of Time Series Large Models, future trends of time series can be accurately predicted. The blue curve in the following figure represents the predicted trend, while the red curve represents the actual trend, with both curves highly consistent. + +![](/img/LargeModel03.png) + +**Data Imputation:** + +Using Time Series Large Models to fill missing data segments through predictive imputation. + +![](/img/timeseries-large-model-data-imputation.png) + +**Anomaly Detection:** + +Using Time Series Large Models to accurately identify outliers that deviate significantly from the normal trend. + +![](/img/LargeModel05.png) + +## 8. Deployment and Usage + +1. Open the IoTDB CLI console and check that the ConfigNode, DataNode, and AINode nodes are all Running. + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. In an online environment, the first startup of the AINode node will automatically pull the Timer-XL, Sundial, and Chronos2 models. + + > Note: + > + > * The AINode installation package does not include model weight files. + > * The automatic pull feature depends on the deployment environment having HuggingFace network access capability. + > * AINode supports manual upload of model weight files. For specific operation methods, refer to [Importing Weight Files](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md#_3-3-importing-built-in-weight-files). + +3. Check if the models are available. + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### Appendix + +**[1]** Timer: Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[2]** TIMER-XL: LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING, Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[3]** Sundial: A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ Back]() + +**[4]** Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821**. [↩ Back]() \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade.md b/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade.md new file mode 100644 index 000000000..6f44068b6 --- /dev/null +++ b/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: AINode_Upgrade_apache.html +--- + \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_apache.md b/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_apache.md new file mode 100644 index 000000000..95120ae19 --- /dev/null +++ b/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_apache.md @@ -0,0 +1,574 @@ + + +# AINode + +AINode is a native IoTDB node that supports the registration, management, and invocation of time-series related models. It includes industry-leading self-developed time-series large models, such as the Timer series models developed by Tsinghua University. These models can be called using standard SQL statements, enabling millisecond-level real-time inference for time series data, supporting applications such as time series trend prediction, missing value imputation, and anomaly detection. + +The system architecture is shown in the following figure: + +![](/img/AINode-0-en.png) + +The responsibilities of the three nodes are as follows: + +* **ConfigNode**: Responsible for distributed node management and load balancing. +* **DataNode**: Responsible for receiving and parsing users' SQL requests; responsible for storing time series data; responsible for data preprocessing calculations. +* **AINode**: Responsible for the management and use of time series models. + +## 1. Advantages + +Compared to building a machine learning service separately, it has the following advantages: + +* **Simple and Easy to Use**: No need to use Python or Java programming. Machine learning model management and inference can be completed using SQL statements. For example, creating a model can use the CREATE MODEL statement, and using a model for inference can use the `CALL INFERENCE(...)` statement, making it simpler and more convenient. +* **Avoid Data Migration**: Using IoTDB's native machine learning can directly apply data stored in IoTDB to machine learning models for inference, without moving data to a separate machine learning service platform. This accelerates data processing, improves security, and reduces costs. + +![](/img/AInode1.png) + +* **Built-in Advanced Algorithms**: Supports industry-leading machine learning analysis algorithms, covering typical time series analysis tasks, and empowering time series databases with native data analysis capabilities. For example: + * **Time Series Forecasting**: Learn change patterns from past time series data; based on given past observations, output the most likely future sequence predictions. + * **Anomaly Detection for Time Series**: Detect and identify anomalies in given time series data, helping to discover abnormal behavior in time series. + +## 2. Basic Concepts + +* **Model**: Machine learning model, which takes time series data as input and outputs the results or decisions of the analysis task. Model is the basic management unit of AINode, supporting model management including creation (registration), deletion, query, and usage (inference). +* **Create**: Load external designed or trained model files or algorithms into AINode, managed and used uniformly by IoTDB. +* **Inference**: Use the created model to complete the time series analysis task applicable to the model on the specified time series data. +* **Built-in**: AINode comes with common time series analysis scenario (e.g., prediction and anomaly detection) machine learning algorithms or self-developed models. + +![](/img/AInode2.png) + +## 3. Installation and Deployment + +AINode deployment can be referenced in the document [AINode Deployment](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md). + +## 4. Usage Guide + +AINode supports two major functions: model inference and model management (registration, viewing, deletion, loading, unloading, etc.). The following sections will provide detailed instructions. + +### 4.1 Model Inference + +SQL syntax: + +```SQL +call inference(,inputSql,(=)*) +``` + +After completing the model registration (built-in models do not require the registration process), the inference function of the model can be used by calling the inference function with the call keyword. The corresponding parameter descriptions are as follows: + +* **model_id**: Corresponds to an already registered model +* **sql**: SQL query statement, the result of the query is used as the input for model inference. The dimensions of the query results (rows and columns) need to match the size specified in the model's config. (It is recommended not to use the `SELECT *` clause in this sql, because in IoTDB, `*` does not sort the columns, so the column order is undefined. It is recommended to use `SELECT s0,s1` to ensure the column order matches the expected input of the model.) +* **parameterName/parameterValue**: currently supports: + + | Parameter Name | Parameter Type | Parameter Description | Default Value | + | ------------------------ | ---------- | -------------------------- | -------- | + | **generateTime** | boolean | Whether to include a timestamp column in the result | false | + | **outputLength** | int | Specifies the length of the output result | 96 | + +Notes: + +1. The prerequisite for using built-in time series large models for inference is that the corresponding model weights are locally stored, with the directory being `/IOTDB_AINODE_HOME/data/ainode/models/builtin/model_id/`. If the local model weights are not present, they will be automatically pulled from HuggingFace. Please ensure that the local environment can directly access HuggingFace. +2. In deep learning applications, time stamp derived features (the time column in the data) are often used as covariates together with the input to the model to improve model performance. However, the time column is generally not included in the model's output results. To ensure generality, the model inference results only correspond to the model's true output. If the model does not output a time column, the result will not include it. + +**Example** + +Sample data [ETTh-tree](/img/ETTh-tree.csv) + +Here is an example of using the sundial model for inference. The input is 96 rows, and the output is 48 rows. We use SQL to perform the inference. + +```SQL +IoTDB> select OT from root.db.** ++-----------------------------+---------------+ +| Time|root.db.etth.OT| ++-----------------------------+---------------+ +|2016-07-01T00:00:00.000+08:00| 30.531| +|2016-07-01T01:00:00.000+08:00| 27.787| +|2016-07-01T02:00:00.000+08:00| 27.787| +|2016-07-01T03:00:00.000+08:00| 25.044| +|2016-07-01T04:00:00.000+08:00| 21.948| +| ...... | ...... | +|2016-07-04T19:00:00.000+08:00| 29.546| +|2016-07-04T20:00:00.000+08:00| 29.475| +|2016-07-04T21:00:00.000+08:00| 29.264| +|2016-07-04T22:00:00.000+08:00| 30.953| +|2016-07-04T23:00:00.000+08:00| 31.726| ++-----------------------------+---------------+ +Total line number = 96 + +IoTDB> call inference(sundial,"select OT from root.db.**", generateTime=True, outputLength=48) ++-----------------------------+------------------+ +| Time| output| ++-----------------------------+------------------+ +|2016-07-04T23:00:00.000+08:00|30.537494659423828| +|2016-07-04T23:59:22.500+08:00|29.619892120361328| +|2016-07-05T00:58:45.000+08:00|28.815832138061523| +|2016-07-05T01:58:07.500+08:00| 27.91131019592285| +|2016-07-05T02:57:30.000+08:00|26.893848419189453| +| ...... | ...... | +|2016-07-06T17:33:07.500+08:00| 24.40607261657715| +|2016-07-06T18:32:30.000+08:00| 25.00441551208496| +|2016-07-06T19:31:52.500+08:00|24.907312393188477| +|2016-07-06T20:31:15.000+08:00|25.156436920166016| +|2016-07-06T21:30:37.500+08:00|25.335433959960938| ++-----------------------------+------------------+ +Total line number = 48 +``` + +### 4.2 Register Custom Models + +**The following requirements must be met for Transformers models to be registered in AINode:** + +1. AINode currently uses transformers v4.56.2, so when building the model, avoid inheriting from low versions (<4.50) interfaces; +2. The model must inherit from a type of AINode inference task pipeline (currently supports forecast pipeline): + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + Preprocess the input data before the inference task, including shape verification and numerical conversion. + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + Postprocess the output results after the inference task. + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + Preprocess the input data before passing it to the model for inference, verifying the shape and type of input data. + + Args: + inputs (list[dict]): + Input data, a list of dictionaries, each dictionary contains: + - 'targets': A tensor of shape (input_length,) or (target_count, input_length). + - 'past_covariates': Optional, a dictionary of tensors, each tensor of shape (input_length,). + - 'future_covariates': Optional, a dictionary of tensors, each tensor of shape (input_length,). + + infer_kwargs (dict, optional): Additional keyword parameters for inference, such as: + - `output_length`(int): Used to verify validity if 'future_covariates' is provided. + + Raises: + ValueError: If the input format is incorrect (e.g., missing keys, invalid tensor shapes). + + Returns: + Preprocessed and verified input data, ready for model inference. + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + Perform prediction on the given input. + + Parameters: + inputs: Input data for prediction. Type and structure depend on the specific model implementation. + **infer_kwargs: Additional inference parameters, for example: + - `output_length`(int): The number of time points the model should generate. + + Returns: + Prediction output, specific form depends on the specific model implementation. + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + Postprocess the model output after inference, verifying the shape of the output tensor and ensuring it meets expected dimensions. + + Args: + outputs: + Model output, a list of 2D tensors, each tensor shape is `[target_count, output_length]`. + + Raises: + InferenceModelInternalException: If the output tensor shape is invalid (e.g., dimension error). + ValueError: If the output format is incorrect. + + Returns: + list[torch.Tensor]: + Postprocessed output, a list of 2D tensors. + """ + pass + ``` +3. Modify the model configuration file config.json to ensure it contains the following fields: + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // Specify the model Config class + "AutoModelForCausalLM": "model.Chronos2Model" // Specify the model class + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // Specify the model's inference pipeline + "model_type": "custom_t5", // Specify the model type + } + ``` + + 1. Must specify the model's Config class and model class through auto_map; + 2. Must integrate and specify the inference pipeline class; + 3. For built-in (builtin) and user-defined (user_defined) models managed by AINode, the model category (model_type) also serves as a unique identifier. That is, the model category to be registered must not duplicate any existing model types. +4. Ensure the model directory to be registered contains the following files, and the model configuration file name and weight file name are not customizable: + 1. Model configuration file: config.json; + 2. Model weight file: model.safetensors; + 3. Model code: other .py files. + +**The SQL syntax for registering a custom model is as follows:** + +```SQL +CREATE MODEL USING URI +``` + +**Parameter descriptions:** + +* **model_id**: The unique identifier of the custom model; must be unique, with the following constraints: + * Allowed characters: [0-9 a-z A-Z _] (letters, numbers (not starting), underscore (not starting)) + * Length limit: 2-64 characters + * Case-sensitive +* **uri**: The local URI address containing the model code and weights. + +**Example of registration:** + +Upload a custom Transformers model from a local path, AINode will copy the folder to the user_defined directory. + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +After executing the SQL, the model registration process will be asynchronous. You can view the model registration status by viewing the model (see the View Model section). After the model registration is complete, you can call the specific function using normal query methods to perform model inference. + +### 4.3 View Models + +Registered models can be viewed using the view command. + +```SQL +SHOW MODELS +``` + +In addition to directly displaying all model information, you can specify `model_id` to view specific model information. + +```SQL +SHOW MODELS -- Show specific model only +``` + +The model display result includes the following content: + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| Model ID | Model Type | Model Category | Model State | + +Where, the State model state machine flowchart is as follows: + +![](/img/ainode-upgrade-state-apache-en.png) + +State machine flow description: + +1. After starting AINode, executing `show models` command can only view the **system built-in (BUILTIN)** models. +2. Users can import their own models, which are identified as **user-defined (USER_DEFINED)**; AINode will try to parse the model type (ModelType) from the model configuration file. If parsing fails, this field will be displayed as empty. +3. Time series large models (built-in models) weight files are not packaged with AINode, and AINode automatically downloads them when starting. + 1. During download, the state is ACTIVATING; after successful download, it becomes ACTIVE; if download fails, it becomes INACTIVE. + +**View Example** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +Built-in traditional time series model introduction: + +| Model Name | Core Concept | Applicable Scenario | Main Features | +|----------------------------------| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| **ARIMA** (AutoRegressive Integrated Moving Average) | Combines autoregression (AR), differencing (I), and moving average (MA), used for predicting stationary time series or data that can be made stationary through differencing. | Univariate time series prediction, such as stock prices, sales, economic indicators. | 1. Suitable for linear trends and weak seasonality data. 2. Requires selecting parameters (p,d,q). 3. Sensitive to missing values. | +| **Holt-Winters** (Three-parameter exponential smoothing) | Based on exponential smoothing, introduces level, trend, and seasonal components, suitable for data with trend and seasonality. | Time series with clear seasonality and trend, such as monthly sales, power demand. | 1. Can handle additive or multiplicative seasonality. 2. Gives higher weight to recent data. 3. Simple to implement. | +| **Exponential Smoothing** (Exponential smoothing) | Uses weighted average of historical data, with weights decreasing exponentially over time, emphasizing the importance of recent observations. | Data without significant seasonality but with trend, such as short-term demand prediction. | 1. Few parameters, simple calculation. 2. Suitable for stationary or slowly changing sequences. 3. Can be extended to double or triple exponential smoothing. | +| **Naive Forecaster** (Naive predictor) | Uses the observation of the most recent period as the prediction for the next period, the simplest baseline model. | As a benchmark for other models or simple prediction when data has no obvious pattern. | 1. No training required. 2. Sensitive to sudden changes. 3. Seasonal naive variant can use the same period of the previous season to predict. | +| **STL Forecaster** (Seasonal-Trend Decomposition Forecast) | Based on STL decomposition of time series, predicts trend, seasonal, and residual components separately, then combines them. | Data with complex seasonality, trend, and non-linear patterns, such as climate data, traffic flow. | 1. Can handle non-fixed seasonality. 2. Robust to outliers. 3. After decomposition, other models can be combined to predict each component. | +| **Gaussian HMM** (Gaussian Hidden Markov Model) | Assumes observed data is generated by hidden states, with each state's observation probability following a Gaussian distribution. | State sequence prediction or classification, such as speech recognition, financial state identification. | 1. Suitable for time series state modeling. 2. Assumes observations are independent given the state. 3. Requires specifying the number of hidden states. | +| **GMM HMM** (Gaussian Mixture Hidden Markov Model) | An extension of Gaussian HMM, where each state's observation probability is described by a Gaussian Mixture Model, capturing more complex observation distributions. | Scenarios requiring multi-modal observation distributions, such as complex action recognition, biosignal analysis. | 1. More flexible than single Gaussian. 2. More parameters, higher computational complexity. 3. Requires training the number of GMM components. | +| **STRAY** (Anomaly Detection based on Singular Value Decomposition) | Detects anomalies in high-dimensional data through Singular Value Decomposition (SVD), commonly used for time series anomaly detection. | High-dimensional time series anomaly detection, such as sensor networks, IT system monitoring. | 1. No distribution assumption required. 2. Can handle high-dimensional data. 3. Sensitive to global anomalies, may miss local anomalies. | + +Built-in time series large model introduction: + +| Model Name | Core Concept | Applicable Scenario | Main Features | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | Time series large model supporting ultra-long context, enhancing generalization capability through large-scale industrial data pre-training. | Complex industrial prediction requiring extremely long historical data, such as energy, aerospace, and transportation. | 1. Ultra-long context support, can handle tens of thousands of time points as input. 2. Multi-scenario coverage, supports non-stationary, multi-variable, and covariate prediction. 3. Pre-trained on trillions of high-quality industrial time series data. | +| **Timer-Sundial** | A generative foundational model based on "Transformer + TimeFlow" architecture, focusing on probabilistic prediction. | Zero-shot prediction scenarios requiring quantification of uncertainty, such as finance, supply chain, and new energy power generation. | 1. Strong zero-shot generalization capability, supports point prediction and probabilistic prediction. 2. Can flexibly analyze any statistical properties of the prediction distribution. 3. Innovative generative architecture, achieving efficient non-deterministic sample generation. | +| **Chronos-2** | A general time series foundational model based on discrete tokenization paradigm, converting prediction into language modeling tasks. | Rapid zero-shot univariate prediction, and scenarios that can leverage covariates (e.g., promotions, weather) to improve results. | 1. Strong zero-shot probabilistic prediction capability. 2. Supports unified covariate modeling, but has strict input requirements: a. The set of names of future covariates must be a subset of the set of names of historical covariates; b. The length of each historical covariate must equal the length of the target variable; c. The length of each future covariate must equal the prediction length; 3. Uses an efficient encoder-style structure, balancing performance and inference speed. | + +### 4.4 Delete Models + +For registered models, users can delete them using SQL. AINode will delete the entire folder of the corresponding model in the user_defined directory. The SQL syntax is as follows: + +```SQL +DROP MODEL +``` + +Specify the model_id that has been successfully registered to delete the corresponding model. Since model deletion involves model data cleanup, the operation will not be completed immediately, and the model state becomes DROPPING. Models in this state cannot be used for model inference. Note that this function does not support deleting built-in models. + +### 4.5 Load/Unload Models + +To adapt to different scenarios, AINode provides two model loading strategies: + +* **On-demand loading**: Load the model temporarily when inference is needed, and release resources after inference. Suitable for testing or low-load scenarios. +* **Persistent loading**: Permanently load the model into memory (CPU) or GPU memory to support high-concurrency inference. Users only need to specify the model to load or unload via SQL, and AINode will automatically manage the number of instances. The current state of persistent models can also be viewed at any time. + +The following details the loading/unloading model content: + +1. Configuration parameters + +Support editing the following configuration items to set persistent loading related parameters. + +```Properties +# The ratio of device memory/GPU memory available for AINode inference +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# The memory ratio required by each instance of a loaded model, i.e., model memory * this value +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. View available devices + +Support using the following SQL command to view all available device IDs. + +```SQL +SHOW AI_DEVICES +``` + +Example + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. Load models + +Support using the following SQL command to manually load models, and the system will **automatically balance** the number of model instances based on hardware resource usage. + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +Parameter requirements + +* **existing_model_id:** The specified model ID, currently only supports timer_xl and sundial. +* **device_id:** The location where the model is loaded. + * **cpu:** Load to the memory of the AINode server. + * **gpu_id:** Load to the corresponding GPU of the AINode server, e.g., "0, 1" means loading to the two GPUs numbered 0 and 1. + +Example + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. Unload models + +Support using the following SQL command to manually unload all instances of a specified model, and the system will **redistribute** the released resources to other models. + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +Parameter requirements + +* **existing_model_id:** The specified model ID, currently only supports timer_xl and sundial. +* **device_id:** The location where the model is loaded. + * **cpu:** Attempt to unload the specified model from the memory of the AINode server. + * **gpu_id:** Attempt to unload the specified model from the corresponding GPU of the AINode server, e.g., "0, 1" means attempting to unload from the two GPUs numbered 0 and 1. + +Example + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. View loaded models + +Support using the following SQL command to view the models that have been manually loaded. You can specify the device with `device_id`. + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # View models in specified devices +``` + +Example: sundial model loaded in memory, gpu_0, and gpu_1 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +Notes: + +* DeviceId: Device ID +* ModelId: Loaded model ID +* Count(instances): Number of model instances per device (automatically assigned by the system) + +### 4.6 Introduction to Time Series Large Models + +AINode currently supports multiple time series large models. For related introductions and deployment usage, refer to [Time Series Large Models](../AI-capability/TimeSeries-Large-Model_Upgrade_apache.md) + +## 5. Permission Management + +When using AINode-related features, permission management can be done using IoTDB's own authentication. Users can only use model management-related features if they have the USE_MODEL permission. When using inference features, users need to have access permissions to the source sequences corresponding to the SQL used for input. + +| Permission Name | Permission Scope | Administrator User (Default ROOT) | Normal User | Related to Path | +| ------------ | ----------------------------------------- | ------------------------ | ---------- | ---------- | +| USE_MODEL | create model / show models / drop model | √ | √ | x | +| READ_DATA | call inference | √ | √ | √ | + +## 6. Contributing Open Source Time Series Large Models to IoTDB-AINode + +Support adding new built-in models to AINode. The specific steps are as follows (using chronos2 as an example): + +* **Send an email to the [dev@iotdb.apache.org](mailto:dev@iotdb.apache.org) mailing list or submit an issue in the main repository to initiate preliminary discussion** +* **Submit a Pull Request to the main branch** + +1. Check the open source license used by the model and declare it in the IoTDB repository. +2. Create a new package for the new built-in model in iotdb-core/ainode/iotdb/ainode/core/model; + 1. Ensure it contains the model configuration class; + 2. Ensure it contains the model class for executing inference tasks; + 3. Ensure it contains the pipeline class inheriting from AINode inference task pipeline; + + ```Bash + root@rootMacBook-Pro model % eza --tree --level=2 . + . + ├── chronos2 + │ ├── __init__.py + │ ├── base.py + │ ├── chronos_bolt.py + │ ├── config.py + │ ├── dataset.py + │ ├── layers.py + │ ├── model.py + │ ├── pipeline_chronos2.py # Inheriting AINode inference task pipeline + │ └── utils.py + ├── sktime + ├── sundial + └── timer_xl + ``` +3. Add the metadata of the new model in iotdb-core/ainode/iotdb/ainode/core/model/model_info.py; + ```Python + BUILTIN_HF_TRANSFORMERS_MODEL_MAP = { + "chronos2": ModelInfo( + model_id="chronos2", # Unique identifier of the model + category=ModelCategory.BUILTIN, # Model category, choose BUILTIN + state=ModelStates.INACTIVE, + model_type="t5", # Model type, must not duplicate other builtin models + pipeline_cls="pipeline_chronos2.Chronos2Pipeline", # Inheriting AINode inference pipeline + repo_id="amazon/chronos-2", # [Optional] Huggingface weights + auto_map={ + "AutoConfig": "config.Chronos2CoreConfig", # Ensure it points to the model's configuration class + "AutoModelForCausalLM": "model.Chronos2Model", # Ensure it points to the model class for inference + }, + ), + } + ``` +4. Add the corresponding model in integration-test/src/test/java/org/apache/iotdb/ainode/utils/AINodeTestUtils.java. + ```Java + public static final Map BUILTIN_LTSM_MAP = + Stream.of( + new AbstractMap.SimpleEntry<>( + "sundial", new FakeModelInfo("sundial", "sundial", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "timer_xl", new FakeModelInfo("timer_xl", "timer", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "chronos2", new FakeModelInfo("chronos2", "t5", "builtin", "active"))) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + ``` +5. Submit a pull request, and only merge after passing the pipeline tests. + +* **Packaging and Deployment** + +1. Compile AINode to obtain the installation package. + ```Bash + # Command to simultaneously build IoTDB and AINode + mvn clean package -pl distribution -P with-ainode -am -DskipTests + # Command to build AINode only + mvn clean package -pl iotdb-core/ainode -P with-ainode -am -DskipTests + ``` +2. Ensure the model can obtain weights at runtime. + 1. If the model weights can be obtained online from Huggingface, ensure `repo_id` is filled in; + 2. Otherwise, manually place the model weights in `data/ainode/models/builtin/` before starting AINode or during runtime. + + ```Bash + root@rootMacBook-Pro models % eza --tree --level=3 . + . + ├── __init__.py + ├── builtin + │ ├── __init__.py + │ ├── chronos2 + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ ├── sundial + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ └── timer_xl + │ ├── __init__.py + │ ├── config.json + │ └── model.safetensors + └── user_defined + ``` + +* **Full Example** + +Full example can be referenced at https://github.com/apache/iotdb/pull/16903 \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_timecho.md b/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_timecho.md new file mode 100644 index 000000000..5fa365dd5 --- /dev/null +++ b/src/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_timecho.md @@ -0,0 +1,559 @@ + + +# AINode + +AINode is a native IoTDB node that supports the registration, management, and invocation of time series related models, with built-in industry-leading self-developed time series large models such as the Tsinghua University's Timer series. It can be invoked through standard SQL statements to achieve millisecond-level real-time inference on time series data, supporting applications such as time series trend prediction, missing value imputation, and anomaly detection. + +The system architecture is shown in the following diagram: + +![](/img/AINode-0-en.png) + +The responsibilities of the three nodes are as follows: + +* **ConfigNode**: Responsible for distributed node management and load balancing. +* **DataNode**: Responsible for receiving and parsing user SQL requests; responsible for storing time series data; responsible for data preprocessing calculations. +* **AINode**: Responsible for managing and using time series models. + +## 1. Advantages + +Compared to building machine learning services separately, it has the following advantages: + +* **Simple and easy to use**: No need to use Python or Java programming, SQL statements can be used to complete the entire process of machine learning model management and inference. For example, creating a model can use the CREATE MODEL statement, and using a model for inference can use the CALL INFERENCE (...) statement, etc., which is simpler and more convenient to use. +* **Avoid data migration**: Using IoTDB native machine learning can directly apply time series data stored in IoTDB to machine learning model inference, without moving data to a separate machine learning service platform, thus accelerating data processing, improving security, and reducing costs. + +![](/img/AInode1.png) + +* **Built-in advanced algorithms**: Supports industry-leading machine learning analysis algorithms, covering typical time series analysis tasks, empowering time series databases with native data analysis capabilities. Such as: + * **Time Series Forecasting**: Learn change patterns from past time series to output the most likely prediction of future sequences based on given past observations. + * **Anomaly Detection for Time Series**: Detect and identify anomalies in given time series data to help discover abnormal behavior in time series. + +## 2. Basic Concepts + +* **Model**: Machine learning model, which takes time series data as input and outputs the results or decisions of the analysis task. The model is the basic management unit of AINode, supporting the addition (registration), deletion, query, modification (fine-tuning), and use (inference) of models. +* **Create**: Load external designed or trained model files or algorithms into AINode, managed and used by IoTDB. +* **Inference**: Use the created model to complete the time series analysis task applicable to the model on the specified time series data. +* **Built-in**: AINode comes with common time series analysis scenario (e.g., prediction and anomaly detection) machine learning algorithms or self-developed models. + +![](/img/AInode2.png) + +## 3. Installation and Deployment + +AINode deployment can be referenced in the documentation [AINode Deployment](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md). + +## 4. Usage Guide + +TimechoDB-AINode supports three major functions: model inference, model fine-tuning, and model management (registration, viewing, deletion, loading, unloading, etc.). The following sections will explain them in detail. + +### 4.1 Model Inference + +SQL syntax as follows: + +```SQL +call inference(,inputSql,(=)*) +``` + +After completing the model registration (built-in model inference does not require a registration process), the inference function of the model can be used by calling the inference function with the call keyword. The corresponding parameter descriptions are as follows: + +* **model\_id**: Corresponds to an already registered model +* **sql**: SQL query statement, the result of the query is used as the input for model inference. The dimensions of the rows and columns in the query result need to match the size specified in the specific model config. (It is not recommended to use the `SELECT *` clause in this sql, because in IoTDB, `*` does not sort columns, so the column order is undefined. It is recommended to use `SELECT ot` to ensure that the column order matches the expected input of the model.) +* **parameterName/parameterValue**: currently supported: + + | Parameter Name | Parameter Type | Parameter Description | Default Value | + | ---------------- | -------------- | ----------------------- | -------------- | + | **generateTime** | boolean | Whether to include a timestamp column in the result | false | + | **outputLength** | int | Specifies the output length of the result | 96 | + +Notes: +1. The prerequisite for using built-in time series large models for inference is that the local machine has the corresponding model weights, located at `/TIMECHODB_AINODE_HOME/data/ainode/models/builtin/model_id/`. If the local machine does not have model weights, it will automatically pull from HuggingFace. Please ensure that the local machine can directly access HuggingFace. +2. In deep learning applications, it is common to use time-derived features (the time column in the data) as covariates and input them into the model together with the data to improve model performance. However, the time column is generally not included in the model's output results. To ensure universality, the model inference result only corresponds to the model's true output. If the model does not output a time column, the result will not contain it. + +**Example** + +Sample data [ETTh-tree](/img/ETTh-tree.csv) + +Below is an example of using the sundial model for inference. The input is 96 rows, and the output is 48 rows. We use SQL to perform the inference. + +```SQL +IoTDB> select OT from root.db.** ++-----------------------------+---------------+ +| Time|root.db.etth.OT| ++-----------------------------+---------------+ +|2016-07-01T00:00:00.000+08:00| 30.531| +|2016-07-01T01:00:00.000+08:00| 27.787| +|2016-07-01T02:00:00.000+08:00| 27.787| +|2016-07-01T03:00:00.000+08:00| 25.044| +|2016-07-01T04:00:00.000+08:00| 21.948| +| ...... | ...... | +|2016-07-04T19:00:00.000+08:00| 29.546| +|2016-07-04T20:00:00.000+08:00| 29.475| +|2016-07-04T21:00:00.000+08:00| 29.264| +|2016-07-04T22:00:00.000+08:00| 30.953| +|2016-07-04T23:00:00.000+08:00| 31.726| ++-----------------------------+---------------+ +Total line number = 96 + +IoTDB> call inference(sundial,"select OT from root.db.**", generateTime=True, outputLength=48) ++-----------------------------+------------------+ +| Time| output| ++-----------------------------+------------------+ +|2016-07-04T23:00:00.000+08:00|30.537494659423828| +|2016-07-04T23:59:22.500+08:00|29.619892120361328| +|2016-07-05T00:58:45.000+08:00|28.815832138061523| +|2016-07-05T01:58:07.500+08:00| 27.91131019592285| +|2016-07-05T02:57:30.000+08:00|26.893848419189453| +| ...... | ...... | +|2016-07-06T17:33:07.500+08:00| 24.40607261657715| +|2016-07-06T18:32:30.000+08:00| 25.00441551208496| +|2016-07-06T19:31:52.500+08:00|24.907312393188477| +|2016-07-06T20:31:15.000+08:00|25.156436920166016| +|2016-07-06T21:30:37.500+08:00|25.335433959960938| ++-----------------------------+------------------+ +Total line number = 48 +``` + +### 4.2 Model Fine-Tuning + +AINode supports model fine-tuning through SQL. + +**SQL Syntax** + +```SQL +createModel + | CREATE MODEL modelId=identifier (WITH HYPERPARAMETERS LR_BRACKET hparamPair (COMMA hparamPair)* RR_BRACKET)? FROM MODEL existingModelId=identifier ON DATASET LR_BRACKET trainingData RR_BRACKET + ; + +trainingData + : dataElement(COMMA dataElement)* + ; + +dataElement + : pathPatternElement (LR_BRACKET timeRange RR_BRACKET)? + ; + +pathPatternElement + : PATH path=prefixPath + ; +``` + +**Parameter Description** + +| Name | Description | +| ------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| modelId | The unique identifier of the fine-tuned model | +| hparamPair | Key-value pairs of hyperparameters used for fine-tuning, currently supported:
`train_epochs`: int type, number of fine-tuning epochs
`iter_per_epoch`: int type, number of iterations per epoch
`learning_rate`: double type, learning rate | +| existingModelId | The base model used for fine-tuning | +| trainingData | The dataset used for fine-tuning | + +**Example** + +1. Select the data of the measurement point root.db.etth.ot within a specified time range as the fine-tuning dataset, and create the model sundialv2 based on sundial. + +```SQL +IoTDB> CREATE MODEL sundialv2 FROM MODEL sundial ON DATASET (PATH root.db.etth.OT([1467302400000, 1467644400000))) +Msg: The statement is executed successfully. +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| +| sundialv2| sundial| fine_tuned| training| ++---------------------+---------+-----------+---------+ +``` + +2. Fine-tuning tasks are started asynchronously in the background, and logs can be seen in the AINode process; after fine-tuning is completed, query and use the new model. + +```SQL +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| +| sundialv2| sundial| fine_tuned| active| ++---------------------+---------+-----------+---------+ +``` + +### 4.3 Register Custom Models + +**Transformers models that meet the following requirements can be registered to AINode:** + +1. AINode currently uses transformers version v4.56.2, so when building the model, it is necessary to **avoid inheriting low-version (<4.50) interfaces**; +2. The model needs to inherit a type of AINode inference task pipeline (currently supports the forecasting pipeline): + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + Preprocess the input data before the inference task starts, including shape verification and numerical conversion. + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + Postprocess the output results after the inference task ends. + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + Preprocess the input data before passing it to the model for inference, verifying the shape and type of input data. + + Args: + inputs (list[dict]): + Input data, a list of dictionaries, each dictionary contains: + - 'targets': a tensor of shape (input_length,) or (target_count, input_length). + - 'past_covariates': optional, a dictionary of tensors, each tensor shape is (input_length,). + - 'future_covariates': optional, a dictionary of tensors, each tensor shape is (input_length,). + + infer_kwargs (dict, optional): Additional inference keyword parameters, such as: + - `output_length`(int): If 'future_covariates' is provided, used to validate its validity. + + Raises: + ValueError: If the input format is incorrect (e.g., missing keys, invalid tensor shapes). + + Returns: + Preprocessed and validated input data, ready for model inference. + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + Perform prediction on the given input. + + Parameters: + inputs: Input data for prediction. The type and structure depend on the specific implementation of the model. + **infer_kwargs: Additional inference parameters, such as: + - `output_length`(int): The number of time points the model should generate. + + Returns: + Prediction output, specific form depends on the specific implementation of the model. + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + Postprocess the model output after inference, verifying the shape of output tensors and ensuring they meet the expected dimensions. + + Args: + outputs: + Model output, a list of 2D tensors, each tensor shape is `[target_count, output_length]`. + + Raises: + InferenceModelInternalException: If the output tensor shape is invalid (e.g., dimension error). + ValueError: If the output format is incorrect. + + Returns: + list[torch.Tensor]: + Postprocessed output, a list of 2D tensors. + """ + pass + ``` +3. Modify the model configuration file config.json to ensure it contains the following fields: + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // Specify the model Config class + "AutoModelForCausalLM": "model.Chronos2Model" // Specify the model class + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // Specify the model's inference pipeline + "model_type": "custom_t5", // Specify the model type + } + ``` + + 1. Must specify the model Config class and model class through auto\_map; + 2. Must integrate and specify the inference pipeline class; + 3. For AINode-managed built-in (builtin) and custom (user\_defined) models, the model category (model\_type) also serves as a unique identifier. That is, the model category to be registered must not be duplicated with any existing model type. Models created through fine-tuning will inherit the model category of the original model. +4. Ensure that the model directory to be registered contains the following files, and the model configuration file name and weight file name are not customizable: + 1. Model configuration file: config.json; + 2. Model weight file: model.safetensors; + 3. Model code: other .py files. + +**The SQL syntax for registering a custom model is as follows:** + +```SQL +CREATE MODEL USING URI +``` + +**Parameter Description:** + +* **model\_id**: The unique identifier of the custom model; non-repetitive, with the following constraints: + * Allowed characters: [0-9 a-z A-Z \_ ] (letters, numbers (not at the beginning), underscore (not at the beginning)) + * Length limit: 2-64 characters + * Case-sensitive +* **uri**: The local URI address containing the model code and weights. + +**Registration Example:** + +Upload a custom Transformers model from a local path. AINode will copy the folder to the user\_defined directory. + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +After executing the SQL, the registration process will be performed asynchronously. The registration status of the model can be viewed by checking the model display (see the model display section). After the model is registered, it can be called using normal query methods to perform model inference. + +### 4.4 View Models + +Registered models can be viewed using the view command. + +```SQL +SHOW MODELS +``` + +In addition to directly displaying all model information, you can specify `model_id` to view the information of a specific model. + +```SQL +SHOW MODELS -- Only display specific model +``` + +The results of model display include the following: + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| Model ID | Model Type | Model Category | Model State | + +Where, State model state machine flow diagram as follows: + +![](/img/ainode-upgrade-state-timecho-en.png) + +State machine flow explanation: + +1. After starting AINode, executing `show models` command, only **system built-in (BUILTIN)** models can be viewed. +2. Users can import their own models, which are identified as **user-defined (USER_DEFINED)**; AINode will attempt to parse the model type (ModelType) from the model configuration file; if parsing fails, this field will display as empty. +3. Time series large models (built-in models) weight files are not packaged with AINode, AINode automatically downloads them when starting. + 1. During download, it is ACTIVATING, and after successful download, it becomes ACTIVE, failure becomes INACTIVE. +4. After users start a model fine-tuning task, the model state is TRAINING, and after successful training, it becomes ACTIVE, failure becomes FAILED. +5. If the fine-tuning task is successful, after fine-tuning, the model will automatically rename the best checkpoint (training file) based on the best metric and become the user-specified model\_id. + +**View Example** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| sundialx_1| sundial| fine_tuned| active| +| sundialx_4| sundial| fine_tuned| training| +| sundialx_5| sundial| fine_tuned| failed| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +Built-in traditional time series models are introduced as follows: + +| Model Name | Core Concept | Applicable Scenario | Main Features | +|------------|--------------|---------------------|---------------| +| **ARIMA** (Autoregressive Integrated Moving Average) | Combines autoregression (AR), differencing (I), and moving average (MA), used for predicting stationary time series or data that can be made stationary through differencing. | Univariate time series prediction, such as stock prices, sales, economic indicators. | 1. Suitable for linear trends and weak seasonality data. 2. Need to select parameters (p,d,q). 3. Sensitive to missing values. | +| **Holt-Winters** (Three-parameter exponential smoothing) | Based on exponential smoothing, introduces three components: level, trend, and seasonality, suitable for data with trend and seasonality. | Time series with clear seasonality and trend, such as monthly sales, power demand. | 1. Can handle additive or multiplicative seasonality. 2. Gives higher weight to recent data. 3. Simple to implement. | +| **Exponential Smoothing** | Uses weighted average of historical data, with weights decreasing exponentially over time, emphasizing the importance of recent observations. | Time series without obvious seasonality but with trend, such as short-term demand prediction. | 1. Few parameters, simple calculation. 2. Suitable for stationary or slowly changing sequences. 3. Can be extended to double or triple exponential smoothing. | +| **Naive Forecaster** | Uses the observation value from the previous period as the prediction for the next period, the simplest baseline model. | As a comparison baseline for other models, or simple prediction when data has no obvious pattern. | 1. No training required. 2. Sensitive to sudden changes. 3. Seasonal naive variant can use the value from the same period of the previous season for prediction. | +| **STL Forecaster** (Seasonal-Trend Decomposition) | Based on STL decomposition of time series, predict trend, seasonal, and residual components separately and combine. | Time series with complex seasonality, trend, and non-linear patterns, such as climate data, traffic flow. | 1. Can handle non-fixed seasonality. 2. Robust to outliers. 3. After decomposition, other models can be combined to predict each component. | +| **Gaussian HMM** (Gaussian Hidden Markov Model) | Assumes that observed data is generated by hidden states, with each state's observed probability following a Gaussian distribution. | State sequence prediction or classification, such as speech recognition, financial state recognition. | 1. Suitable for modeling time series state. 2. Assumes observed values are independent given the state. 3. Need to specify the number of hidden states. | +| **GMM HMM** (Gaussian Mixture Hidden Markov Model) | An extension of Gaussian HMM, where the observed probability of each state is described by a Gaussian Mixture Model, capturing more complex observed distributions. | Scenarios requiring multi-modal observed distributions, such as complex action recognition, bio-signal analysis. | 1. More flexible than single Gaussian. 2. More parameters, higher computational complexity. 3. Need to train the number of GMM components. | +| **STRAY** (Singular Value-based Anomaly Detection) | Detects anomalies in high-dimensional data through Singular Value Decomposition (SVD), commonly used for time series anomaly detection. | High-dimensional time series anomaly detection, such as sensor networks, IT system monitoring. | 1. No distribution assumption required. 2. Can handle high-dimensional data. 3. Sensitive to global anomalies, may miss local anomalies. | + +Built-in time series large models are introduced as follows: + +| Model Name | Core Concept | Applicable Scenario | Main Features | +|------------|--------------|---------------------|---------------| +| **Timer-XL** | Time series large model supporting ultra-long context, enhanced generalization ability through large-scale industrial data pre-training. | Complex industrial prediction requiring extremely long historical data, such as energy, aerospace, transportation. | 1. Ultra-long context support, can handle tens of thousands of time points as input. 2. Multi-scenario coverage, supports non-stationary, multi-variable, and covariate prediction. 3. Pre-trained on trillions of high-quality industrial time series data. | +| **Timer-Sundial** | A generative foundational model using "Transformer + TimeFlow" architecture, focused on probabilistic prediction. | Zero-shot prediction scenarios requiring quantification of uncertainty, such as finance, supply chain, new energy power generation. | 1. Strong zero-shot generalization ability, supports point prediction and probabilistic prediction. 2. Flexible analysis of any statistical characteristics of the prediction distribution. 3. Innovative generative architecture, achieving efficient non-deterministic sample generation. | +| **Chronos-2** | A universal time series foundational model based on discrete tokenization paradigm, transforming prediction into language modeling tasks. | Fast zero-shot univariate prediction, and scenarios that can leverage covariates (e.g., promotions, weather) to improve results. | 1. Strong zero-shot probabilistic prediction ability. 2. Supports covariate unified modeling, but has strict input requirements: a. The set of names of future covariates must be a subset of the set of names of historical covariates; b. The length of each historical covariate must equal the length of the target variable; c. The length of each future covariate must equal the prediction length; 3. Uses an efficient encoder-based structure, balancing performance and inference speed. | + +### 4.5 Delete Models + +For registered models, users can delete them through SQL. AINode will delete the corresponding model folder in the user\_defined directory. The SQL syntax is as follows: + +```SQL +DROP MODEL +``` + +The model id that has been successfully registered must be specified to delete the corresponding model. Since model deletion involves model data cleanup, the operation will not be completed immediately, and the model status becomes DROPPING, and the model in this state cannot be used for model inference. Note that this feature does not support deleting built-in models. + +### 4.6 Load/Unload Models + +To adapt to different scenarios, AINode provides the following two model loading strategies: + +* **On-demand loading**: Load the model temporarily when inference is performed, and release resources after completion. Suitable for testing or low-load scenarios. +* **Persistent loading**: Load the model persistently in memory (CPU) or GPU memory, to support high-concurrency inference. Users only need to specify the model to load or unload through SQL, and AINode will automatically manage the number of instances. The status of the persistent model can also be viewed at any time. + +The following sections will detail the loading/unloading model content: + +1. Configuration parameters + +Support editing the following configuration items to set persistent loading related parameters. + +```Properties +# The proportion of device memory/GPU memory available for AINode inference +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# The proportion of memory that each loaded model instance needs to occupy, i.e., model occupancy * this value +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. Show available devices + +Support viewing all available device IDs through the following SQL command. + +```SQL +SHOW AI_DEVICES +``` + +Example + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. Load model + +Support loading models through the following SQL command, and the system will **automatically balance** the number of model instances based on hardware resource usage. + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +Parameter requirements + +* **existing\_model\_id:** The model id to be specified, current version only supports timer\_xl and sundial. +* **device\_id:** The location where the model is loaded. + * **cpu:** Load to the memory of the AINode server. + * **gpu\_id:** Load to the corresponding GPU of the AINode server, e.g., "0, 1" means load to the two GPUs numbered 0 and 1. + +Example + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. Unload model + +Support unloading specified models through the following SQL command, and the system will **reallocate** the freed resources to other models. + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +Parameter requirements + +* **existing\_model\_id:** The model id to be specified, current version only supports timer\_xl and sundial. +* **device\_id:** The location where the model is loaded. + * **cpu:** Attempt to unload the specified model from the memory of the AINode server. + * **gpu\_id:** Attempt to unload the specified model from the corresponding GPU of the AINode server, e.g., "0, 1" means attempt to unload from the two GPUs numbered 0 and 1. + +Example + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. Show loaded models + +Support viewing the models that have been manually loaded through the following SQL command, and you can specify the device via `device_id`. + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # View models in specified devices +``` + +Example: sundial model is loaded on memory, gpu_0, and gpu_1 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +Explanation: +* DeviceId: Device ID +* ModelId: Loaded model ID +* Count(instances): Number of model instances on each device (automatically assigned by the system) + +### 4.7 Introduction to Time Series Large Models + +AINode currently supports multiple time series large models. For related introductions and deployment usage, please refer to [Time Series Large Models](../AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md) + +## 5. Permission Management + +When using AINode related features, you can use IoTDB's own authentication for permission management. Users can only use the model management related features if they have the USE_MODEL permission. When using the inference feature, users need to have permission to access the source sequence corresponding to the SQL for the input model. + +| Permission Name | Permission Scope | Administrator User (Default ROOT) | Ordinary User | Path-related | +| --------------- | ----------------- | ------------------------------- | -------------- | ------------ | +| USE_MODEL | create model / show models / drop model | √ | √ | x | +| READ_DATA | call inference | √ | √ | √ | \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade.md b/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade.md new file mode 100644 index 000000000..440615354 --- /dev/null +++ b/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: TimeSeries-Large-Model_Upgrade_apache.html +--- + diff --git a/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md b/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md new file mode 100644 index 000000000..bc20138a4 --- /dev/null +++ b/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md @@ -0,0 +1,157 @@ + +# Time Series Large Models + +## 1. Introduction + +Time Series Large Models are foundational models specifically designed for time series data analysis. The IoTDB team has been developing the Timer, a self-researched foundational time series model, which is based on the Transformer architecture and pre-trained on massive multi-domain time series data, supporting downstream tasks such as time series forecasting, anomaly detection, and time series imputation. The AINode platform developed by the team also supports the integration of cutting-edge time series foundational models from the industry, providing users with diverse model options. Unlike traditional time series analysis techniques, these large models possess universal feature extraction capabilities and can serve a wide range of analytical tasks through zero-shot analysis, fine-tuning, and other services. + +All technical achievements in the field of time series large models related to this paper (including both the team's self-researched models and industry-leading directions) have been published in top international machine learning conferences, with specific details in the appendix. + +## 2. Application Scenarios + +* **Time Series Forecasting**: Providing time series data forecasting services for industrial production, natural environments, and other fields to help users understand future trends in advance. +* **Data Imputation**: Performing context-based filling for missing segments in time series to enhance the continuity and integrity of the dataset. +* **Anomaly Detection**: Using autoregressive analysis technology to monitor time series data in real-time, promptly alerting potential anomalies. + +![](/img/LargeModel10.png) + +## 3. Timer-1 Model + +The Timer model (non-built-in model) not only demonstrates excellent few-shot generalization and multi-task adaptability, but also acquires a rich knowledge base through pre-training, endowing it with universal capabilities to handle diverse downstream tasks, with the following characteristics: + +* **Generalizability**: The model can achieve industry-leading deep model prediction results through fine-tuning with only a small number of samples. +* **Universality**: The model design is flexible, capable of adapting to various different task requirements, and supports variable input and output lengths, enabling it to function effectively in various application scenarios. +* **Scalability**: As the number of model parameters increases or the scale of pre-training data expands, the model's performance will continue to improve, ensuring that the model can continuously optimize its prediction effectiveness as time and data volume grow. + +![](/img/model01.png) + +## 4. Timer-XL Model + +Timer-XL further extends and upgrades the network structure based on Timer, achieving comprehensive breakthroughs in multiple dimensions: + +* **Ultra-Long Context Support**: This model breaks through the limitations of traditional time series forecasting models, supporting the processing of inputs with thousands of Tokens (equivalent to tens of thousands of time points), effectively solving the context length bottleneck problem. +* **Coverage of Multi-Variable Forecasting Scenarios**: Supports various forecasting scenarios, including the prediction of non-stationary time series, multi-variable prediction tasks, and predictions involving covariates, meeting diversified business needs. +* **Large-Scale Industrial Time Series Dataset**: Pre-trained on a trillion-scale time series dataset from the industrial IoT field, the dataset possesses important characteristics such as massive scale, excellent quality, and rich domain coverage, covering multiple fields including energy, aerospace, steel, and transportation. + +![](/img/model02.png) + +## 5. Timer-Sundial Model + +Timer-Sundial is a series of generative foundational models focused on time series forecasting. The base version has 128 million parameters and has been pre-trained on 1 trillion time points, with the following core characteristics: + +* **Strong Generalization Performance**: Possesses zero-shot forecasting capabilities and can support both point forecasting and probabilistic forecasting simultaneously. +* **Flexible Prediction Distribution Analysis**: Not only can it predict means or quantiles, but it can also evaluate any statistical properties of the prediction distribution through the raw samples generated by the model. +* **Innovative Generative Architecture**: Employs a "Transformer + TimeFlow" collaborative architecture - the Transformer learns the autoregressive representations of time segments, while the TimeFlow module transforms random noise into diverse prediction trajectories based on the flow-matching framework (Flow-Matching), achieving efficient generation of non-deterministic samples. + +![](/img/model03.png) + +## 6. Chronos-2 Model + +Chronos-2 is a universal time series foundational model developed by the Amazon Web Services (AWS) research team, evolved from the Chronos discrete token modeling paradigm. This model is suitable for both zero-shot univariate forecasting and covariate forecasting. Its main characteristics include: + +* **Probabilistic Forecasting Capability**: The model outputs multi-step prediction results in a generative manner, supporting quantile or distribution-level forecasting to characterize future uncertainty. +* **Zero-Shot General Forecasting**: Leveraging the contextual learning ability acquired through pre-training, it can directly execute forecasting on unseen datasets without retraining or parameter updates. +* **Unified Modeling of Multi-Variable and Covariates**: Supports joint modeling of multiple related time series and their covariates under the same architecture to improve prediction performance for complex tasks. However, it has strict input requirements: + * The set of names of future covariates must be a subset of the set of names of historical covariates; + * The length of each historical covariate must equal the length of the target variable; + * The length of each future covariate must equal the prediction length; +* **Efficient Inference and Deployment**: The model adopts a compact encoder-only structure, maintaining strong generalization capabilities while ensuring inference efficiency. + +![](/img/timeseries-large-model-chronos2.png) + +## 7. Performance Showcase + +Time Series Large Models can adapt to real time series data from various different domains and scenarios, demonstrating excellent processing capabilities across various tasks. The following shows the actual performance on different datasets: + +**Time Series Forecasting:** + +Leveraging the forecasting capabilities of Time Series Large Models, future trends of time series can be accurately predicted. The blue curve in the following figure represents the predicted trend, while the red curve represents the actual trend, with both curves highly consistent. + +![](/img/LargeModel03.png) + +**Data Imputation:** + +Using Time Series Large Models to fill missing data segments through predictive imputation. + +![](/img/timeseries-large-model-data-imputation.png) + +**Anomaly Detection:** + +Using Time Series Large Models to accurately identify outliers that deviate significantly from the normal trend. + +![](/img/LargeModel05.png) + +## 8. Deployment and Usage + +1. Open the IoTDB CLI console and check that the ConfigNode, DataNode, and AINode nodes are all Running. + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. In an online environment, the first startup of the AINode node will automatically pull the Timer-XL, Sundial, and Chronos2 models. + + > Note: + > + > * The AINode installation package does not include model weight files. + > * The automatic pull feature depends on the deployment environment having HuggingFace network access capability. + > * AINode supports manual upload of model weight files. For specific operation methods, refer to [Importing Weight Files](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md#_3-3-importing-built-in-weight-files). + +3. Check if the models are available. + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### Appendix + +**[1]** Timer: Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[2]** TIMER-XL: LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING, Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[3]** Sundial: A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ Back]() + +**[4]** Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821**. [↩ Back]() \ No newline at end of file diff --git a/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md b/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md new file mode 100644 index 000000000..c7fde0bf2 --- /dev/null +++ b/src/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md @@ -0,0 +1,157 @@ + +# Time Series Large Models + +## 1. Introduction + +Time Series Large Models are foundational models specifically designed for time series data analysis. The IoTDB team has been developing the Timer, a self-researched foundational time series model, which is based on the Transformer architecture and pre-trained on massive multi-domain time series data, supporting downstream tasks such as time series forecasting, anomaly detection, and time series imputation. The AINode platform developed by the team also supports the integration of cutting-edge time series foundational models from the industry, providing users with diverse model options. Unlike traditional time series analysis techniques, these large models possess universal feature extraction capabilities and can serve a wide range of analytical tasks through zero-shot analysis, fine-tuning, and other services. + +All technical achievements in the field of time series large models related to this paper (including both the team's self-researched models and industry-leading directions) have been published in top international machine learning conferences, with specific details in the appendix. + +## 2. Application Scenarios + +* **Time Series Forecasting**: Providing time series data forecasting services for industrial production, natural environments, and other fields to help users understand future trends in advance. +* **Data Imputation**: Performing context-based filling for missing segments in time series to enhance the continuity and integrity of the dataset. +* **Anomaly Detection**: Using autoregressive analysis technology to monitor time series data in real-time, promptly alerting potential anomalies. + +![](/img/LargeModel10.png) + +## 3. Timer-1 Model + +The Timer model (non-built-in model) not only demonstrates excellent few-shot generalization and multi-task adaptability, but also acquires a rich knowledge base through pre-training, endowing it with universal capabilities to handle diverse downstream tasks, with the following characteristics: + +* **Generalizability**: The model can achieve industry-leading deep model prediction results through fine-tuning with only a small number of samples. +* **Universality**: The model design is flexible, capable of adapting to various different task requirements, and supports variable input and output lengths, enabling it to function effectively in various application scenarios. +* **Scalability**: As the number of model parameters increases or the scale of pre-training data expands, the model's performance will continue to improve, ensuring that the model can continuously optimize its prediction effectiveness as time and data volume grow. + +![](/img/model01.png) + +## 4. Timer-XL Model + +Timer-XL further extends and upgrades the network structure based on Timer, achieving comprehensive breakthroughs in multiple dimensions: + +* **Ultra-Long Context Support**: This model breaks through the limitations of traditional time series forecasting models, supporting the processing of inputs with thousands of Tokens (equivalent to tens of thousands of time points), effectively solving the context length bottleneck problem. +* **Coverage of Multi-Variable Forecasting Scenarios**: Supports various forecasting scenarios, including the prediction of non-stationary time series, multi-variable prediction tasks, and predictions involving covariates, meeting diversified business needs. +* **Large-Scale Industrial Time Series Dataset**: Pre-trained on a trillion-scale time series dataset from the industrial IoT field, the dataset possesses important characteristics such as massive scale, excellent quality, and rich domain coverage, covering multiple fields including energy, aerospace, steel, and transportation. + +![](/img/model02.png) + +## 5. Timer-Sundial Model + +Timer-Sundial is a series of generative foundational models focused on time series forecasting. The base version has 128 million parameters and has been pre-trained on 1 trillion time points, with the following core characteristics: + +* **Strong Generalization Performance**: Possesses zero-shot forecasting capabilities and can support both point forecasting and probabilistic forecasting simultaneously. +* **Flexible Prediction Distribution Analysis**: Not only can it predict means or quantiles, but it can also evaluate any statistical properties of the prediction distribution through the raw samples generated by the model. +* **Innovative Generative Architecture**: Employs a "Transformer + TimeFlow" collaborative architecture - the Transformer learns the autoregressive representations of time segments, while the TimeFlow module transforms random noise into diverse prediction trajectories based on the flow-matching framework (Flow-Matching), achieving efficient generation of non-deterministic samples. + +![](/img/model03.png) + +## 6. Chronos-2 Model + +Chronos-2 is a universal time series foundational model developed by the Amazon Web Services (AWS) research team, evolved from the Chronos discrete token modeling paradigm. This model is suitable for both zero-shot univariate forecasting and covariate forecasting. Its main characteristics include: + +* **Probabilistic Forecasting Capability**: The model outputs multi-step prediction results in a generative manner, supporting quantile or distribution-level forecasting to characterize future uncertainty. +* **Zero-Shot General Forecasting**: Leveraging the contextual learning ability acquired through pre-training, it can directly execute forecasting on unseen datasets without retraining or parameter updates. +* **Unified Modeling of Multi-Variable and Covariates**: Supports joint modeling of multiple related time series and their covariates under the same architecture to improve prediction performance for complex tasks. However, it has strict input requirements: + * The set of names of future covariates must be a subset of the set of names of historical covariates; + * The length of each historical covariate must equal the length of the target variable; + * The length of each future covariate must equal the prediction length; +* **Efficient Inference and Deployment**: The model adopts a compact encoder-only structure, maintaining strong generalization capabilities while ensuring inference efficiency. + +![](/img/timeseries-large-model-chronos2.png) + +## 7. Performance Showcase + +Time Series Large Models can adapt to real time series data from various different domains and scenarios, demonstrating excellent processing capabilities across various tasks. The following shows the actual performance on different datasets: + +**Time Series Forecasting:** + +Leveraging the forecasting capabilities of Time Series Large Models, future trends of time series can be accurately predicted. The blue curve in the following figure represents the predicted trend, while the red curve represents the actual trend, with both curves highly consistent. + +![](/img/LargeModel03.png) + +**Data Imputation:** + +Using Time Series Large Models to fill missing data segments through predictive imputation. + +![](/img/timeseries-large-model-data-imputation.png) + +**Anomaly Detection:** + +Using Time Series Large Models to accurately identify outliers that deviate significantly from the normal trend. + +![](/img/LargeModel05.png) + +## 8. Deployment and Usage + +1. Open the IoTDB CLI console and check that the ConfigNode, DataNode, and AINode nodes are all Running. + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. In an online environment, the first startup of the AINode node will automatically pull the Timer-XL, Sundial, and Chronos2 models. + + > Note: + > + > * The AINode installation package does not include model weight files. + > * The automatic pull feature depends on the deployment environment having HuggingFace network access capability. + > * AINode supports manual upload of model weight files. For specific operation methods, refer to [Importing Weight Files](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md#_3-3-importing-built-in-weight-files). + +3. Check if the models are available. + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### Appendix + +**[1]** Timer: Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[2]** TIMER-XL: LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING, Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[3]** Sundial: A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ Back]() + +**[4]** Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821**. [↩ Back]() \ No newline at end of file diff --git a/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade.md b/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade.md new file mode 100644 index 000000000..6f44068b6 --- /dev/null +++ b/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: AINode_Upgrade_apache.html +--- + \ No newline at end of file diff --git a/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade_apache.md b/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade_apache.md new file mode 100644 index 000000000..548c22f69 --- /dev/null +++ b/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade_apache.md @@ -0,0 +1,540 @@ + + +# AINode + +AINode is a native IoTDB node designed for registering, managing, and invoking time series-related models. It integrates industry-leading self-developed time series large models—such as the Timer series developed by Tsinghua University—and supports millisecond-level real-time inference on time series data via standard SQL statements. It enables key application scenarios including time series trend forecasting, missing value imputation, and anomaly detection. + +System architecture is illustrated below: + +![](/img/AINode-0-en.png) + +Responsibilities of the three node types are as follows: + +* **ConfigNode**: Manages distributed nodes and handles load balancing. +* **DataNode**: Receives and parses user SQL requests; stores time series data; performs data preprocessing computations. +* **AINode**: Manages and utilizes time series models. + +## 1. Advantages and Features + +Compared to building a standalone machine learning service, AINode offers the following benefits: + +* **Ease of Use**: No Python or Java programming required. Complete model management and inference workflows are achievable via SQL statements. For example, use `CREATE MODEL` to register a model and ` SELECT * FROM FORECAST (...) ` for inference—simple and efficient. +* **Eliminates Data Migration**: IoTDB-native machine learning enables direct inference on data stored within IoTDB, avoiding data transfer to external ML platforms. This accelerates processing, enhances security, and reduces costs. + +![](/img/h1.png) + +* **Built-in Advanced Algorithms**: Integrates state-of-the-art machine learning algorithms covering typical time series analysis tasks, empowering IoTDB with native analytical capabilities: + * **Time Series Forecasting**: Learns patterns from historical sequences to predict future values based on past observations. + * **Anomaly Detection for Time Series**: Detects and identifies outliers in time series data to uncover abnormal behaviors. + +## 2. Core Concepts + +* **Model**: A machine learning model that takes time series data as input and outputs analytical results or decisions. Models are the fundamental management units in AINode, supporting creation (registration), deletion, querying, and inference. +* **Create**: Loads externally designed or trained model files/algorithms into AINode for unified management and usage. +* **Inference**: Applies a registered model to perform time series analysis tasks on specified data. +* **Built-in Capability**: AINode includes native algorithms/models for common time series scenarios (e.g., forecasting and anomaly detection). + +![](/img/AINode-en.png) + +## 3. Installation and Deployment + +Refer to the documentation [AINode Deployment](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md) for deployment instructions. + +## 4. Usage Guide + +AINode supports two core functionalities: model inference and model management (registration, viewing, deletion, loading, unloading). Details follow. + +### 4.1 Model Inference + +AINode supports forecasting inference on single target variables. Syntax, parameters, and examples are provided below. + +1. **SQL Syntax** + +```SQL +SELECT * FROM FORECAST( + MODEL_ID, + TARGETS, -- SQL to retrieve target variables + OUTPUT_START_TIME, + OUTPUT_LENGTH, + OUTPUT_INTERVAL, + TIMECOL, + PRESERVE_INPUT, + [MODEL_OPTIONS]? +) +``` + +* Built-in models require no registration. Specify `model_id` in the `forecast` function to invoke inference. +* Parameter Description + +| Parameter Name | Type | Attribute | Description | Required | Notes | +|---------------------|-----------|------------------------------------------------------|-----------------------------------------------------------------------------|----------|-----------------------------------------------------------------------| +| model_id | Scalar | String | Unique identifier of the forecasting model | Yes | | +| targets | Table | SET SEMANTIC | Input data for target variables. IoTDB automatically sorts data by time before sending to AINode | Yes | Invalid SQL in this clause triggers query errors | +| output_start_time | Scalar | Timestamp. Default: last timestamp of targets + output_interval | Start timestamp of forecast output (issue time) | No | Must be later than the maximum timestamp in targets | +| output_length | Scalar | INT32. Default: 96 | Output window size | No | Must be > 0 | +| output_interval | Scalar | Interval. Default: (last_ts - first_ts) / (n - 1) | Time interval between forecast points (units: ns, us, ms, s, m, h, d, w) | No | Must be > 0 | +| timecol | Scalar | String. Default: "time" | Name of the time column | No | Must exist in `targets` and be of TIMESTAMP type | +| preserve_input | Scalar | Boolean. Default: false | Whether to retain all original input rows in output | No | | +| model_options | Scalar | String. Default: empty string | Model-specific key-value pairs (e.g., normalization settings); separated by ';' | No | | + +Notes: +* **Default Behavior**: Forecasts all columns in `targets`. Currently supports INT32, INT64, FLOAT, DOUBLE types only. +* **Input Requirements**: + * Must include a time column. + * Row count: Errors if below minimum; truncates to latest rows if exceeding maximum. +* **Output**: + * Contains all target variable columns with original data types. + * If `preserve_input=true`, adds an `is_input` column to mark original rows. +* **Timestamp Generation**: + * Uses `OUTPUT_START_TIME` (optional) as forecast start point. + * Uses `OUTPUT_INTERVAL` (optional, defaults to input sampling interval). Timestamp of row N: `OUTPUT_START_TIME + (N - 1) * OUTPUT_INTERVAL`. + +2. **Usage Example** + +Create database `etth` and table `eg`: + +```SQL +CREATE DATABASE etth; +CREATE TABLE eg (hufl FLOAT FIELD, hull FLOAT FIELD, mufl FLOAT FIELD, mull FLOAT FIELD, lufl FLOAT FIELD, lull FLOAT FIELD, ot FLOAT FIELD) +``` + +Prepare source data [ETTh1-tab](/img/ETTh1-tab.csv) + +Forecast 96 future values of sensor `ot` using its latest 96 historical records: + +```SQL +IoTDB:etth> SELECT Time, HUFL, HULL, MUFL, MULL, LUFL, LULL, OT FROM eg LIMIT 96 ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +| Time| HUFL| HULL| MUFL| MULL| LUFL| LULL| OT| ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +|2016-07-01T00:00:00.000+08:00| 5.827|2.009|1.599|0.462|4.203| 1.34|30.531| +|2016-07-01T01:00:00.000+08:00| 5.693|2.076|1.492|0.426|4.142|1.371|27.787| +|2016-07-01T02:00:00.000+08:00| 5.157|1.741|1.279|0.355|3.777|1.218|27.787| +|2016-07-01T03:00:00.000+08:00| 5.09|1.942|1.279|0.391|3.807|1.279|25.044| +...... +Total line number = 96 +It costs 0.119s + +IoTDB:etth> SELECT * FROM forecast( + model_id => 'sundial', + targets => (SELECT Time, ot FROM etth.eg WHERE time >= 2016-08-07T18:00:00.000+08:00 LIMIT 1440) ORDER BY time, + output_length => 96 +) ++-----------------------------+---------+ +| time| ot| ++-----------------------------+---------+ +|2016-10-06T18:00:00.000+08:00|20.781654| +|2016-10-06T19:00:00.000+08:00|20.252121| +|2016-10-06T20:00:00.000+08:00|19.960138| +|2016-10-06T21:00:00.000+08:00|19.662334| +...... +Total line number = 96 +It costs 1.615s +``` + +### 4.2 Registering Custom Models + +**Transformers models meeting the following criteria can be registered to AINode:** + +1. AINode uses Transformers v4.56.2; avoid inheriting interfaces from older versions (<4.50). +2. The model must inherit an AINode inference pipeline class (currently supports forecasting pipeline): + ```python + # iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic_pipeline.py + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """Preprocess input data before inference, including shape validation and numerical conversion.""" + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """Postprocess model outputs after inference.""" + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + Preprocess and validate input data before model inference. + + Args: + inputs (list[dict]): + Input data as list of dicts containing: + - 'targets': Tensor of shape (input_length,) or (target_count, input_length). + - 'past_covariates': Optional dict of tensors, each of shape (input_length,). + - 'future_covariates': Optional dict of tensors, each of shape (input_length,). + infer_kwargs (dict, optional): Additional inference parameters, e.g.: + - `output_length` (int): Required if 'future_covariates' provided for validation. + + Raises: + ValueError: For invalid input formats (missing keys, invalid tensor shapes). + + Returns: + Preprocessed and validated input ready for model inference. + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + Perform forecasting on given inputs. + + Parameters: + inputs: Input data for forecasting (type/structure model-specific). + **infer_kwargs: Additional parameters, e.g.: + - `output_length` (int): Number of future time points to generate. + + Returns: + Forecast output (format model-specific). + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + Postprocess model outputs, validate shapes, and ensure expected dimensions. + + Args: + outputs: List of 2D tensors, each of shape `[target_count, output_length]`. + + Raises: + InferenceModelInternalException: For invalid output tensor shapes. + ValueError: For incorrect output format. + + Returns: + List of postprocessed 2D tensors. + """ + pass + ``` +3. Modify `config.json` to include: + ```json + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", + "AutoModelForCausalLM": "model.Chronos2Model" + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", + "model_type": "custom_t5" + } + ``` + * Must specify model Config and model classes via `auto_map`. + * Must implement and specify the inference pipeline class. + * `model_type` serves as a unique identifier. Must not conflict with existing model types (for both `builtin` and `user_defined` models). +4. Ensure the model directory contains: + * `config.json` (model configuration) + * `model.safetensors` (model weights) + * Other `.py` files (model code) + * *Note: Filenames for config and weights are fixed and non-customizable.* + +**SQL Syntax for Registration:** +```SQL +CREATE MODEL USING URI +``` + +**Parameter Details:** +* **model_id**: Unique identifier for the custom model (case-sensitive): + * Allowed characters: `[0-9a-zA-Z_]` (alphanumeric and underscore; cannot start with digit/underscore) + * Length: 2–64 characters +* **uri**: Local URI path containing model code and weights. + +**Registration Example:** +Upload a custom Transformers model from local path. AINode copies the folder to the `user_defined` directory. +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` +Registration proceeds asynchronously. Check status via `SHOW MODELS` (see Section 4.3). After successful registration, invoke inference via standard queries. + +### 4.3 Viewing Models + +Registered models can be queried using: +```SQL +SHOW MODELS +``` +Filter by specific model: +```SQL +SHOW MODELS -- Display specific model only +``` + +Result columns: + +| **ModelId** | **ModelType** | **Category** | **State** | +|-------------|---------------|--------------|-----------| +| Model ID | Model Type | Category | State | + +State transition diagram: + +![](/img/ainode-upgrade-state-apache-en.png) + +State Flow Explanation: +1. After AINode startup, `SHOW MODELS` displays only **system built-in (BUILTIN)** models. +2. User-uploaded models are marked as **user-defined (USER_DEFINED)**. AINode attempts to parse `ModelType` from config; displays empty if parsing fails. +3. Time series large model weights (built-in) are not bundled with AINode. Download occurs on startup: + * `ACTIVATING` during download → `ACTIVE` on success → `INACTIVE` on failure. + +**Viewing Example:** +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +**Built-in Traditional Time Series Models:** + +| Model Name | Core Concept | Applicable Scenarios | Key Features | +|-----------------------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------------------------| +| **ARIMA** (Autoregressive Integrated Moving Average) | Combines AR, differencing (I), and MA for stationary or differenced series | Univariate forecasting (stock prices, sales, economics) | 1. For linear trends with weak seasonality2. Requires (p,d,q) tuning3. Sensitive to missing values | +| **Holt-Winters** (Triple Exponential Smoothing) | Exponential smoothing with level, trend, and seasonal components | Data with clear trend & seasonality (monthly sales, power demand) | 1. Handles additive/multiplicative seasonality2. Weights recent data higher3. Simple implementation | +| **Exponential Smoothing** | Weighted average of history with exponentially decaying weights | Trending but non-seasonal data (short-term demand) | 1. Few parameters, simple computation2. Suitable for stable/slow-changing series3. Extensible to double/triple smoothing | +| **Naive Forecaster** | Uses last observation as next prediction (simplest baseline) | Benchmarking or data with no clear pattern | 1. No training needed2. Sensitive to sudden changes3. Seasonal variant uses prior season value | +| **STL Forecaster** | Decomposes series into trend, seasonal, residual; forecasts components | Complex seasonality/trends (climate, traffic) | 1. Handles non-fixed seasonality2. Robust to outliers3. Components can use other models | +| **Gaussian HMM** | Hidden states generate observations; each state follows Gaussian distribution | State sequence prediction/classification (speech, finance) | 1. Models temporal state transitions2. Observations independent per state3. Requires state count | +| **GMM HMM** | Extends Gaussian HMM; each state uses Gaussian Mixture Model | Multi-modal observation scenarios (motion recognition, biosignals) | 1. More flexible than single Gaussian2. Higher complexity3. Requires GMM component count | +| **STRAY** (Search for Outliers using Random Projection and Adaptive Thresholding) | Uses SVD to detect anomalies in high-dimensional time series | High-dimensional anomaly detection (sensor networks, IT monitoring) | 1. No distribution assumption2. Handles high dimensions3. Sensitive to global anomalies | + +**Built-in Time Series Large Models:** + +| Model Name | Core Concept | Applicable Scenarios | Key Features | +|-----------------|------------------------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------------------------| +| **Timer-XL** | Long-context time series large model pretrained on massive industrial data | Complex industrial forecasting requiring ultra-long history (energy, aerospace, transport) | 1. Supports input of tens of thousands of time points2. Covers non-stationary, multivariate, and covariate scenarios3. Pretrained on trillion-scale high-quality industrial IoT data | +| **Timer-Sundial** | Generative foundation model with "Transformer + TimeFlow" architecture | Zero-shot forecasting requiring uncertainty quantification (finance, supply chain, renewable energy) | 1. Strong zero-shot generalization; supports point & probabilistic forecasting2. Flexible analysis of any prediction distribution statistic3. Innovative flow-matching architecture for efficient non-deterministic sample generation | +| **Chronos-2** | Universal time series foundation model based on discrete tokenization | Rapid zero-shot univariate forecasting; scenarios enhanced by covariates (promotions, weather) | 1. Powerful zero-shot probabilistic forecasting2. Unified multi-variable & covariate modeling (strict input requirements):  a. Future covariate names ⊆ historical covariate names  b. Each historical covariate length = target length  c. Each future covariate length = prediction length3. Efficient encoder-only structure balancing performance and speed | + +### 4.4 Deleting Models + +Registered models can be deleted via SQL. AINode removes the corresponding folder under `user_defined`. Syntax: +```SQL +DROP MODEL +``` +* Specify a successfully registered `model_id`. +* Deletion is asynchronous; model enters `DROPPING` state (unavailable for inference during this phase). +* **Built-in models cannot be deleted.** + +### 4.5 Loading/Unloading Models + +AINode supports two loading strategies: +* **On-Demand Loading**: Load model temporarily during inference, then release resources. Suitable for testing or low-load scenarios. +* **Persistent Loading**: Keep model instances resident in CPU memory or GPU VRAM to support high-concurrency inference. Users specify load/unload targets via SQL; AINode auto-manages instance counts. Current loaded status is queryable. + +Details below: + +1. **Configuration Parameters** + Edit these settings to control persistent loading behavior: + ```properties + # Ratio of total device memory/VRAM usable by AINode for inference + # Datatype: Float + ain_inference_memory_usage_ratio=0.4 + + # Memory overhead ratio per loaded model instance (model_size * this_value) + # Datatype: Float + ain_inference_extra_memory_ratio=1.2 + ``` + +2. **List Available Devices** + ```SQL + SHOW AI_DEVICES + ``` + Example: + ```SQL + IoTDB> SHOW AI_DEVICES + +-------------+ + | DeviceId| + +-------------+ + | cpu| + | 0| + | 1| + +-------------+ + ``` + +3. **Load Model** + Manually load model; system auto-balances instance count based on resources: + ```SQL + LOAD MODEL TO DEVICES (, )* + ``` + Parameters: + * `existing_model_id`: Model ID (current version supports `timer_xl` and `sundial` only) + * `device_id`: + * `cpu`: Load into server memory + * `gpu_id`: Load into specified GPU(s), e.g., `'0,1'` for GPUs 0 and 1 + Example: + ```SQL + LOAD MODEL sundial TO DEVICES 'cpu,0,1' + ``` + +4. **Unload Model** + Unload all instances of a model; system reallocates freed resources: + ```SQL + UNLOAD MODEL FROM DEVICES (, )* + ``` + Parameters same as `LOAD MODEL`. + Example: + ```SQL + UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' + ``` + +5. **View Loaded Models** + ```SQL + SHOW LOADED MODELS + SHOW LOADED MODELS (, )* -- Filter by device + ``` + Example (sundial loaded on CPU, GPU 0, GPU 1): + ```SQL + IoTDB> SHOW LOADED MODELS + +-------------+--------------+------------------+ + | DeviceId| ModelId| Count(instances)| + +-------------+--------------+------------------+ + | cpu| sundial| 4| + | 0| sundial| 6| + | 1| sundial| 6| + +-------------+--------------+------------------+ + ``` + * `DeviceId`: Device identifier + * `ModelId`: Loaded model ID + * `Count(instances)`: Number of model instances per device (auto-assigned by system) + +### 4.6 Time Series Large Models Overview + +AINode supports multiple time series large models. For detailed introduction and deployment guidance, refer to [Time Series Large Models](../AI-capability/TimeSeries-Large-Model_Upgrade_apache.md). + +## 5. Permission Management + +AINode leverages IoTDB's native authentication system. Users require `USE_MODEL` permission to manage models. For inference, users must have access permissions to source time series referenced in the input SQL. + +| **Permission Name** | **Scope** | **Admin User (default ROOT)** | **Regular User** | +|---------------------|----------------------------------------|-------------------------------|------------------| +| USE_MODEL | CREATE MODEL / SHOW MODELS / DROP MODEL | √ | √ | +| READ_SCHEMA & READ_DATA | FORECAST | √ | √ | + +## 6. Contributing Open Source Time Series Large Models to IoTDB-AINode + +To add a new built-in custom model to AINode (using Chronos2 as example): + +* **Initiate Discussion** + Email [dev@iotdb.apache.org](mailto:dev@iotdb.apache.org) or open an issue in the main repository. + +* **Submit Pull Request to Main Branch** + 1. Verify the model's open-source license and declare it appropriately in the IoTDB repository. + 2. Create a new package for the model under `iotdb-core/ainode/iotdb/ainode/core/model/`: + * Include model configuration class + * Include model class for inference execution + * Include class inheriting AINode's inference pipeline + ```bash + root@rootMacBook-Pro model % eza --tree --level=2 . + . + ├── chronos2 + │ ├── __init__.py + │ ├── base.py + │ ├── chronos_bolt.py + │ ├── config.py + │ ├── dataset.py + │ ├── layers.py + │ ├── model.py + │ ├── pipeline_chronos2.py # Inherits AINode inference pipeline + │ └── utils.py + ├── sktime + ├── sundial + └── timer_xl + ``` + 3. Add model metadata in `iotdb-core/ainode/iotdb/ainode/core/model/model_info.py`: + ```python + BUILTIN_HF_TRANSFORMERS_MODEL_MAP = { + "chronos2": ModelInfo( + model_id="chronos2", + category=ModelCategory.BUILTIN, + state=ModelStates.INACTIVE, + model_type="t5", + pipeline_cls="pipeline_chronos2.Chronos2Pipeline", + repo_id="amazon/chronos-2", # [Optional] HuggingFace weights repo + auto_map={ + "AutoConfig": "config.Chronos2CoreConfig", + "AutoModelForCausalLM": "model.Chronos2Model", + }, + ), + } + ``` + 4. Add model entry in `integration-test/src/test/java/org/apache/iotdb/ainode/utils/AINodeTestUtils.java`: + ```java + public static final Map BUILTIN_LTSM_MAP = + Stream.of( + new AbstractMap.SimpleEntry<>( + "sundial", new FakeModelInfo("sundial", "sundial", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "timer_xl", new FakeModelInfo("timer_xl", "timer", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "chronos2", new FakeModelInfo("chronos2", "t5", "builtin", "active"))) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + ``` + 5. Submit PR; ensure CI tests pass before merging. + +* **Packaging and Deployment** + 1. Build AINode to generate installation package: + ```bash + # Build IoTDB and AINode together + mvn clean package -pl distribution -P with-ainode -am -DskipTests + # Build AINode only + mvn clean package -pl iotdb-core/ainode -P with-ainode -am -DskipTests + ``` + 2. Ensure model weights are accessible at runtime: + * If weights are fetchable from HuggingFace, confirm `repo_id` is set. + * Otherwise, manually place weights in `data/ainode/models/builtin/` before/during startup. + ```bash + root@rootMacBook-Pro models % eza --tree --level=3 . + . + ├── __init__.py + ├── builtin + │ ├── __init__.py + │ ├── chronos2 + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ ├── sundial + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ └── timer_xl + │ ├── __init__.py + │ ├── config.json + │ └── model.safetensors + └── user_defined + ``` + +* **Complete Example** + Reference implementation: https://github.com/apache/iotdb/pull/16903 \ No newline at end of file diff --git a/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade_timecho.md b/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade_timecho.md new file mode 100644 index 000000000..5467a5af3 --- /dev/null +++ b/src/UserGuide/latest-Table/AI-capability/AINode_Upgrade_timecho.md @@ -0,0 +1,714 @@ + + +# AINode + +AINode is a native IoTDB node that supports the registration, management, and invocation of time series related models. It includes industry-leading self-developed time series large models, such as the Timer series models developed by Tsinghua University. Models can be invoked using standard SQL statements, enabling millisecond-level real-time inference on time series data, and supporting application scenarios such as time series trend prediction, missing value filling, and anomaly value detection. + +The system architecture is shown in the following figure: + +![](/img/AINode-0-en.png) + +The responsibilities of the three nodes are as follows: + +* **ConfigNode**: Responsible for distributed node management and load balancing. +* **DataNode**: Responsible for receiving and parsing user SQL requests; responsible for storing time series data; responsible for data preprocessing calculations. +* **AINode**: Responsible for managing and using time series models. + +## 1. Advantages and Features + +Compared to building a machine learning service separately, it has the following advantages: + +* **Simple and Easy to Use**: No need to use Python or Java programming, you can complete the entire process of machine learning model management and inference using SQL statements. For example, creating a model can be done using the CREATE MODEL statement, and using a model for inference can be done using the `SELECT * FROM FORECAST (...)` statement, making it more simple and convenient. +* **Avoid Data Migration**: Using IoTDB-native machine learning can directly apply data stored in IoTDB to machine learning model inference without moving data to a separate machine learning service platform, thus accelerating data processing, improving security, and reducing costs. + +![](/img/h1.png) + +* **Built-in Advanced Algorithms**: Supports industry-leading machine learning analysis algorithms, covering typical time series analysis tasks, and empowering time series databases with native data analysis capabilities. For example: + * **Time Series Forecasting**: Learning change patterns from past time series data; outputting the most likely predictions for future sequences based on given past observations. + * **Time Series Anomaly Detection**: Detecting and identifying abnormal values in given time series data to help discover abnormal behavior in time series. + +## 2. Basic Concepts + +* **Model (Model)**: A machine learning model that takes time series data as input and outputs the results or decisions of the analysis task. The model is the basic management unit of AINode, supporting the creation (registration), deletion, query, modification (fine-tuning), and use (inference) of models. +* **Create (Create)**: Load the external designed or trained model file or algorithm into AINode, managed and used uniformly by IoTDB. +* **Inference (Inference)**: Use the created model to complete the time series analysis task on the specified time series data. +* **Built-in (Built-in)**: AINode comes with common time series analysis scenario (e.g., prediction and anomaly detection) machine learning algorithms or self-developed models. + +![](/img/AINode-en.png) + +## 3. Installation and Deployment + +AINode deployment can be referred to the documentation [AINode Deployment](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md). + +## 4. Usage Guide + +TimechoDB-AINode supports three major functions: model inference, model fine-tuning, and model management (registration, viewing, deletion, loading, unloading, etc.). The following sections will provide detailed explanations. + +### 4.1 Model Inference + +TimechoDB-AINode provides the following time series prediction capabilities: + +* **Univariate Prediction**: Supports prediction of a single target variable. +* **Covariate Prediction**: Can simultaneously predict multiple target variables and supports introducing covariates in prediction to improve accuracy. + +The following sections will detail the syntax definition, parameter descriptions, and usage examples of the prediction inference function. + +1. **SQL Syntax** + +```SQL +SELECT * FROM FORECAST( + MODEL_ID, + TARGETS, -- SQL to get target variables + [HISTORY_COVS, -- String, SQL to get historical covariates + FUTURE_COVS, -- String, SQL to get future covariates + OUTPUT_START_TIME, + OUTPUT_LENGTH, + OUTPUT_INTERVAL, + TIMECOL, + PRESERVE_INPUT, + MODEL_OPTIONS]? +) +``` + +* Built-in model inference does not require a registration process. By using the forecast function and specifying model_id, you can use the inference function of the model. +* Parameter description + +| Parameter Name | Parameter Type | Parameter Attributes | Description | Required | Notes | +|----------------|----------------|----------------------|-------------|----------|-------| +| model_id | Scalar parameter | String type | Unique identifier of the prediction model | Yes | | +| targets | Table parameter | SET SEMANTIC | Input data for the target variables to be predicted. IoTDB will automatically sort the data in ascending order of time before passing it to AINode. | Yes | Use SQL to describe the input data with target variables. If the input SQL is invalid, corresponding query errors will be reported. | +| history_covs | Scalar parameter | String type (valid table model query SQL), default: none | Specifies historical data of covariates for this prediction task, which are used to assist in predicting target variables. AINode will not output prediction results for historical covariates. Before passing data to the model, AINode will automatically sort the data in ascending order of time. | No | 1. Query results can only contain FIELD columns; 2. Other: Different models may have specific requirements, and errors will be thrown if not met. | +| future_covs | Scalar parameter | String type (valid table model query SQL), default: none | Specifies future data of some covariates for this prediction task, which are used to assist in predicting target variables. Before passing data to the model, AINode will automatically sort the data in ascending order of time. | No | 1. Can only be specified when history_covs is set; 2. The covariate names involved must be a subset of history_covs; 3. Query results can only contain FIELD columns; 4. Other: Different models may have specific requirements, and errors will be thrown if not met. | +| output_start_time | Scalar parameter | Timestamp type. Default value: last timestamp of target variable + output_interval | Starting timestamp of output prediction points [i.e., forecast start time] | No | Must be greater than the maximum timestamp of target variable timestamps | +| output_length | Scalar parameter | INT32 type. Default value: 96 | Output window size | No | Must be greater than 0 | +| output_interval | Scalar parameter | Time interval type. Default value: (last timestamp - first timestamp of input data) / n - 1 | Time interval between output prediction points. Supported units: ns, us, ms, s, m, h, d, w | No | Must be greater than 0 | +| timecol | Scalar parameter | String type. Default value: time | Name of time column | No | Must be a TIMESTAMP column existing in targets | +| preserve_input | Scalar parameter | Boolean type. Default value: false | Whether to retain all original rows of target variable input in the output result set | No | | +| model_options | Scalar parameter | String type. Default value: empty string | Key-value pairs related to the model, such as whether to normalize the input. Different key-value pairs are separated by ';'. | No | | + +Notes: +* **Default behavior**: Predict all columns of targets. Currently, only supports INT32, INT64, FLOAT, DOUBLE types. +* **Input data requirements**: + * Must contain a time column. + * Row count requirements: If insufficient, an error will be reported; if exceeding the maximum, the last data will be automatically truncated. + * Column count requirements: Univariate models only support single columns, multi-column will report errors; covariate models usually have no restrictions unless the model itself has clear constraints. +* **Output results**: + * Includes all target variable columns, with data types consistent with the original table. + * If `preserve_input=true` is specified, an additional `is_input` column will be added to identify original data rows. +* **Timestamp generation**: + * Uses `OUTPUT_START_TIME` (optional) as the starting time point for prediction and divides historical and future data. + * Uses `OUTPUT_INTERVAL` (optional, default is the sampling interval of input data) as the output time interval. The timestamp of the Nth row is calculated as: `OUTPUT_START_TIME + (N - 1) * OUTPUT_INTERVAL`. + +2. **Usage Examples** + +**Example 1: Univariate Prediction** + +Create database etth and table eg in advance + +```SQL +create database etth; +create table eg (hufl FLOAT FIELD, hull FLOAT FIELD, mufl FLOAT FIELD, mull FLOAT FIELD, lufl FLOAT FIELD, lull FLOAT FIELD, ot FLOAT FIELD) +``` + +Prepare original data [ETTh1-tab](/img/ETTh1-tab.csv) + +Use the first 96 rows of data from column ot in table eg to predict its future 96 rows of data. + +```SQL +IoTDB:etth> select Time, HUFL,HULL,MUFL,MULL,LUFL,LULL,OT from eg LIMIT 96 ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +| Time| HUFL| HULL| MUFL| MULL| LUFL| LULL| OT| ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +|2016-07-01T00:00:00.000+08:00| 5.827|2.009|1.599|0.462|4.203| 1.34|30.531| +|2016-07-01T01:00:00.000+08:00| 5.693|2.076|1.492|0.426|4.142|1.371|27.787| +|2016-07-01T02:00:00.000+08:00| 5.157|1.741|1.279|0.355|3.777|1.218|27.787| +|2016-07-01T03:00:00.000+08:00| 5.09|1.942|1.279|0.391|3.807|1.279|25.044| +...... +Total line number = 96 +It costs 0.119s + +IoTDB:etth> select * from forecast( + model_id => 'sundial', + targets => (select Time, ot from etth.eg where time >= 2016-08-07T18:00:00.000+08:00 limit 1440) order BY time, + output_length => 96 +) ++-----------------------------+---------+ +| time| ot| ++-----------------------------+---------+ +|2016-10-06T18:00:00.000+08:00|20.781654| +|2016-10-06T19:00:00.000+08:00|20.252121| +|2016-10-06T20:00:00.000+08:00|19.960138| +|2016-10-06T21:00:00.000+08:00|19.662334| +...... +Total line number = 96 +It costs 1.615s +``` + +**Example 2: Covariate Prediction** + +Create table tab_real (to store original real data) in advance + +```SQL +create table tab_real (target1 DOUBLE FIELD, target2 DOUBLE FIELD, cov1 DOUBLE FIELD, cov2 DOUBLE FIELD, cov3 DOUBLE FIELD); +``` + +Prepare original data + +```SQL +IoTDB:etth> SELECT * FROM tab_real ++-----------------------------+-------+-------+----+----+----+ +| time|target1|target2|cov1|cov2|cov3| ++-----------------------------+-------+-------+----+----+----+ +|1970-01-01T08:00:00.001+08:00| 1.0| 1.0| 1.0| 1.0| 1.0| +|1970-01-01T08:00:00.002+08:00| 2.0| 2.0| 2.0| 2.0| 2.0| +|1970-01-01T08:00:00.003+08:00| 3.0| 3.0| 3.0| 3.0| 3.0| +|1970-01-01T08:00:00.004+08:00| 4.0| 4.0| 4.0| 4.0| 4.0| +|1970-01-01T08:00:00.005+08:00| 5.0| 5.0| 5.0| 5.0| 5.0| +|1970-01-01T08:00:00.006+08:00| 6.0| 6.0| 6.0| 6.0| 6.0| +|1970-01-01T08:00:00.007+08:00| null| null|null|null| 7.0| +|1970-01-01T08:00:00.008+08:00| null| null|null|null| 8.0| ++-----------------------------+-------+-------+----+----+----+ + + +-- Insert statement +IoTDB:etth> INSERT INTO tab_real (time, target1, target2, cov1, cov2, cov3) VALUES +(1, 1.0, 1.0, 1.0, 1.0, 1.0), +(2, 2.0, 2.0, 2.0, 2.0, 2.0), +(3, 3.0, 3.0, 3.0, 3.0, 3.0), +(4, 4.0, 4.0, 4.0, 4.0, 4.0), +(5, 5.0, 5.0, 5.0, 5.0, 5.0), +(6, 6.0, 6.0, 6.0, 6.0, 6.0), +(7, NULL, NULL, NULL, NULL, 7.0), +(8, NULL, NULL, NULL, NULL, 8.0); +``` + +* Prediction task 1: Use historical covariates cov1, cov2, and cov3 to assist in predicting target variables target1 and target2. + + ![](/img/ainode-upgrade-table-forecast-timecho-1-en.png) + + * Use the first 6 rows of historical data from cov1, cov2, cov3, target1, target2 in table tab_real to predict the next 2 rows of target variables target1 and target2. + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.338330268859863|7.338330268859863| + |1970-01-01T08:00:00.008+08:00| 8.02529525756836| 8.02529525756836| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.315s + ``` +* Prediction task 2: Use historical covariates cov1, cov2 and known covariates cov3 in the same table to assist in predicting target variables target1 and target2. + + ![](/img/ainode-upgrade-table-forecast-timecho-2-en.png) + + * Use the first 6 rows of historical data from cov1, cov2, cov3, target1, target2 in table tab_real, and known covariate cov3 in the future 2 rows of the same table to predict the next 2 rows of target variables target1 and target2. + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + FUTURE_COVS => ' + SELECT TIME, cov3 + FROM etth.tab_real + WHERE TIME >= 7 + LIMIT 2', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.244050025939941|7.244050025939941| + |1970-01-01T08:00:00.008+08:00|7.907227516174316|7.907227516174316| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.291s + ``` +* Prediction task 3: Use historical covariates cov1, cov2 from different tables and known covariates cov3 to assist in predicting target variables target1 and target2. + + ![](/img/ainode-upgrade-table-forecast-timecho-3-en.png) + + * Create table tab_cov_forecast (to store known covariate cov3 prediction values) in advance, and prepare related data. + ```SQL + create table tab_cov_forecast (cov3 DOUBLE FIELD); + + -- Insert statement + INSERT INTO tab_cov_forecast (time, cov3) VALUES (7, 7.0),(8, 8.0); + + IoTDB:etth> SELECT * FROM tab_cov_forecast + +----+----+ + |time|cov3| + +----+----+ + | 7| 7.0| + | 8| 8.0| + +----+----+ + ``` + * Use the first 6 rows of known data from cov1, cov2, cov3, target1, target2 in table tab_real, and known covariate cov3 in the future 2 rows from table tab_cov_forecast to predict the next 2 rows of target variables target1 and target2. + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + FUTURE_COVS => ' + SELECT TIME, cov3 + FROM etth.tab_cov_forecast + WHERE TIME >= 7 + LIMIT 2', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.244050025939941|7.244050025939941| + |1970-01-01T08:00:00.008+08:00|7.907227516174316|7.907227516174316| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.351s + ``` + + +### 4.2 Model Fine-Tuning + +AINode supports model fine-tuning through SQL. + +**SQL Syntax** + +```SQL +createModelStatement + | CREATE MODEL modelId=identifier (WITH HYPERPARAMETERS '(' hparamPair (',' hparamPair)* ')')? FROM MODEL existingModelId=identifier ON DATASET '(' targetData=string ')' + ; +hparamPair + : hparamKey=identifier '=' hyparamValue=primaryExpression + ; +``` + +**Parameter Description** + +| Name | Description | +|------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| modelId | Unique identifier of the fine-tuned model | +| hparamPair | Hyperparameter key-value pairs used for fine-tuning, currently supports the following:
`train_epochs`: int type, number of fine-tuning epochs
`iter_per_epoch`: int type, number of iterations per epoch
`learning_rate`: double type, learning rate | +| existingModelId | Base model used for fine-tuning | +| targetData | SQL to get the dataset used for fine-tuning | + +**Example** + +1. Select data from the ot field in the specified time range as the fine-tuning dataset, and create the model sundialv3 based on sundial. + +```SQL +IoTDB> set sql_dialect=table +Msg: The statement is executed successfully. +IoTDB> CREATE MODEL sundialv3 FROM MODEL sundial ON DATASET ('SELECT time, ot from etth.eg where 1467302400000 <= time and time < 1517468400001') +Msg: The statement is executed successfully. +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| +| sundialv2| sundial| fine_tuned| active| +| sundialv3| sundial| fine_tuned| training| ++---------------------+---------+-----------+---------+ +``` + +2. Fine-tuning tasks are started asynchronously in the background, which can be seen in the AINode process log; after fine-tuning is completed, query and use the new model. + +```SQL +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| +| sundialv2| sundial| fine_tuned| active| +| sundialv3| sundial| fine_tuned| active| ++---------------------+---------+-----------+---------+ +``` + +### 4.3 Register Custom Models + +**The following Transformers models can be registered to AINode:** + +1. AINode currently uses transformers version 4.56.2, so when building the model, avoid inheriting interfaces from lower versions (<4.50); +2. The model must inherit a pipeline for inference tasks of AINode (currently supports prediction pipeline): + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + Preprocess input data before the inference task, including shape validation and numerical conversion. + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + Postprocess output results after the inference task. + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + Preprocess input data before passing it to the model for inference, validate input data shape and type. + + Args: + inputs (list[dict]): + Input data, list of dictionaries, each dictionary contains: + - 'targets': tensor of shape (input_length,) or (target_count, input_length). + - 'past_covariates': optional, tensor dictionary, each tensor of shape (input_length,). + - 'future_covariates': optional, tensor dictionary, each tensor of shape (input_length,). + + infer_kwargs (dict, optional): Additional keyword parameters for inference, such as: + - `output_length`(int): If 'future_covariates' is provided, used to validate its validity. + + Raises: + ValueError: If input format is incorrect (e.g., missing keys, invalid tensor shapes). + + Returns: + Processed and validated input data, ready for model inference. + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + Perform prediction on given input. + + Parameters: + inputs: Input data for prediction. Type and structure depend on the model's specific implementation. + **infer_kwargs: Additional inference parameters, e.g.: + - `output_length`(int): Number of time points the model should generate. + + Returns: + Prediction output, specific form depends on the model's specific implementation. + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + Postprocess model output after inference, validate output data shape and ensure it meets expected dimensions. + + Args: + outputs: + Model output, list of 2D tensors, each tensor of shape `[target_count, output_length]`. + + Raises: + InferenceModelInternalException: If output tensor shape is invalid (e.g., dimension error). + ValueError: If output format is incorrect. + + Returns: + list[torch.Tensor]: + Postprocessed output, a list of 2D tensors. + """ + pass + ``` +3. Modify the model configuration file config.json to ensure it includes the following fields: + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // Specify the Config class of the model + "AutoModelForCausalLM": "model.Chronos2Model" // Specify the model class + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // Specify the model's inference pipeline + "model_type": "custom_t5", // Specify the model type + } + ``` + + 1. Must specify the Config class and model class through auto_map; + 2. Must integrate and specify the inference pipeline class; + 3. For built-in (builtin) and custom (user_defined) models managed by AINode, the model category (model_type) also serves as a unique identifier. That is, the model category to be registered must not duplicate any existing model types. Models created through fine-tuning will inherit the model category of the original model. +4. Ensure the model directory to be registered contains the following files, and the model configuration file name and weight file name are not customizable: + 1. Model configuration file: config.json; + 2. Model weight file: model.safetensors; + 3. Model code: other .py files. + +**The SQL syntax for registering custom models is as follows:** + +```SQL +CREATE MODEL USING URI +``` + +**Parameter Description:** + +* **model_id**: Unique identifier for the custom model; cannot be duplicated, with the following constraints: + * Allowed characters: [0-9 a-z A-Z \_ ] (letters, numbers (not at the beginning), underscore (not at the beginning)) + * Length limit: 2-64 characters + * Case-sensitive +* **uri**: Local URI address containing the model code and weights. + +**Registration Example:** + +Upload a custom Transformers model from a local path, AINode will copy the folder to the user_defined directory. + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +After executing the SQL, the registration process will be asynchronous. The registration status of the model can be viewed by checking the model display (see the "Viewing Models" section). After the model is registered successfully, it can be called using normal query methods for model inference. + +### 4.4 Viewing Models + +Registered models can be queried using the view command. + +```SQL +SHOW MODELS +``` + +In addition to displaying all model information directly, you can specify `model_id` to view the information of a specific model. + +```SQL +SHOW MODELS -- Only show specific model +``` + +The result of the model display contains the following: + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| Model ID | Model Type | Model Category | Model State | + +Where, the State model status machine flowchart is as follows: + +![](/img/ainode-upgrade-state-timecho-en.png) + +State machine flow description: + +1. After starting AINode, executing `show models` command, only **system built-in (BUILTIN)** models can be viewed. +2. Users can import their own models, which are identified as **user-defined (USER_DEFINED)**; AINode will try to parse the model type (ModelType) from the model configuration file; if parsing fails, this field will be displayed as empty. +3. Time series large models (built-in models) do not have weight files packaged with AINode, and AINode automatically downloads them when starting. + 1. During download, it is ACTIVATING, and after successful download, it becomes ACTIVE, and if failed, it becomes INACTIVE. +4. After users start a model fine-tuning task, the model state during training is TRAINING, and after successful training, it becomes ACTIVE, and if failed, it becomes FAILED. +5. If the fine-tuning task is successful, after fine-tuning, all ckpt (training files) will be statistically analyzed to find the best file and automatically renamed to the user-specified model_id. + +**Viewing Example** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| sundialx_1| sundial| fine_tuned| active| +| sundialx_4| sundial| fine_tuned| training| +| sundialx_5| sundial| fine_tuned| failed| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +**Built-in Traditional Time Series Models:** + +| Model Name | Core Concept | Applicable Scenarios | Key Features | +|-----------------------------------------|------------------------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------------------------| +| **ARIMA** (Autoregressive Integrated Moving Average) | Combines AR, differencing (I), and MA for stationary or differenced series | Univariate forecasting (stock prices, sales, economics) | 1. For linear trends with weak seasonality2. Requires (p,d,q) tuning3. Sensitive to missing values | +| **Holt-Winters** (Triple Exponential Smoothing) | Exponential smoothing with level, trend, and seasonal components | Data with clear trend & seasonality (monthly sales, power demand) | 1. Handles additive/multiplicative seasonality2. Weights recent data higher3. Simple implementation | +| **Exponential Smoothing** | Weighted average of history with exponentially decaying weights | Trending but non-seasonal data (short-term demand) | 1. Few parameters, simple computation2. Suitable for stable/slow-changing series3. Extensible to double/triple smoothing | +| **Naive Forecaster** | Uses last observation as next prediction (simplest baseline) | Benchmarking or data with no clear pattern | 1. No training needed2. Sensitive to sudden changes3. Seasonal variant uses prior season value | +| **STL Forecaster** | Decomposes series into trend, seasonal, residual; forecasts components | Complex seasonality/trends (climate, traffic) | 1. Handles non-fixed seasonality2. Robust to outliers3. Components can use other models | +| **Gaussian HMM** | Hidden states generate observations; each state follows Gaussian distribution | State sequence prediction/classification (speech, finance) | 1. Models temporal state transitions2. Observations independent per state3. Requires state count | +| **GMM HMM** | Extends Gaussian HMM; each state uses Gaussian Mixture Model | Multi-modal observation scenarios (motion recognition, biosignals) | 1. More flexible than single Gaussian2. Higher complexity3. Requires GMM component count | +| **STRAY** (Search for Outliers using Random Projection and Adaptive Thresholding) | Uses SVD to detect anomalies in high-dimensional time series | High-dimensional anomaly detection (sensor networks, IT monitoring) | 1. No distribution assumption2. Handles high dimensions3. Sensitive to global anomalies | + +**Built-in Time Series Large Models:** + +| Model Name | Core Concept | Applicable Scenarios | Key Features | +|-----------------|------------------------------------------------------------------------------|-----------------------------------------------------------|------------------------------------------------------------------------------| +| **Timer-XL** | Long-context time series large model pretrained on massive industrial data | Complex industrial forecasting requiring ultra-long history (energy, aerospace, transport) | 1. Supports input of tens of thousands of time points2. Covers non-stationary, multivariate, and covariate scenarios3. Pretrained on trillion-scale high-quality industrial IoT data | +| **Timer-Sundial** | Generative foundation model with "Transformer + TimeFlow" architecture | Zero-shot forecasting requiring uncertainty quantification (finance, supply chain, renewable energy) | 1. Strong zero-shot generalization; supports point & probabilistic forecasting2. Flexible analysis of any prediction distribution statistic3. Innovative flow-matching architecture for efficient non-deterministic sample generation | +| **Chronos-2** | Universal time series foundation model based on discrete tokenization | Rapid zero-shot univariate forecasting; scenarios enhanced by covariates (promotions, weather) | 1. Powerful zero-shot probabilistic forecasting2. Unified multi-variable & covariate modeling (strict input requirements):  a. Future covariate names ⊆ historical covariate names  b. Each historical covariate length = target length  c. Each future covariate length = prediction length3. Efficient encoder-only structure balancing performance and speed | + +### 4.5 Model Deletion + +Registered models can be deleted via SQL. AINode removes the corresponding model folder under `user_defined`. Syntax: +```SQL +DROP MODEL +``` +- Requires specifying an existing `model_id`. +- Deletion is asynchronous (status: `DROPPING`), during which the model cannot be used for inference. +- **Built-in models cannot be deleted.** + +### 4.6 Loading/Unloading Models + +AINode supports two loading strategies: +* **On-Demand Loading**: Load model temporarily during inference, then release resources. Suitable for testing or low-load scenarios. +* **Persistent Loading**: Keep model instances resident in CPU memory or GPU VRAM to support high-concurrency inference. Users specify load/unload targets via SQL; AINode auto-manages instance counts. Current loaded status is queryable. + +Details below: + +1. **Configuration Parameters** + Edit these settings to control persistent loading behavior: + ```properties + # Ratio of total device memory/VRAM usable by AINode for inference + # Datatype: Float + ain_inference_memory_usage_ratio=0.4 + + # Memory overhead ratio per loaded model instance (model_size * this_value) + # Datatype: Float + ain_inference_extra_memory_ratio=1.2 + ``` + +2. **List Available Devices** + ```SQL + SHOW AI_DEVICES + ``` + Example: + ```SQL + IoTDB> SHOW AI_DEVICES + +-------------+ + | DeviceId| + +-------------+ + | cpu| + | 0| + | 1| + +-------------+ + ``` + +3. **Load Model** + Manually load model; system auto-balances instance count based on resources: + ```SQL + LOAD MODEL TO DEVICES (, )* + ``` + Parameters: + * `existing_model_id`: Model ID (current version supports `timer_xl` and `sundial` only) + * `device_id`: + * `cpu`: Load into server memory + * `gpu_id`: Load into specified GPU(s), e.g., `'0,1'` for GPUs 0 and 1 + Example: + ```SQL + LOAD MODEL sundial TO DEVICES 'cpu,0,1' + ``` + +4. **Unload Model** + Unload all instances of a model; system reallocates freed resources: + ```SQL + UNLOAD MODEL FROM DEVICES (, )* + ``` + Parameters same as `LOAD MODEL`. + Example: + ```SQL + UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' + ``` + +5. **View Loaded Models** + ```SQL + SHOW LOADED MODELS + SHOW LOADED MODELS (, )* -- Filter by device + ``` + Example (sundial loaded on CPU, GPU 0, GPU 1): + ```SQL + IoTDB> SHOW LOADED MODELS + +-------------+--------------+------------------+ + | DeviceId| ModelId| Count(instances)| + +-------------+--------------+------------------+ + | cpu| sundial| 4| + | 0| sundial| 6| + | 1| sundial| 6| + +-------------+--------------+------------------+ + ``` + * `DeviceId`: Device identifier + * `ModelId`: Loaded model ID + * `Count(instances)`: Number of model instances per device (auto-assigned by system) + +### 4.7 Large Time Series Models + +AINode supports multiple large time series models. For deployment details, refer to [Time Series Large Model](../AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md) + +### 5. Permission Management + +Use IoTDB's built-in authentication for AINode permissions. Users need `USE_MODEL` permission to manage models and access input data for inference. + +| **Permission** | **Scope** | **Administrator (default ROOT)** | **Normal User** | +|---------------------|--------------------------------|----------------------------------|-----------------| +| USE_MODEL | create model / show models / drop model | √ | √ | +| READ_SCHEMA&READ_DATA | forecast | √ | √ | \ No newline at end of file diff --git a/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade.md b/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade.md new file mode 100644 index 000000000..440615354 --- /dev/null +++ b/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: TimeSeries-Large-Model_Upgrade_apache.html +--- + diff --git a/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md b/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md new file mode 100644 index 000000000..bc20138a4 --- /dev/null +++ b/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md @@ -0,0 +1,157 @@ + +# Time Series Large Models + +## 1. Introduction + +Time Series Large Models are foundational models specifically designed for time series data analysis. The IoTDB team has been developing the Timer, a self-researched foundational time series model, which is based on the Transformer architecture and pre-trained on massive multi-domain time series data, supporting downstream tasks such as time series forecasting, anomaly detection, and time series imputation. The AINode platform developed by the team also supports the integration of cutting-edge time series foundational models from the industry, providing users with diverse model options. Unlike traditional time series analysis techniques, these large models possess universal feature extraction capabilities and can serve a wide range of analytical tasks through zero-shot analysis, fine-tuning, and other services. + +All technical achievements in the field of time series large models related to this paper (including both the team's self-researched models and industry-leading directions) have been published in top international machine learning conferences, with specific details in the appendix. + +## 2. Application Scenarios + +* **Time Series Forecasting**: Providing time series data forecasting services for industrial production, natural environments, and other fields to help users understand future trends in advance. +* **Data Imputation**: Performing context-based filling for missing segments in time series to enhance the continuity and integrity of the dataset. +* **Anomaly Detection**: Using autoregressive analysis technology to monitor time series data in real-time, promptly alerting potential anomalies. + +![](/img/LargeModel10.png) + +## 3. Timer-1 Model + +The Timer model (non-built-in model) not only demonstrates excellent few-shot generalization and multi-task adaptability, but also acquires a rich knowledge base through pre-training, endowing it with universal capabilities to handle diverse downstream tasks, with the following characteristics: + +* **Generalizability**: The model can achieve industry-leading deep model prediction results through fine-tuning with only a small number of samples. +* **Universality**: The model design is flexible, capable of adapting to various different task requirements, and supports variable input and output lengths, enabling it to function effectively in various application scenarios. +* **Scalability**: As the number of model parameters increases or the scale of pre-training data expands, the model's performance will continue to improve, ensuring that the model can continuously optimize its prediction effectiveness as time and data volume grow. + +![](/img/model01.png) + +## 4. Timer-XL Model + +Timer-XL further extends and upgrades the network structure based on Timer, achieving comprehensive breakthroughs in multiple dimensions: + +* **Ultra-Long Context Support**: This model breaks through the limitations of traditional time series forecasting models, supporting the processing of inputs with thousands of Tokens (equivalent to tens of thousands of time points), effectively solving the context length bottleneck problem. +* **Coverage of Multi-Variable Forecasting Scenarios**: Supports various forecasting scenarios, including the prediction of non-stationary time series, multi-variable prediction tasks, and predictions involving covariates, meeting diversified business needs. +* **Large-Scale Industrial Time Series Dataset**: Pre-trained on a trillion-scale time series dataset from the industrial IoT field, the dataset possesses important characteristics such as massive scale, excellent quality, and rich domain coverage, covering multiple fields including energy, aerospace, steel, and transportation. + +![](/img/model02.png) + +## 5. Timer-Sundial Model + +Timer-Sundial is a series of generative foundational models focused on time series forecasting. The base version has 128 million parameters and has been pre-trained on 1 trillion time points, with the following core characteristics: + +* **Strong Generalization Performance**: Possesses zero-shot forecasting capabilities and can support both point forecasting and probabilistic forecasting simultaneously. +* **Flexible Prediction Distribution Analysis**: Not only can it predict means or quantiles, but it can also evaluate any statistical properties of the prediction distribution through the raw samples generated by the model. +* **Innovative Generative Architecture**: Employs a "Transformer + TimeFlow" collaborative architecture - the Transformer learns the autoregressive representations of time segments, while the TimeFlow module transforms random noise into diverse prediction trajectories based on the flow-matching framework (Flow-Matching), achieving efficient generation of non-deterministic samples. + +![](/img/model03.png) + +## 6. Chronos-2 Model + +Chronos-2 is a universal time series foundational model developed by the Amazon Web Services (AWS) research team, evolved from the Chronos discrete token modeling paradigm. This model is suitable for both zero-shot univariate forecasting and covariate forecasting. Its main characteristics include: + +* **Probabilistic Forecasting Capability**: The model outputs multi-step prediction results in a generative manner, supporting quantile or distribution-level forecasting to characterize future uncertainty. +* **Zero-Shot General Forecasting**: Leveraging the contextual learning ability acquired through pre-training, it can directly execute forecasting on unseen datasets without retraining or parameter updates. +* **Unified Modeling of Multi-Variable and Covariates**: Supports joint modeling of multiple related time series and their covariates under the same architecture to improve prediction performance for complex tasks. However, it has strict input requirements: + * The set of names of future covariates must be a subset of the set of names of historical covariates; + * The length of each historical covariate must equal the length of the target variable; + * The length of each future covariate must equal the prediction length; +* **Efficient Inference and Deployment**: The model adopts a compact encoder-only structure, maintaining strong generalization capabilities while ensuring inference efficiency. + +![](/img/timeseries-large-model-chronos2.png) + +## 7. Performance Showcase + +Time Series Large Models can adapt to real time series data from various different domains and scenarios, demonstrating excellent processing capabilities across various tasks. The following shows the actual performance on different datasets: + +**Time Series Forecasting:** + +Leveraging the forecasting capabilities of Time Series Large Models, future trends of time series can be accurately predicted. The blue curve in the following figure represents the predicted trend, while the red curve represents the actual trend, with both curves highly consistent. + +![](/img/LargeModel03.png) + +**Data Imputation:** + +Using Time Series Large Models to fill missing data segments through predictive imputation. + +![](/img/timeseries-large-model-data-imputation.png) + +**Anomaly Detection:** + +Using Time Series Large Models to accurately identify outliers that deviate significantly from the normal trend. + +![](/img/LargeModel05.png) + +## 8. Deployment and Usage + +1. Open the IoTDB CLI console and check that the ConfigNode, DataNode, and AINode nodes are all Running. + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. In an online environment, the first startup of the AINode node will automatically pull the Timer-XL, Sundial, and Chronos2 models. + + > Note: + > + > * The AINode installation package does not include model weight files. + > * The automatic pull feature depends on the deployment environment having HuggingFace network access capability. + > * AINode supports manual upload of model weight files. For specific operation methods, refer to [Importing Weight Files](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md#_3-3-importing-built-in-weight-files). + +3. Check if the models are available. + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### Appendix + +**[1]** Timer: Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[2]** TIMER-XL: LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING, Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[3]** Sundial: A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ Back]() + +**[4]** Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821**. [↩ Back]() \ No newline at end of file diff --git a/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md b/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md new file mode 100644 index 000000000..c7fde0bf2 --- /dev/null +++ b/src/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md @@ -0,0 +1,157 @@ + +# Time Series Large Models + +## 1. Introduction + +Time Series Large Models are foundational models specifically designed for time series data analysis. The IoTDB team has been developing the Timer, a self-researched foundational time series model, which is based on the Transformer architecture and pre-trained on massive multi-domain time series data, supporting downstream tasks such as time series forecasting, anomaly detection, and time series imputation. The AINode platform developed by the team also supports the integration of cutting-edge time series foundational models from the industry, providing users with diverse model options. Unlike traditional time series analysis techniques, these large models possess universal feature extraction capabilities and can serve a wide range of analytical tasks through zero-shot analysis, fine-tuning, and other services. + +All technical achievements in the field of time series large models related to this paper (including both the team's self-researched models and industry-leading directions) have been published in top international machine learning conferences, with specific details in the appendix. + +## 2. Application Scenarios + +* **Time Series Forecasting**: Providing time series data forecasting services for industrial production, natural environments, and other fields to help users understand future trends in advance. +* **Data Imputation**: Performing context-based filling for missing segments in time series to enhance the continuity and integrity of the dataset. +* **Anomaly Detection**: Using autoregressive analysis technology to monitor time series data in real-time, promptly alerting potential anomalies. + +![](/img/LargeModel10.png) + +## 3. Timer-1 Model + +The Timer model (non-built-in model) not only demonstrates excellent few-shot generalization and multi-task adaptability, but also acquires a rich knowledge base through pre-training, endowing it with universal capabilities to handle diverse downstream tasks, with the following characteristics: + +* **Generalizability**: The model can achieve industry-leading deep model prediction results through fine-tuning with only a small number of samples. +* **Universality**: The model design is flexible, capable of adapting to various different task requirements, and supports variable input and output lengths, enabling it to function effectively in various application scenarios. +* **Scalability**: As the number of model parameters increases or the scale of pre-training data expands, the model's performance will continue to improve, ensuring that the model can continuously optimize its prediction effectiveness as time and data volume grow. + +![](/img/model01.png) + +## 4. Timer-XL Model + +Timer-XL further extends and upgrades the network structure based on Timer, achieving comprehensive breakthroughs in multiple dimensions: + +* **Ultra-Long Context Support**: This model breaks through the limitations of traditional time series forecasting models, supporting the processing of inputs with thousands of Tokens (equivalent to tens of thousands of time points), effectively solving the context length bottleneck problem. +* **Coverage of Multi-Variable Forecasting Scenarios**: Supports various forecasting scenarios, including the prediction of non-stationary time series, multi-variable prediction tasks, and predictions involving covariates, meeting diversified business needs. +* **Large-Scale Industrial Time Series Dataset**: Pre-trained on a trillion-scale time series dataset from the industrial IoT field, the dataset possesses important characteristics such as massive scale, excellent quality, and rich domain coverage, covering multiple fields including energy, aerospace, steel, and transportation. + +![](/img/model02.png) + +## 5. Timer-Sundial Model + +Timer-Sundial is a series of generative foundational models focused on time series forecasting. The base version has 128 million parameters and has been pre-trained on 1 trillion time points, with the following core characteristics: + +* **Strong Generalization Performance**: Possesses zero-shot forecasting capabilities and can support both point forecasting and probabilistic forecasting simultaneously. +* **Flexible Prediction Distribution Analysis**: Not only can it predict means or quantiles, but it can also evaluate any statistical properties of the prediction distribution through the raw samples generated by the model. +* **Innovative Generative Architecture**: Employs a "Transformer + TimeFlow" collaborative architecture - the Transformer learns the autoregressive representations of time segments, while the TimeFlow module transforms random noise into diverse prediction trajectories based on the flow-matching framework (Flow-Matching), achieving efficient generation of non-deterministic samples. + +![](/img/model03.png) + +## 6. Chronos-2 Model + +Chronos-2 is a universal time series foundational model developed by the Amazon Web Services (AWS) research team, evolved from the Chronos discrete token modeling paradigm. This model is suitable for both zero-shot univariate forecasting and covariate forecasting. Its main characteristics include: + +* **Probabilistic Forecasting Capability**: The model outputs multi-step prediction results in a generative manner, supporting quantile or distribution-level forecasting to characterize future uncertainty. +* **Zero-Shot General Forecasting**: Leveraging the contextual learning ability acquired through pre-training, it can directly execute forecasting on unseen datasets without retraining or parameter updates. +* **Unified Modeling of Multi-Variable and Covariates**: Supports joint modeling of multiple related time series and their covariates under the same architecture to improve prediction performance for complex tasks. However, it has strict input requirements: + * The set of names of future covariates must be a subset of the set of names of historical covariates; + * The length of each historical covariate must equal the length of the target variable; + * The length of each future covariate must equal the prediction length; +* **Efficient Inference and Deployment**: The model adopts a compact encoder-only structure, maintaining strong generalization capabilities while ensuring inference efficiency. + +![](/img/timeseries-large-model-chronos2.png) + +## 7. Performance Showcase + +Time Series Large Models can adapt to real time series data from various different domains and scenarios, demonstrating excellent processing capabilities across various tasks. The following shows the actual performance on different datasets: + +**Time Series Forecasting:** + +Leveraging the forecasting capabilities of Time Series Large Models, future trends of time series can be accurately predicted. The blue curve in the following figure represents the predicted trend, while the red curve represents the actual trend, with both curves highly consistent. + +![](/img/LargeModel03.png) + +**Data Imputation:** + +Using Time Series Large Models to fill missing data segments through predictive imputation. + +![](/img/timeseries-large-model-data-imputation.png) + +**Anomaly Detection:** + +Using Time Series Large Models to accurately identify outliers that deviate significantly from the normal trend. + +![](/img/LargeModel05.png) + +## 8. Deployment and Usage + +1. Open the IoTDB CLI console and check that the ConfigNode, DataNode, and AINode nodes are all Running. + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. In an online environment, the first startup of the AINode node will automatically pull the Timer-XL, Sundial, and Chronos2 models. + + > Note: + > + > * The AINode installation package does not include model weight files. + > * The automatic pull feature depends on the deployment environment having HuggingFace network access capability. + > * AINode supports manual upload of model weight files. For specific operation methods, refer to [Importing Weight Files](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md#_3-3-importing-built-in-weight-files). + +3. Check if the models are available. + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### Appendix + +**[1]** Timer: Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[2]** TIMER-XL: LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING, Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[3]** Sundial: A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ Back]() + +**[4]** Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821**. [↩ Back]() \ No newline at end of file diff --git a/src/UserGuide/latest/AI-capability/AINode_Upgrade.md b/src/UserGuide/latest/AI-capability/AINode_Upgrade.md new file mode 100644 index 000000000..6f44068b6 --- /dev/null +++ b/src/UserGuide/latest/AI-capability/AINode_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: AINode_Upgrade_apache.html +--- + \ No newline at end of file diff --git a/src/UserGuide/latest/AI-capability/AINode_Upgrade_apache.md b/src/UserGuide/latest/AI-capability/AINode_Upgrade_apache.md new file mode 100644 index 000000000..95120ae19 --- /dev/null +++ b/src/UserGuide/latest/AI-capability/AINode_Upgrade_apache.md @@ -0,0 +1,574 @@ + + +# AINode + +AINode is a native IoTDB node that supports the registration, management, and invocation of time-series related models. It includes industry-leading self-developed time-series large models, such as the Timer series models developed by Tsinghua University. These models can be called using standard SQL statements, enabling millisecond-level real-time inference for time series data, supporting applications such as time series trend prediction, missing value imputation, and anomaly detection. + +The system architecture is shown in the following figure: + +![](/img/AINode-0-en.png) + +The responsibilities of the three nodes are as follows: + +* **ConfigNode**: Responsible for distributed node management and load balancing. +* **DataNode**: Responsible for receiving and parsing users' SQL requests; responsible for storing time series data; responsible for data preprocessing calculations. +* **AINode**: Responsible for the management and use of time series models. + +## 1. Advantages + +Compared to building a machine learning service separately, it has the following advantages: + +* **Simple and Easy to Use**: No need to use Python or Java programming. Machine learning model management and inference can be completed using SQL statements. For example, creating a model can use the CREATE MODEL statement, and using a model for inference can use the `CALL INFERENCE(...)` statement, making it simpler and more convenient. +* **Avoid Data Migration**: Using IoTDB's native machine learning can directly apply data stored in IoTDB to machine learning models for inference, without moving data to a separate machine learning service platform. This accelerates data processing, improves security, and reduces costs. + +![](/img/AInode1.png) + +* **Built-in Advanced Algorithms**: Supports industry-leading machine learning analysis algorithms, covering typical time series analysis tasks, and empowering time series databases with native data analysis capabilities. For example: + * **Time Series Forecasting**: Learn change patterns from past time series data; based on given past observations, output the most likely future sequence predictions. + * **Anomaly Detection for Time Series**: Detect and identify anomalies in given time series data, helping to discover abnormal behavior in time series. + +## 2. Basic Concepts + +* **Model**: Machine learning model, which takes time series data as input and outputs the results or decisions of the analysis task. Model is the basic management unit of AINode, supporting model management including creation (registration), deletion, query, and usage (inference). +* **Create**: Load external designed or trained model files or algorithms into AINode, managed and used uniformly by IoTDB. +* **Inference**: Use the created model to complete the time series analysis task applicable to the model on the specified time series data. +* **Built-in**: AINode comes with common time series analysis scenario (e.g., prediction and anomaly detection) machine learning algorithms or self-developed models. + +![](/img/AInode2.png) + +## 3. Installation and Deployment + +AINode deployment can be referenced in the document [AINode Deployment](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md). + +## 4. Usage Guide + +AINode supports two major functions: model inference and model management (registration, viewing, deletion, loading, unloading, etc.). The following sections will provide detailed instructions. + +### 4.1 Model Inference + +SQL syntax: + +```SQL +call inference(,inputSql,(=)*) +``` + +After completing the model registration (built-in models do not require the registration process), the inference function of the model can be used by calling the inference function with the call keyword. The corresponding parameter descriptions are as follows: + +* **model_id**: Corresponds to an already registered model +* **sql**: SQL query statement, the result of the query is used as the input for model inference. The dimensions of the query results (rows and columns) need to match the size specified in the model's config. (It is recommended not to use the `SELECT *` clause in this sql, because in IoTDB, `*` does not sort the columns, so the column order is undefined. It is recommended to use `SELECT s0,s1` to ensure the column order matches the expected input of the model.) +* **parameterName/parameterValue**: currently supports: + + | Parameter Name | Parameter Type | Parameter Description | Default Value | + | ------------------------ | ---------- | -------------------------- | -------- | + | **generateTime** | boolean | Whether to include a timestamp column in the result | false | + | **outputLength** | int | Specifies the length of the output result | 96 | + +Notes: + +1. The prerequisite for using built-in time series large models for inference is that the corresponding model weights are locally stored, with the directory being `/IOTDB_AINODE_HOME/data/ainode/models/builtin/model_id/`. If the local model weights are not present, they will be automatically pulled from HuggingFace. Please ensure that the local environment can directly access HuggingFace. +2. In deep learning applications, time stamp derived features (the time column in the data) are often used as covariates together with the input to the model to improve model performance. However, the time column is generally not included in the model's output results. To ensure generality, the model inference results only correspond to the model's true output. If the model does not output a time column, the result will not include it. + +**Example** + +Sample data [ETTh-tree](/img/ETTh-tree.csv) + +Here is an example of using the sundial model for inference. The input is 96 rows, and the output is 48 rows. We use SQL to perform the inference. + +```SQL +IoTDB> select OT from root.db.** ++-----------------------------+---------------+ +| Time|root.db.etth.OT| ++-----------------------------+---------------+ +|2016-07-01T00:00:00.000+08:00| 30.531| +|2016-07-01T01:00:00.000+08:00| 27.787| +|2016-07-01T02:00:00.000+08:00| 27.787| +|2016-07-01T03:00:00.000+08:00| 25.044| +|2016-07-01T04:00:00.000+08:00| 21.948| +| ...... | ...... | +|2016-07-04T19:00:00.000+08:00| 29.546| +|2016-07-04T20:00:00.000+08:00| 29.475| +|2016-07-04T21:00:00.000+08:00| 29.264| +|2016-07-04T22:00:00.000+08:00| 30.953| +|2016-07-04T23:00:00.000+08:00| 31.726| ++-----------------------------+---------------+ +Total line number = 96 + +IoTDB> call inference(sundial,"select OT from root.db.**", generateTime=True, outputLength=48) ++-----------------------------+------------------+ +| Time| output| ++-----------------------------+------------------+ +|2016-07-04T23:00:00.000+08:00|30.537494659423828| +|2016-07-04T23:59:22.500+08:00|29.619892120361328| +|2016-07-05T00:58:45.000+08:00|28.815832138061523| +|2016-07-05T01:58:07.500+08:00| 27.91131019592285| +|2016-07-05T02:57:30.000+08:00|26.893848419189453| +| ...... | ...... | +|2016-07-06T17:33:07.500+08:00| 24.40607261657715| +|2016-07-06T18:32:30.000+08:00| 25.00441551208496| +|2016-07-06T19:31:52.500+08:00|24.907312393188477| +|2016-07-06T20:31:15.000+08:00|25.156436920166016| +|2016-07-06T21:30:37.500+08:00|25.335433959960938| ++-----------------------------+------------------+ +Total line number = 48 +``` + +### 4.2 Register Custom Models + +**The following requirements must be met for Transformers models to be registered in AINode:** + +1. AINode currently uses transformers v4.56.2, so when building the model, avoid inheriting from low versions (<4.50) interfaces; +2. The model must inherit from a type of AINode inference task pipeline (currently supports forecast pipeline): + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + Preprocess the input data before the inference task, including shape verification and numerical conversion. + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + Postprocess the output results after the inference task. + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + Preprocess the input data before passing it to the model for inference, verifying the shape and type of input data. + + Args: + inputs (list[dict]): + Input data, a list of dictionaries, each dictionary contains: + - 'targets': A tensor of shape (input_length,) or (target_count, input_length). + - 'past_covariates': Optional, a dictionary of tensors, each tensor of shape (input_length,). + - 'future_covariates': Optional, a dictionary of tensors, each tensor of shape (input_length,). + + infer_kwargs (dict, optional): Additional keyword parameters for inference, such as: + - `output_length`(int): Used to verify validity if 'future_covariates' is provided. + + Raises: + ValueError: If the input format is incorrect (e.g., missing keys, invalid tensor shapes). + + Returns: + Preprocessed and verified input data, ready for model inference. + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + Perform prediction on the given input. + + Parameters: + inputs: Input data for prediction. Type and structure depend on the specific model implementation. + **infer_kwargs: Additional inference parameters, for example: + - `output_length`(int): The number of time points the model should generate. + + Returns: + Prediction output, specific form depends on the specific model implementation. + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + Postprocess the model output after inference, verifying the shape of the output tensor and ensuring it meets expected dimensions. + + Args: + outputs: + Model output, a list of 2D tensors, each tensor shape is `[target_count, output_length]`. + + Raises: + InferenceModelInternalException: If the output tensor shape is invalid (e.g., dimension error). + ValueError: If the output format is incorrect. + + Returns: + list[torch.Tensor]: + Postprocessed output, a list of 2D tensors. + """ + pass + ``` +3. Modify the model configuration file config.json to ensure it contains the following fields: + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // Specify the model Config class + "AutoModelForCausalLM": "model.Chronos2Model" // Specify the model class + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // Specify the model's inference pipeline + "model_type": "custom_t5", // Specify the model type + } + ``` + + 1. Must specify the model's Config class and model class through auto_map; + 2. Must integrate and specify the inference pipeline class; + 3. For built-in (builtin) and user-defined (user_defined) models managed by AINode, the model category (model_type) also serves as a unique identifier. That is, the model category to be registered must not duplicate any existing model types. +4. Ensure the model directory to be registered contains the following files, and the model configuration file name and weight file name are not customizable: + 1. Model configuration file: config.json; + 2. Model weight file: model.safetensors; + 3. Model code: other .py files. + +**The SQL syntax for registering a custom model is as follows:** + +```SQL +CREATE MODEL USING URI +``` + +**Parameter descriptions:** + +* **model_id**: The unique identifier of the custom model; must be unique, with the following constraints: + * Allowed characters: [0-9 a-z A-Z _] (letters, numbers (not starting), underscore (not starting)) + * Length limit: 2-64 characters + * Case-sensitive +* **uri**: The local URI address containing the model code and weights. + +**Example of registration:** + +Upload a custom Transformers model from a local path, AINode will copy the folder to the user_defined directory. + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +After executing the SQL, the model registration process will be asynchronous. You can view the model registration status by viewing the model (see the View Model section). After the model registration is complete, you can call the specific function using normal query methods to perform model inference. + +### 4.3 View Models + +Registered models can be viewed using the view command. + +```SQL +SHOW MODELS +``` + +In addition to directly displaying all model information, you can specify `model_id` to view specific model information. + +```SQL +SHOW MODELS -- Show specific model only +``` + +The model display result includes the following content: + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| Model ID | Model Type | Model Category | Model State | + +Where, the State model state machine flowchart is as follows: + +![](/img/ainode-upgrade-state-apache-en.png) + +State machine flow description: + +1. After starting AINode, executing `show models` command can only view the **system built-in (BUILTIN)** models. +2. Users can import their own models, which are identified as **user-defined (USER_DEFINED)**; AINode will try to parse the model type (ModelType) from the model configuration file. If parsing fails, this field will be displayed as empty. +3. Time series large models (built-in models) weight files are not packaged with AINode, and AINode automatically downloads them when starting. + 1. During download, the state is ACTIVATING; after successful download, it becomes ACTIVE; if download fails, it becomes INACTIVE. + +**View Example** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +Built-in traditional time series model introduction: + +| Model Name | Core Concept | Applicable Scenario | Main Features | +|----------------------------------| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- | +| **ARIMA** (AutoRegressive Integrated Moving Average) | Combines autoregression (AR), differencing (I), and moving average (MA), used for predicting stationary time series or data that can be made stationary through differencing. | Univariate time series prediction, such as stock prices, sales, economic indicators. | 1. Suitable for linear trends and weak seasonality data. 2. Requires selecting parameters (p,d,q). 3. Sensitive to missing values. | +| **Holt-Winters** (Three-parameter exponential smoothing) | Based on exponential smoothing, introduces level, trend, and seasonal components, suitable for data with trend and seasonality. | Time series with clear seasonality and trend, such as monthly sales, power demand. | 1. Can handle additive or multiplicative seasonality. 2. Gives higher weight to recent data. 3. Simple to implement. | +| **Exponential Smoothing** (Exponential smoothing) | Uses weighted average of historical data, with weights decreasing exponentially over time, emphasizing the importance of recent observations. | Data without significant seasonality but with trend, such as short-term demand prediction. | 1. Few parameters, simple calculation. 2. Suitable for stationary or slowly changing sequences. 3. Can be extended to double or triple exponential smoothing. | +| **Naive Forecaster** (Naive predictor) | Uses the observation of the most recent period as the prediction for the next period, the simplest baseline model. | As a benchmark for other models or simple prediction when data has no obvious pattern. | 1. No training required. 2. Sensitive to sudden changes. 3. Seasonal naive variant can use the same period of the previous season to predict. | +| **STL Forecaster** (Seasonal-Trend Decomposition Forecast) | Based on STL decomposition of time series, predicts trend, seasonal, and residual components separately, then combines them. | Data with complex seasonality, trend, and non-linear patterns, such as climate data, traffic flow. | 1. Can handle non-fixed seasonality. 2. Robust to outliers. 3. After decomposition, other models can be combined to predict each component. | +| **Gaussian HMM** (Gaussian Hidden Markov Model) | Assumes observed data is generated by hidden states, with each state's observation probability following a Gaussian distribution. | State sequence prediction or classification, such as speech recognition, financial state identification. | 1. Suitable for time series state modeling. 2. Assumes observations are independent given the state. 3. Requires specifying the number of hidden states. | +| **GMM HMM** (Gaussian Mixture Hidden Markov Model) | An extension of Gaussian HMM, where each state's observation probability is described by a Gaussian Mixture Model, capturing more complex observation distributions. | Scenarios requiring multi-modal observation distributions, such as complex action recognition, biosignal analysis. | 1. More flexible than single Gaussian. 2. More parameters, higher computational complexity. 3. Requires training the number of GMM components. | +| **STRAY** (Anomaly Detection based on Singular Value Decomposition) | Detects anomalies in high-dimensional data through Singular Value Decomposition (SVD), commonly used for time series anomaly detection. | High-dimensional time series anomaly detection, such as sensor networks, IT system monitoring. | 1. No distribution assumption required. 2. Can handle high-dimensional data. 3. Sensitive to global anomalies, may miss local anomalies. | + +Built-in time series large model introduction: + +| Model Name | Core Concept | Applicable Scenario | Main Features | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | Time series large model supporting ultra-long context, enhancing generalization capability through large-scale industrial data pre-training. | Complex industrial prediction requiring extremely long historical data, such as energy, aerospace, and transportation. | 1. Ultra-long context support, can handle tens of thousands of time points as input. 2. Multi-scenario coverage, supports non-stationary, multi-variable, and covariate prediction. 3. Pre-trained on trillions of high-quality industrial time series data. | +| **Timer-Sundial** | A generative foundational model based on "Transformer + TimeFlow" architecture, focusing on probabilistic prediction. | Zero-shot prediction scenarios requiring quantification of uncertainty, such as finance, supply chain, and new energy power generation. | 1. Strong zero-shot generalization capability, supports point prediction and probabilistic prediction. 2. Can flexibly analyze any statistical properties of the prediction distribution. 3. Innovative generative architecture, achieving efficient non-deterministic sample generation. | +| **Chronos-2** | A general time series foundational model based on discrete tokenization paradigm, converting prediction into language modeling tasks. | Rapid zero-shot univariate prediction, and scenarios that can leverage covariates (e.g., promotions, weather) to improve results. | 1. Strong zero-shot probabilistic prediction capability. 2. Supports unified covariate modeling, but has strict input requirements: a. The set of names of future covariates must be a subset of the set of names of historical covariates; b. The length of each historical covariate must equal the length of the target variable; c. The length of each future covariate must equal the prediction length; 3. Uses an efficient encoder-style structure, balancing performance and inference speed. | + +### 4.4 Delete Models + +For registered models, users can delete them using SQL. AINode will delete the entire folder of the corresponding model in the user_defined directory. The SQL syntax is as follows: + +```SQL +DROP MODEL +``` + +Specify the model_id that has been successfully registered to delete the corresponding model. Since model deletion involves model data cleanup, the operation will not be completed immediately, and the model state becomes DROPPING. Models in this state cannot be used for model inference. Note that this function does not support deleting built-in models. + +### 4.5 Load/Unload Models + +To adapt to different scenarios, AINode provides two model loading strategies: + +* **On-demand loading**: Load the model temporarily when inference is needed, and release resources after inference. Suitable for testing or low-load scenarios. +* **Persistent loading**: Permanently load the model into memory (CPU) or GPU memory to support high-concurrency inference. Users only need to specify the model to load or unload via SQL, and AINode will automatically manage the number of instances. The current state of persistent models can also be viewed at any time. + +The following details the loading/unloading model content: + +1. Configuration parameters + +Support editing the following configuration items to set persistent loading related parameters. + +```Properties +# The ratio of device memory/GPU memory available for AINode inference +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# The memory ratio required by each instance of a loaded model, i.e., model memory * this value +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. View available devices + +Support using the following SQL command to view all available device IDs. + +```SQL +SHOW AI_DEVICES +``` + +Example + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. Load models + +Support using the following SQL command to manually load models, and the system will **automatically balance** the number of model instances based on hardware resource usage. + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +Parameter requirements + +* **existing_model_id:** The specified model ID, currently only supports timer_xl and sundial. +* **device_id:** The location where the model is loaded. + * **cpu:** Load to the memory of the AINode server. + * **gpu_id:** Load to the corresponding GPU of the AINode server, e.g., "0, 1" means loading to the two GPUs numbered 0 and 1. + +Example + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. Unload models + +Support using the following SQL command to manually unload all instances of a specified model, and the system will **redistribute** the released resources to other models. + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +Parameter requirements + +* **existing_model_id:** The specified model ID, currently only supports timer_xl and sundial. +* **device_id:** The location where the model is loaded. + * **cpu:** Attempt to unload the specified model from the memory of the AINode server. + * **gpu_id:** Attempt to unload the specified model from the corresponding GPU of the AINode server, e.g., "0, 1" means attempting to unload from the two GPUs numbered 0 and 1. + +Example + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. View loaded models + +Support using the following SQL command to view the models that have been manually loaded. You can specify the device with `device_id`. + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # View models in specified devices +``` + +Example: sundial model loaded in memory, gpu_0, and gpu_1 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +Notes: + +* DeviceId: Device ID +* ModelId: Loaded model ID +* Count(instances): Number of model instances per device (automatically assigned by the system) + +### 4.6 Introduction to Time Series Large Models + +AINode currently supports multiple time series large models. For related introductions and deployment usage, refer to [Time Series Large Models](../AI-capability/TimeSeries-Large-Model_Upgrade_apache.md) + +## 5. Permission Management + +When using AINode-related features, permission management can be done using IoTDB's own authentication. Users can only use model management-related features if they have the USE_MODEL permission. When using inference features, users need to have access permissions to the source sequences corresponding to the SQL used for input. + +| Permission Name | Permission Scope | Administrator User (Default ROOT) | Normal User | Related to Path | +| ------------ | ----------------------------------------- | ------------------------ | ---------- | ---------- | +| USE_MODEL | create model / show models / drop model | √ | √ | x | +| READ_DATA | call inference | √ | √ | √ | + +## 6. Contributing Open Source Time Series Large Models to IoTDB-AINode + +Support adding new built-in models to AINode. The specific steps are as follows (using chronos2 as an example): + +* **Send an email to the [dev@iotdb.apache.org](mailto:dev@iotdb.apache.org) mailing list or submit an issue in the main repository to initiate preliminary discussion** +* **Submit a Pull Request to the main branch** + +1. Check the open source license used by the model and declare it in the IoTDB repository. +2. Create a new package for the new built-in model in iotdb-core/ainode/iotdb/ainode/core/model; + 1. Ensure it contains the model configuration class; + 2. Ensure it contains the model class for executing inference tasks; + 3. Ensure it contains the pipeline class inheriting from AINode inference task pipeline; + + ```Bash + root@rootMacBook-Pro model % eza --tree --level=2 . + . + ├── chronos2 + │ ├── __init__.py + │ ├── base.py + │ ├── chronos_bolt.py + │ ├── config.py + │ ├── dataset.py + │ ├── layers.py + │ ├── model.py + │ ├── pipeline_chronos2.py # Inheriting AINode inference task pipeline + │ └── utils.py + ├── sktime + ├── sundial + └── timer_xl + ``` +3. Add the metadata of the new model in iotdb-core/ainode/iotdb/ainode/core/model/model_info.py; + ```Python + BUILTIN_HF_TRANSFORMERS_MODEL_MAP = { + "chronos2": ModelInfo( + model_id="chronos2", # Unique identifier of the model + category=ModelCategory.BUILTIN, # Model category, choose BUILTIN + state=ModelStates.INACTIVE, + model_type="t5", # Model type, must not duplicate other builtin models + pipeline_cls="pipeline_chronos2.Chronos2Pipeline", # Inheriting AINode inference pipeline + repo_id="amazon/chronos-2", # [Optional] Huggingface weights + auto_map={ + "AutoConfig": "config.Chronos2CoreConfig", # Ensure it points to the model's configuration class + "AutoModelForCausalLM": "model.Chronos2Model", # Ensure it points to the model class for inference + }, + ), + } + ``` +4. Add the corresponding model in integration-test/src/test/java/org/apache/iotdb/ainode/utils/AINodeTestUtils.java. + ```Java + public static final Map BUILTIN_LTSM_MAP = + Stream.of( + new AbstractMap.SimpleEntry<>( + "sundial", new FakeModelInfo("sundial", "sundial", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "timer_xl", new FakeModelInfo("timer_xl", "timer", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "chronos2", new FakeModelInfo("chronos2", "t5", "builtin", "active"))) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + ``` +5. Submit a pull request, and only merge after passing the pipeline tests. + +* **Packaging and Deployment** + +1. Compile AINode to obtain the installation package. + ```Bash + # Command to simultaneously build IoTDB and AINode + mvn clean package -pl distribution -P with-ainode -am -DskipTests + # Command to build AINode only + mvn clean package -pl iotdb-core/ainode -P with-ainode -am -DskipTests + ``` +2. Ensure the model can obtain weights at runtime. + 1. If the model weights can be obtained online from Huggingface, ensure `repo_id` is filled in; + 2. Otherwise, manually place the model weights in `data/ainode/models/builtin/` before starting AINode or during runtime. + + ```Bash + root@rootMacBook-Pro models % eza --tree --level=3 . + . + ├── __init__.py + ├── builtin + │ ├── __init__.py + │ ├── chronos2 + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ ├── sundial + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ └── timer_xl + │ ├── __init__.py + │ ├── config.json + │ └── model.safetensors + └── user_defined + ``` + +* **Full Example** + +Full example can be referenced at https://github.com/apache/iotdb/pull/16903 \ No newline at end of file diff --git a/src/UserGuide/latest/AI-capability/AINode_Upgrade_timecho.md b/src/UserGuide/latest/AI-capability/AINode_Upgrade_timecho.md new file mode 100644 index 000000000..5fa365dd5 --- /dev/null +++ b/src/UserGuide/latest/AI-capability/AINode_Upgrade_timecho.md @@ -0,0 +1,559 @@ + + +# AINode + +AINode is a native IoTDB node that supports the registration, management, and invocation of time series related models, with built-in industry-leading self-developed time series large models such as the Tsinghua University's Timer series. It can be invoked through standard SQL statements to achieve millisecond-level real-time inference on time series data, supporting applications such as time series trend prediction, missing value imputation, and anomaly detection. + +The system architecture is shown in the following diagram: + +![](/img/AINode-0-en.png) + +The responsibilities of the three nodes are as follows: + +* **ConfigNode**: Responsible for distributed node management and load balancing. +* **DataNode**: Responsible for receiving and parsing user SQL requests; responsible for storing time series data; responsible for data preprocessing calculations. +* **AINode**: Responsible for managing and using time series models. + +## 1. Advantages + +Compared to building machine learning services separately, it has the following advantages: + +* **Simple and easy to use**: No need to use Python or Java programming, SQL statements can be used to complete the entire process of machine learning model management and inference. For example, creating a model can use the CREATE MODEL statement, and using a model for inference can use the CALL INFERENCE (...) statement, etc., which is simpler and more convenient to use. +* **Avoid data migration**: Using IoTDB native machine learning can directly apply time series data stored in IoTDB to machine learning model inference, without moving data to a separate machine learning service platform, thus accelerating data processing, improving security, and reducing costs. + +![](/img/AInode1.png) + +* **Built-in advanced algorithms**: Supports industry-leading machine learning analysis algorithms, covering typical time series analysis tasks, empowering time series databases with native data analysis capabilities. Such as: + * **Time Series Forecasting**: Learn change patterns from past time series to output the most likely prediction of future sequences based on given past observations. + * **Anomaly Detection for Time Series**: Detect and identify anomalies in given time series data to help discover abnormal behavior in time series. + +## 2. Basic Concepts + +* **Model**: Machine learning model, which takes time series data as input and outputs the results or decisions of the analysis task. The model is the basic management unit of AINode, supporting the addition (registration), deletion, query, modification (fine-tuning), and use (inference) of models. +* **Create**: Load external designed or trained model files or algorithms into AINode, managed and used by IoTDB. +* **Inference**: Use the created model to complete the time series analysis task applicable to the model on the specified time series data. +* **Built-in**: AINode comes with common time series analysis scenario (e.g., prediction and anomaly detection) machine learning algorithms or self-developed models. + +![](/img/AInode2.png) + +## 3. Installation and Deployment + +AINode deployment can be referenced in the documentation [AINode Deployment](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md). + +## 4. Usage Guide + +TimechoDB-AINode supports three major functions: model inference, model fine-tuning, and model management (registration, viewing, deletion, loading, unloading, etc.). The following sections will explain them in detail. + +### 4.1 Model Inference + +SQL syntax as follows: + +```SQL +call inference(,inputSql,(=)*) +``` + +After completing the model registration (built-in model inference does not require a registration process), the inference function of the model can be used by calling the inference function with the call keyword. The corresponding parameter descriptions are as follows: + +* **model\_id**: Corresponds to an already registered model +* **sql**: SQL query statement, the result of the query is used as the input for model inference. The dimensions of the rows and columns in the query result need to match the size specified in the specific model config. (It is not recommended to use the `SELECT *` clause in this sql, because in IoTDB, `*` does not sort columns, so the column order is undefined. It is recommended to use `SELECT ot` to ensure that the column order matches the expected input of the model.) +* **parameterName/parameterValue**: currently supported: + + | Parameter Name | Parameter Type | Parameter Description | Default Value | + | ---------------- | -------------- | ----------------------- | -------------- | + | **generateTime** | boolean | Whether to include a timestamp column in the result | false | + | **outputLength** | int | Specifies the output length of the result | 96 | + +Notes: +1. The prerequisite for using built-in time series large models for inference is that the local machine has the corresponding model weights, located at `/TIMECHODB_AINODE_HOME/data/ainode/models/builtin/model_id/`. If the local machine does not have model weights, it will automatically pull from HuggingFace. Please ensure that the local machine can directly access HuggingFace. +2. In deep learning applications, it is common to use time-derived features (the time column in the data) as covariates and input them into the model together with the data to improve model performance. However, the time column is generally not included in the model's output results. To ensure universality, the model inference result only corresponds to the model's true output. If the model does not output a time column, the result will not contain it. + +**Example** + +Sample data [ETTh-tree](/img/ETTh-tree.csv) + +Below is an example of using the sundial model for inference. The input is 96 rows, and the output is 48 rows. We use SQL to perform the inference. + +```SQL +IoTDB> select OT from root.db.** ++-----------------------------+---------------+ +| Time|root.db.etth.OT| ++-----------------------------+---------------+ +|2016-07-01T00:00:00.000+08:00| 30.531| +|2016-07-01T01:00:00.000+08:00| 27.787| +|2016-07-01T02:00:00.000+08:00| 27.787| +|2016-07-01T03:00:00.000+08:00| 25.044| +|2016-07-01T04:00:00.000+08:00| 21.948| +| ...... | ...... | +|2016-07-04T19:00:00.000+08:00| 29.546| +|2016-07-04T20:00:00.000+08:00| 29.475| +|2016-07-04T21:00:00.000+08:00| 29.264| +|2016-07-04T22:00:00.000+08:00| 30.953| +|2016-07-04T23:00:00.000+08:00| 31.726| ++-----------------------------+---------------+ +Total line number = 96 + +IoTDB> call inference(sundial,"select OT from root.db.**", generateTime=True, outputLength=48) ++-----------------------------+------------------+ +| Time| output| ++-----------------------------+------------------+ +|2016-07-04T23:00:00.000+08:00|30.537494659423828| +|2016-07-04T23:59:22.500+08:00|29.619892120361328| +|2016-07-05T00:58:45.000+08:00|28.815832138061523| +|2016-07-05T01:58:07.500+08:00| 27.91131019592285| +|2016-07-05T02:57:30.000+08:00|26.893848419189453| +| ...... | ...... | +|2016-07-06T17:33:07.500+08:00| 24.40607261657715| +|2016-07-06T18:32:30.000+08:00| 25.00441551208496| +|2016-07-06T19:31:52.500+08:00|24.907312393188477| +|2016-07-06T20:31:15.000+08:00|25.156436920166016| +|2016-07-06T21:30:37.500+08:00|25.335433959960938| ++-----------------------------+------------------+ +Total line number = 48 +``` + +### 4.2 Model Fine-Tuning + +AINode supports model fine-tuning through SQL. + +**SQL Syntax** + +```SQL +createModel + | CREATE MODEL modelId=identifier (WITH HYPERPARAMETERS LR_BRACKET hparamPair (COMMA hparamPair)* RR_BRACKET)? FROM MODEL existingModelId=identifier ON DATASET LR_BRACKET trainingData RR_BRACKET + ; + +trainingData + : dataElement(COMMA dataElement)* + ; + +dataElement + : pathPatternElement (LR_BRACKET timeRange RR_BRACKET)? + ; + +pathPatternElement + : PATH path=prefixPath + ; +``` + +**Parameter Description** + +| Name | Description | +| ------ |---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| modelId | The unique identifier of the fine-tuned model | +| hparamPair | Key-value pairs of hyperparameters used for fine-tuning, currently supported:
`train_epochs`: int type, number of fine-tuning epochs
`iter_per_epoch`: int type, number of iterations per epoch
`learning_rate`: double type, learning rate | +| existingModelId | The base model used for fine-tuning | +| trainingData | The dataset used for fine-tuning | + +**Example** + +1. Select the data of the measurement point root.db.etth.ot within a specified time range as the fine-tuning dataset, and create the model sundialv2 based on sundial. + +```SQL +IoTDB> CREATE MODEL sundialv2 FROM MODEL sundial ON DATASET (PATH root.db.etth.OT([1467302400000, 1467644400000))) +Msg: The statement is executed successfully. +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| +| sundialv2| sundial| fine_tuned| training| ++---------------------+---------+-----------+---------+ +``` + +2. Fine-tuning tasks are started asynchronously in the background, and logs can be seen in the AINode process; after fine-tuning is completed, query and use the new model. + +```SQL +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| +| sundialv2| sundial| fine_tuned| active| ++---------------------+---------+-----------+---------+ +``` + +### 4.3 Register Custom Models + +**Transformers models that meet the following requirements can be registered to AINode:** + +1. AINode currently uses transformers version v4.56.2, so when building the model, it is necessary to **avoid inheriting low-version (<4.50) interfaces**; +2. The model needs to inherit a type of AINode inference task pipeline (currently supports the forecasting pipeline): + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + Preprocess the input data before the inference task starts, including shape verification and numerical conversion. + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + Postprocess the output results after the inference task ends. + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + Preprocess the input data before passing it to the model for inference, verifying the shape and type of input data. + + Args: + inputs (list[dict]): + Input data, a list of dictionaries, each dictionary contains: + - 'targets': a tensor of shape (input_length,) or (target_count, input_length). + - 'past_covariates': optional, a dictionary of tensors, each tensor shape is (input_length,). + - 'future_covariates': optional, a dictionary of tensors, each tensor shape is (input_length,). + + infer_kwargs (dict, optional): Additional inference keyword parameters, such as: + - `output_length`(int): If 'future_covariates' is provided, used to validate its validity. + + Raises: + ValueError: If the input format is incorrect (e.g., missing keys, invalid tensor shapes). + + Returns: + Preprocessed and validated input data, ready for model inference. + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + Perform prediction on the given input. + + Parameters: + inputs: Input data for prediction. The type and structure depend on the specific implementation of the model. + **infer_kwargs: Additional inference parameters, such as: + - `output_length`(int): The number of time points the model should generate. + + Returns: + Prediction output, specific form depends on the specific implementation of the model. + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + Postprocess the model output after inference, verifying the shape of output tensors and ensuring they meet the expected dimensions. + + Args: + outputs: + Model output, a list of 2D tensors, each tensor shape is `[target_count, output_length]`. + + Raises: + InferenceModelInternalException: If the output tensor shape is invalid (e.g., dimension error). + ValueError: If the output format is incorrect. + + Returns: + list[torch.Tensor]: + Postprocessed output, a list of 2D tensors. + """ + pass + ``` +3. Modify the model configuration file config.json to ensure it contains the following fields: + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // Specify the model Config class + "AutoModelForCausalLM": "model.Chronos2Model" // Specify the model class + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // Specify the model's inference pipeline + "model_type": "custom_t5", // Specify the model type + } + ``` + + 1. Must specify the model Config class and model class through auto\_map; + 2. Must integrate and specify the inference pipeline class; + 3. For AINode-managed built-in (builtin) and custom (user\_defined) models, the model category (model\_type) also serves as a unique identifier. That is, the model category to be registered must not be duplicated with any existing model type. Models created through fine-tuning will inherit the model category of the original model. +4. Ensure that the model directory to be registered contains the following files, and the model configuration file name and weight file name are not customizable: + 1. Model configuration file: config.json; + 2. Model weight file: model.safetensors; + 3. Model code: other .py files. + +**The SQL syntax for registering a custom model is as follows:** + +```SQL +CREATE MODEL USING URI +``` + +**Parameter Description:** + +* **model\_id**: The unique identifier of the custom model; non-repetitive, with the following constraints: + * Allowed characters: [0-9 a-z A-Z \_ ] (letters, numbers (not at the beginning), underscore (not at the beginning)) + * Length limit: 2-64 characters + * Case-sensitive +* **uri**: The local URI address containing the model code and weights. + +**Registration Example:** + +Upload a custom Transformers model from a local path. AINode will copy the folder to the user\_defined directory. + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +After executing the SQL, the registration process will be performed asynchronously. The registration status of the model can be viewed by checking the model display (see the model display section). After the model is registered, it can be called using normal query methods to perform model inference. + +### 4.4 View Models + +Registered models can be viewed using the view command. + +```SQL +SHOW MODELS +``` + +In addition to directly displaying all model information, you can specify `model_id` to view the information of a specific model. + +```SQL +SHOW MODELS -- Only display specific model +``` + +The results of model display include the following: + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| Model ID | Model Type | Model Category | Model State | + +Where, State model state machine flow diagram as follows: + +![](/img/ainode-upgrade-state-timecho-en.png) + +State machine flow explanation: + +1. After starting AINode, executing `show models` command, only **system built-in (BUILTIN)** models can be viewed. +2. Users can import their own models, which are identified as **user-defined (USER_DEFINED)**; AINode will attempt to parse the model type (ModelType) from the model configuration file; if parsing fails, this field will display as empty. +3. Time series large models (built-in models) weight files are not packaged with AINode, AINode automatically downloads them when starting. + 1. During download, it is ACTIVATING, and after successful download, it becomes ACTIVE, failure becomes INACTIVE. +4. After users start a model fine-tuning task, the model state is TRAINING, and after successful training, it becomes ACTIVE, failure becomes FAILED. +5. If the fine-tuning task is successful, after fine-tuning, the model will automatically rename the best checkpoint (training file) based on the best metric and become the user-specified model\_id. + +**View Example** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| sundialx_1| sundial| fine_tuned| active| +| sundialx_4| sundial| fine_tuned| training| +| sundialx_5| sundial| fine_tuned| failed| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +Built-in traditional time series models are introduced as follows: + +| Model Name | Core Concept | Applicable Scenario | Main Features | +|------------|--------------|---------------------|---------------| +| **ARIMA** (Autoregressive Integrated Moving Average) | Combines autoregression (AR), differencing (I), and moving average (MA), used for predicting stationary time series or data that can be made stationary through differencing. | Univariate time series prediction, such as stock prices, sales, economic indicators. | 1. Suitable for linear trends and weak seasonality data. 2. Need to select parameters (p,d,q). 3. Sensitive to missing values. | +| **Holt-Winters** (Three-parameter exponential smoothing) | Based on exponential smoothing, introduces three components: level, trend, and seasonality, suitable for data with trend and seasonality. | Time series with clear seasonality and trend, such as monthly sales, power demand. | 1. Can handle additive or multiplicative seasonality. 2. Gives higher weight to recent data. 3. Simple to implement. | +| **Exponential Smoothing** | Uses weighted average of historical data, with weights decreasing exponentially over time, emphasizing the importance of recent observations. | Time series without obvious seasonality but with trend, such as short-term demand prediction. | 1. Few parameters, simple calculation. 2. Suitable for stationary or slowly changing sequences. 3. Can be extended to double or triple exponential smoothing. | +| **Naive Forecaster** | Uses the observation value from the previous period as the prediction for the next period, the simplest baseline model. | As a comparison baseline for other models, or simple prediction when data has no obvious pattern. | 1. No training required. 2. Sensitive to sudden changes. 3. Seasonal naive variant can use the value from the same period of the previous season for prediction. | +| **STL Forecaster** (Seasonal-Trend Decomposition) | Based on STL decomposition of time series, predict trend, seasonal, and residual components separately and combine. | Time series with complex seasonality, trend, and non-linear patterns, such as climate data, traffic flow. | 1. Can handle non-fixed seasonality. 2. Robust to outliers. 3. After decomposition, other models can be combined to predict each component. | +| **Gaussian HMM** (Gaussian Hidden Markov Model) | Assumes that observed data is generated by hidden states, with each state's observed probability following a Gaussian distribution. | State sequence prediction or classification, such as speech recognition, financial state recognition. | 1. Suitable for modeling time series state. 2. Assumes observed values are independent given the state. 3. Need to specify the number of hidden states. | +| **GMM HMM** (Gaussian Mixture Hidden Markov Model) | An extension of Gaussian HMM, where the observed probability of each state is described by a Gaussian Mixture Model, capturing more complex observed distributions. | Scenarios requiring multi-modal observed distributions, such as complex action recognition, bio-signal analysis. | 1. More flexible than single Gaussian. 2. More parameters, higher computational complexity. 3. Need to train the number of GMM components. | +| **STRAY** (Singular Value-based Anomaly Detection) | Detects anomalies in high-dimensional data through Singular Value Decomposition (SVD), commonly used for time series anomaly detection. | High-dimensional time series anomaly detection, such as sensor networks, IT system monitoring. | 1. No distribution assumption required. 2. Can handle high-dimensional data. 3. Sensitive to global anomalies, may miss local anomalies. | + +Built-in time series large models are introduced as follows: + +| Model Name | Core Concept | Applicable Scenario | Main Features | +|------------|--------------|---------------------|---------------| +| **Timer-XL** | Time series large model supporting ultra-long context, enhanced generalization ability through large-scale industrial data pre-training. | Complex industrial prediction requiring extremely long historical data, such as energy, aerospace, transportation. | 1. Ultra-long context support, can handle tens of thousands of time points as input. 2. Multi-scenario coverage, supports non-stationary, multi-variable, and covariate prediction. 3. Pre-trained on trillions of high-quality industrial time series data. | +| **Timer-Sundial** | A generative foundational model using "Transformer + TimeFlow" architecture, focused on probabilistic prediction. | Zero-shot prediction scenarios requiring quantification of uncertainty, such as finance, supply chain, new energy power generation. | 1. Strong zero-shot generalization ability, supports point prediction and probabilistic prediction. 2. Flexible analysis of any statistical characteristics of the prediction distribution. 3. Innovative generative architecture, achieving efficient non-deterministic sample generation. | +| **Chronos-2** | A universal time series foundational model based on discrete tokenization paradigm, transforming prediction into language modeling tasks. | Fast zero-shot univariate prediction, and scenarios that can leverage covariates (e.g., promotions, weather) to improve results. | 1. Strong zero-shot probabilistic prediction ability. 2. Supports covariate unified modeling, but has strict input requirements: a. The set of names of future covariates must be a subset of the set of names of historical covariates; b. The length of each historical covariate must equal the length of the target variable; c. The length of each future covariate must equal the prediction length; 3. Uses an efficient encoder-based structure, balancing performance and inference speed. | + +### 4.5 Delete Models + +For registered models, users can delete them through SQL. AINode will delete the corresponding model folder in the user\_defined directory. The SQL syntax is as follows: + +```SQL +DROP MODEL +``` + +The model id that has been successfully registered must be specified to delete the corresponding model. Since model deletion involves model data cleanup, the operation will not be completed immediately, and the model status becomes DROPPING, and the model in this state cannot be used for model inference. Note that this feature does not support deleting built-in models. + +### 4.6 Load/Unload Models + +To adapt to different scenarios, AINode provides the following two model loading strategies: + +* **On-demand loading**: Load the model temporarily when inference is performed, and release resources after completion. Suitable for testing or low-load scenarios. +* **Persistent loading**: Load the model persistently in memory (CPU) or GPU memory, to support high-concurrency inference. Users only need to specify the model to load or unload through SQL, and AINode will automatically manage the number of instances. The status of the persistent model can also be viewed at any time. + +The following sections will detail the loading/unloading model content: + +1. Configuration parameters + +Support editing the following configuration items to set persistent loading related parameters. + +```Properties +# The proportion of device memory/GPU memory available for AINode inference +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# The proportion of memory that each loaded model instance needs to occupy, i.e., model occupancy * this value +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. Show available devices + +Support viewing all available device IDs through the following SQL command. + +```SQL +SHOW AI_DEVICES +``` + +Example + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. Load model + +Support loading models through the following SQL command, and the system will **automatically balance** the number of model instances based on hardware resource usage. + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +Parameter requirements + +* **existing\_model\_id:** The model id to be specified, current version only supports timer\_xl and sundial. +* **device\_id:** The location where the model is loaded. + * **cpu:** Load to the memory of the AINode server. + * **gpu\_id:** Load to the corresponding GPU of the AINode server, e.g., "0, 1" means load to the two GPUs numbered 0 and 1. + +Example + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. Unload model + +Support unloading specified models through the following SQL command, and the system will **reallocate** the freed resources to other models. + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +Parameter requirements + +* **existing\_model\_id:** The model id to be specified, current version only supports timer\_xl and sundial. +* **device\_id:** The location where the model is loaded. + * **cpu:** Attempt to unload the specified model from the memory of the AINode server. + * **gpu\_id:** Attempt to unload the specified model from the corresponding GPU of the AINode server, e.g., "0, 1" means attempt to unload from the two GPUs numbered 0 and 1. + +Example + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. Show loaded models + +Support viewing the models that have been manually loaded through the following SQL command, and you can specify the device via `device_id`. + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # View models in specified devices +``` + +Example: sundial model is loaded on memory, gpu_0, and gpu_1 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +Explanation: +* DeviceId: Device ID +* ModelId: Loaded model ID +* Count(instances): Number of model instances on each device (automatically assigned by the system) + +### 4.7 Introduction to Time Series Large Models + +AINode currently supports multiple time series large models. For related introductions and deployment usage, please refer to [Time Series Large Models](../AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md) + +## 5. Permission Management + +When using AINode related features, you can use IoTDB's own authentication for permission management. Users can only use the model management related features if they have the USE_MODEL permission. When using the inference feature, users need to have permission to access the source sequence corresponding to the SQL for the input model. + +| Permission Name | Permission Scope | Administrator User (Default ROOT) | Ordinary User | Path-related | +| --------------- | ----------------- | ------------------------------- | -------------- | ------------ | +| USE_MODEL | create model / show models / drop model | √ | √ | x | +| READ_DATA | call inference | √ | √ | √ | \ No newline at end of file diff --git a/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade.md b/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade.md new file mode 100644 index 000000000..440615354 --- /dev/null +++ b/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: TimeSeries-Large-Model_Upgrade_apache.html +--- + diff --git a/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md b/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md new file mode 100644 index 000000000..bc20138a4 --- /dev/null +++ b/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md @@ -0,0 +1,157 @@ + +# Time Series Large Models + +## 1. Introduction + +Time Series Large Models are foundational models specifically designed for time series data analysis. The IoTDB team has been developing the Timer, a self-researched foundational time series model, which is based on the Transformer architecture and pre-trained on massive multi-domain time series data, supporting downstream tasks such as time series forecasting, anomaly detection, and time series imputation. The AINode platform developed by the team also supports the integration of cutting-edge time series foundational models from the industry, providing users with diverse model options. Unlike traditional time series analysis techniques, these large models possess universal feature extraction capabilities and can serve a wide range of analytical tasks through zero-shot analysis, fine-tuning, and other services. + +All technical achievements in the field of time series large models related to this paper (including both the team's self-researched models and industry-leading directions) have been published in top international machine learning conferences, with specific details in the appendix. + +## 2. Application Scenarios + +* **Time Series Forecasting**: Providing time series data forecasting services for industrial production, natural environments, and other fields to help users understand future trends in advance. +* **Data Imputation**: Performing context-based filling for missing segments in time series to enhance the continuity and integrity of the dataset. +* **Anomaly Detection**: Using autoregressive analysis technology to monitor time series data in real-time, promptly alerting potential anomalies. + +![](/img/LargeModel10.png) + +## 3. Timer-1 Model + +The Timer model (non-built-in model) not only demonstrates excellent few-shot generalization and multi-task adaptability, but also acquires a rich knowledge base through pre-training, endowing it with universal capabilities to handle diverse downstream tasks, with the following characteristics: + +* **Generalizability**: The model can achieve industry-leading deep model prediction results through fine-tuning with only a small number of samples. +* **Universality**: The model design is flexible, capable of adapting to various different task requirements, and supports variable input and output lengths, enabling it to function effectively in various application scenarios. +* **Scalability**: As the number of model parameters increases or the scale of pre-training data expands, the model's performance will continue to improve, ensuring that the model can continuously optimize its prediction effectiveness as time and data volume grow. + +![](/img/model01.png) + +## 4. Timer-XL Model + +Timer-XL further extends and upgrades the network structure based on Timer, achieving comprehensive breakthroughs in multiple dimensions: + +* **Ultra-Long Context Support**: This model breaks through the limitations of traditional time series forecasting models, supporting the processing of inputs with thousands of Tokens (equivalent to tens of thousands of time points), effectively solving the context length bottleneck problem. +* **Coverage of Multi-Variable Forecasting Scenarios**: Supports various forecasting scenarios, including the prediction of non-stationary time series, multi-variable prediction tasks, and predictions involving covariates, meeting diversified business needs. +* **Large-Scale Industrial Time Series Dataset**: Pre-trained on a trillion-scale time series dataset from the industrial IoT field, the dataset possesses important characteristics such as massive scale, excellent quality, and rich domain coverage, covering multiple fields including energy, aerospace, steel, and transportation. + +![](/img/model02.png) + +## 5. Timer-Sundial Model + +Timer-Sundial is a series of generative foundational models focused on time series forecasting. The base version has 128 million parameters and has been pre-trained on 1 trillion time points, with the following core characteristics: + +* **Strong Generalization Performance**: Possesses zero-shot forecasting capabilities and can support both point forecasting and probabilistic forecasting simultaneously. +* **Flexible Prediction Distribution Analysis**: Not only can it predict means or quantiles, but it can also evaluate any statistical properties of the prediction distribution through the raw samples generated by the model. +* **Innovative Generative Architecture**: Employs a "Transformer + TimeFlow" collaborative architecture - the Transformer learns the autoregressive representations of time segments, while the TimeFlow module transforms random noise into diverse prediction trajectories based on the flow-matching framework (Flow-Matching), achieving efficient generation of non-deterministic samples. + +![](/img/model03.png) + +## 6. Chronos-2 Model + +Chronos-2 is a universal time series foundational model developed by the Amazon Web Services (AWS) research team, evolved from the Chronos discrete token modeling paradigm. This model is suitable for both zero-shot univariate forecasting and covariate forecasting. Its main characteristics include: + +* **Probabilistic Forecasting Capability**: The model outputs multi-step prediction results in a generative manner, supporting quantile or distribution-level forecasting to characterize future uncertainty. +* **Zero-Shot General Forecasting**: Leveraging the contextual learning ability acquired through pre-training, it can directly execute forecasting on unseen datasets without retraining or parameter updates. +* **Unified Modeling of Multi-Variable and Covariates**: Supports joint modeling of multiple related time series and their covariates under the same architecture to improve prediction performance for complex tasks. However, it has strict input requirements: + * The set of names of future covariates must be a subset of the set of names of historical covariates; + * The length of each historical covariate must equal the length of the target variable; + * The length of each future covariate must equal the prediction length; +* **Efficient Inference and Deployment**: The model adopts a compact encoder-only structure, maintaining strong generalization capabilities while ensuring inference efficiency. + +![](/img/timeseries-large-model-chronos2.png) + +## 7. Performance Showcase + +Time Series Large Models can adapt to real time series data from various different domains and scenarios, demonstrating excellent processing capabilities across various tasks. The following shows the actual performance on different datasets: + +**Time Series Forecasting:** + +Leveraging the forecasting capabilities of Time Series Large Models, future trends of time series can be accurately predicted. The blue curve in the following figure represents the predicted trend, while the red curve represents the actual trend, with both curves highly consistent. + +![](/img/LargeModel03.png) + +**Data Imputation:** + +Using Time Series Large Models to fill missing data segments through predictive imputation. + +![](/img/timeseries-large-model-data-imputation.png) + +**Anomaly Detection:** + +Using Time Series Large Models to accurately identify outliers that deviate significantly from the normal trend. + +![](/img/LargeModel05.png) + +## 8. Deployment and Usage + +1. Open the IoTDB CLI console and check that the ConfigNode, DataNode, and AINode nodes are all Running. + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. In an online environment, the first startup of the AINode node will automatically pull the Timer-XL, Sundial, and Chronos2 models. + + > Note: + > + > * The AINode installation package does not include model weight files. + > * The automatic pull feature depends on the deployment environment having HuggingFace network access capability. + > * AINode supports manual upload of model weight files. For specific operation methods, refer to [Importing Weight Files](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md#_3-3-importing-built-in-weight-files). + +3. Check if the models are available. + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### Appendix + +**[1]** Timer: Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[2]** TIMER-XL: LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING, Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[3]** Sundial: A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ Back]() + +**[4]** Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821**. [↩ Back]() \ No newline at end of file diff --git a/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md b/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md new file mode 100644 index 000000000..c7fde0bf2 --- /dev/null +++ b/src/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md @@ -0,0 +1,157 @@ + +# Time Series Large Models + +## 1. Introduction + +Time Series Large Models are foundational models specifically designed for time series data analysis. The IoTDB team has been developing the Timer, a self-researched foundational time series model, which is based on the Transformer architecture and pre-trained on massive multi-domain time series data, supporting downstream tasks such as time series forecasting, anomaly detection, and time series imputation. The AINode platform developed by the team also supports the integration of cutting-edge time series foundational models from the industry, providing users with diverse model options. Unlike traditional time series analysis techniques, these large models possess universal feature extraction capabilities and can serve a wide range of analytical tasks through zero-shot analysis, fine-tuning, and other services. + +All technical achievements in the field of time series large models related to this paper (including both the team's self-researched models and industry-leading directions) have been published in top international machine learning conferences, with specific details in the appendix. + +## 2. Application Scenarios + +* **Time Series Forecasting**: Providing time series data forecasting services for industrial production, natural environments, and other fields to help users understand future trends in advance. +* **Data Imputation**: Performing context-based filling for missing segments in time series to enhance the continuity and integrity of the dataset. +* **Anomaly Detection**: Using autoregressive analysis technology to monitor time series data in real-time, promptly alerting potential anomalies. + +![](/img/LargeModel10.png) + +## 3. Timer-1 Model + +The Timer model (non-built-in model) not only demonstrates excellent few-shot generalization and multi-task adaptability, but also acquires a rich knowledge base through pre-training, endowing it with universal capabilities to handle diverse downstream tasks, with the following characteristics: + +* **Generalizability**: The model can achieve industry-leading deep model prediction results through fine-tuning with only a small number of samples. +* **Universality**: The model design is flexible, capable of adapting to various different task requirements, and supports variable input and output lengths, enabling it to function effectively in various application scenarios. +* **Scalability**: As the number of model parameters increases or the scale of pre-training data expands, the model's performance will continue to improve, ensuring that the model can continuously optimize its prediction effectiveness as time and data volume grow. + +![](/img/model01.png) + +## 4. Timer-XL Model + +Timer-XL further extends and upgrades the network structure based on Timer, achieving comprehensive breakthroughs in multiple dimensions: + +* **Ultra-Long Context Support**: This model breaks through the limitations of traditional time series forecasting models, supporting the processing of inputs with thousands of Tokens (equivalent to tens of thousands of time points), effectively solving the context length bottleneck problem. +* **Coverage of Multi-Variable Forecasting Scenarios**: Supports various forecasting scenarios, including the prediction of non-stationary time series, multi-variable prediction tasks, and predictions involving covariates, meeting diversified business needs. +* **Large-Scale Industrial Time Series Dataset**: Pre-trained on a trillion-scale time series dataset from the industrial IoT field, the dataset possesses important characteristics such as massive scale, excellent quality, and rich domain coverage, covering multiple fields including energy, aerospace, steel, and transportation. + +![](/img/model02.png) + +## 5. Timer-Sundial Model + +Timer-Sundial is a series of generative foundational models focused on time series forecasting. The base version has 128 million parameters and has been pre-trained on 1 trillion time points, with the following core characteristics: + +* **Strong Generalization Performance**: Possesses zero-shot forecasting capabilities and can support both point forecasting and probabilistic forecasting simultaneously. +* **Flexible Prediction Distribution Analysis**: Not only can it predict means or quantiles, but it can also evaluate any statistical properties of the prediction distribution through the raw samples generated by the model. +* **Innovative Generative Architecture**: Employs a "Transformer + TimeFlow" collaborative architecture - the Transformer learns the autoregressive representations of time segments, while the TimeFlow module transforms random noise into diverse prediction trajectories based on the flow-matching framework (Flow-Matching), achieving efficient generation of non-deterministic samples. + +![](/img/model03.png) + +## 6. Chronos-2 Model + +Chronos-2 is a universal time series foundational model developed by the Amazon Web Services (AWS) research team, evolved from the Chronos discrete token modeling paradigm. This model is suitable for both zero-shot univariate forecasting and covariate forecasting. Its main characteristics include: + +* **Probabilistic Forecasting Capability**: The model outputs multi-step prediction results in a generative manner, supporting quantile or distribution-level forecasting to characterize future uncertainty. +* **Zero-Shot General Forecasting**: Leveraging the contextual learning ability acquired through pre-training, it can directly execute forecasting on unseen datasets without retraining or parameter updates. +* **Unified Modeling of Multi-Variable and Covariates**: Supports joint modeling of multiple related time series and their covariates under the same architecture to improve prediction performance for complex tasks. However, it has strict input requirements: + * The set of names of future covariates must be a subset of the set of names of historical covariates; + * The length of each historical covariate must equal the length of the target variable; + * The length of each future covariate must equal the prediction length; +* **Efficient Inference and Deployment**: The model adopts a compact encoder-only structure, maintaining strong generalization capabilities while ensuring inference efficiency. + +![](/img/timeseries-large-model-chronos2.png) + +## 7. Performance Showcase + +Time Series Large Models can adapt to real time series data from various different domains and scenarios, demonstrating excellent processing capabilities across various tasks. The following shows the actual performance on different datasets: + +**Time Series Forecasting:** + +Leveraging the forecasting capabilities of Time Series Large Models, future trends of time series can be accurately predicted. The blue curve in the following figure represents the predicted trend, while the red curve represents the actual trend, with both curves highly consistent. + +![](/img/LargeModel03.png) + +**Data Imputation:** + +Using Time Series Large Models to fill missing data segments through predictive imputation. + +![](/img/timeseries-large-model-data-imputation.png) + +**Anomaly Detection:** + +Using Time Series Large Models to accurately identify outliers that deviate significantly from the normal trend. + +![](/img/LargeModel05.png) + +## 8. Deployment and Usage + +1. Open the IoTDB CLI console and check that the ConfigNode, DataNode, and AINode nodes are all Running. + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. In an online environment, the first startup of the AINode node will automatically pull the Timer-XL, Sundial, and Chronos2 models. + + > Note: + > + > * The AINode installation package does not include model weight files. + > * The automatic pull feature depends on the deployment environment having HuggingFace network access capability. + > * AINode supports manual upload of model weight files. For specific operation methods, refer to [Importing Weight Files](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md#_3-3-importing-built-in-weight-files). + +3. Check if the models are available. + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### Appendix + +**[1]** Timer: Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[2]** TIMER-XL: LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING, Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ Back]() + +**[3]** Sundial: A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ Back]() + +**[4]** Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821**. [↩ Back]() \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade.md b/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade.md new file mode 100644 index 000000000..6f44068b6 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: AINode_Upgrade_apache.html +--- + \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade_apache.md b/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade_apache.md new file mode 100644 index 000000000..b7a4fc62d --- /dev/null +++ b/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade_apache.md @@ -0,0 +1,596 @@ + + +# AINode + +AINode 是支持时序相关模型注册、管理、调用的 IoTDB 原生节点，内置业界领先的自研时序大模型，如清华自研时序模型 Timer 系列，可通过标准 SQL 语句进行调用，实现时序数据的毫秒级实时推理，可支持时序趋势预测、缺失值填补、异常值检测等应用场景。 + +系统架构如下图所示： + +![](/img/AINode-0.png) + +三种节点的职责如下： + +* **ConfigNode**：负责分布式节点管理和负载均衡。 +* **DataNode**：负责接收并解析用户的 SQL请求；负责存储时间序列数据；负责数据的预处理计算。 +* **AINode**：负责时序模型的管理和使用。 + +## 1. 优势特点 + +与单独构建机器学习服务相比，具有以下优势： + +* **简单易用**：无需使用 Python 或 Java 编程，使用 SQL 语句即可完成机器学习模型管理与推理的完整流程。如创建模型可使用CREATE MODEL语句、使用模型进行推理可使用`SELECT * FROM FORECAST (...) ` 语句等，使用更加简单便捷。 +* **避免数据迁移**：使用 IoTDB 原生机器学习可以将存储在 IoTDB 中的数据直接应用于机器学习模型的推理，无需将数据移动到单独的机器学习服务平台，从而加速数据处理、提高安全性并降低成本。 + +![](/img/h1.png) + +* **内置先进算法**：支持业内领先机器学习分析算法，覆盖典型时序分析任务，为时序数据库赋能原生数据分析能力。如： + * **时间序列预测（Time Series Forecasting）**：从过去时间序列中学习变化模式；从而根据给定过去时间的观测值，输出未来序列最可能的预测。 + * **时序异常检测（Anomaly Detection for Time Series）**：在给定的时间序列数据中检测和识别异常值，帮助发现时间序列中的异常行为。 + +## 2. 基本概念 + +* **模型（Model）**：机器学习模型，以时序数据作为输入，输出分析任务的结果或决策。模型是 AINode 的基本管理单元，支持模型的增（注册）、删、查、用（推理）。 +* **创建（Create）**: 将外部设计或训练好的模型文件或算法加载到 AINode 中，由 IoTDB 统一管理与使用。 +* **推理（Inference）**：使用创建的模型在指定时序数据上完成该模型适用的时序分析任务。 +* **内置能力（Built-in）**：AINode 自带常见时序分析场景（例如预测与异常检测）的机器学习算法或自研模型。 + +![](/img/AINode-new.png) + +## 3. 安装部署 + +AINode 的部署可参考文档 [AINode 部署](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md) 。 + +## 4. 使用指导 + +AINode 支持模型推理和模型管理（注册、查看、删除、加载、卸载等）两大功能，下面章节将进行详细说明。 + +### 4.1 模型推理 + +AINode 表模型支持对单一目标变量进行预测的推理功能，下文将详细介绍该功能的语法定义、参数说明以及使用实例。 + +1. **SQL 语法** + +```SQL +SELECT * FROM FORECAST( + MODEL_ID, + TARGETS, -- 获取目标变量的 SQL + OUTPUT_START_TIME, + OUTPUT_LENGTH, + OUTPUT_INTERVAL, + TIMECOL, + PRESERVE_INPUT, + MODEL_OPTIONS]? +) +``` + +* 内置模型推理无需注册流程，通过 forecast 函数，指定 model\_id 就可以使用模型的推理功能。 +* 参数介绍 + +| 参数名 | 参数类型 | 参数属性 | 描述 | 是否必填 | 备注 | +|---------------------|-------|-------------------------------------------------|-----------------------------------------------------------| ---------- | -------------------------------------------------------------------------------- | +| model\_id | 标量参数 | 字符串类型 | 预测所用模型的唯一标识 | 是| | +| targets | 表参数 | SET SEMANTIC | 待预测目标变量的输入数据。IoTDB会自动将数据按时间升序排序再交给AINode 。 | 是 | 使用 SQL 描述带预测目标变量的输入数据，输入的 SQL 不合法时会有对应的查询报错。| +| output\_start\_time | 标量参数 | 时间戳类型。默认值：目标变量最后一个时间戳 + output\_interval | 输出的预测点的起始时间戳【即起报时间】 | 否 | 必须大于目标变量时间戳的最大值 | +| output\_length | 标量参数 | INT32 类型。默认值：96 | 输出窗口大小 | 否| 必须大于 0 | +| output\_interval | 标量参数 | 时间间隔类型。默认值：(输入数据的最后一个时间戳 - 输入数据的第一个时间戳) / n - 1 | 输出的预测点之间的时间间隔支持的单位是 ns、us、ms、s、m、h、d、w | 否 | 必须大于 0| +| timecol | 标量参数 | 字符串类型。默认值：time | 时间列名 | 否 | 必须为存在于 targets 中的且数据类型为 TIMESTAMP 的列 | +| preserve\_input | 标量参数 | 布尔类型。默认值：false | 是否在输出结果集中保留目标变量输入的所有原始行 | 否| | +| model\_options | 标量参数 | 字符串类型。默认值：空字符串 | 模型相关的 key-value 对，比如是否需要对输入进行归一化等。不同的 key-value 对以 ';' 间隔 | 否| | + +说明： + +* **默认行为**：预测 targets 的所有列。当前仅支持 INT32、INT64、FLOAT、DOUBLE 类型。 +* **输入数据要求**： + * 必须包含时间列。 + * 行数要求：不足最低行数会报错，超过最大行数则自动截取末尾数据。 +* **输出结果**： + * 包含所有目标变量列，数据类型与原表一致。 + * 若指定 `preserve_input=true`，会额外增加 `is_input` 列来标识原始数据行。 +* **时间戳生成**： + * 使用 `OUTPUT_START_TIME`（可选）作为预测起始时间点，并以此划分历史与未来数据。 + * 使用 `OUTPUT_INTERVAL`（可选，默认为输入数据的采样间隔）作为输出时间间隔。第 N 行的时间戳计算公式为：`OUTPUT_START_TIME + (N - 1) * OUTPUT_INTERVAL`。 + +2. **使用示例** + +提前创建数据库 etth 及表 eg + +```SQL +create database etth; +create table eg (hufl FLOAT FIELD, hull FLOAT FIELD, mufl FLOAT FIELD, mull FLOAT FIELD, lufl FLOAT FIELD, lull FLOAT FIELD, ot FLOAT FIELD) +``` + +准备原始数据 [ETTh1-tab](/img/ETTh1-tab.csv) + +使用表 eg 中测点 ot 已知的 96 行数据，预测其未来的 96 行数据. + +```SQL +IoTDB:etth> select Time, HUFL,HULL,MUFL,MULL,LUFL,LULL,OT from eg LIMIT 96 ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +| Time| HUFL| HULL| MUFL| MULL| LUFL| LULL| OT| ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +|2016-07-01T00:00:00.000+08:00| 5.827|2.009|1.599|0.462|4.203| 1.34|30.531| +|2016-07-01T01:00:00.000+08:00| 5.693|2.076|1.492|0.426|4.142|1.371|27.787| +|2016-07-01T02:00:00.000+08:00| 5.157|1.741|1.279|0.355|3.777|1.218|27.787| +|2016-07-01T03:00:00.000+08:00| 5.09|1.942|1.279|0.391|3.807|1.279|25.044| +...... +Total line number = 96 +It costs 0.119s + +IoTDB:etth> select * from forecast( + model_id => 'sundial', + targets => (select Time, ot from etth.eg where time >= 2016-08-07T18:00:00.000+08:00 limit 1440) order BY time, + output_length => 96 +) ++-----------------------------+---------+ +| time| ot| ++-----------------------------+---------+ +|2016-10-06T18:00:00.000+08:00|20.781654| +|2016-10-06T19:00:00.000+08:00|20.252121| +|2016-10-06T20:00:00.000+08:00|19.960138| +|2016-10-06T21:00:00.000+08:00|19.662334| +...... +Total line number = 96 +It costs 1.615s +``` + +### 4.2 注册自定义模型 + +**符合以下要求的 Transformers 模型可以注册到 AINode 中：** + +1. AINode 目前使用 v4.56.2 版本的 transformers，构建模型时需**避免继承低版本（<4.50）接口**； +2. 模型需继承一类 AINode 的推理任务流水线（当前支持预测流水线）： + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + 在推理任务开始前对输入数据进行前处理，包括形状验证和数值转换。 + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + 在推理任务结束后对输出结果进行后处理。 + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + 在将输入数据传递给模型进行推理之前进行预处理，验证输入数据的形状和类型。 + + Args: + inputs (list[dict]): + 输入数据，字典列表，每个字典包含： + - 'targets': 形状为 (input_length,) 或 (target_count, input_length) 的张量。 + - 'past_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + - 'future_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + + infer_kwargs (dict, optional): 推理的额外关键字参数，如： + - `output_length`(int): 如果提供'future_covariates'，用于验证其有效性。 + + Raises: + ValueError: 如果输入格式不正确（例如，缺少键、张量形状无效）。 + + Returns: + 经过预处理和验证的输入数据，可直接用于模型推理。 + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + 对给定输入执行预测。 + + Parameters: + inputs: 用于进行预测的输入数据。类型和结构取决于模型的具体实现。 + **infer_kwargs: 额外的推理参数，例如： + - `output_length`(int): 模型应该生成的时间点数量。 + + Returns: + 预测输出，具体形式取决于模型的具体实现。 + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + 在推理后对模型输出进行后处理，验证输出数据的形状并确保其符合预期维度。 + + Args: + outputs: + 模型输出，2D张量列表，每个张量形状为 `[target_count, output_length]`。 + + Raises: + InferenceModelInternalException: 如果输出张量形状无效（例如，维数错误）。 + ValueError: 如果输出格式不正确。 + + Returns: + list[torch.Tensor]: + 后处理后的输出，将是一个2D张量列表。 + """ + pass + ``` +3. 修改模型配置文件 config.json，确保包含以下字段： + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // 指定模型 Config 类 + "AutoModelForCausalLM": "model.Chronos2Model" // 指定模型类 + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // 指定模型的推理流水线 + "model_type": "custom_t5", // 指定模型类型 + } + ``` + + 1. 必须通过 auto\_map 指定模型的 Config 类和模型类； + 2. 必须集成并指定推理流水线类； + 3. 对于 AINode 管理的内置（builtin）和自定义（user\_defined）模型，模型类别（model\_type）也作为不可重复的唯一标识。即，要注册的模型类别不得与任何已存在的模型类型重复。 +4. 确保要注册的模型目录包含以下文件，且模型配置文件名称和权重文件名称不支持自定义： + 1. 模型配置文件：config.json； + 2. 模型权重文件：model.safetensors； + 3. 模型代码：其它 .py 文件。 + +**注册自定义模型的 SQL 语法如下所示：** + +```SQL +CREATE MODEL USING URI +``` + +**参数说明：** + +* **model\_id**：自定义模型的唯一标识；不可重复，有以下约束： + * 允许出现标识符 [ 0-9 a-z A-Z \_ ] （字母，数字（非开头），下划线（非开头）） + * 长度限制为 2-64 字符 + * 大小写敏感 +* **uri**：包含模型代码和权重的本地 uri 地址。 + +**注册示例：** + +从本地路径上传自定义 Transformers 模型，AINode 会将该文件夹拷贝至 user\_defined 目录中。 + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +SQL执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见查看模型章节）。模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。 + +### 4.3 查看模型 + +注册成功的模型可以通过查看指令查询模型的具体信息。 + +```SQL +SHOW MODELS +``` + +除了直接展示所有模型的信息外，可以指定`model_id`来查看某一具体模型的信息。 + +```SQL +SHOW MODELS -- 只展示特定模型 +``` + +模型展示的结果中包含如下内容： + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| 模型ID | 模型类型 | 模型种类 | 模型状态 | + +其中，State 模型状态机流转示意图如下: + +![](/img/ainode-upgrade-state-apache.png) + +状态机流程说明： + +1. 启动 AINode 后，执行 `show models` 命令，仅能查看到**系统内置（BUILTIN）**的模型。 +2. 用户可导入自己的模型，这类模型的来源标识为**用户自定义（USER\_DEFINED）**；AINode 会尝试从模型配置文件中解析模型类型（ModelType），若解析失败，该字段则显示为空。 +3. 时序大模型（内置模型）权重文件不随 AINode 打包，AINode 启动时自动下载。 + 1. 下载过程中为 ACTIVATING，下载成功转变为 ACTIVE，失败则变成 INACTIVE。 + +**查看示例** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +内置传统时序模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|----------------------------------| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **ARIMA**(自回归整合移动平均模型) | 结合自回归(AR)、差分(I)和移动平均(MA)，用于预测平稳时间序列或可通过差分变为平稳的数据。 | 单变量时间序列预测，如股票价格、销量、经济指标等。| 1. 适用于线性趋势和季节性较弱的数据。2. 需要选择参数 (p,d,q)。3. 对缺失值敏感。 | +| **Holt-Winters**(三参数指数平滑) | 基于指数平滑，引入水平、趋势和季节性三个分量，适用于具有趋势和季节性的数据。 | 有明显季节性和趋势的时间序列，如月度销售额、电力需求等。 | 1. 可处理加性或乘性季节性。2. 对近期数据赋予更高权重。3. 简单易实现。 | +| **Exponential Smoothing**(指数平滑) | 通过加权平均历史数据，权重随时间指数递减，强调近期观测值的重要性。 | 无显著季节性但存在趋势的数据，如短期需求预测。 | 1. 参数少，计算简单。2. 适合平稳或缓慢变化序列。3. 可扩展为双指数或三指数平滑。 | +| **Naive Forecaster**(朴素预测器) | 使用最近一期的观测值作为下一期的预测值，是最简单的基准模型。 | 作为其他模型的比较基准，或数据无明显模式时的简单预测。 | 1. 无需训练。2. 对突发变化敏感。3. 季节性朴素变体可用前一季节同期值预测。 | +| **STL Forecaster**(季节趋势分解预测) | 基于STL分解时间序列，分别预测趋势、季节性和残差分量后组合。 | 具有复杂季节性、趋势和非线性模式的数据，如气候数据、交通流量。 | 1. 能处理非固定季节性。2. 对异常值稳健。3. 分解后可结合其他模型预测各分量。 | +| **Gaussian HMM**(高斯隐马尔可夫模型) | 假设观测数据由隐藏状态生成，每个状态的观测概率服从高斯分布。 | 状态序列预测或分类，如语音识别、金融状态识别。 | 1. 适用于时序数据的状态建模。2. 假设观测值在给定状态下独立。3. 需指定隐藏状态数量。 | +| **GMM HMM** (高斯混合隐马尔可夫模型) | 扩展Gaussian HMM，每个状态的观测概率由高斯混合模型描述，可捕捉更复杂的观测分布。 | 需要多模态观测分布的场景，如复杂动作识别、生物信号分析。 | 1. 比单一高斯更灵活。2. 参数更多，计算复杂度高。3. 需训练GMM成分数。 | +| **STRAY**(基于奇异值的异常检测) | 通过奇异值分解(SVD)检测高维数据中的异常点，常用于时间序列异常检测。 | 高维时间序列的异常检测，如传感器网络、IT系统监控。 | 1. 无需分布假设。2. 可处理高维数据。3. 对全局异常敏感，局部异常可能漏检。 | + +内置时序大模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | 支持超长上下文的时序大模型，通过大规模工业数据预训练增强泛化能力。 | 需利用极长历史数据的复杂工业预测，如能源、航空航天、交通等领域。 | 1. 超长上下文支持，可处理数万时间点输入。2. 多场景覆盖，支持非平稳、多变量及协变量预测。3. 基于万亿级高质量工业时序数据预训练。 | +| **Timer-Sundial** | 采用“Transformer + TimeFlow”架构的生成式基础模型，专注于概率预测。 | 需要量化不确定性的零样本预测场景，如金融、供应链、新能源发电预测。 | 1. 强大的零样本泛化能力，支持点预测与概率预测 2. 可灵活分析预测分布的任意统计特性。3. 创新生成架构，实现高效的非确定性样本生成。 | +| **Chronos-2** | 基于离散词元化范式的通用时序基础模型，将预测转化为语言建模任务。 | 快速零样本单变量预测，以及可借助协变量（如促销、天气）提升效果的场景。 | 1. 强大的零样本概率预测能力。2. 支持协变量统一建模，但对输入有严格要求：a. 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集；b. 每个历史协变量的长度必须等于目标变量的长度； c. 每个未来协变量的长度必须等于预测长度；3. 采用高效的编码器式结构，兼顾性能与推理速度。 | + +### 4.4 删除模型 + +对于注册成功的模型，用户可以通过 SQL 进行删除，AINode 会将 user\_defined 目录下的对应模型文件夹整个删除。其 SQL 语法如下： + +```SQL +DROP MODEL +``` + +需要指定已经成功注册的模型 model\_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。 + +### 4.5 加载/卸载模型 + +为适应不同场景，AINode 提供以下两种模型加载策略： + +* 即时加载：即推理时临时加载模型，结束后释放资源。适用于测试或低负载场景。 +* 常驻加载：即将模型持久化加载在内存（CPU）或显存（GPU）中，以支持高并发推理。用户只需通过 SQL 指定加载或卸载的模型，AINode 会自动管理实例数量。当前常驻模型的状态也可随时查看。 + +下文将详细介绍加载/卸载模型的相关内容： + +1. 配置参数 + +支持通过编辑如下配置项设置常驻加载相关参数。 + +```Properties +# AINode 在推理时可使用的设备内存/显存占总量的比例 +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# AINode 每个加载的模型实例需要占用的内存比例，即模型占用*该值 +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. 展示可用的 device + +支持通过如下 SQL 命令查看所有可用的设备 ID + +```SQL +SHOW AI_DEVICES +``` + +示例 + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. 加载模型 + +支持通过如下 SQL 命令手动加载模型，系统根据硬件资源使用情况**自动均衡**模型实例数量。 + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 加载到 AINode 所在服务器的内存中。 + * **gpu\_id:** 加载到 AINode 所在服务器的对应显卡中，如 "0, 1" 表示加载到编号为 0 和 1 的两张显卡中。 + +示例 + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. 卸载模型 + +支持通过如下 SQL 命令手动卸载指定模型的所有实例，系统会**重分配**空闲出的资源给其他模型 + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 尝试从 AINode 所在服务器的内存中卸载指定模型。 + * **gpu\_id:** 尝试从 AINode 所在服务器的对应显卡中卸载指定模型，如 "0, 1" 表示尝试从编号为 0 和 1 的两张显卡卸载指定模型。 + +示例 + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. 展示加载的模型 + +支持通过如下 SQL 命令查看已经手动加载的模型实例，可通过 `device_id `指定设备。 + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # 展示指定设备中的模型实例 +``` + +示例：在内存、gpu\_0 和 gpu\_1 两张显卡加载了sundial 模型 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +说明： + +* DeviceId : 设备 ID +* ModelId ：加载的模型 ID +* Count(instances) ：每个设备中的模型实例数量（系统自动分配） + +### 4.6 时序大模型介绍 + +AINode 目前支持多种时序大模型，相关介绍及部署使用可参考[时序大模型](../AI-capability/TimeSeries-Large-Model_Upgrade_apache.md) + +## 5. 权限管理 + +使用 AINode 相关的功能时，可以使用IoTDB本身的鉴权去做一个权限管理，用户只有在具备 USE\_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。 + +| **权限名称** | **权限范围** | **管理员用户（默认ROOT）** | **普通用户** | +| ------------------------- | ----------------------------------------- | ---------------------------------- | -------------------- | +| USE\_MODEL | create model / show models / drop model | √ | √ | +| READ\_SCHEMA&READ\_DATA | forecast | √ | √ | + + +## 6. 向 IoTDB-AINode 贡献开源时序大模型 + +支持在 AINode 新增自定义内置模型，具体操作步骤如下（以 chronos2 为例）： + +* **向 [dev@iotdb.apache.org](mailto:dev@iotdb.apache.org) 邮件列表发送邮件或在项目主仓库提交 issue，发起初步讨论** +* **向主分支提交 Pull Request** + +1. 检查模型所用的开源协议，并在 IoTDB 仓库进行对应声明。 +2. 在 iotdb-core/ainode/iotdb/ainode/core/model 创建新内置模型对应的包； + 1. 确保包含模型配置类； + 2. 确保包含执行推理任务的模型类； + 3. 确保包含继承 AINode 推理任务流水线的类； + + ```Bash + root@rootMacBook-Pro model % eza --tree --level=2 . + . + ├── chronos2 + │ ├── __init__.py + │ ├── base.py + │ ├── chronos_bolt.py + │ ├── config.py + │ ├── dataset.py + │ ├── layers.py + │ ├── model.py + │ ├── pipeline_chronos2.py # 继承 AINode 推理任务流水线 + │ └── utils.py + ├── sktime + ├── sundial + └── timer_xl + ``` +3. 在 iotdb-core/ainode/iotdb/ainode/core/model/model\_info.py 新增该模型的元信息； + ```Python + BUILTIN_HF_TRANSFORMERS_MODEL_MAP = { + "chronos2": ModelInfo( + model_id="chronos2", # 模型的唯一标识 + category=ModelCategory.BUILTIN, # 模型类别，选择 BUILTIN + state=ModelStates.INACTIVE, + model_type="t5", # 模型种类，不能和其它 builtin 模型相同 + pipeline_cls="pipeline_chronos2.Chronos2Pipeline", # 继承 AINode 的推理流水线 + repo_id="amazon/chronos-2", # 【可选】Huggingface 权重 + auto_map={ + "AutoConfig": "config.Chronos2CoreConfig", # 确保指向模型的配置类 + "AutoModelForCausalLM": "model.Chronos2Model", # 确保指向推理所用的模型类 + }, + ), + } + ``` +4. 在 integration-test/src/test/java/org/apache/iotdb/ainode/utils/AINodeTestUtils.java 添加对应模型。 + ```Java + public static final Map BUILTIN_LTSM_MAP = + Stream.of( + new AbstractMap.SimpleEntry<>( + "sundial", new FakeModelInfo("sundial", "sundial", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "timer_xl", new FakeModelInfo("timer_xl", "timer", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "chronos2", new FakeModelInfo("chronos2", "t5", "builtin", "active"))) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + ``` +5. 提交 pull request，确保通过流水线测试后才能合并。 + +* **打包部署** + +1. 编译 AINode，获取安装包； + ```Bash + # 同时构建 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 + ``` +2. 在运行时确保模型能获取权重。 + 1. 若模型权重可从 Huggingface 在线获取，确保已填写`repo_id`； + 2. 否则，可在 AINode 启动前/运行时手动将模型权重放在`data/ainode/models/builtin/`。 + + ```Bash + root@rootMacBook-Pro models % eza --tree --level=3 . + . + ├── __init__.py + ├── builtin + │ ├── __init__.py + │ ├── chronos2 + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ ├── sundial + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ └── timer_xl + │ ├── __init__.py + │ ├── config.json + │ └── model.safetensors + └── user_defined + ``` + +* **完整示例** + +完整示例可参考 https://github.com/apache/iotdb/pull/16903 diff --git a/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade_timecho.md b/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade_timecho.md new file mode 100644 index 000000000..6439e43d7 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/AI-capability/AINode_Upgrade_timecho.md @@ -0,0 +1,749 @@ + + +# AINode + +AINode 是支持时序相关模型注册、管理、调用的 IoTDB 原生节点，内置业界领先的自研时序大模型，如清华自研时序模型 Timer 系列，可通过标准 SQL 语句进行调用，实现时序数据的毫秒级实时推理，可支持时序趋势预测、缺失值填补、异常值检测等应用场景。 + +系统架构如下图所示： + +![](/img/AINode-0.png) + +三种节点的职责如下： + +* **ConfigNode**：负责分布式节点管理和负载均衡。 +* **DataNode**：负责接收并解析用户的 SQL请求；负责存储时间序列数据；负责数据的预处理计算。 +* **AINode**：负责时序模型的管理和使用。 + +## 1. 优势特点 + +与单独构建机器学习服务相比，具有以下优势： + +* **简单易用**：无需使用 Python 或 Java 编程，使用 SQL 语句即可完成机器学习模型管理与推理的完整流程。如创建模型可使用CREATE MODEL语句、使用模型进行推理可使用 `SELECT * FROM FORECAST (...)` 语句等，使用更加简单便捷。 +* **避免数据迁移**：使用 IoTDB 原生机器学习可以将存储在 IoTDB 中的数据直接应用于机器学习模型的推理，无需将数据移动到单独的机器学习服务平台，从而加速数据处理、提高安全性并降低成本。 + +![](/img/h1.png) + +* **内置先进算法**：支持业内领先机器学习分析算法，覆盖典型时序分析任务，为时序数据库赋能原生数据分析能力。如： + * **时间序列预测（Time Series Forecasting）**：从过去时间序列中学习变化模式；从而根据给定过去时间的观测值，输出未来序列最可能的预测。 + * **时序异常检测（Anomaly Detection for Time Series）**：在给定的时间序列数据中检测和识别异常值，帮助发现时间序列中的异常行为。 + +## 2. 基本概念 + +* **模型（Model）**：机器学习模型，以时序数据作为输入，输出分析任务的结果或决策。模型是 AINode 的基本管理单元，支持模型的增（注册）、删、查、改（微调）、用（推理）。 +* **创建（Create）**: 将外部设计或训练好的模型文件或算法加载到 AINode 中，由 IoTDB 统一管理与使用。 +* **推理（Inference）**：使用创建的模型在指定时序数据上完成该模型适用的时序分析任务。 +* **内置能力（Built-in）**：AINode 自带常见时序分析场景（例如预测与异常检测）的机器学习算法或自研模型。 + +![](/img/AINode-new.png) + +## 3. 安装部署 + +AINode 的部署可参考文档 [AINode 部署](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md) 。 + +## 4. 使用指导 + +TimechoDB-AINode 支持模型推理、模型微调以及模型管理（注册、查看、删除、加载、卸载等）三大功能，下面章节将进行详细说明。 + +### 4.1 模型推理 + +TimechoDB-AINode 表模型提供以下时序预测能力： + +* **单变量预测**：支持对单一目标变量进行预测。 +* **协变量预测**：可同时对多个目标变量进行联合预测，并支持在预测中引入协变量，以提升预测的准确性。 + +下文将详细介绍预测推理功能的语法定义、参数说明以及使用实例。 + +1. **SQL 语法** + +```SQL +SELECT * FROM FORECAST( + MODEL_ID, + TARGETS, -- 获取目标变量的 SQL + [HISTORY_COVS, -- 字符串，用于获取历史协变量的 SQL + FUTURE_COVS, -- 字符串，用于获取未来协变量的 SQL + OUTPUT_START_TIME, + OUTPUT_LENGTH, + OUTPUT_INTERVAL, + TIMECOL, + PRESERVE_INPUT, + MODEL_OPTIONS]? +) +``` + +* 内置模型推理无需注册流程，通过 forecast 函数，指定 model\_id 就可以使用模型的推理功能。 +* 参数介绍 + +| 参数名 | 参数类型 | 参数属性 | 描述 | 是否必填 | 备注 | +|---------------------|-------|----------------------------------------------------|-----------------------------------------------------------------------------------------| ---------- |--------------------------------------------------------------------------------------------------------------------------| +| model\_id | 标量参数 | 字符串类型 | 预测所用模型的唯一标识 | 是| | +| targets | 表参数 | SET SEMANTIC | 待预测目标变量的输入数据。IoTDB会自动将数据按时间升序排序再交给AINode 。 | 是 | 使用 SQL 描述带预测目标变量的输入数据，输入的 SQL 不合法时会有对应的查询报错。 | +| history\_covs | 标量参数 | 字符串类型（合法的表模型查询 SQL）默认：无 | 指定此次预测任务的协变量的历史数据，这些数据用于辅助目标变量的预测，AINode 不会对历史协变量输出预测结果。在将数据给予模型前，AINode 会自动将数据按时间升序排序。 | 否 | 1. 查询结果只能包含 FIELD 列； 2. 其它：不同模型可能会有独特要求，不符合时会抛出对应的错误。 | +| future\_covs | 标量参数 | 字符串类型（合法的表模型查询 SQL） 默认：无 | 指定此次预测任务部分协变量的未来数据，这些数据用于辅助目标变量的预测。 在将数据给予模型前，AINode 会自动将数据按时间升序排序。 | 否 | 1. 当且仅当设置 history\_covs 时可以指定此参数；2. 所涉及协变量名称必须是 history\_covs 的子集； 3. 查询结果只能包含 FIELD 列； 4. 其它：不同模型可能会有独特要求，不符合时会抛出对应的错误。 | +| output\_start\_time | 标量参数 | 时间戳类型。 默认值：目标变量最后一个时间戳 + output\_interval | 输出的预测点的起始时间戳 【即起报时间】 | 否 | 必须大于目标变量时间戳的最大值 | +| output\_length | 标量参数 | INT32 类型。 默认值：96 | 输出窗口大小 | 否 | 必须大于 0 | +| output\_interval | 标量参数 | 时间间隔类型。 默认值：(输入数据的最后一个时间戳 - 输入数据的第一个时间戳) / n - 1 | 输出的预测点之间的时间间隔 支持的单位是 ns、us、ms、s、m、h、d、w | 否 | 必须大于 0 | +| timecol | 标量参数 | 字符串类型。 默认值：time | 时间列名 | 否 | 必须为存在于 targets 中的且数据类型为 TIMESTAMP 的列 | +| preserve\_input | 标量参数 | 布尔类型。 默认值：false | 是否在输出结果集中保留目标变量输入的所有原始行 | 否 | | +| model\_options | 标量参数 | 字符串类型。 默认值：空字符串 | 模型相关的 key-value 对，比如是否需要对输入进行归一化等。不同的 key-value 对以 ';' 间隔 | 否 | | + +说明： + +* **默认行为**：预测 targets 的所有列。当前仅支持 INT32、INT64、FLOAT、DOUBLE 类型。 +* **输入数据要求**： + * 必须包含时间列。 + * 行数要求：不足最低行数会报错，超过最大行数则自动截取末尾数据。 + * 列数要求：单变量模型仅支持单列，多列将报错；协变量模型通常无限制，除非模型自身有明确约束。 + * 协变量预测时，SQL 语句中需明确指定 DATABASE。 +* **输出结果**： + * 包含所有目标变量列，数据类型与原表一致。 + * 若指定 `preserve_input=true`，会额外增加 `is_input` 列来标识原始数据行。 +* **时间戳生成**： + * 使用 `OUTPUT_START_TIME`（可选）作为预测起始时间点，并以此划分历史与未来数据。 + * 使用 `OUTPUT_INTERVAL`（可选，默认为输入数据的采样间隔）作为输出时间间隔。第 N 行的时间戳计算公式为：`OUTPUT_START_TIME + (N - 1) * OUTPUT_INTERVAL`。 + +2. **使用示例** + +**示例一：单变量预测** + +提前创建数据库 etth 及表 eg + +```SQL +create database etth; +create table eg (hufl FLOAT FIELD, hull FLOAT FIELD, mufl FLOAT FIELD, mull FLOAT FIELD, lufl FLOAT FIELD, lull FLOAT FIELD, ot FLOAT FIELD) +``` + +准备原始数据 [ETTh1-tab](/img/ETTh1-tab.csv) + +使用表 eg 中测点 ot 已知的 96 行数据，预测其未来的 96 行数据. + +```SQL +IoTDB:etth> select Time, HUFL,HULL,MUFL,MULL,LUFL,LULL,OT from eg LIMIT 96 ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +| Time| HUFL| HULL| MUFL| MULL| LUFL| LULL| OT| ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +|2016-07-01T00:00:00.000+08:00| 5.827|2.009|1.599|0.462|4.203| 1.34|30.531| +|2016-07-01T01:00:00.000+08:00| 5.693|2.076|1.492|0.426|4.142|1.371|27.787| +|2016-07-01T02:00:00.000+08:00| 5.157|1.741|1.279|0.355|3.777|1.218|27.787| +|2016-07-01T03:00:00.000+08:00| 5.09|1.942|1.279|0.391|3.807|1.279|25.044| +...... +Total line number = 96 +It costs 0.119s + +IoTDB:etth> select * from forecast( + model_id => 'sundial', + targets => (select Time, ot from etth.eg where time >= 2016-08-07T18:00:00.000+08:00 limit 1440) order BY time, + output_length => 96 +) ++-----------------------------+---------+ +| time| ot| ++-----------------------------+---------+ +|2016-10-06T18:00:00.000+08:00|20.781654| +|2016-10-06T19:00:00.000+08:00|20.252121| +|2016-10-06T20:00:00.000+08:00|19.960138| +|2016-10-06T21:00:00.000+08:00|19.662334| +...... +Total line number = 96 +It costs 1.615s +``` + +**示例二：协变量预测** + +提前创建表 tab\_real（存储原始真实数据） + +```SQL +create table tab_real (target1 DOUBLE FIELD, target2 DOUBLE FIELD, cov1 DOUBLE FIELD, cov2 DOUBLE FIELD, cov3 DOUBLE FIELD); +``` + +准备原始数据 + +```SQL +IoTDB:etth> SELECT * FROM tab_real ++-----------------------------+-------+-------+----+----+----+ +| time|target1|target2|cov1|cov2|cov3| ++-----------------------------+-------+-------+----+----+----+ +|1970-01-01T08:00:00.001+08:00| 1.0| 1.0| 1.0| 1.0| 1.0| +|1970-01-01T08:00:00.002+08:00| 2.0| 2.0| 2.0| 2.0| 2.0| +|1970-01-01T08:00:00.003+08:00| 3.0| 3.0| 3.0| 3.0| 3.0| +|1970-01-01T08:00:00.004+08:00| 4.0| 4.0| 4.0| 4.0| 4.0| +|1970-01-01T08:00:00.005+08:00| 5.0| 5.0| 5.0| 5.0| 5.0| +|1970-01-01T08:00:00.006+08:00| 6.0| 6.0| 6.0| 6.0| 6.0| +|1970-01-01T08:00:00.007+08:00| null| null|null|null| 7.0| +|1970-01-01T08:00:00.008+08:00| null| null|null|null| 8.0| ++-----------------------------+-------+-------+----+----+----+ + + +--写入语句 +IoTDB:etth> INSERT INTO tab_real (time, target1, target2, cov1, cov2, cov3) VALUES +(1, 1.0, 1.0, 1.0, 1.0, 1.0), +(2, 2.0, 2.0, 2.0, 2.0, 2.0), +(3, 3.0, 3.0, 3.0, 3.0, 3.0), +(4, 4.0, 4.0, 4.0, 4.0, 4.0), +(5, 5.0, 5.0, 5.0, 5.0, 5.0), +(6, 6.0, 6.0, 6.0, 6.0, 6.0), +(7, NULL, NULL, NULL, NULL, 7.0), +(8, NULL, NULL, NULL, NULL, 8.0); +``` + +* 预测任务一：使用历史协变量 cov1，cov2 和 cov3 辅助预测目标变量 target1 和 target2。 + + ![](/img/ainode-upgrade-table-forecast-timecho-1.png) + + * 使用表 tab\_real 中 cov1，cov2，cov3，target1，target2 的 前 6 行历史数据，预测目标变量 target1 和 target2 未来的 2 行数据 + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.338330268859863|7.338330268859863| + |1970-01-01T08:00:00.008+08:00| 8.02529525756836| 8.02529525756836| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.315s + ``` +* 预测任务二：使用相同表中的历史协变量 cov1，cov2 和已知协变量 cov3 辅助预测目标变量 target1 和 target2。 + + ![](/img/ainode-upgrade-table-forecast-timecho-2.png) + + * 使用表 tab\_real 中 cov1，cov2，cov3，target1，target2 的 前 6 行历史数据，以及同表中已知协变量 cov3 在未来的 2 行数据来预测目标变量 target1 和 target2 未来的 2 行数据 + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + FUTURE_COVS => ' + SELECT TIME, cov3 + FROM etth.tab_real + WHERE TIME >= 7 + LIMIT 2', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.244050025939941|7.244050025939941| + |1970-01-01T08:00:00.008+08:00|7.907227516174316|7.907227516174316| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.291s + ``` +* 预测任务三：使用不同表中的历史协变量 cov1，cov2 和已知协变量 cov3 辅助预测目标变量 target1 和 target2。 + + ![](/img/ainode-upgrade-table-forecast-timecho-3.png) + + * 提前创建表 tab\_cov\_forecast（存储已知协变量 cov3 的预测值 ），并准备相关数据。 + ```SQL + create table tab_cov_forecast (cov3 DOUBLE FIELD); + + --写入语句 + INSERT INTO tab_cov_forecast (time, cov3) VALUES (7, 7.0),(8, 8.0); + + IoTDB:etth> SELECT * FROM tab_cov_forecast + +----+----+ + |time|cov3| + +----+----+ + | 7| 7.0| + | 8| 8.0| + +----+----+ + ``` + * 使用表 tab\_real 中 cov1，cov2，cov3，target1，target2 已知的前 6 行数据，以及表 tab\_cov\_forecast 中已知协变量 cov3 在未来的 2 行数据来预测目标变量 target1 和 target2 未来的 2 行数据 + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + FUTURE_COVS => ' + SELECT TIME, cov3 + FROM etth.tab_cov_forecast + WHERE TIME >= 7 + LIMIT 2', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.244050025939941|7.244050025939941| + |1970-01-01T08:00:00.008+08:00|7.907227516174316|7.907227516174316| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.351s + ``` + + +### 4.2 模型微调 + +AINode 支持通过 SQL 进行模型微调任务。 + +**SQL 语法** + +```SQL +createModelStatement + | CREATE MODEL modelId=identifier (WITH HYPERPARAMETERS '(' hparamPair (',' hparamPair)* ')')? FROM MODEL existingModelId=identifier ON DATASET '(' targetData=string ')' + ; +hparamPair + : hparamKey=identifier '=' hyparamValue=primaryExpression + ; +``` + +**参数说明** + +| 名称 | 描述 | +| ----------------- |----------------------------------------------------------------------------------------------------------------------------------------| +| modelId | 微调出的模型的唯一标识 | +| hparamPair | 微调使用的超参数 key-value 对，目前支持如下：
`train_epochs`: int 类型，微调轮数
`iter_per_epoch`: int 类型，每轮微调的迭代次数
`learning_rate`: double 类型，学习率 | +| existingModelId | 微调使用的基座模型 | +| targetData | 用于获取微调使用的数据集的 SQL | + +**示例** + +1. 选择测点 ot 中指定时间范围的数据作为微调数据集，基于 sundial 创建模型 sundialv3。 + +```SQL +IoTDB> set sql_dialect=table +Msg: The statement is executed successfully. +IoTDB> CREATE MODEL sundialv3 FROM MODEL sundial ON DATASET ('SELECT time, ot from etth.eg where 1467302400000 <= time and time < 1517468400001') +Msg: The statement is executed successfully. +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| +| sundialv2| sundial| fine_tuned| active| +| sundialv3| sundial| fine_tuned| training| ++---------------------+---------+-----------+---------+ +``` + +2. 微调任务后台异步启动，可在 AINode 进程看到 log；微调完成后，查询并使用新的模型 + +```SQL +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| +| sundialv2| sundial| fine_tuned| active| +| sundialv3| sundial| fine_tuned| active| ++---------------------+---------+-----------+---------+ +``` + +### 4.3 注册自定义模型 + +**符合以下要求的 Transformers 模型可以注册到 AINode 中：** + +1. AINode 目前使用 v4.56.2 版本的 transformers，构建模型时需**避免继承低版本（<4.50）接口**； +2. 模型需继承一类 AINode 的推理任务流水线（当前支持预测流水线）： + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + 在推理任务开始前对输入数据进行前处理，包括形状验证和数值转换。 + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + 在推理任务结束后对输出结果进行后处理。 + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + 在将输入数据传递给模型进行推理之前进行预处理，验证输入数据的形状和类型。 + + Args: + inputs (list[dict]): + 输入数据，字典列表，每个字典包含： + - 'targets': 形状为 (input_length,) 或 (target_count, input_length) 的张量。 + - 'past_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + - 'future_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + + infer_kwargs (dict, optional): 推理的额外关键字参数，如： + - `output_length`(int): 如果提供'future_covariates'，用于验证其有效性。 + + Raises: + ValueError: 如果输入格式不正确（例如，缺少键、张量形状无效）。 + + Returns: + 经过预处理和验证的输入数据，可直接用于模型推理。 + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + 对给定输入执行预测。 + + Parameters: + inputs: 用于进行预测的输入数据。类型和结构取决于模型的具体实现。 + **infer_kwargs: 额外的推理参数，例如： + - `output_length`(int): 模型应该生成的时间点数量。 + + Returns: + 预测输出，具体形式取决于模型的具体实现。 + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + 在推理后对模型输出进行后处理，验证输出数据的形状并确保其符合预期维度。 + + Args: + outputs: + 模型输出，2D张量列表，每个张量形状为 `[target_count, output_length]`。 + + Raises: + InferenceModelInternalException: 如果输出张量形状无效（例如，维数错误）。 + ValueError: 如果输出格式不正确。 + + Returns: + list[torch.Tensor]: + 后处理后的输出，将是一个2D张量列表。 + """ + pass + ``` +3. 修改模型配置文件 config.json，确保包含以下字段： + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // 指定模型 Config 类 + "AutoModelForCausalLM": "model.Chronos2Model" // 指定模型类 + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // 指定模型的推理流水线 + "model_type": "custom_t5", // 指定模型类型 + } + ``` + + 1. 必须通过 auto\_map 指定模型的 Config 类和模型类； + 2. 必须集成并指定推理流水线类； + 3. 对于 AINode 管理的内置（builtin）和自定义（user\_defined）模型，模型类别（model\_type）也作为不可重复的唯一标识。即，要注册的模型类别不得与任何已存在的模型类型重复，通过微调创建的模型将继承原模型的模型类别。 +4. 确保要注册的模型目录包含以下文件，且模型配置文件名称和权重文件名称不支持自定义： + 1. 模型配置文件：config.json； + 2. 模型权重文件：model.safetensors； + 3. 模型代码：其它 .py 文件。 + +**注册自定义模型的 SQL 语法如下所示：** + +```SQL +CREATE MODEL USING URI +``` + +**参数说明：** + +* **model\_id**：自定义模型的唯一标识；不可重复，有以下约束： + * 允许出现标识符 [ 0-9 a-z A-Z \_ ] （字母，数字（非开头），下划线（非开头）） + * 长度限制为 2-64 字符 + * 大小写敏感 +* **uri**：包含模型代码和权重的本地 uri 地址。 + +**注册示例：** + +从本地路径上传自定义 Transformers 模型，AINode 会将该文件夹拷贝至 user\_defined 目录中。 + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +SQL执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见查看模型章节）。模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。 + +### 4.4 查看模型 + +注册成功的模型可以通过查看指令查询模型的具体信息。 + +```SQL +SHOW MODELS +``` + +除了直接展示所有模型的信息外，可以指定`model_id`来查看某一具体模型的信息。 + +```SQL +SHOW MODELS -- 只展示特定模型 +``` + +模型展示的结果中包含如下内容： + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| 模型ID | 模型类型 | 模型种类 | 模型状态 | + +其中，State 模型状态机流转示意图如下: + +![](/img/ainode-upgrade-state-timecho.png) + +状态机流程说明： + +1. 启动 AINode 后，执行 `show models` 命令，仅能查看到**系统内置（BUILTIN）**的模型。 +2. 用户可导入自己的模型，这类模型的来源标识为**用户自定义（USER\_****DEFINED）**；AINode 会尝试从模型配置文件中解析模型类型（ModelType），若解析失败，该字段则显示为空。 +3. 时序大模型（内置模型）权重文件不随 AINode 打包，AINode 启动时自动下载。 + 1. 下载过程中为 ACTIVATING，下载成功转变为 ACTIVE，失败则变成 INACTIVE。 +4. 用户启动模型微调任务后，正在训练的模型状态为 TRAINING，训练成功变为 ACTIVE，失败则是 FAILED。 +5. 若微调任务成功，微调结束后会统计所有 ckpt （训练文件）中指标最佳的文件并自动重命名，变成用户指定的 model\_id。 + +**查看示例** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| sundialx_1| sundial| fine_tuned| active| +| sundialx_4| sundial| fine_tuned| training| +| sundialx_5| sundial| fine_tuned| failed| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +内置传统时序模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|----------------------------------| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **ARIMA**(自回归整合移动平均模型) | 结合自回归(AR)、差分(I)和移动平均(MA)，用于预测平稳时间序列或可通过差分变为平稳的数据。 | 单变量时间序列预测，如股票价格、销量、经济指标等。| 1. 适用于线性趋势和季节性较弱的数据。2. 需要选择参数 (p,d,q)。3. 对缺失值敏感。 | +| **Holt-Winters**(三参数指数平滑) | 基于指数平滑，引入水平、趋势和季节性三个分量，适用于具有趋势和季节性的数据。 | 有明显季节性和趋势的时间序列，如月度销售额、电力需求等。 | 1. 可处理加性或乘性季节性。2. 对近期数据赋予更高权重。3. 简单易实现。 | +| **Exponential Smoothing**(指数平滑) | 通过加权平均历史数据，权重随时间指数递减，强调近期观测值的重要性。 | 无显著季节性但存在趋势的数据，如短期需求预测。 | 1. 参数少，计算简单。2. 适合平稳或缓慢变化序列。3. 可扩展为双指数或三指数平滑。 | +| **Naive Forecaster**(朴素预测器) | 使用最近一期的观测值作为下一期的预测值，是最简单的基准模型。 | 作为其他模型的比较基准，或数据无明显模式时的简单预测。 | 1. 无需训练。2. 对突发变化敏感。3. 季节性朴素变体可用前一季节同期值预测。 | +| **STL Forecaster**(季节趋势分解预测) | 基于STL分解时间序列，分别预测趋势、季节性和残差分量后组合。 | 具有复杂季节性、趋势和非线性模式的数据，如气候数据、交通流量。 | 1. 能处理非固定季节性。2. 对异常值稳健。3. 分解后可结合其他模型预测各分量。 | +| **Gaussian HMM**(高斯隐马尔可夫模型) | 假设观测数据由隐藏状态生成，每个状态的观测概率服从高斯分布。 | 状态序列预测或分类，如语音识别、金融状态识别。 | 1. 适用于时序数据的状态建模。2. 假设观测值在给定状态下独立。3. 需指定隐藏状态数量。 | +| **GMM HMM** (高斯混合隐马尔可夫模型) | 扩展Gaussian HMM，每个状态的观测概率由高斯混合模型描述，可捕捉更复杂的观测分布。 | 需要多模态观测分布的场景，如复杂动作识别、生物信号分析。 | 1. 比单一高斯更灵活。2. 参数更多，计算复杂度高。3. 需训练GMM成分数。 | +| **STRAY**(基于奇异值的异常检测) | 通过奇异值分解(SVD)检测高维数据中的异常点，常用于时间序列异常检测。 | 高维时间序列的异常检测，如传感器网络、IT系统监控。 | 1. 无需分布假设。2. 可处理高维数据。3. 对全局异常敏感，局部异常可能漏检。 | + +内置时序大模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | 支持超长上下文的时序大模型，通过大规模工业数据预训练增强泛化能力。 | 需利用极长历史数据的复杂工业预测，如能源、航空航天、交通等领域。 | 1. 超长上下文支持，可处理数万时间点输入。2. 多场景覆盖，支持非平稳、多变量及协变量预测。3. 基于万亿级高质量工业时序数据预训练。 | +| **Timer-Sundial** | 采用“Transformer + TimeFlow”架构的生成式基础模型，专注于概率预测。 | 需要量化不确定性的零样本预测场景，如金融、供应链、新能源发电预测。 | 1. 强大的零样本泛化能力，支持点预测与概率预测 2. 可灵活分析预测分布的任意统计特性。3. 创新生成架构，实现高效的非确定性样本生成。 | +| **Chronos-2** | 基于离散词元化范式的通用时序基础模型，将预测转化为语言建模任务。 | 快速零样本单变量预测，以及可借助协变量（如促销、天气）提升效果的场景。 | 1. 强大的零样本概率预测能力。2. 支持协变量统一建模，但对输入有严格要求：a. 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集；b. 每个历史协变量的长度必须等于目标变量的长度； c. 每个未来协变量的长度必须等于预测长度；3. 采用高效的编码器式结构，兼顾性能与推理速度。 | + + +### 4.5 删除模型 + +对于注册成功的模型，用户可以通过 SQL 进行删除，AINode 会将 user\_defined 目录下的对应模型文件夹整个删除。其 SQL 语法如下： + +```SQL +DROP MODEL +``` + +需要指定已经成功注册的模型 model\_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。 + +### 4.6 加载/卸载模型 + +为适应不同场景，AINode 提供以下两种模型加载策略： + +* 即时加载：即推理时临时加载模型，结束后释放资源。适用于测试或低负载场景。 +* 常驻加载：即将模型持久化加载在内存（CPU）或显存（GPU）中，以支持高并发推理。用户只需通过 SQL 指定加载或卸载的模型，AINode 会自动管理实例数量。当前常驻模型的状态也可随时查看。 + +下文将详细介绍加载/卸载模型的相关内容： + +1. 配置参数 + +支持通过编辑如下配置项设置常驻加载相关参数。 + +```Properties +# AINode 在推理时可使用的设备内存/显存占总量的比例 +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# AINode 每个加载的模型实例需要占用的内存比例，即模型占用*该值 +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. 展示可用的 device + +支持通过如下 SQL 命令查看所有可用的设备 ID + +```SQL +SHOW AI_DEVICES +``` + +示例 + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. 加载模型 + +支持通过如下 SQL 命令手动加载模型，系统根据硬件资源使用情况**自动均衡**模型实例数量。 + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 加载到 AINode 所在服务器的内存中。 + * **gpu\_id:** 加载到 AINode 所在服务器的对应显卡中，如 "0, 1" 表示加载到编号为 0 和 1 的两张显卡中。 + +示例 + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. 卸载模型 + +支持通过如下 SQL 命令手动卸载指定模型的所有实例，系统会**重分配**空闲出的资源给其他模型 + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 尝试从 AINode 所在服务器的内存中卸载指定模型。 + * **gpu\_id:** 尝试从 AINode 所在服务器的对应显卡中卸载指定模型，如 "0, 1" 表示尝试从编号为 0 和 1 的两张显卡卸载指定模型。 + +示例 + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. 展示加载的模型 + +支持通过如下 SQL 命令查看已经手动加载的模型实例，可通过 `device_id `指定设备。 + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # 展示指定设备中的模型实例 +``` + +示例：在内存、gpu\_0 和 gpu\_1 两张显卡加载了sundial 模型 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +说明： + +* DeviceId : 设备 ID +* ModelId ：加载的模型 ID +* Count(instances) ：每个设备中的模型实例数量（系统自动分配） + +### 4.7 时序大模型介绍 + +AINode 目前支持多种时序大模型，相关介绍及部署使用可参考[时序大模型](../AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md) + +## 5. 权限管理 + +使用 AINode 相关的功能时，可以使用IoTDB本身的鉴权去做一个权限管理，用户只有在具备 USE\_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。 + +| **权限名称** | **权限范围** | **管理员用户（默认ROOT）** | **普通用户** | +| ------------------------- | ----------------------------------------- | ---------------------------------- | -------------------- | +| USE\_MODEL | create model / show models / drop model | √ | √ | +| READ\_SCHEMA&READ\_DATA | forecast | √ | √ | diff --git a/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade.md b/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade.md new file mode 100644 index 000000000..440615354 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: TimeSeries-Large-Model_Upgrade_apache.html +--- + diff --git a/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md b/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md new file mode 100644 index 000000000..e1af1e1d0 --- /dev/null +++ b/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md @@ -0,0 +1,157 @@ + +# 时序大模型 + +## 1. 简介 + +时序大模型是专为时序数据分析设计的基础模型。IoTDB 团队长期自研时序基础模型 Timer，该模型基于 Transformer 架构，经海量多领域时序数据预训练，可支撑时序预测、异常检测、时序填补等下游任务；团队打造的 AINode 平台同时支持集成业界前沿时序基础模型，为用户提供多元选型。不同于传统时序分析技术，这类大模型具备通用特征提取能力，可通过零样本分析、微调等技术服务广泛的分析任务。 + +本文相关时序大模型领域的技术成果（含团队自研及业界前沿方向）均发表于国际机器学习顶级会议，具体内容见附录。 + +## 2. 应用场景 + +* **时序预测**：为工业生产、自然环境等领域提供时间序列数据的预测服务，帮助用户提前了解未来变化趋势。 +* **数据填补**：针对时间序列中的缺失序列段，进行上下文填补，以增强数据集的连续性和完整性。 +* **异常检测**：利用自回归分析技术，对时间序列数据进行实时监测，及时预警潜在的异常情况。 + +![](/img/LargeModel09.png) + +## 3. Timer-1 模型 + +Timer[1] 模型（非内置模型）不仅展现了出色的少样本泛化和多任务适配能力，还通过预训练获得了丰富的知识库，赋予了它处理多样化下游任务的通用能力，拥有以下特点： + +* **泛化性**：模型能够通过使用少量样本进行微调，达到行业内领先的深度模型预测效果。 +* **通用性**：模型设计灵活，能够适配多种不同的任务需求，并且支持变化的输入和输出长度，使其在各种应用场景中都能发挥作用。 +* **可扩展性**：随着模型参数数量的增加或预训练数据规模的扩大，模型效果会持续提升，确保模型能够随着时间和数据量的增长而不断优化其预测效果。 + +![](/img/model01.png) + +## 4. Timer-XL 模型 + +Timer-XL[2]基于 Timer 进一步扩展升级了网络结构，在多个维度全面突破： + +* **超长上下文支持**：该模型突破了传统时序预测模型的限制，支持处理数千个 Token（相当于数万个时间点）的输入，有效解决了上下文长度瓶颈问题。 +* **多变量预测场景覆盖**：支持多种预测场景，包括非平稳时间序列的预测、涉及多个变量的预测任务以及包含协变量的预测，满足多样化的业务需求。 +* **大规模工业时序数据集：**采用万亿大规模工业物联网领域的时序数据集进行预训练，数据集兼有庞大的体量、卓越的质量和丰富的领域等重要特质，覆盖能源、航空航天、钢铁、交通等多领域。 + +![](/img/model02.png) + +## 5. Timer-Sundial 模型 + +Timer-Sundial[3]是一个专注于时间序列预测的生成式基础模型系列，其基础版本拥有 1.28 亿参数，并在 1 万亿个时间点上进行了大规模预训练，其核心特性包括： + +* **强大的泛化性能：**具备零样本预测能力，可同时支持点预测和概率预测。 +* **灵活预测分布分析：**不仅能预测均值或分位数，还可通过模型生成的原始样本评估预测分布的任意统计特性。 +* **创新生成架构：** 采用 “Transformer + TimeFlow” 协同架构——Transformer 学习时间片段的自回归表征，TimeFlow 模块基于流匹配框架 (Flow-Matching) 将随机噪声转化为多样化预测轨迹，实现高效的非确定性样本生成。 + +![](/img/model03.png) + +## 6. Chronos-2 模型 + +Chronos-2 [4]是由 Amazon Web Services (AWS) 研究团队开发的，基于 Chronos 离散词元建模范式发展起来的通用时间序列基础模型，该模型同时适用于零样本单变量预测和协变量预测。其主要特性包括： + +* **概率性预测能力**：模型以生成式方式输出多步预测结果，支持分位数或分布级预测，从而刻画未来不确定性。 +* **零样本通用预测**：依托预训练获得的上下文学习能力，可直接对未见过的数据集执行预测，无需重新训练或参数更新。 +* **多变量与协变量统一建模**：支持在同一架构下联合建模多条相关时间序列及其协变量，以提升复杂任务的预测效果。但对输入有严格要求： + * 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集； + * 每个历史协变量的长度必须等于目标变量的长度； + * 每个未来协变量的长度必须等于预测长度； +* **高效推理与部署**：模型采用紧凑的编码器式（encoder-only）结构，在保持强泛化能力的同时兼顾推理效率。 + +![](/img/timeseries-large-model-chronos2.png) + +## 7. 效果展示 + +时序大模型能够适应多种不同领域和场景的真实时序数据，在各种任务上拥有优异的处理效果，以下是在不同数据上的真实表现： + +**时序预测：** + +利用时序大模型的预测能力，能够准确预测时间序列的未来变化趋势，如下图蓝色曲线代表预测趋势，红色曲线为实际趋势，两曲线高度吻合。 + +![](/img/LargeModel03.png) + +**数据填补**： + +利用时序大模型对缺失数据段进行预测式填补。 + +![](/img/timeseries-large-model-data-imputation.png) + +**异常检测**： + +利用时序大模型精准识别与正常趋势偏离过大的异常值。 + +![](/img/LargeModel05.png) + +## 8. 部署使用 + +1. 打开 IoTDB cli 控制台，检查 ConfigNode、DataNode、AINode 节点确保均为 Running。 + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. 联网环境下首次启动 AINode 节点会自动拉取 Timer-XL、Sundial、Chronos2 模型。 + + > 注意： + > + > * AINode 安装包不包含模型权重文件 + > * 自动拉取功能依赖部署环境具备 HuggingFace 网络访问能力 + > * AINode 支持手动上传模型权重文件，具体操作方法可参考[导入权重文件](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md#_3-3-导入内置权重文件) + +3. 检查模型是否可用。 + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### 附录 + +**[1]** Timer- Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref1) + +**[2]** TIMER-XL- LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING ,Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref2) + +**[3]** Sundial- A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ 返回](#ref3) + +**[4] **Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821.**[↩ 返回](#ref4) diff --git a/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md b/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md new file mode 100644 index 000000000..3d86bfc4f --- /dev/null +++ b/src/zh/UserGuide/Master/Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md @@ -0,0 +1,157 @@ + +# 时序大模型 + +## 1. 简介 + +时序大模型是专为时序数据分析设计的基础模型。IoTDB 团队长期自研时序基础模型 Timer，该模型基于 Transformer 架构，经海量多领域时序数据预训练，可支撑时序预测、异常检测、时序填补等下游任务；团队打造的 AINode 平台同时支持集成业界前沿时序基础模型，为用户提供多元选型。不同于传统时序分析技术，这类大模型具备通用特征提取能力，可通过零样本分析、微调等技术服务广泛的分析任务。 + +本文相关时序大模型领域的技术成果（含团队自研及业界前沿方向）均发表于国际机器学习顶级会议，具体内容见附录。 + +## 2. 应用场景 + +* **时序预测**：为工业生产、自然环境等领域提供时间序列数据的预测服务，帮助用户提前了解未来变化趋势。 +* **数据填补**：针对时间序列中的缺失序列段，进行上下文填补，以增强数据集的连续性和完整性。 +* **异常检测**：利用自回归分析技术，对时间序列数据进行实时监测，及时预警潜在的异常情况。 + +![](/img/LargeModel09.png) + +## 3. Timer-1 模型 + +Timer[1] 模型（非内置模型）不仅展现了出色的少样本泛化和多任务适配能力，还通过预训练获得了丰富的知识库，赋予了它处理多样化下游任务的通用能力，拥有以下特点： + +* **泛化性**：模型能够通过使用少量样本进行微调，达到行业内领先的深度模型预测效果。 +* **通用性**：模型设计灵活，能够适配多种不同的任务需求，并且支持变化的输入和输出长度，使其在各种应用场景中都能发挥作用。 +* **可扩展性**：随着模型参数数量的增加或预训练数据规模的扩大，模型效果会持续提升，确保模型能够随着时间和数据量的增长而不断优化其预测效果。 + +![](/img/model01.png) + +## 4. Timer-XL 模型 + +Timer-XL[2]基于 Timer 进一步扩展升级了网络结构，在多个维度全面突破： + +* **超长上下文支持**：该模型突破了传统时序预测模型的限制，支持处理数千个 Token（相当于数万个时间点）的输入，有效解决了上下文长度瓶颈问题。 +* **多变量预测场景覆盖**：支持多种预测场景，包括非平稳时间序列的预测、涉及多个变量的预测任务以及包含协变量的预测，满足多样化的业务需求。 +* **大规模工业时序数据集：**采用万亿大规模工业物联网领域的时序数据集进行预训练，数据集兼有庞大的体量、卓越的质量和丰富的领域等重要特质，覆盖能源、航空航天、钢铁、交通等多领域。 + +![](/img/model02.png) + +## 5. Timer-Sundial 模型 + +Timer-Sundial[3]是一个专注于时间序列预测的生成式基础模型系列，其基础版本拥有 1.28 亿参数，并在 1 万亿个时间点上进行了大规模预训练，其核心特性包括： + +* **强大的泛化性能：**具备零样本预测能力，可同时支持点预测和概率预测。 +* **灵活预测分布分析：**不仅能预测均值或分位数，还可通过模型生成的原始样本评估预测分布的任意统计特性。 +* **创新生成架构：** 采用 “Transformer + TimeFlow” 协同架构——Transformer 学习时间片段的自回归表征，TimeFlow 模块基于流匹配框架 (Flow-Matching) 将随机噪声转化为多样化预测轨迹，实现高效的非确定性样本生成。 + +![](/img/model03.png) + +## 6. Chronos-2 模型 + +Chronos-2 [4]是由 Amazon Web Services (AWS) 研究团队开发的，基于 Chronos 离散词元建模范式发展起来的通用时间序列基础模型，该模型同时适用于零样本单变量预测和协变量预测。其主要特性包括： + +* **概率性预测能力**：模型以生成式方式输出多步预测结果，支持分位数或分布级预测，从而刻画未来不确定性。 +* **零样本通用预测**：依托预训练获得的上下文学习能力，可直接对未见过的数据集执行预测，无需重新训练或参数更新。 +* **多变量与协变量统一建模**：支持在同一架构下联合建模多条相关时间序列及其协变量，以提升复杂任务的预测效果。但对输入有严格要求： + * 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集； + * 每个历史协变量的长度必须等于目标变量的长度； + * 每个未来协变量的长度必须等于预测长度； +* **高效推理与部署**：模型采用紧凑的编码器式（encoder-only）结构，在保持强泛化能力的同时兼顾推理效率。 + +![](/img/timeseries-large-model-chronos2.png) + +## 7. 效果展示 + +时序大模型能够适应多种不同领域和场景的真实时序数据，在各种任务上拥有优异的处理效果，以下是在不同数据上的真实表现： + +**时序预测：** + +利用时序大模型的预测能力，能够准确预测时间序列的未来变化趋势，如下图蓝色曲线代表预测趋势，红色曲线为实际趋势，两曲线高度吻合。 + +![](/img/LargeModel03.png) + +**数据填补**： + +利用时序大模型对缺失数据段进行预测式填补。 + +![](/img/timeseries-large-model-data-imputation.png) + +**异常检测**： + +利用时序大模型精准识别与正常趋势偏离过大的异常值。 + +![](/img/LargeModel05.png) + +## 8. 部署使用 + +1. 打开 IoTDB cli 控制台，检查 ConfigNode、DataNode、AINode 节点确保均为 Running。 + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. 联网环境下首次启动 AINode 节点会自动拉取 Timer-XL、Sundial、Chronos2 模型。 + + > 注意： + > + > * AINode 安装包不包含模型权重文件 + > * 自动拉取功能依赖部署环境具备 HuggingFace 网络访问能力 + > * AINode 支持手动上传模型权重文件，具体操作方法可参考[导入权重文件](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md#_3-3-导入内置权重文件) + +3. 检查模型是否可用。 + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### 附录 + +**[1]** Timer- Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref1) + +**[2]** TIMER-XL- LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING ,Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref2) + +**[3]** Sundial- A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ 返回](#ref3) + +**[4] **Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821.**[↩ 返回](#ref4) diff --git a/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade.md b/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade.md new file mode 100644 index 000000000..6f44068b6 --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: AINode_Upgrade_apache.html +--- + \ No newline at end of file diff --git a/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_apache.md b/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_apache.md new file mode 100644 index 000000000..8a9fdb274 --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_apache.md @@ -0,0 +1,575 @@ + + +# AINode + +AINode 是支持时序相关模型注册、管理、调用的 IoTDB 原生节点，内置业界领先的自研时序大模型，如清华自研时序模型 Timer 系列，可通过标准 SQL 语句进行调用，实现时序数据的毫秒级实时推理，可支持时序趋势预测、缺失值填补、异常值检测等应用场景。 + +系统架构如下图所示： + +![](/img/AINode-0.png) + +三种节点的职责如下： + +* **ConfigNode**：负责分布式节点管理和负载均衡。 +* **DataNode**：负责接收并解析用户的 SQL请求；负责存储时间序列数据；负责数据的预处理计算。 +* **AINode**：负责时序模型的管理和使用。 + +## 1. 优势特点 + +与单独构建机器学习服务相比，具有以下优势： + +* **简单易用**：无需使用 Python 或 Java 编程，使用 SQL 语句即可完成机器学习模型管理与推理的完整流程。如创建模型可使用CREATE MODEL语句、使用模型进行推理可使用` CALL INFERENCE(...)` 语句等，使用更加简单便捷。 +* **避免数据迁移**：使用 IoTDB 原生机器学习可以将存储在 IoTDB 中的数据直接应用于机器学习模型的推理，无需将数据移动到单独的机器学习服务平台，从而加速数据处理、提高安全性并降低成本。 + +![](/img/h1.png) + +* **内置先进算法**：支持业内领先机器学习分析算法，覆盖典型时序分析任务，为时序数据库赋能原生数据分析能力。如： + * **时间序列预测（Time Series Forecasting）**：从过去时间序列中学习变化模式；从而根据给定过去时间的观测值，输出未来序列最可能的预测。 + * **时序异常检测（Anomaly Detection for Time Series）**：在给定的时间序列数据中检测和识别异常值，帮助发现时间序列中的异常行为。 + +## 2. 基本概念 + +* **模型（Model）**：机器学习模型，以时序数据作为输入，输出分析任务的结果或决策。模型是 AINode 的基本管理单元，支持模型的增（注册）、删、查、用（推理）。 +* **创建（Create）**: 将外部设计或训练好的模型文件或算法加载到 AINode 中，由 IoTDB 统一管理与使用。 +* **推理（Inference）**：使用创建的模型在指定时序数据上完成该模型适用的时序分析任务。 +* **内置能力（Built-in）**：AINode 自带常见时序分析场景（例如预测与异常检测）的机器学习算法或自研模型。 + +![](/img/h3.png) + +## 3. 安装部署 + +AINode 的部署可参考文档 [AINode 部署](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md) 。 + +## 4. 使用指导 + +AINode 支持模型推理和模型管理（注册、查看、删除、加载、卸载等）两大功能，下面章节将进行详细说明。 + +### 4.1 模型推理 + +SQL语法如下： + +```SQL +call inference(,inputSql,(=)*) +``` + +在完成模型的注册后（内置模型推理无需注册流程），通过call关键字，调用inference函数就可以使用模型的推理功能，其对应的参数介绍如下： + +* **model\_id**: 对应一个已经注册的模型 +* **sql**：sql查询语句，查询的结果作为模型的输入进行模型推理。查询的结果中行列的维度需要与具体模型config中指定的大小相匹配。(这里的sql不建议使用`SELECT *`子句，因为在IoTDB中，`*`并不会对列进行排序，因此列的顺序是未定义的，可以使用`SELECT s0,s1`的方式确保列的顺序符合模型输入的预期) +* **parameterName/parameterValue**：参数名/参数值，目前支持： + + | 参数名称 | 参数类型 | 参数描述 | 默认值 | + | ------------------------ | ---------- | -------------------------- | -------- | + | **generateTime** | boolean | 返回结果是否包含时间戳列 | false | + | **outputLength** | int | 指定返回结果的输出长度 | 96 | + + +说明： + +1. 使用内置时序大模型进行推理的前提条件是本地存有对应模型权重，目录为 `/IOTDB_AINODE_HOME/data/ainode/models/builtin/model_id/`。若本地没有模型权重，则会自动从 HuggingFace 拉取，请保证本地能直接访问 HuggingFace。 +2. 在深度学习应用中，经常将时间戳衍生特征（数据中的时间列）作为生成式任务的协变量，一同输入到模型中以提升模型的效果，但是在模型的输出结果中一般不包含时间列。为了保证实现的通用性，模型推理结果只对应模型的真实输出，如果模型不输出时间列，则结果中不会包含。 + +**示例** + +样本数据 [ETTh-tree](/img/ETTh-tree.csv) + +下面是使用 sundial 模型推理的一个操作示例，输入 96 行， 输出 48 行，我们通过SQL使用其进行推理。 + +```SQL +IoTDB> select OT from root.db.** ++-----------------------------+---------------+ +| Time|root.db.etth.OT| ++-----------------------------+---------------+ +|2016-07-01T00:00:00.000+08:00| 30.531| +|2016-07-01T01:00:00.000+08:00| 27.787| +|2016-07-01T02:00:00.000+08:00| 27.787| +|2016-07-01T03:00:00.000+08:00| 25.044| +|2016-07-01T04:00:00.000+08:00| 21.948| +| ...... | ...... | +|2016-07-04T19:00:00.000+08:00| 29.546| +|2016-07-04T20:00:00.000+08:00| 29.475| +|2016-07-04T21:00:00.000+08:00| 29.264| +|2016-07-04T22:00:00.000+08:00| 30.953| +|2016-07-04T23:00:00.000+08:00| 31.726| ++-----------------------------+---------------+ +Total line number = 96 + +IoTDB> call inference(sundial,"select OT from root.db.**", generateTime=True, outputLength=48) ++-----------------------------+------------------+ +| Time| output| ++-----------------------------+------------------+ +|2016-07-04T23:00:00.000+08:00|30.537494659423828| +|2016-07-04T23:59:22.500+08:00|29.619892120361328| +|2016-07-05T00:58:45.000+08:00|28.815832138061523| +|2016-07-05T01:58:07.500+08:00| 27.91131019592285| +|2016-07-05T02:57:30.000+08:00|26.893848419189453| +| ...... | ...... | +|2016-07-06T17:33:07.500+08:00| 24.40607261657715| +|2016-07-06T18:32:30.000+08:00| 25.00441551208496| +|2016-07-06T19:31:52.500+08:00|24.907312393188477| +|2016-07-06T20:31:15.000+08:00|25.156436920166016| +|2016-07-06T21:30:37.500+08:00|25.335433959960938| ++-----------------------------+------------------+ +Total line number = 48 +``` + +### 4.2 注册自定义模型 + +**符合以下要求的 Transformers 模型可以注册到 AINode 中：** + +1. AINode 目前使用 v4.56.2 版本的 transformers，构建模型时需**避免继承低版本（<4.50）接口**； +2. 模型需继承一类 AINode 的推理任务流水线（当前支持预测流水线）： + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + 在推理任务开始前对输入数据进行前处理，包括形状验证和数值转换。 + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + 在推理任务结束后对输出结果进行后处理。 + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + 在将输入数据传递给模型进行推理之前进行预处理，验证输入数据的形状和类型。 + + Args: + inputs (list[dict]): + 输入数据，字典列表，每个字典包含： + - 'targets': 形状为 (input_length,) 或 (target_count, input_length) 的张量。 + - 'past_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + - 'future_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + + infer_kwargs (dict, optional): 推理的额外关键字参数，如： + - `output_length`(int): 如果提供'future_covariates'，用于验证其有效性。 + + Raises: + ValueError: 如果输入格式不正确（例如，缺少键、张量形状无效）。 + + Returns: + 经过预处理和验证的输入数据，可直接用于模型推理。 + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + 对给定输入执行预测。 + + Parameters: + inputs: 用于进行预测的输入数据。类型和结构取决于模型的具体实现。 + **infer_kwargs: 额外的推理参数，例如： + - `output_length`(int): 模型应该生成的时间点数量。 + + Returns: + 预测输出，具体形式取决于模型的具体实现。 + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + 在推理后对模型输出进行后处理，验证输出数据的形状并确保其符合预期维度。 + + Args: + outputs: + 模型输出，2D张量列表，每个张量形状为 `[target_count, output_length]`。 + + Raises: + InferenceModelInternalException: 如果输出张量形状无效（例如，维数错误）。 + ValueError: 如果输出格式不正确。 + + Returns: + list[torch.Tensor]: + 后处理后的输出，将是一个2D张量列表。 + """ + pass + ``` +3. 修改模型配置文件 config.json，确保包含以下字段： + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // 指定模型 Config 类 + "AutoModelForCausalLM": "model.Chronos2Model" // 指定模型类 + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // 指定模型的推理流水线 + "model_type": "custom_t5", // 指定模型类型 + } + ``` + + 1. 必须通过 auto\_map 指定模型的 Config 类和模型类； + 2. 必须集成并指定推理流水线类； + 3. 对于 AINode 管理的内置（builtin）和自定义（user\_defined）模型，模型类别（model\_type）也作为不可重复的唯一标识。即，要注册的模型类别不得与任何已存在的模型类型重复。 +4. 确保要注册的模型目录包含以下文件，且模型配置文件名称和权重文件名称不支持自定义： + 1. 模型配置文件：config.json； + 2. 模型权重文件：model.safetensors； + 3. 模型代码：其它 .py 文件。 + +**注册自定义模型的 SQL 语法如下所示：** + +```SQL +CREATE MODEL USING URI +``` + +**参数说明：** + +* **model\_id**：自定义模型的唯一标识；不可重复，有以下约束： + * 允许出现标识符 [ 0-9 a-z A-Z \_ ] （字母，数字（非开头），下划线（非开头）） + * 长度限制为 2-64 字符 + * 大小写敏感 +* **uri**：包含模型代码和权重的本地 uri 地址。 + +**注册示例：** + +从本地路径上传自定义 Transformers 模型，AINode 会将该文件夹拷贝至 user\_defined 目录中。 + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +SQL执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见查看模型章节）。模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。 + +### 4.3 查看模型 + +注册成功的模型可以通过查看指令查询模型的具体信息。 + +```SQL +SHOW MODELS +``` + +除了直接展示所有模型的信息外，可以指定`model_id`来查看某一具体模型的信息。 + +```SQL +SHOW MODELS -- 只展示特定模型 +``` + +模型展示的结果中包含如下内容： + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| 模型ID | 模型类型 | 模型种类 | 模型状态 | + +其中，State 模型状态机流转示意图如下: + +![](/img/ainode-upgrade-state-apache.png) + +状态机流程说明： + +1. 启动 AINode 后，执行 `show models` 命令，仅能查看到**系统内置（BUILTIN）**的模型。 +2. 用户可导入自己的模型，这类模型的来源标识为**用户自定义（USER\_DEFINED）**；AINode 会尝试从模型配置文件中解析模型类型（ModelType），若解析失败，该字段则显示为空。 +3. 时序大模型（内置模型）权重文件不随 AINode 打包，AINode 启动时自动下载。 + 1. 下载过程中为 ACTIVATING，下载成功转变为 ACTIVE，失败则变成 INACTIVE。 + +**查看示例** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +内置传统时序模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|----------------------------------| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **ARIMA**(自回归整合移动平均模型) | 结合自回归(AR)、差分(I)和移动平均(MA)，用于预测平稳时间序列或可通过差分变为平稳的数据。 | 单变量时间序列预测，如股票价格、销量、经济指标等。| 1. 适用于线性趋势和季节性较弱的数据。2. 需要选择参数 (p,d,q)。3. 对缺失值敏感。 | +| **Holt-Winters**(三参数指数平滑) | 基于指数平滑，引入水平、趋势和季节性三个分量，适用于具有趋势和季节性的数据。 | 有明显季节性和趋势的时间序列，如月度销售额、电力需求等。 | 1. 可处理加性或乘性季节性。2. 对近期数据赋予更高权重。3. 简单易实现。 | +| **Exponential Smoothing**(指数平滑) | 通过加权平均历史数据，权重随时间指数递减，强调近期观测值的重要性。 | 无显著季节性但存在趋势的数据，如短期需求预测。 | 1. 参数少，计算简单。2. 适合平稳或缓慢变化序列。3. 可扩展为双指数或三指数平滑。 | +| **Naive Forecaster**(朴素预测器) | 使用最近一期的观测值作为下一期的预测值，是最简单的基准模型。 | 作为其他模型的比较基准，或数据无明显模式时的简单预测。 | 1. 无需训练。2. 对突发变化敏感。3. 季节性朴素变体可用前一季节同期值预测。 | +| **STL Forecaster**(季节趋势分解预测) | 基于STL分解时间序列，分别预测趋势、季节性和残差分量后组合。 | 具有复杂季节性、趋势和非线性模式的数据，如气候数据、交通流量。 | 1. 能处理非固定季节性。2. 对异常值稳健。3. 分解后可结合其他模型预测各分量。 | +| **Gaussian HMM**(高斯隐马尔可夫模型) | 假设观测数据由隐藏状态生成，每个状态的观测概率服从高斯分布。 | 状态序列预测或分类，如语音识别、金融状态识别。 | 1. 适用于时序数据的状态建模。2. 假设观测值在给定状态下独立。3. 需指定隐藏状态数量。 | +| **GMM HMM** (高斯混合隐马尔可夫模型) | 扩展Gaussian HMM，每个状态的观测概率由高斯混合模型描述，可捕捉更复杂的观测分布。 | 需要多模态观测分布的场景，如复杂动作识别、生物信号分析。 | 1. 比单一高斯更灵活。2. 参数更多，计算复杂度高。3. 需训练GMM成分数。 | +| **STRAY**(基于奇异值的异常检测) | 通过奇异值分解(SVD)检测高维数据中的异常点，常用于时间序列异常检测。 | 高维时间序列的异常检测，如传感器网络、IT系统监控。 | 1. 无需分布假设。2. 可处理高维数据。3. 对全局异常敏感，局部异常可能漏检。 | + +内置时序大模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | 支持超长上下文的时序大模型，通过大规模工业数据预训练增强泛化能力。 | 需利用极长历史数据的复杂工业预测，如能源、航空航天、交通等领域。 | 1. 超长上下文支持，可处理数万时间点输入。2. 多场景覆盖，支持非平稳、多变量及协变量预测。3. 基于万亿级高质量工业时序数据预训练。 | +| **Timer-Sundial** | 采用“Transformer + TimeFlow”架构的生成式基础模型，专注于概率预测。 | 需要量化不确定性的零样本预测场景，如金融、供应链、新能源发电预测。 | 1. 强大的零样本泛化能力，支持点预测与概率预测 2. 可灵活分析预测分布的任意统计特性。3. 创新生成架构，实现高效的非确定性样本生成。 | +| **Chronos-2** | 基于离散词元化范式的通用时序基础模型，将预测转化为语言建模任务。 | 快速零样本单变量预测，以及可借助协变量（如促销、天气）提升效果的场景。 | 1. 强大的零样本概率预测能力。2. 支持协变量统一建模，但对输入有严格要求：a. 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集；b. 每个历史协变量的长度必须等于目标变量的长度； c. 每个未来协变量的长度必须等于预测长度；3. 采用高效的编码器式结构，兼顾性能与推理速度。 | + +### 4.4 删除模型 + +对于注册成功的模型，用户可以通过 SQL 进行删除，AINode 会将 user\_defined 目录下的对应模型文件夹整个删除。其 SQL 语法如下： + +```SQL +DROP MODEL +``` + +需要指定已经成功注册的模型 model\_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。 + +### 4.5 加载/卸载模型 + +为适应不同场景，AINode 提供以下两种模型加载策略： + +* 即时加载：即推理时临时加载模型，结束后释放资源。适用于测试或低负载场景。 +* 常驻加载：即将模型持久化加载在内存（CPU）或显存（GPU）中，以支持高并发推理。用户只需通过 SQL 指定加载或卸载的模型，AINode 会自动管理实例数量。当前常驻模型的状态也可随时查看。 + +下文将详细介绍加载/卸载模型的相关内容： + +1. 配置参数 + +支持通过编辑如下配置项设置常驻加载相关参数。 + +```Properties +# AINode 在推理时可使用的设备内存/显存占总量的比例 +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# AINode 每个加载的模型实例需要占用的内存比例，即模型占用*该值 +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. 展示可用的 device + +支持通过如下 SQL 命令查看所有可用的设备 ID + +```SQL +SHOW AI_DEVICES +``` + +示例 + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. 加载模型 + +支持通过如下 SQL 命令手动加载模型，系统根据硬件资源使用情况**自动均衡**模型实例数量。 + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 加载到 AINode 所在服务器的内存中。 + * **gpu\_id:** 加载到 AINode 所在服务器的对应显卡中，如 "0, 1" 表示加载到编号为 0 和 1 的两张显卡中。 + +示例 + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. 卸载模型 + +支持通过如下 SQL 命令手动卸载指定模型的所有实例，系统会**重分配**空闲出的资源给其他模型 + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 尝试从 AINode 所在服务器的内存中卸载指定模型。 + * **gpu\_id:** 尝试从 AINode 所在服务器的对应显卡中卸载指定模型，如 "0, 1" 表示尝试从编号为 0 和 1 的两张显卡卸载指定模型。 + +示例 + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. 展示加载的模型 + +支持通过如下 SQL 命令查看已经手动加载的模型实例，可通过 `device_id `指定设备。 + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # 展示指定设备中的模型实例 +``` + +示例：在内存、gpu\_0 和 gpu\_1 两张显卡加载了sundial 模型 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +说明： + +* DeviceId : 设备 ID +* ModelId ：加载的模型 ID +* Count(instances) ：每个设备中的模型实例数量（系统自动分配） + +### 4.6 时序大模型介绍 + +AINode 目前支持多种时序大模型，相关介绍及部署使用可参考[时序大模型](../AI-capability/TimeSeries-Large-Model_Upgrade_apache.md) + +## 5. 权限管理 + +使用 AINode 相关的功能时，可以使用IoTDB本身的鉴权去做一个权限管理，用户只有在具备 USE\_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。 + +| 权限名称 | 权限范围 | 管理员用户（默认ROOT） | 普通用户 | 路径相关 | +| ------------ | ----------------------------------------- | ------------------------ | ---------- | ---------- | +| USE\_MODEL | create model / show models / drop model | √ | √ | x | +| READ\_DATA | call inference | √ | √ | √ | + +## 6. 向 IoTDB-AINode 贡献开源时序大模型 + +支持在 AINode 新增自定义内置模型，具体操作步骤如下（以 chronos2 为例）： + +* **向 [dev@iotdb.apache.org](mailto:dev@iotdb.apache.org) 邮件列表发送邮件或在项目主仓库提交 issue，发起初步讨论** +* **向主分支提交 Pull Request** + +1. 检查模型所用的开源协议，并在 IoTDB 仓库进行对应声明。 +2. 在 iotdb-core/ainode/iotdb/ainode/core/model 创建新内置模型对应的包； + 1. 确保包含模型配置类； + 2. 确保包含执行推理任务的模型类； + 3. 确保包含继承 AINode 推理任务流水线的类； + + ```Bash + root@rootMacBook-Pro model % eza --tree --level=2 . + . + ├── chronos2 + │ ├── __init__.py + │ ├── base.py + │ ├── chronos_bolt.py + │ ├── config.py + │ ├── dataset.py + │ ├── layers.py + │ ├── model.py + │ ├── pipeline_chronos2.py # 继承 AINode 推理任务流水线 + │ └── utils.py + ├── sktime + ├── sundial + └── timer_xl + ``` +3. 在 iotdb-core/ainode/iotdb/ainode/core/model/model\_info.py 新增该模型的元信息； + ```Python + BUILTIN_HF_TRANSFORMERS_MODEL_MAP = { + "chronos2": ModelInfo( + model_id="chronos2", # 模型的唯一标识 + category=ModelCategory.BUILTIN, # 模型类别，选择 BUILTIN + state=ModelStates.INACTIVE, + model_type="t5", # 模型种类，不能和其它 builtin 模型相同 + pipeline_cls="pipeline_chronos2.Chronos2Pipeline", # 继承 AINode 的推理流水线 + repo_id="amazon/chronos-2", # 【可选】Huggingface 权重 + auto_map={ + "AutoConfig": "config.Chronos2CoreConfig", # 确保指向模型的配置类 + "AutoModelForCausalLM": "model.Chronos2Model", # 确保指向推理所用的模型类 + }, + ), + } + ``` +4. 在 integration-test/src/test/java/org/apache/iotdb/ainode/utils/AINodeTestUtils.java 添加对应模型。 + ```Java + public static final Map BUILTIN_LTSM_MAP = + Stream.of( + new AbstractMap.SimpleEntry<>( + "sundial", new FakeModelInfo("sundial", "sundial", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "timer_xl", new FakeModelInfo("timer_xl", "timer", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "chronos2", new FakeModelInfo("chronos2", "t5", "builtin", "active"))) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + ``` +5. 提交 pull request，确保通过流水线测试后才能合并。 + +* **打包部署** + +1. 编译 AINode，获取安装包； + ```Bash + # 同时构建 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 + ``` +2. 在运行时确保模型能获取权重。 + 1. 若模型权重可从 Huggingface 在线获取，确保已填写`repo_id`； + 2. 否则，可在 AINode 启动前/运行时手动将模型权重放在`data/ainode/models/builtin/`。 + + ```Bash + root@rootMacBook-Pro models % eza --tree --level=3 . + . + ├── __init__.py + ├── builtin + │ ├── __init__.py + │ ├── chronos2 + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ ├── sundial + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ └── timer_xl + │ ├── __init__.py + │ ├── config.json + │ └── model.safetensors + └── user_defined + ``` + +* **完整示例** + +完整示例可参考 https://github.com/apache/iotdb/pull/16903 diff --git a/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_timecho.md b/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_timecho.md new file mode 100644 index 000000000..d637cb0f6 --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/AI-capability/AINode_Upgrade_timecho.md @@ -0,0 +1,563 @@ + + +# AINode + +AINode 是支持时序相关模型注册、管理、调用的 IoTDB 原生节点，内置业界领先的自研时序大模型，如清华自研时序模型 Timer 系列，可通过标准 SQL 语句进行调用，实现时序数据的毫秒级实时推理，可支持时序趋势预测、缺失值填补、异常值检测等应用场景。 + +系统架构如下图所示： + +![](/img/AINode-0.png) + +三种节点的职责如下： + +* **ConfigNode**：负责分布式节点管理和负载均衡。 +* **DataNode**：负责接收并解析用户的 SQL请求；负责存储时间序列数据；负责数据的预处理计算。 +* **AINode**：负责时序模型的管理和使用。 + +## 1. 优势特点 + +与单独构建机器学习服务相比，具有以下优势： + +* **简单易用**：无需使用 Python 或 Java 编程，使用 SQL 语句即可完成机器学习模型管理与推理的完整流程。如创建模型可使用CREATE MODEL语句、使用模型进行推理可使用 CALL INFERENCE (...) 语句等，使用更加简单便捷。 +* **避免数据迁移**：使用 IoTDB 原生机器学习可以将存储在 IoTDB 中的数据直接应用于机器学习模型的推理，无需将数据移动到单独的机器学习服务平台，从而加速数据处理、提高安全性并降低成本。 + +![](/img/h1.png) + +* **内置先进算法**：支持业内领先机器学习分析算法，覆盖典型时序分析任务，为时序数据库赋能原生数据分析能力。如： + * **时间序列预测（Time Series Forecasting）**：从过去时间序列中学习变化模式；从而根据给定过去时间的观测值，输出未来序列最可能的预测。 + * **时序异常检测（Anomaly Detection for Time Series）**：在给定的时间序列数据中检测和识别异常值，帮助发现时间序列中的异常行为。 + +## 2. 基本概念 + +* **模型（Model）**：机器学习模型，以时序数据作为输入，输出分析任务的结果或决策。模型是 AINode 的基本管理单元，支持模型的增（注册）、删、查、改（微调）、用（推理）。 +* **创建（Create）**: 将外部设计或训练好的模型文件或算法加载到 AINode 中，由 IoTDB 统一管理与使用。 +* **推理（Inference）**：使用创建的模型在指定时序数据上完成该模型适用的时序分析任务。 +* **内置能力（Built-in）**：AINode 自带常见时序分析场景（例如预测与异常检测）的机器学习算法或自研模型。 + +![](/img/h3.png) + +## 3. 安装部署 + +AINode 的部署可参考文档 [AINode 部署](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md) 。 + +## 4. 使用指导 + +TimechoDB-AINode 支持模型推理、模型微调以及模型管理（注册、查看、删除、加载、卸载等）三大功能，下面章节将进行详细说明。 + +### 4.1 模型推理 + +SQL语法如下： + +```SQL +call inference(,inputSql,(=)*) +``` + +在完成模型的注册后（内置模型推理无需注册流程），通过call关键字，调用inference函数就可以使用模型的推理功能，其对应的参数介绍如下： + +* **model\_id**: 对应一个已经注册的模型 +* **sql**：sql查询语句，查询的结果作为模型的输入进行模型推理。查询的结果中行列的维度需要与具体模型config中指定的大小相匹配。(这里的sql不建议使用`SELECT *`子句，因为在IoTDB中，`*`并不会对列进行排序，因此列的顺序是未定义的，可以使用`SELECT ot` 的方式确保列的顺序符合模型输入的预期) +* **parameterName/parameterValue**：参数名/参数值，目前支持： + + | 参数名称 | 参数类型 | 参数描述 | 默认值 | + | ------------------------ | ---------- | -------------------------- | -------- | + | **generateTime** | boolean | 返回结果是否包含时间戳列 | false | + | **outputLength** | int | 指定返回结果的输出长度 | 96 | + + +说明： + +1. 使用内置时序大模型进行推理的前提条件是本地存有对应模型权重，目录为 /TIMECHODB\_AINODE\_HOME/data/ainode/models/builtin/model\_id/。若本地没有模型权重，则会自动从 HuggingFace 拉取，请保证本地能直接访问 HuggingFace。 +2. 在深度学习应用中，经常将时间戳衍生特征（数据中的时间列）作为生成式任务的协变量，一同输入到模型中以提升模型的效果，但是在模型的输出结果中一般不包含时间列。为了保证实现的通用性，模型推理结果只对应模型的真实输出，如果模型不输出时间列，则结果中不会包含。 + +**示例** + +样本数据 [ETTh-tree](/img/ETTh-tree.csv) + +下面是使用 sundial 模型推理的一个操作示例，输入 96 行， 输出 48 行，我们通过SQL使用其进行推理。 + +```SQL +IoTDB> select OT from root.db.** ++-----------------------------+---------------+ +| Time|root.db.etth.OT| ++-----------------------------+---------------+ +|2016-07-01T00:00:00.000+08:00| 30.531| +|2016-07-01T01:00:00.000+08:00| 27.787| +|2016-07-01T02:00:00.000+08:00| 27.787| +|2016-07-01T03:00:00.000+08:00| 25.044| +|2016-07-01T04:00:00.000+08:00| 21.948| +| ...... | ...... | +|2016-07-04T19:00:00.000+08:00| 29.546| +|2016-07-04T20:00:00.000+08:00| 29.475| +|2016-07-04T21:00:00.000+08:00| 29.264| +|2016-07-04T22:00:00.000+08:00| 30.953| +|2016-07-04T23:00:00.000+08:00| 31.726| ++-----------------------------+---------------+ +Total line number = 96 + +IoTDB> call inference(sundial,"select OT from root.db.**", generateTime=True, outputLength=48) ++-----------------------------+------------------+ +| Time| output| ++-----------------------------+------------------+ +|2016-07-04T23:00:00.000+08:00|30.537494659423828| +|2016-07-04T23:59:22.500+08:00|29.619892120361328| +|2016-07-05T00:58:45.000+08:00|28.815832138061523| +|2016-07-05T01:58:07.500+08:00| 27.91131019592285| +|2016-07-05T02:57:30.000+08:00|26.893848419189453| +| ...... | ...... | +|2016-07-06T17:33:07.500+08:00| 24.40607261657715| +|2016-07-06T18:32:30.000+08:00| 25.00441551208496| +|2016-07-06T19:31:52.500+08:00|24.907312393188477| +|2016-07-06T20:31:15.000+08:00|25.156436920166016| +|2016-07-06T21:30:37.500+08:00|25.335433959960938| ++-----------------------------+------------------+ +Total line number = 48 +``` + +### 4.2 模型微调 + +AINode 支持通过 SQL 进行模型微调任务。 + +**SQL 语法** + +```SQL +createModel + | CREATE MODEL modelId=identifier (WITH HYPERPARAMETERS LR_BRACKET hparamPair (COMMA hparamPair)* RR_BRACKET)? FROM MODEL existingModelId=identifier ON DATASET LR_BRACKET trainingData RR_BRACKET + ; + +trainingData + : dataElement(COMMA dataElement)* + ; + +dataElement + : pathPatternElement (LR_BRACKET timeRange RR_BRACKET)? + ; + +pathPatternElement + : PATH path=prefixPath + ; +``` + +**参数说明** + +| 名称 | 描述 | +| ----------------- |---------------------------------------------------------------------------------------------------------------------------------------| +| modelId | 微调出的模型的唯一标识 | +| hparamPair | 微调使用的超参数 key-value 对，目前支持如下：
`train_epochs`: int 类型，微调轮数
`iter_per_epoch`: int 类型，每轮微调的迭代次数
`learning_rate`: double 类型，学习率 | +| existingModelId | 微调使用的基座模型 | +| trainingData | 微调使用的数据集 | + +**示例** + +1. 选择测点 root.db.etth.ot 中指定时间范围的数据作为微调数据集，基于 sundial 创建模型 sundialv2. + +```SQL +IoTDB> CREATE MODEL sundialv2 FROM MODEL sundial ON DATASET (PATH root.db.etth.OT([1467302400000, 1467644400000))) +Msg: The statement is executed successfully. +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| +| sundialv2| sundial| fine_tuned| training| ++---------------------+---------+-----------+---------+ +``` + +2. 微调任务后台异步启动，可在 AINode 进程看到 log；微调完成后，查询并使用新的模型 + +```SQL +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| +| sundialv2| sundial| fine_tuned| active| ++---------------------+---------+-----------+---------+ +``` + +### 4.3 注册自定义模型 + +**符合以下要求的 Transformers 模型可以注册到 AINode 中：** + +1. AINode 目前使用 v4.56.2 版本的 transformers，构建模型时需**避免继承低版本（<4.50）接口**； +2. 模型需继承一类 AINode 的推理任务流水线（当前支持预测流水线）： + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + 在推理任务开始前对输入数据进行前处理，包括形状验证和数值转换。 + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + 在推理任务结束后对输出结果进行后处理。 + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + 在将输入数据传递给模型进行推理之前进行预处理，验证输入数据的形状和类型。 + + Args: + inputs (list[dict]): + 输入数据，字典列表，每个字典包含： + - 'targets': 形状为 (input_length,) 或 (target_count, input_length) 的张量。 + - 'past_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + - 'future_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + + infer_kwargs (dict, optional): 推理的额外关键字参数，如： + - `output_length`(int): 如果提供'future_covariates'，用于验证其有效性。 + + Raises: + ValueError: 如果输入格式不正确（例如，缺少键、张量形状无效）。 + + Returns: + 经过预处理和验证的输入数据，可直接用于模型推理。 + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + 对给定输入执行预测。 + + Parameters: + inputs: 用于进行预测的输入数据。类型和结构取决于模型的具体实现。 + **infer_kwargs: 额外的推理参数，例如： + - `output_length`(int): 模型应该生成的时间点数量。 + + Returns: + 预测输出，具体形式取决于模型的具体实现。 + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + 在推理后对模型输出进行后处理，验证输出数据的形状并确保其符合预期维度。 + + Args: + outputs: + 模型输出，2D张量列表，每个张量形状为 `[target_count, output_length]`。 + + Raises: + InferenceModelInternalException: 如果输出张量形状无效（例如，维数错误）。 + ValueError: 如果输出格式不正确。 + + Returns: + list[torch.Tensor]: + 后处理后的输出，将是一个2D张量列表。 + """ + pass + ``` +3. 修改模型配置文件 config.json，确保包含以下字段： + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // 指定模型 Config 类 + "AutoModelForCausalLM": "model.Chronos2Model" // 指定模型类 + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // 指定模型的推理流水线 + "model_type": "custom_t5", // 指定模型类型 + } + ``` + + 1. 必须通过 auto\_map 指定模型的 Config 类和模型类； + 2. 必须集成并指定推理流水线类； + 3. 对于 AINode 管理的内置（builtin）和自定义（user\_defined）模型，模型类别（model\_type）也作为不可重复的唯一标识。即，要注册的模型类别不得与任何已存在的模型类型重复，通过微调创建的模型将继承原模型的模型类别。 +4. 确保要注册的模型目录包含以下文件，且模型配置文件名称和权重文件名称不支持自定义： + 1. 模型配置文件：config.json； + 2. 模型权重文件：model.safetensors； + 3. 模型代码：其它 .py 文件。 + +**注册自定义模型的 SQL 语法如下所示：** + +```SQL +CREATE MODEL USING URI +``` + +**参数说明：** + +* **model\_id**：自定义模型的唯一标识；不可重复，有以下约束： + * 允许出现标识符 [ 0-9 a-z A-Z \_ ] （字母，数字（非开头），下划线（非开头）） + * 长度限制为 2-64 字符 + * 大小写敏感 +* **uri**：包含模型代码和权重的本地 uri 地址。 + +**注册示例：** + +从本地路径上传自定义 Transformers 模型，AINode 会将该文件夹拷贝至 user\_defined 目录中。 + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +SQL执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见查看模型章节）。模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。 + +### 4.4 查看模型 + +注册成功的模型可以通过查看指令查询模型的具体信息。 + +```SQL +SHOW MODELS +``` + +除了直接展示所有模型的信息外，可以指定`model_id`来查看某一具体模型的信息。 + +```SQL +SHOW MODELS -- 只展示特定模型 +``` + +模型展示的结果中包含如下内容： + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| 模型ID | 模型类型 | 模型种类 | 模型状态 | + +其中，State 模型状态机流转示意图如下: + +![](/img/ainode-upgrade-state-timecho.png) + +状态机流程说明： + +1. 启动 AINode 后，执行 `show models` 命令，仅能查看到**系统内置（BUILTIN）**的模型。 +2. 用户可导入自己的模型，这类模型的来源标识为**用户自定义（USER\_****DEFINED）**；AINode 会尝试从模型配置文件中解析模型类型（ModelType），若解析失败，该字段则显示为空。 +3. 时序大模型（内置模型）权重文件不随 AINode 打包，AINode 启动时自动下载。 + 1. 下载过程中为 ACTIVATING，下载成功转变为 ACTIVE，失败则变成 INACTIVE。 +4. 用户启动模型微调任务后，正在训练的模型状态为 TRAINING，训练成功变为 ACTIVE，失败则是 FAILED。 +5. 若微调任务成功，微调结束后会统计所有 ckpt （训练文件）中指标最佳的文件并自动重命名，变成用户指定的 model\_id。 + +**查看示例** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| sundialx_1| sundial| fine_tuned| active| +| sundialx_4| sundial| fine_tuned| training| +| sundialx_5| sundial| fine_tuned| failed| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +内置传统时序模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|----------------------------------| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **ARIMA**(自回归整合移动平均模型) | 结合自回归(AR)、差分(I)和移动平均(MA)，用于预测平稳时间序列或可通过差分变为平稳的数据。 | 单变量时间序列预测，如股票价格、销量、经济指标等。| 1. 适用于线性趋势和季节性较弱的数据。2. 需要选择参数 (p,d,q)。3. 对缺失值敏感。 | +| **Holt-Winters**(三参数指数平滑) | 基于指数平滑，引入水平、趋势和季节性三个分量，适用于具有趋势和季节性的数据。 | 有明显季节性和趋势的时间序列，如月度销售额、电力需求等。 | 1. 可处理加性或乘性季节性。2. 对近期数据赋予更高权重。3. 简单易实现。 | +| **Exponential Smoothing**(指数平滑) | 通过加权平均历史数据，权重随时间指数递减，强调近期观测值的重要性。 | 无显著季节性但存在趋势的数据，如短期需求预测。 | 1. 参数少，计算简单。2. 适合平稳或缓慢变化序列。3. 可扩展为双指数或三指数平滑。 | +| **Naive Forecaster**(朴素预测器) | 使用最近一期的观测值作为下一期的预测值，是最简单的基准模型。 | 作为其他模型的比较基准，或数据无明显模式时的简单预测。 | 1. 无需训练。2. 对突发变化敏感。3. 季节性朴素变体可用前一季节同期值预测。 | +| **STL Forecaster**(季节趋势分解预测) | 基于STL分解时间序列，分别预测趋势、季节性和残差分量后组合。 | 具有复杂季节性、趋势和非线性模式的数据，如气候数据、交通流量。 | 1. 能处理非固定季节性。2. 对异常值稳健。3. 分解后可结合其他模型预测各分量。 | +| **Gaussian HMM**(高斯隐马尔可夫模型) | 假设观测数据由隐藏状态生成，每个状态的观测概率服从高斯分布。 | 状态序列预测或分类，如语音识别、金融状态识别。 | 1. 适用于时序数据的状态建模。2. 假设观测值在给定状态下独立。3. 需指定隐藏状态数量。 | +| **GMM HMM** (高斯混合隐马尔可夫模型) | 扩展Gaussian HMM，每个状态的观测概率由高斯混合模型描述，可捕捉更复杂的观测分布。 | 需要多模态观测分布的场景，如复杂动作识别、生物信号分析。 | 1. 比单一高斯更灵活。2. 参数更多，计算复杂度高。3. 需训练GMM成分数。 | +| **STRAY**(基于奇异值的异常检测) | 通过奇异值分解(SVD)检测高维数据中的异常点，常用于时间序列异常检测。 | 高维时间序列的异常检测，如传感器网络、IT系统监控。 | 1. 无需分布假设。2. 可处理高维数据。3. 对全局异常敏感，局部异常可能漏检。 | + +内置时序大模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | 支持超长上下文的时序大模型，通过大规模工业数据预训练增强泛化能力。 | 需利用极长历史数据的复杂工业预测，如能源、航空航天、交通等领域。 | 1. 超长上下文支持，可处理数万时间点输入。2. 多场景覆盖，支持非平稳、多变量及协变量预测。3. 基于万亿级高质量工业时序数据预训练。 | +| **Timer-Sundial** | 采用“Transformer + TimeFlow”架构的生成式基础模型，专注于概率预测。 | 需要量化不确定性的零样本预测场景，如金融、供应链、新能源发电预测。 | 1. 强大的零样本泛化能力，支持点预测与概率预测 2. 可灵活分析预测分布的任意统计特性。3. 创新生成架构，实现高效的非确定性样本生成。 | +| **Chronos-2** | 基于离散词元化范式的通用时序基础模型，将预测转化为语言建模任务。 | 快速零样本单变量预测，以及可借助协变量（如促销、天气）提升效果的场景。 | 1. 强大的零样本概率预测能力。2. 支持协变量统一建模，但对输入有严格要求：a. 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集；b. 每个历史协变量的长度必须等于目标变量的长度； c. 每个未来协变量的长度必须等于预测长度；3. 采用高效的编码器式结构，兼顾性能与推理速度。 | + + +### 4.5 删除模型 + +对于注册成功的模型，用户可以通过 SQL 进行删除，AINode 会将 user\_defined 目录下的对应模型文件夹整个删除。其 SQL 语法如下： + +```SQL +DROP MODEL +``` + +需要指定已经成功注册的模型 model\_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。 + +### 4.6 加载/卸载模型 + +为适应不同场景，AINode 提供以下两种模型加载策略： + +* 即时加载：即推理时临时加载模型，结束后释放资源。适用于测试或低负载场景。 +* 常驻加载：即将模型持久化加载在内存（CPU）或显存（GPU）中，以支持高并发推理。用户只需通过 SQL 指定加载或卸载的模型，AINode 会自动管理实例数量。当前常驻模型的状态也可随时查看。 + +下文将详细介绍加载/卸载模型的相关内容： + +1. 配置参数 + +支持通过编辑如下配置项设置常驻加载相关参数。 + +```Properties +# AINode 在推理时可使用的设备内存/显存占总量的比例 +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# AINode 每个加载的模型实例需要占用的内存比例，即模型占用*该值 +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. 展示可用的 device + +支持通过如下 SQL 命令查看所有可用的设备 ID + +```SQL +SHOW AI_DEVICES +``` + +示例 + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. 加载模型 + +支持通过如下 SQL 命令手动加载模型，系统根据硬件资源使用情况**自动均衡**模型实例数量。 + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 加载到 AINode 所在服务器的内存中。 + * **gpu\_id:** 加载到 AINode 所在服务器的对应显卡中，如 "0, 1" 表示加载到编号为 0 和 1 的两张显卡中。 + +示例 + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. 卸载模型 + +支持通过如下 SQL 命令手动卸载指定模型的所有实例，系统会**重分配**空闲出的资源给其他模型 + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 尝试从 AINode 所在服务器的内存中卸载指定模型。 + * **gpu\_id:** 尝试从 AINode 所在服务器的对应显卡中卸载指定模型，如 "0, 1" 表示尝试从编号为 0 和 1 的两张显卡卸载指定模型。 + +示例 + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. 展示加载的模型 + +支持通过如下 SQL 命令查看已经手动加载的模型实例，可通过 `device_id `指定设备。 + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # 展示指定设备中的模型实例 +``` + +示例：在内存、gpu\_0 和 gpu\_1 两张显卡加载了sundial 模型 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +说明： + +* DeviceId : 设备 ID +* ModelId ：加载的模型 ID +* Count(instances) ：每个设备中的模型实例数量（系统自动分配） + +### 4.7 时序大模型介绍 + +AINode 目前支持多种时序大模型，相关介绍及部署使用可参考[时序大模型](../AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md) + +## 5. 权限管理 + +使用 AINode 相关的功能时，可以使用IoTDB本身的鉴权去做一个权限管理，用户只有在具备 USE\_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。 + +| 权限名称 | 权限范围 | 管理员用户（默认ROOT） | 普通用户 | 路径相关 | +| ------------ | ----------------------------------------- | ------------------------ | ---------- | ---------- | +| USE\_MODEL | create model / show models / drop model | √ | √ | x | +| READ\_DATA | call inference | √ | √ | √ | diff --git a/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade.md b/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade.md new file mode 100644 index 000000000..440615354 --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: TimeSeries-Large-Model_Upgrade_apache.html +--- + diff --git a/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md b/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md new file mode 100644 index 000000000..e1af1e1d0 --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md @@ -0,0 +1,157 @@ + +# 时序大模型 + +## 1. 简介 + +时序大模型是专为时序数据分析设计的基础模型。IoTDB 团队长期自研时序基础模型 Timer，该模型基于 Transformer 架构，经海量多领域时序数据预训练，可支撑时序预测、异常检测、时序填补等下游任务；团队打造的 AINode 平台同时支持集成业界前沿时序基础模型，为用户提供多元选型。不同于传统时序分析技术，这类大模型具备通用特征提取能力，可通过零样本分析、微调等技术服务广泛的分析任务。 + +本文相关时序大模型领域的技术成果（含团队自研及业界前沿方向）均发表于国际机器学习顶级会议，具体内容见附录。 + +## 2. 应用场景 + +* **时序预测**：为工业生产、自然环境等领域提供时间序列数据的预测服务，帮助用户提前了解未来变化趋势。 +* **数据填补**：针对时间序列中的缺失序列段，进行上下文填补，以增强数据集的连续性和完整性。 +* **异常检测**：利用自回归分析技术，对时间序列数据进行实时监测，及时预警潜在的异常情况。 + +![](/img/LargeModel09.png) + +## 3. Timer-1 模型 + +Timer[1] 模型（非内置模型）不仅展现了出色的少样本泛化和多任务适配能力，还通过预训练获得了丰富的知识库，赋予了它处理多样化下游任务的通用能力，拥有以下特点： + +* **泛化性**：模型能够通过使用少量样本进行微调，达到行业内领先的深度模型预测效果。 +* **通用性**：模型设计灵活，能够适配多种不同的任务需求，并且支持变化的输入和输出长度，使其在各种应用场景中都能发挥作用。 +* **可扩展性**：随着模型参数数量的增加或预训练数据规模的扩大，模型效果会持续提升，确保模型能够随着时间和数据量的增长而不断优化其预测效果。 + +![](/img/model01.png) + +## 4. Timer-XL 模型 + +Timer-XL[2]基于 Timer 进一步扩展升级了网络结构，在多个维度全面突破： + +* **超长上下文支持**：该模型突破了传统时序预测模型的限制，支持处理数千个 Token（相当于数万个时间点）的输入，有效解决了上下文长度瓶颈问题。 +* **多变量预测场景覆盖**：支持多种预测场景，包括非平稳时间序列的预测、涉及多个变量的预测任务以及包含协变量的预测，满足多样化的业务需求。 +* **大规模工业时序数据集：**采用万亿大规模工业物联网领域的时序数据集进行预训练，数据集兼有庞大的体量、卓越的质量和丰富的领域等重要特质，覆盖能源、航空航天、钢铁、交通等多领域。 + +![](/img/model02.png) + +## 5. Timer-Sundial 模型 + +Timer-Sundial[3]是一个专注于时间序列预测的生成式基础模型系列，其基础版本拥有 1.28 亿参数，并在 1 万亿个时间点上进行了大规模预训练，其核心特性包括： + +* **强大的泛化性能：**具备零样本预测能力，可同时支持点预测和概率预测。 +* **灵活预测分布分析：**不仅能预测均值或分位数，还可通过模型生成的原始样本评估预测分布的任意统计特性。 +* **创新生成架构：** 采用 “Transformer + TimeFlow” 协同架构——Transformer 学习时间片段的自回归表征，TimeFlow 模块基于流匹配框架 (Flow-Matching) 将随机噪声转化为多样化预测轨迹，实现高效的非确定性样本生成。 + +![](/img/model03.png) + +## 6. Chronos-2 模型 + +Chronos-2 [4]是由 Amazon Web Services (AWS) 研究团队开发的，基于 Chronos 离散词元建模范式发展起来的通用时间序列基础模型，该模型同时适用于零样本单变量预测和协变量预测。其主要特性包括： + +* **概率性预测能力**：模型以生成式方式输出多步预测结果，支持分位数或分布级预测，从而刻画未来不确定性。 +* **零样本通用预测**：依托预训练获得的上下文学习能力，可直接对未见过的数据集执行预测，无需重新训练或参数更新。 +* **多变量与协变量统一建模**：支持在同一架构下联合建模多条相关时间序列及其协变量，以提升复杂任务的预测效果。但对输入有严格要求： + * 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集； + * 每个历史协变量的长度必须等于目标变量的长度； + * 每个未来协变量的长度必须等于预测长度； +* **高效推理与部署**：模型采用紧凑的编码器式（encoder-only）结构，在保持强泛化能力的同时兼顾推理效率。 + +![](/img/timeseries-large-model-chronos2.png) + +## 7. 效果展示 + +时序大模型能够适应多种不同领域和场景的真实时序数据，在各种任务上拥有优异的处理效果，以下是在不同数据上的真实表现： + +**时序预测：** + +利用时序大模型的预测能力，能够准确预测时间序列的未来变化趋势，如下图蓝色曲线代表预测趋势，红色曲线为实际趋势，两曲线高度吻合。 + +![](/img/LargeModel03.png) + +**数据填补**： + +利用时序大模型对缺失数据段进行预测式填补。 + +![](/img/timeseries-large-model-data-imputation.png) + +**异常检测**： + +利用时序大模型精准识别与正常趋势偏离过大的异常值。 + +![](/img/LargeModel05.png) + +## 8. 部署使用 + +1. 打开 IoTDB cli 控制台，检查 ConfigNode、DataNode、AINode 节点确保均为 Running。 + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. 联网环境下首次启动 AINode 节点会自动拉取 Timer-XL、Sundial、Chronos2 模型。 + + > 注意： + > + > * AINode 安装包不包含模型权重文件 + > * 自动拉取功能依赖部署环境具备 HuggingFace 网络访问能力 + > * AINode 支持手动上传模型权重文件，具体操作方法可参考[导入权重文件](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md#_3-3-导入内置权重文件) + +3. 检查模型是否可用。 + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### 附录 + +**[1]** Timer- Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref1) + +**[2]** TIMER-XL- LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING ,Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref2) + +**[3]** Sundial- A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ 返回](#ref3) + +**[4] **Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821.**[↩ 返回](#ref4) diff --git a/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md b/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md new file mode 100644 index 000000000..3d86bfc4f --- /dev/null +++ b/src/zh/UserGuide/Master/Tree/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md @@ -0,0 +1,157 @@ + +# 时序大模型 + +## 1. 简介 + +时序大模型是专为时序数据分析设计的基础模型。IoTDB 团队长期自研时序基础模型 Timer，该模型基于 Transformer 架构，经海量多领域时序数据预训练，可支撑时序预测、异常检测、时序填补等下游任务；团队打造的 AINode 平台同时支持集成业界前沿时序基础模型，为用户提供多元选型。不同于传统时序分析技术，这类大模型具备通用特征提取能力，可通过零样本分析、微调等技术服务广泛的分析任务。 + +本文相关时序大模型领域的技术成果（含团队自研及业界前沿方向）均发表于国际机器学习顶级会议，具体内容见附录。 + +## 2. 应用场景 + +* **时序预测**：为工业生产、自然环境等领域提供时间序列数据的预测服务，帮助用户提前了解未来变化趋势。 +* **数据填补**：针对时间序列中的缺失序列段，进行上下文填补，以增强数据集的连续性和完整性。 +* **异常检测**：利用自回归分析技术，对时间序列数据进行实时监测，及时预警潜在的异常情况。 + +![](/img/LargeModel09.png) + +## 3. Timer-1 模型 + +Timer[1] 模型（非内置模型）不仅展现了出色的少样本泛化和多任务适配能力，还通过预训练获得了丰富的知识库，赋予了它处理多样化下游任务的通用能力，拥有以下特点： + +* **泛化性**：模型能够通过使用少量样本进行微调，达到行业内领先的深度模型预测效果。 +* **通用性**：模型设计灵活，能够适配多种不同的任务需求，并且支持变化的输入和输出长度，使其在各种应用场景中都能发挥作用。 +* **可扩展性**：随着模型参数数量的增加或预训练数据规模的扩大，模型效果会持续提升，确保模型能够随着时间和数据量的增长而不断优化其预测效果。 + +![](/img/model01.png) + +## 4. Timer-XL 模型 + +Timer-XL[2]基于 Timer 进一步扩展升级了网络结构，在多个维度全面突破： + +* **超长上下文支持**：该模型突破了传统时序预测模型的限制，支持处理数千个 Token（相当于数万个时间点）的输入，有效解决了上下文长度瓶颈问题。 +* **多变量预测场景覆盖**：支持多种预测场景，包括非平稳时间序列的预测、涉及多个变量的预测任务以及包含协变量的预测，满足多样化的业务需求。 +* **大规模工业时序数据集：**采用万亿大规模工业物联网领域的时序数据集进行预训练，数据集兼有庞大的体量、卓越的质量和丰富的领域等重要特质，覆盖能源、航空航天、钢铁、交通等多领域。 + +![](/img/model02.png) + +## 5. Timer-Sundial 模型 + +Timer-Sundial[3]是一个专注于时间序列预测的生成式基础模型系列，其基础版本拥有 1.28 亿参数，并在 1 万亿个时间点上进行了大规模预训练，其核心特性包括： + +* **强大的泛化性能：**具备零样本预测能力，可同时支持点预测和概率预测。 +* **灵活预测分布分析：**不仅能预测均值或分位数，还可通过模型生成的原始样本评估预测分布的任意统计特性。 +* **创新生成架构：** 采用 “Transformer + TimeFlow” 协同架构——Transformer 学习时间片段的自回归表征，TimeFlow 模块基于流匹配框架 (Flow-Matching) 将随机噪声转化为多样化预测轨迹，实现高效的非确定性样本生成。 + +![](/img/model03.png) + +## 6. Chronos-2 模型 + +Chronos-2 [4]是由 Amazon Web Services (AWS) 研究团队开发的，基于 Chronos 离散词元建模范式发展起来的通用时间序列基础模型，该模型同时适用于零样本单变量预测和协变量预测。其主要特性包括： + +* **概率性预测能力**：模型以生成式方式输出多步预测结果，支持分位数或分布级预测，从而刻画未来不确定性。 +* **零样本通用预测**：依托预训练获得的上下文学习能力，可直接对未见过的数据集执行预测，无需重新训练或参数更新。 +* **多变量与协变量统一建模**：支持在同一架构下联合建模多条相关时间序列及其协变量，以提升复杂任务的预测效果。但对输入有严格要求： + * 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集； + * 每个历史协变量的长度必须等于目标变量的长度； + * 每个未来协变量的长度必须等于预测长度； +* **高效推理与部署**：模型采用紧凑的编码器式（encoder-only）结构，在保持强泛化能力的同时兼顾推理效率。 + +![](/img/timeseries-large-model-chronos2.png) + +## 7. 效果展示 + +时序大模型能够适应多种不同领域和场景的真实时序数据，在各种任务上拥有优异的处理效果，以下是在不同数据上的真实表现： + +**时序预测：** + +利用时序大模型的预测能力，能够准确预测时间序列的未来变化趋势，如下图蓝色曲线代表预测趋势，红色曲线为实际趋势，两曲线高度吻合。 + +![](/img/LargeModel03.png) + +**数据填补**： + +利用时序大模型对缺失数据段进行预测式填补。 + +![](/img/timeseries-large-model-data-imputation.png) + +**异常检测**： + +利用时序大模型精准识别与正常趋势偏离过大的异常值。 + +![](/img/LargeModel05.png) + +## 8. 部署使用 + +1. 打开 IoTDB cli 控制台，检查 ConfigNode、DataNode、AINode 节点确保均为 Running。 + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. 联网环境下首次启动 AINode 节点会自动拉取 Timer-XL、Sundial、Chronos2 模型。 + + > 注意： + > + > * AINode 安装包不包含模型权重文件 + > * 自动拉取功能依赖部署环境具备 HuggingFace 网络访问能力 + > * AINode 支持手动上传模型权重文件，具体操作方法可参考[导入权重文件](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md#_3-3-导入内置权重文件) + +3. 检查模型是否可用。 + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### 附录 + +**[1]** Timer- Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref1) + +**[2]** TIMER-XL- LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING ,Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref2) + +**[3]** Sundial- A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ 返回](#ref3) + +**[4] **Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821.**[↩ 返回](#ref4) diff --git a/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade.md b/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade.md new file mode 100644 index 000000000..6f44068b6 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: AINode_Upgrade_apache.html +--- + \ No newline at end of file diff --git a/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade_apache.md b/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade_apache.md new file mode 100644 index 000000000..b7a4fc62d --- /dev/null +++ b/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade_apache.md @@ -0,0 +1,596 @@ + + +# AINode + +AINode 是支持时序相关模型注册、管理、调用的 IoTDB 原生节点，内置业界领先的自研时序大模型，如清华自研时序模型 Timer 系列，可通过标准 SQL 语句进行调用，实现时序数据的毫秒级实时推理，可支持时序趋势预测、缺失值填补、异常值检测等应用场景。 + +系统架构如下图所示： + +![](/img/AINode-0.png) + +三种节点的职责如下： + +* **ConfigNode**：负责分布式节点管理和负载均衡。 +* **DataNode**：负责接收并解析用户的 SQL请求；负责存储时间序列数据；负责数据的预处理计算。 +* **AINode**：负责时序模型的管理和使用。 + +## 1. 优势特点 + +与单独构建机器学习服务相比，具有以下优势： + +* **简单易用**：无需使用 Python 或 Java 编程，使用 SQL 语句即可完成机器学习模型管理与推理的完整流程。如创建模型可使用CREATE MODEL语句、使用模型进行推理可使用`SELECT * FROM FORECAST (...) ` 语句等，使用更加简单便捷。 +* **避免数据迁移**：使用 IoTDB 原生机器学习可以将存储在 IoTDB 中的数据直接应用于机器学习模型的推理，无需将数据移动到单独的机器学习服务平台，从而加速数据处理、提高安全性并降低成本。 + +![](/img/h1.png) + +* **内置先进算法**：支持业内领先机器学习分析算法，覆盖典型时序分析任务，为时序数据库赋能原生数据分析能力。如： + * **时间序列预测（Time Series Forecasting）**：从过去时间序列中学习变化模式；从而根据给定过去时间的观测值，输出未来序列最可能的预测。 + * **时序异常检测（Anomaly Detection for Time Series）**：在给定的时间序列数据中检测和识别异常值，帮助发现时间序列中的异常行为。 + +## 2. 基本概念 + +* **模型（Model）**：机器学习模型，以时序数据作为输入，输出分析任务的结果或决策。模型是 AINode 的基本管理单元，支持模型的增（注册）、删、查、用（推理）。 +* **创建（Create）**: 将外部设计或训练好的模型文件或算法加载到 AINode 中，由 IoTDB 统一管理与使用。 +* **推理（Inference）**：使用创建的模型在指定时序数据上完成该模型适用的时序分析任务。 +* **内置能力（Built-in）**：AINode 自带常见时序分析场景（例如预测与异常检测）的机器学习算法或自研模型。 + +![](/img/AINode-new.png) + +## 3. 安装部署 + +AINode 的部署可参考文档 [AINode 部署](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md) 。 + +## 4. 使用指导 + +AINode 支持模型推理和模型管理（注册、查看、删除、加载、卸载等）两大功能，下面章节将进行详细说明。 + +### 4.1 模型推理 + +AINode 表模型支持对单一目标变量进行预测的推理功能，下文将详细介绍该功能的语法定义、参数说明以及使用实例。 + +1. **SQL 语法** + +```SQL +SELECT * FROM FORECAST( + MODEL_ID, + TARGETS, -- 获取目标变量的 SQL + OUTPUT_START_TIME, + OUTPUT_LENGTH, + OUTPUT_INTERVAL, + TIMECOL, + PRESERVE_INPUT, + MODEL_OPTIONS]? +) +``` + +* 内置模型推理无需注册流程，通过 forecast 函数，指定 model\_id 就可以使用模型的推理功能。 +* 参数介绍 + +| 参数名 | 参数类型 | 参数属性 | 描述 | 是否必填 | 备注 | +|---------------------|-------|-------------------------------------------------|-----------------------------------------------------------| ---------- | -------------------------------------------------------------------------------- | +| model\_id | 标量参数 | 字符串类型 | 预测所用模型的唯一标识 | 是| | +| targets | 表参数 | SET SEMANTIC | 待预测目标变量的输入数据。IoTDB会自动将数据按时间升序排序再交给AINode 。 | 是 | 使用 SQL 描述带预测目标变量的输入数据，输入的 SQL 不合法时会有对应的查询报错。| +| output\_start\_time | 标量参数 | 时间戳类型。默认值：目标变量最后一个时间戳 + output\_interval | 输出的预测点的起始时间戳【即起报时间】 | 否 | 必须大于目标变量时间戳的最大值 | +| output\_length | 标量参数 | INT32 类型。默认值：96 | 输出窗口大小 | 否| 必须大于 0 | +| output\_interval | 标量参数 | 时间间隔类型。默认值：(输入数据的最后一个时间戳 - 输入数据的第一个时间戳) / n - 1 | 输出的预测点之间的时间间隔支持的单位是 ns、us、ms、s、m、h、d、w | 否 | 必须大于 0| +| timecol | 标量参数 | 字符串类型。默认值：time | 时间列名 | 否 | 必须为存在于 targets 中的且数据类型为 TIMESTAMP 的列 | +| preserve\_input | 标量参数 | 布尔类型。默认值：false | 是否在输出结果集中保留目标变量输入的所有原始行 | 否| | +| model\_options | 标量参数 | 字符串类型。默认值：空字符串 | 模型相关的 key-value 对，比如是否需要对输入进行归一化等。不同的 key-value 对以 ';' 间隔 | 否| | + +说明： + +* **默认行为**：预测 targets 的所有列。当前仅支持 INT32、INT64、FLOAT、DOUBLE 类型。 +* **输入数据要求**： + * 必须包含时间列。 + * 行数要求：不足最低行数会报错，超过最大行数则自动截取末尾数据。 +* **输出结果**： + * 包含所有目标变量列，数据类型与原表一致。 + * 若指定 `preserve_input=true`，会额外增加 `is_input` 列来标识原始数据行。 +* **时间戳生成**： + * 使用 `OUTPUT_START_TIME`（可选）作为预测起始时间点，并以此划分历史与未来数据。 + * 使用 `OUTPUT_INTERVAL`（可选，默认为输入数据的采样间隔）作为输出时间间隔。第 N 行的时间戳计算公式为：`OUTPUT_START_TIME + (N - 1) * OUTPUT_INTERVAL`。 + +2. **使用示例** + +提前创建数据库 etth 及表 eg + +```SQL +create database etth; +create table eg (hufl FLOAT FIELD, hull FLOAT FIELD, mufl FLOAT FIELD, mull FLOAT FIELD, lufl FLOAT FIELD, lull FLOAT FIELD, ot FLOAT FIELD) +``` + +准备原始数据 [ETTh1-tab](/img/ETTh1-tab.csv) + +使用表 eg 中测点 ot 已知的 96 行数据，预测其未来的 96 行数据. + +```SQL +IoTDB:etth> select Time, HUFL,HULL,MUFL,MULL,LUFL,LULL,OT from eg LIMIT 96 ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +| Time| HUFL| HULL| MUFL| MULL| LUFL| LULL| OT| ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +|2016-07-01T00:00:00.000+08:00| 5.827|2.009|1.599|0.462|4.203| 1.34|30.531| +|2016-07-01T01:00:00.000+08:00| 5.693|2.076|1.492|0.426|4.142|1.371|27.787| +|2016-07-01T02:00:00.000+08:00| 5.157|1.741|1.279|0.355|3.777|1.218|27.787| +|2016-07-01T03:00:00.000+08:00| 5.09|1.942|1.279|0.391|3.807|1.279|25.044| +...... +Total line number = 96 +It costs 0.119s + +IoTDB:etth> select * from forecast( + model_id => 'sundial', + targets => (select Time, ot from etth.eg where time >= 2016-08-07T18:00:00.000+08:00 limit 1440) order BY time, + output_length => 96 +) ++-----------------------------+---------+ +| time| ot| ++-----------------------------+---------+ +|2016-10-06T18:00:00.000+08:00|20.781654| +|2016-10-06T19:00:00.000+08:00|20.252121| +|2016-10-06T20:00:00.000+08:00|19.960138| +|2016-10-06T21:00:00.000+08:00|19.662334| +...... +Total line number = 96 +It costs 1.615s +``` + +### 4.2 注册自定义模型 + +**符合以下要求的 Transformers 模型可以注册到 AINode 中：** + +1. AINode 目前使用 v4.56.2 版本的 transformers，构建模型时需**避免继承低版本（<4.50）接口**； +2. 模型需继承一类 AINode 的推理任务流水线（当前支持预测流水线）： + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + 在推理任务开始前对输入数据进行前处理，包括形状验证和数值转换。 + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + 在推理任务结束后对输出结果进行后处理。 + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + 在将输入数据传递给模型进行推理之前进行预处理，验证输入数据的形状和类型。 + + Args: + inputs (list[dict]): + 输入数据，字典列表，每个字典包含： + - 'targets': 形状为 (input_length,) 或 (target_count, input_length) 的张量。 + - 'past_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + - 'future_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + + infer_kwargs (dict, optional): 推理的额外关键字参数，如： + - `output_length`(int): 如果提供'future_covariates'，用于验证其有效性。 + + Raises: + ValueError: 如果输入格式不正确（例如，缺少键、张量形状无效）。 + + Returns: + 经过预处理和验证的输入数据，可直接用于模型推理。 + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + 对给定输入执行预测。 + + Parameters: + inputs: 用于进行预测的输入数据。类型和结构取决于模型的具体实现。 + **infer_kwargs: 额外的推理参数，例如： + - `output_length`(int): 模型应该生成的时间点数量。 + + Returns: + 预测输出，具体形式取决于模型的具体实现。 + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + 在推理后对模型输出进行后处理，验证输出数据的形状并确保其符合预期维度。 + + Args: + outputs: + 模型输出，2D张量列表，每个张量形状为 `[target_count, output_length]`。 + + Raises: + InferenceModelInternalException: 如果输出张量形状无效（例如，维数错误）。 + ValueError: 如果输出格式不正确。 + + Returns: + list[torch.Tensor]: + 后处理后的输出，将是一个2D张量列表。 + """ + pass + ``` +3. 修改模型配置文件 config.json，确保包含以下字段： + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // 指定模型 Config 类 + "AutoModelForCausalLM": "model.Chronos2Model" // 指定模型类 + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // 指定模型的推理流水线 + "model_type": "custom_t5", // 指定模型类型 + } + ``` + + 1. 必须通过 auto\_map 指定模型的 Config 类和模型类； + 2. 必须集成并指定推理流水线类； + 3. 对于 AINode 管理的内置（builtin）和自定义（user\_defined）模型，模型类别（model\_type）也作为不可重复的唯一标识。即，要注册的模型类别不得与任何已存在的模型类型重复。 +4. 确保要注册的模型目录包含以下文件，且模型配置文件名称和权重文件名称不支持自定义： + 1. 模型配置文件：config.json； + 2. 模型权重文件：model.safetensors； + 3. 模型代码：其它 .py 文件。 + +**注册自定义模型的 SQL 语法如下所示：** + +```SQL +CREATE MODEL USING URI +``` + +**参数说明：** + +* **model\_id**：自定义模型的唯一标识；不可重复，有以下约束： + * 允许出现标识符 [ 0-9 a-z A-Z \_ ] （字母，数字（非开头），下划线（非开头）） + * 长度限制为 2-64 字符 + * 大小写敏感 +* **uri**：包含模型代码和权重的本地 uri 地址。 + +**注册示例：** + +从本地路径上传自定义 Transformers 模型，AINode 会将该文件夹拷贝至 user\_defined 目录中。 + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +SQL执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见查看模型章节）。模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。 + +### 4.3 查看模型 + +注册成功的模型可以通过查看指令查询模型的具体信息。 + +```SQL +SHOW MODELS +``` + +除了直接展示所有模型的信息外，可以指定`model_id`来查看某一具体模型的信息。 + +```SQL +SHOW MODELS -- 只展示特定模型 +``` + +模型展示的结果中包含如下内容： + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| 模型ID | 模型类型 | 模型种类 | 模型状态 | + +其中，State 模型状态机流转示意图如下: + +![](/img/ainode-upgrade-state-apache.png) + +状态机流程说明： + +1. 启动 AINode 后，执行 `show models` 命令，仅能查看到**系统内置（BUILTIN）**的模型。 +2. 用户可导入自己的模型，这类模型的来源标识为**用户自定义（USER\_DEFINED）**；AINode 会尝试从模型配置文件中解析模型类型（ModelType），若解析失败，该字段则显示为空。 +3. 时序大模型（内置模型）权重文件不随 AINode 打包，AINode 启动时自动下载。 + 1. 下载过程中为 ACTIVATING，下载成功转变为 ACTIVE，失败则变成 INACTIVE。 + +**查看示例** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +内置传统时序模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|----------------------------------| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **ARIMA**(自回归整合移动平均模型) | 结合自回归(AR)、差分(I)和移动平均(MA)，用于预测平稳时间序列或可通过差分变为平稳的数据。 | 单变量时间序列预测，如股票价格、销量、经济指标等。| 1. 适用于线性趋势和季节性较弱的数据。2. 需要选择参数 (p,d,q)。3. 对缺失值敏感。 | +| **Holt-Winters**(三参数指数平滑) | 基于指数平滑，引入水平、趋势和季节性三个分量，适用于具有趋势和季节性的数据。 | 有明显季节性和趋势的时间序列，如月度销售额、电力需求等。 | 1. 可处理加性或乘性季节性。2. 对近期数据赋予更高权重。3. 简单易实现。 | +| **Exponential Smoothing**(指数平滑) | 通过加权平均历史数据，权重随时间指数递减，强调近期观测值的重要性。 | 无显著季节性但存在趋势的数据，如短期需求预测。 | 1. 参数少，计算简单。2. 适合平稳或缓慢变化序列。3. 可扩展为双指数或三指数平滑。 | +| **Naive Forecaster**(朴素预测器) | 使用最近一期的观测值作为下一期的预测值，是最简单的基准模型。 | 作为其他模型的比较基准，或数据无明显模式时的简单预测。 | 1. 无需训练。2. 对突发变化敏感。3. 季节性朴素变体可用前一季节同期值预测。 | +| **STL Forecaster**(季节趋势分解预测) | 基于STL分解时间序列，分别预测趋势、季节性和残差分量后组合。 | 具有复杂季节性、趋势和非线性模式的数据，如气候数据、交通流量。 | 1. 能处理非固定季节性。2. 对异常值稳健。3. 分解后可结合其他模型预测各分量。 | +| **Gaussian HMM**(高斯隐马尔可夫模型) | 假设观测数据由隐藏状态生成，每个状态的观测概率服从高斯分布。 | 状态序列预测或分类，如语音识别、金融状态识别。 | 1. 适用于时序数据的状态建模。2. 假设观测值在给定状态下独立。3. 需指定隐藏状态数量。 | +| **GMM HMM** (高斯混合隐马尔可夫模型) | 扩展Gaussian HMM，每个状态的观测概率由高斯混合模型描述，可捕捉更复杂的观测分布。 | 需要多模态观测分布的场景，如复杂动作识别、生物信号分析。 | 1. 比单一高斯更灵活。2. 参数更多，计算复杂度高。3. 需训练GMM成分数。 | +| **STRAY**(基于奇异值的异常检测) | 通过奇异值分解(SVD)检测高维数据中的异常点，常用于时间序列异常检测。 | 高维时间序列的异常检测，如传感器网络、IT系统监控。 | 1. 无需分布假设。2. 可处理高维数据。3. 对全局异常敏感，局部异常可能漏检。 | + +内置时序大模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | 支持超长上下文的时序大模型，通过大规模工业数据预训练增强泛化能力。 | 需利用极长历史数据的复杂工业预测，如能源、航空航天、交通等领域。 | 1. 超长上下文支持，可处理数万时间点输入。2. 多场景覆盖，支持非平稳、多变量及协变量预测。3. 基于万亿级高质量工业时序数据预训练。 | +| **Timer-Sundial** | 采用“Transformer + TimeFlow”架构的生成式基础模型，专注于概率预测。 | 需要量化不确定性的零样本预测场景，如金融、供应链、新能源发电预测。 | 1. 强大的零样本泛化能力，支持点预测与概率预测 2. 可灵活分析预测分布的任意统计特性。3. 创新生成架构，实现高效的非确定性样本生成。 | +| **Chronos-2** | 基于离散词元化范式的通用时序基础模型，将预测转化为语言建模任务。 | 快速零样本单变量预测，以及可借助协变量（如促销、天气）提升效果的场景。 | 1. 强大的零样本概率预测能力。2. 支持协变量统一建模，但对输入有严格要求：a. 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集；b. 每个历史协变量的长度必须等于目标变量的长度； c. 每个未来协变量的长度必须等于预测长度；3. 采用高效的编码器式结构，兼顾性能与推理速度。 | + +### 4.4 删除模型 + +对于注册成功的模型，用户可以通过 SQL 进行删除，AINode 会将 user\_defined 目录下的对应模型文件夹整个删除。其 SQL 语法如下： + +```SQL +DROP MODEL +``` + +需要指定已经成功注册的模型 model\_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。 + +### 4.5 加载/卸载模型 + +为适应不同场景，AINode 提供以下两种模型加载策略： + +* 即时加载：即推理时临时加载模型，结束后释放资源。适用于测试或低负载场景。 +* 常驻加载：即将模型持久化加载在内存（CPU）或显存（GPU）中，以支持高并发推理。用户只需通过 SQL 指定加载或卸载的模型，AINode 会自动管理实例数量。当前常驻模型的状态也可随时查看。 + +下文将详细介绍加载/卸载模型的相关内容： + +1. 配置参数 + +支持通过编辑如下配置项设置常驻加载相关参数。 + +```Properties +# AINode 在推理时可使用的设备内存/显存占总量的比例 +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# AINode 每个加载的模型实例需要占用的内存比例，即模型占用*该值 +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. 展示可用的 device + +支持通过如下 SQL 命令查看所有可用的设备 ID + +```SQL +SHOW AI_DEVICES +``` + +示例 + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. 加载模型 + +支持通过如下 SQL 命令手动加载模型，系统根据硬件资源使用情况**自动均衡**模型实例数量。 + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 加载到 AINode 所在服务器的内存中。 + * **gpu\_id:** 加载到 AINode 所在服务器的对应显卡中，如 "0, 1" 表示加载到编号为 0 和 1 的两张显卡中。 + +示例 + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. 卸载模型 + +支持通过如下 SQL 命令手动卸载指定模型的所有实例，系统会**重分配**空闲出的资源给其他模型 + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 尝试从 AINode 所在服务器的内存中卸载指定模型。 + * **gpu\_id:** 尝试从 AINode 所在服务器的对应显卡中卸载指定模型，如 "0, 1" 表示尝试从编号为 0 和 1 的两张显卡卸载指定模型。 + +示例 + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. 展示加载的模型 + +支持通过如下 SQL 命令查看已经手动加载的模型实例，可通过 `device_id `指定设备。 + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # 展示指定设备中的模型实例 +``` + +示例：在内存、gpu\_0 和 gpu\_1 两张显卡加载了sundial 模型 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +说明： + +* DeviceId : 设备 ID +* ModelId ：加载的模型 ID +* Count(instances) ：每个设备中的模型实例数量（系统自动分配） + +### 4.6 时序大模型介绍 + +AINode 目前支持多种时序大模型，相关介绍及部署使用可参考[时序大模型](../AI-capability/TimeSeries-Large-Model_Upgrade_apache.md) + +## 5. 权限管理 + +使用 AINode 相关的功能时，可以使用IoTDB本身的鉴权去做一个权限管理，用户只有在具备 USE\_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。 + +| **权限名称** | **权限范围** | **管理员用户（默认ROOT）** | **普通用户** | +| ------------------------- | ----------------------------------------- | ---------------------------------- | -------------------- | +| USE\_MODEL | create model / show models / drop model | √ | √ | +| READ\_SCHEMA&READ\_DATA | forecast | √ | √ | + + +## 6. 向 IoTDB-AINode 贡献开源时序大模型 + +支持在 AINode 新增自定义内置模型，具体操作步骤如下（以 chronos2 为例）： + +* **向 [dev@iotdb.apache.org](mailto:dev@iotdb.apache.org) 邮件列表发送邮件或在项目主仓库提交 issue，发起初步讨论** +* **向主分支提交 Pull Request** + +1. 检查模型所用的开源协议，并在 IoTDB 仓库进行对应声明。 +2. 在 iotdb-core/ainode/iotdb/ainode/core/model 创建新内置模型对应的包； + 1. 确保包含模型配置类； + 2. 确保包含执行推理任务的模型类； + 3. 确保包含继承 AINode 推理任务流水线的类； + + ```Bash + root@rootMacBook-Pro model % eza --tree --level=2 . + . + ├── chronos2 + │ ├── __init__.py + │ ├── base.py + │ ├── chronos_bolt.py + │ ├── config.py + │ ├── dataset.py + │ ├── layers.py + │ ├── model.py + │ ├── pipeline_chronos2.py # 继承 AINode 推理任务流水线 + │ └── utils.py + ├── sktime + ├── sundial + └── timer_xl + ``` +3. 在 iotdb-core/ainode/iotdb/ainode/core/model/model\_info.py 新增该模型的元信息； + ```Python + BUILTIN_HF_TRANSFORMERS_MODEL_MAP = { + "chronos2": ModelInfo( + model_id="chronos2", # 模型的唯一标识 + category=ModelCategory.BUILTIN, # 模型类别，选择 BUILTIN + state=ModelStates.INACTIVE, + model_type="t5", # 模型种类，不能和其它 builtin 模型相同 + pipeline_cls="pipeline_chronos2.Chronos2Pipeline", # 继承 AINode 的推理流水线 + repo_id="amazon/chronos-2", # 【可选】Huggingface 权重 + auto_map={ + "AutoConfig": "config.Chronos2CoreConfig", # 确保指向模型的配置类 + "AutoModelForCausalLM": "model.Chronos2Model", # 确保指向推理所用的模型类 + }, + ), + } + ``` +4. 在 integration-test/src/test/java/org/apache/iotdb/ainode/utils/AINodeTestUtils.java 添加对应模型。 + ```Java + public static final Map BUILTIN_LTSM_MAP = + Stream.of( + new AbstractMap.SimpleEntry<>( + "sundial", new FakeModelInfo("sundial", "sundial", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "timer_xl", new FakeModelInfo("timer_xl", "timer", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "chronos2", new FakeModelInfo("chronos2", "t5", "builtin", "active"))) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + ``` +5. 提交 pull request，确保通过流水线测试后才能合并。 + +* **打包部署** + +1. 编译 AINode，获取安装包； + ```Bash + # 同时构建 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 + ``` +2. 在运行时确保模型能获取权重。 + 1. 若模型权重可从 Huggingface 在线获取，确保已填写`repo_id`； + 2. 否则，可在 AINode 启动前/运行时手动将模型权重放在`data/ainode/models/builtin/`。 + + ```Bash + root@rootMacBook-Pro models % eza --tree --level=3 . + . + ├── __init__.py + ├── builtin + │ ├── __init__.py + │ ├── chronos2 + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ ├── sundial + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ └── timer_xl + │ ├── __init__.py + │ ├── config.json + │ └── model.safetensors + └── user_defined + ``` + +* **完整示例** + +完整示例可参考 https://github.com/apache/iotdb/pull/16903 diff --git a/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade_timecho.md b/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade_timecho.md new file mode 100644 index 000000000..60ddbdd3c --- /dev/null +++ b/src/zh/UserGuide/latest-Table/AI-capability/AINode_Upgrade_timecho.md @@ -0,0 +1,749 @@ + + +# AINode + +AINode 是支持时序相关模型注册、管理、调用的 IoTDB 原生节点，内置业界领先的自研时序大模型，如清华自研时序模型 Timer 系列，可通过标准 SQL 语句进行调用，实现时序数据的毫秒级实时推理，可支持时序趋势预测、缺失值填补、异常值检测等应用场景。 + +系统架构如下图所示： + +![](/img/AINode-0.png) + +三种节点的职责如下： + +* **ConfigNode**：负责分布式节点管理和负载均衡。 +* **DataNode**：负责接收并解析用户的 SQL请求；负责存储时间序列数据；负责数据的预处理计算。 +* **AINode**：负责时序模型的管理和使用。 + +## 1. 优势特点 + +与单独构建机器学习服务相比，具有以下优势： + +* **简单易用**：无需使用 Python 或 Java 编程，使用 SQL 语句即可完成机器学习模型管理与推理的完整流程。如创建模型可使用CREATE MODEL语句、使用模型进行推理可使用` SELECT * FROM FORECAST (...) ` 语句等，使用更加简单便捷。 +* **避免数据迁移**：使用 IoTDB 原生机器学习可以将存储在 IoTDB 中的数据直接应用于机器学习模型的推理，无需将数据移动到单独的机器学习服务平台，从而加速数据处理、提高安全性并降低成本。 + +![](/img/h1.png) + +* **内置先进算法**：支持业内领先机器学习分析算法，覆盖典型时序分析任务，为时序数据库赋能原生数据分析能力。如： + * **时间序列预测（Time Series Forecasting）**：从过去时间序列中学习变化模式；从而根据给定过去时间的观测值，输出未来序列最可能的预测。 + * **时序异常检测（Anomaly Detection for Time Series）**：在给定的时间序列数据中检测和识别异常值，帮助发现时间序列中的异常行为。 + +## 2. 基本概念 + +* **模型（Model）**：机器学习模型，以时序数据作为输入，输出分析任务的结果或决策。模型是 AINode 的基本管理单元，支持模型的增（注册）、删、查、改（微调）、用（推理）。 +* **创建（Create）**: 将外部设计或训练好的模型文件或算法加载到 AINode 中，由 IoTDB 统一管理与使用。 +* **推理（Inference）**：使用创建的模型在指定时序数据上完成该模型适用的时序分析任务。 +* **内置能力（Built-in）**：AINode 自带常见时序分析场景（例如预测与异常检测）的机器学习算法或自研模型。 + +![](/img/AINode-new.png) + +## 3. 安装部署 + +AINode 的部署可参考文档 [AINode 部署](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md) 。 + +## 4. 使用指导 + +TimechoDB-AINode 支持模型推理、模型微调以及模型管理（注册、查看、删除、加载、卸载等）三大功能，下面章节将进行详细说明。 + +### 4.1 模型推理 + +TimechoDB-AINode 表模型提供以下时序预测能力： + +* **单变量预测**：支持对单一目标变量进行预测。 +* **协变量预测**：可同时对多个目标变量进行联合预测，并支持在预测中引入协变量，以提升预测的准确性。 + +下文将详细介绍预测推理功能的语法定义、参数说明以及使用实例。 + +1. **SQL 语法** + +```SQL +SELECT * FROM FORECAST( + MODEL_ID, + TARGETS, -- 获取目标变量的 SQL + [HISTORY_COVS, -- 字符串，用于获取历史协变量的 SQL + FUTURE_COVS, -- 字符串，用于获取未来协变量的 SQL + OUTPUT_START_TIME, + OUTPUT_LENGTH, + OUTPUT_INTERVAL, + TIMECOL, + PRESERVE_INPUT, + MODEL_OPTIONS]? +) +``` + +* 内置模型推理无需注册流程，通过 forecast 函数，指定 model\_id 就可以使用模型的推理功能。 +* 参数介绍 + +| 参数名 | 参数类型 | 参数属性 | 描述 | 是否必填 | 备注 | +|---------------------|-------|----------------------------------------------------|-----------------------------------------------------------------------------------------| ---------- |--------------------------------------------------------------------------------------------------------------------------| +| model\_id | 标量参数 | 字符串类型 | 预测所用模型的唯一标识 | 是| | +| targets | 表参数 | SET SEMANTIC | 待预测目标变量的输入数据。IoTDB会自动将数据按时间升序排序再交给AINode 。 | 是 | 使用 SQL 描述带预测目标变量的输入数据，输入的 SQL 不合法时会有对应的查询报错。 | +| history\_covs | 标量参数 | 字符串类型（合法的表模型查询 SQL）默认：无 | 指定此次预测任务的协变量的历史数据，这些数据用于辅助目标变量的预测，AINode 不会对历史协变量输出预测结果。在将数据给予模型前，AINode 会自动将数据按时间升序排序。 | 否 | 1. 查询结果只能包含 FIELD 列； 2. 其它：不同模型可能会有独特要求，不符合时会抛出对应的错误。 | +| future\_covs | 标量参数 | 字符串类型（合法的表模型查询 SQL） 默认：无 | 指定此次预测任务部分协变量的未来数据，这些数据用于辅助目标变量的预测。 在将数据给予模型前，AINode 会自动将数据按时间升序排序。 | 否 | 1. 当且仅当设置 history\_covs 时可以指定此参数；2. 所涉及协变量名称必须是 history\_covs 的子集； 3. 查询结果只能包含 FIELD 列； 4. 其它：不同模型可能会有独特要求，不符合时会抛出对应的错误。 | +| output\_start\_time | 标量参数 | 时间戳类型。 默认值：目标变量最后一个时间戳 + output\_interval | 输出的预测点的起始时间戳 【即起报时间】 | 否 | 必须大于目标变量时间戳的最大值 | +| output\_length | 标量参数 | INT32 类型。 默认值：96 | 输出窗口大小 | 否 | 必须大于 0 | +| output\_interval | 标量参数 | 时间间隔类型。 默认值：(输入数据的最后一个时间戳 - 输入数据的第一个时间戳) / n - 1 | 输出的预测点之间的时间间隔 支持的单位是 ns、us、ms、s、m、h、d、w | 否 | 必须大于 0 | +| timecol | 标量参数 | 字符串类型。 默认值：time | 时间列名 | 否 | 必须为存在于 targets 中的且数据类型为 TIMESTAMP 的列 | +| preserve\_input | 标量参数 | 布尔类型。 默认值：false | 是否在输出结果集中保留目标变量输入的所有原始行 | 否 | | +| model\_options | 标量参数 | 字符串类型。 默认值：空字符串 | 模型相关的 key-value 对，比如是否需要对输入进行归一化等。不同的 key-value 对以 ';' 间隔 | 否 | | + +说明： + +* **默认行为**：预测 targets 的所有列。当前仅支持 INT32、INT64、FLOAT、DOUBLE 类型。 +* **输入数据要求**： + * 必须包含时间列。 + * 行数要求：不足最低行数会报错，超过最大行数则自动截取末尾数据。 + * 列数要求：单变量模型仅支持单列，多列将报错；协变量模型通常无限制，除非模型自身有明确约束。 + * 协变量预测时，SQL 语句中需明确指定 DATABASE。 +* **输出结果**： + * 包含所有目标变量列，数据类型与原表一致。 + * 若指定 `preserve_input=true`，会额外增加 `is_input` 列来标识原始数据行。 +* **时间戳生成**： + * 使用 `OUTPUT_START_TIME`（可选）作为预测起始时间点，并以此划分历史与未来数据。 + * 使用 `OUTPUT_INTERVAL`（可选，默认为输入数据的采样间隔）作为输出时间间隔。第 N 行的时间戳计算公式为：`OUTPUT_START_TIME + (N - 1) * OUTPUT_INTERVAL`。 + +2. **使用示例** + +**示例一：单变量预测** + +提前创建数据库 etth 及表 eg + +```SQL +create database etth; +create table eg (hufl FLOAT FIELD, hull FLOAT FIELD, mufl FLOAT FIELD, mull FLOAT FIELD, lufl FLOAT FIELD, lull FLOAT FIELD, ot FLOAT FIELD) +``` + +准备原始数据 [ETTh1-tab](/img/ETTh1-tab.csv) + +使用表 eg 中测点 ot 已知的 96 行数据，预测其未来的 96 行数据. + +```SQL +IoTDB:etth> select Time, HUFL,HULL,MUFL,MULL,LUFL,LULL,OT from eg LIMIT 96 ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +| Time| HUFL| HULL| MUFL| MULL| LUFL| LULL| OT| ++-----------------------------+------+-----+-----+-----+-----+-----+------+ +|2016-07-01T00:00:00.000+08:00| 5.827|2.009|1.599|0.462|4.203| 1.34|30.531| +|2016-07-01T01:00:00.000+08:00| 5.693|2.076|1.492|0.426|4.142|1.371|27.787| +|2016-07-01T02:00:00.000+08:00| 5.157|1.741|1.279|0.355|3.777|1.218|27.787| +|2016-07-01T03:00:00.000+08:00| 5.09|1.942|1.279|0.391|3.807|1.279|25.044| +...... +Total line number = 96 +It costs 0.119s + +IoTDB:etth> select * from forecast( + model_id => 'sundial', + targets => (select Time, ot from etth.eg where time >= 2016-08-07T18:00:00.000+08:00 limit 1440) order BY time, + output_length => 96 +) ++-----------------------------+---------+ +| time| ot| ++-----------------------------+---------+ +|2016-10-06T18:00:00.000+08:00|20.781654| +|2016-10-06T19:00:00.000+08:00|20.252121| +|2016-10-06T20:00:00.000+08:00|19.960138| +|2016-10-06T21:00:00.000+08:00|19.662334| +...... +Total line number = 96 +It costs 1.615s +``` + +**示例二：协变量预测** + +提前创建表 tab\_real（存储原始真实数据） + +```SQL +create table tab_real (target1 DOUBLE FIELD, target2 DOUBLE FIELD, cov1 DOUBLE FIELD, cov2 DOUBLE FIELD, cov3 DOUBLE FIELD); +``` + +准备原始数据 + +```SQL +IoTDB:etth> SELECT * FROM tab_real ++-----------------------------+-------+-------+----+----+----+ +| time|target1|target2|cov1|cov2|cov3| ++-----------------------------+-------+-------+----+----+----+ +|1970-01-01T08:00:00.001+08:00| 1.0| 1.0| 1.0| 1.0| 1.0| +|1970-01-01T08:00:00.002+08:00| 2.0| 2.0| 2.0| 2.0| 2.0| +|1970-01-01T08:00:00.003+08:00| 3.0| 3.0| 3.0| 3.0| 3.0| +|1970-01-01T08:00:00.004+08:00| 4.0| 4.0| 4.0| 4.0| 4.0| +|1970-01-01T08:00:00.005+08:00| 5.0| 5.0| 5.0| 5.0| 5.0| +|1970-01-01T08:00:00.006+08:00| 6.0| 6.0| 6.0| 6.0| 6.0| +|1970-01-01T08:00:00.007+08:00| null| null|null|null| 7.0| +|1970-01-01T08:00:00.008+08:00| null| null|null|null| 8.0| ++-----------------------------+-------+-------+----+----+----+ + + +--写入语句 +IoTDB:etth> INSERT INTO tab_real (time, target1, target2, cov1, cov2, cov3) VALUES +(1, 1.0, 1.0, 1.0, 1.0, 1.0), +(2, 2.0, 2.0, 2.0, 2.0, 2.0), +(3, 3.0, 3.0, 3.0, 3.0, 3.0), +(4, 4.0, 4.0, 4.0, 4.0, 4.0), +(5, 5.0, 5.0, 5.0, 5.0, 5.0), +(6, 6.0, 6.0, 6.0, 6.0, 6.0), +(7, NULL, NULL, NULL, NULL, 7.0), +(8, NULL, NULL, NULL, NULL, 8.0); +``` + +* 预测任务一：使用历史协变量 cov1，cov2 和 cov3 辅助预测目标变量 target1 和 target2。 + + ![](/img/ainode-upgrade-table-forecast-timecho-1.png) + + * 使用表 tab\_real 中 cov1，cov2，cov3，target1，target2 的 前 6 行历史数据，预测目标变量 target1 和 target2 未来的 2 行数据 + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.338330268859863|7.338330268859863| + |1970-01-01T08:00:00.008+08:00| 8.02529525756836| 8.02529525756836| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.315s + ``` +* 预测任务二：使用相同表中的历史协变量 cov1，cov2 和已知协变量 cov3 辅助预测目标变量 target1 和 target2。 + + ![](/img/ainode-upgrade-table-forecast-timecho-2.png) + + * 使用表 tab\_real 中 cov1，cov2，cov3，target1，target2 的 前 6 行历史数据，以及同表中已知协变量 cov3 在未来的 2 行数据来预测目标变量 target1 和 target2 未来的 2 行数据 + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + FUTURE_COVS => ' + SELECT TIME, cov3 + FROM etth.tab_real + WHERE TIME >= 7 + LIMIT 2', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.244050025939941|7.244050025939941| + |1970-01-01T08:00:00.008+08:00|7.907227516174316|7.907227516174316| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.291s + ``` +* 预测任务三：使用不同表中的历史协变量 cov1，cov2 和已知协变量 cov3 辅助预测目标变量 target1 和 target2。 + + ![](/img/ainode-upgrade-table-forecast-timecho-3.png) + + * 提前创建表 tab\_cov\_forecast（存储已知协变量 cov3 的预测值 ），并准备相关数据。 + ```SQL + create table tab_cov_forecast (cov3 DOUBLE FIELD); + + --写入语句 + INSERT INTO tab_cov_forecast (time, cov3) VALUES (7, 7.0),(8, 8.0); + + IoTDB:etth> SELECT * FROM tab_cov_forecast + +----+----+ + |time|cov3| + +----+----+ + | 7| 7.0| + | 8| 8.0| + +----+----+ + ``` + * 使用表 tab\_real 中 cov1，cov2，cov3，target1，target2 已知的前 6 行数据，以及表 tab\_cov\_forecast 中已知协变量 cov3 在未来的 2 行数据来预测目标变量 target1 和 target2 未来的 2 行数据 + ```SQL + IoTDB:etth> SELECT * FROM FORECAST ( + MODEL_ID => 'chronos2', + TARGETS => ( + SELECT TIME, target1, target2 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6) ORDER BY TIME, + HISTORY_COVS => ' + SELECT TIME, cov1, cov2, cov3 + FROM etth.tab_real + WHERE TIME < 7 + ORDER BY TIME DESC + LIMIT 6', + FUTURE_COVS => ' + SELECT TIME, cov3 + FROM etth.tab_cov_forecast + WHERE TIME >= 7 + LIMIT 2', + OUTPUT_LENGTH => 2 + ) + +-----------------------------+-----------------+-----------------+ + | time| target1| target2| + +-----------------------------+-----------------+-----------------+ + |1970-01-01T08:00:00.007+08:00|7.244050025939941|7.244050025939941| + |1970-01-01T08:00:00.008+08:00|7.907227516174316|7.907227516174316| + +-----------------------------+-----------------+-----------------+ + Total line number = 2 + It costs 0.351s + ``` + + +### 4.2 模型微调 + +AINode 支持通过 SQL 进行模型微调任务。 + +**SQL 语法** + +```SQL +createModelStatement + | CREATE MODEL modelId=identifier (WITH HYPERPARAMETERS '(' hparamPair (',' hparamPair)* ')')? FROM MODEL existingModelId=identifier ON DATASET '(' targetData=string ')' + ; +hparamPair + : hparamKey=identifier '=' hyparamValue=primaryExpression + ; +``` + +**参数说明** + +| 名称 | 描述 | +| ----------------- |----------------------------------------------------------------------------------------------------------------------------------------| +| modelId | 微调出的模型的唯一标识 | +| hparamPair | 微调使用的超参数 key-value 对，目前支持如下：
`train_epochs`: int 类型，微调轮数
`iter_per_epoch`: int 类型，每轮微调的迭代次数
`learning_rate`: double 类型，学习率 | +| existingModelId | 微调使用的基座模型 | +| targetData | 用于获取微调使用的数据集的 SQL | + +**示例** + +1. 选择测点 ot 中指定时间范围的数据作为微调数据集，基于 sundial 创建模型 sundialv3。 + +```SQL +IoTDB> set sql_dialect=table +Msg: The statement is executed successfully. +IoTDB> CREATE MODEL sundialv3 FROM MODEL sundial ON DATASET ('SELECT time, ot from etth.eg where 1467302400000 <= time and time < 1517468400001') +Msg: The statement is executed successfully. +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| +| sundialv2| sundial| fine_tuned| active| +| sundialv3| sundial| fine_tuned| training| ++---------------------+---------+-----------+---------+ +``` + +2. 微调任务后台异步启动，可在 AINode 进程看到 log；微调完成后，查询并使用新的模型 + +```SQL +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| +| sundialv2| sundial| fine_tuned| active| +| sundialv3| sundial| fine_tuned| active| ++---------------------+---------+-----------+---------+ +``` + +### 4.3 注册自定义模型 + +**符合以下要求的 Transformers 模型可以注册到 AINode 中：** + +1. AINode 目前使用 v4.56.2 版本的 transformers，构建模型时需**避免继承低版本（<4.50）接口**； +2. 模型需继承一类 AINode 的推理任务流水线（当前支持预测流水线）： + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + 在推理任务开始前对输入数据进行前处理，包括形状验证和数值转换。 + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + 在推理任务结束后对输出结果进行后处理。 + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + 在将输入数据传递给模型进行推理之前进行预处理，验证输入数据的形状和类型。 + + Args: + inputs (list[dict]): + 输入数据，字典列表，每个字典包含： + - 'targets': 形状为 (input_length,) 或 (target_count, input_length) 的张量。 + - 'past_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + - 'future_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + + infer_kwargs (dict, optional): 推理的额外关键字参数，如： + - `output_length`(int): 如果提供'future_covariates'，用于验证其有效性。 + + Raises: + ValueError: 如果输入格式不正确（例如，缺少键、张量形状无效）。 + + Returns: + 经过预处理和验证的输入数据，可直接用于模型推理。 + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + 对给定输入执行预测。 + + Parameters: + inputs: 用于进行预测的输入数据。类型和结构取决于模型的具体实现。 + **infer_kwargs: 额外的推理参数，例如： + - `output_length`(int): 模型应该生成的时间点数量。 + + Returns: + 预测输出，具体形式取决于模型的具体实现。 + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + 在推理后对模型输出进行后处理，验证输出数据的形状并确保其符合预期维度。 + + Args: + outputs: + 模型输出，2D张量列表，每个张量形状为 `[target_count, output_length]`。 + + Raises: + InferenceModelInternalException: 如果输出张量形状无效（例如，维数错误）。 + ValueError: 如果输出格式不正确。 + + Returns: + list[torch.Tensor]: + 后处理后的输出，将是一个2D张量列表。 + """ + pass + ``` +3. 修改模型配置文件 config.json，确保包含以下字段： + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // 指定模型 Config 类 + "AutoModelForCausalLM": "model.Chronos2Model" // 指定模型类 + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // 指定模型的推理流水线 + "model_type": "custom_t5", // 指定模型类型 + } + ``` + + 1. 必须通过 auto\_map 指定模型的 Config 类和模型类； + 2. 必须集成并指定推理流水线类； + 3. 对于 AINode 管理的内置（builtin）和自定义（user\_defined）模型，模型类别（model\_type）也作为不可重复的唯一标识。即，要注册的模型类别不得与任何已存在的模型类型重复，通过微调创建的模型将继承原模型的模型类别。 +4. 确保要注册的模型目录包含以下文件，且模型配置文件名称和权重文件名称不支持自定义： + 1. 模型配置文件：config.json； + 2. 模型权重文件：model.safetensors； + 3. 模型代码：其它 .py 文件。 + +**注册自定义模型的 SQL 语法如下所示：** + +```SQL +CREATE MODEL USING URI +``` + +**参数说明：** + +* **model\_id**：自定义模型的唯一标识；不可重复，有以下约束： + * 允许出现标识符 [ 0-9 a-z A-Z \_ ] （字母，数字（非开头），下划线（非开头）） + * 长度限制为 2-64 字符 + * 大小写敏感 +* **uri**：包含模型代码和权重的本地 uri 地址。 + +**注册示例：** + +从本地路径上传自定义 Transformers 模型，AINode 会将该文件夹拷贝至 user\_defined 目录中。 + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +SQL执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见查看模型章节）。模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。 + +### 4.4 查看模型 + +注册成功的模型可以通过查看指令查询模型的具体信息。 + +```SQL +SHOW MODELS +``` + +除了直接展示所有模型的信息外，可以指定`model_id`来查看某一具体模型的信息。 + +```SQL +SHOW MODELS -- 只展示特定模型 +``` + +模型展示的结果中包含如下内容： + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| 模型ID | 模型类型 | 模型种类 | 模型状态 | + +其中，State 模型状态机流转示意图如下: + +![](/img/ainode-upgrade-state-timecho.png) + +状态机流程说明： + +1. 启动 AINode 后，执行 `show models` 命令，仅能查看到**系统内置（BUILTIN）**的模型。 +2. 用户可导入自己的模型，这类模型的来源标识为**用户自定义（USER\_****DEFINED）**；AINode 会尝试从模型配置文件中解析模型类型（ModelType），若解析失败，该字段则显示为空。 +3. 时序大模型（内置模型）权重文件不随 AINode 打包，AINode 启动时自动下载。 + 1. 下载过程中为 ACTIVATING，下载成功转变为 ACTIVE，失败则变成 INACTIVE。 +4. 用户启动模型微调任务后，正在训练的模型状态为 TRAINING，训练成功变为 ACTIVE，失败则是 FAILED。 +5. 若微调任务成功，微调结束后会统计所有 ckpt （训练文件）中指标最佳的文件并自动重命名，变成用户指定的 model\_id。 + +**查看示例** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| sundialx_1| sundial| fine_tuned| active| +| sundialx_4| sundial| fine_tuned| training| +| sundialx_5| sundial| fine_tuned| failed| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +内置传统时序模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|----------------------------------| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **ARIMA**(自回归整合移动平均模型) | 结合自回归(AR)、差分(I)和移动平均(MA)，用于预测平稳时间序列或可通过差分变为平稳的数据。 | 单变量时间序列预测，如股票价格、销量、经济指标等。| 1. 适用于线性趋势和季节性较弱的数据。2. 需要选择参数 (p,d,q)。3. 对缺失值敏感。 | +| **Holt-Winters**(三参数指数平滑) | 基于指数平滑，引入水平、趋势和季节性三个分量，适用于具有趋势和季节性的数据。 | 有明显季节性和趋势的时间序列，如月度销售额、电力需求等。 | 1. 可处理加性或乘性季节性。2. 对近期数据赋予更高权重。3. 简单易实现。 | +| **Exponential Smoothing**(指数平滑) | 通过加权平均历史数据，权重随时间指数递减，强调近期观测值的重要性。 | 无显著季节性但存在趋势的数据，如短期需求预测。 | 1. 参数少，计算简单。2. 适合平稳或缓慢变化序列。3. 可扩展为双指数或三指数平滑。 | +| **Naive Forecaster**(朴素预测器) | 使用最近一期的观测值作为下一期的预测值，是最简单的基准模型。 | 作为其他模型的比较基准，或数据无明显模式时的简单预测。 | 1. 无需训练。2. 对突发变化敏感。3. 季节性朴素变体可用前一季节同期值预测。 | +| **STL Forecaster**(季节趋势分解预测) | 基于STL分解时间序列，分别预测趋势、季节性和残差分量后组合。 | 具有复杂季节性、趋势和非线性模式的数据，如气候数据、交通流量。 | 1. 能处理非固定季节性。2. 对异常值稳健。3. 分解后可结合其他模型预测各分量。 | +| **Gaussian HMM**(高斯隐马尔可夫模型) | 假设观测数据由隐藏状态生成，每个状态的观测概率服从高斯分布。 | 状态序列预测或分类，如语音识别、金融状态识别。 | 1. 适用于时序数据的状态建模。2. 假设观测值在给定状态下独立。3. 需指定隐藏状态数量。 | +| **GMM HMM** (高斯混合隐马尔可夫模型) | 扩展Gaussian HMM，每个状态的观测概率由高斯混合模型描述，可捕捉更复杂的观测分布。 | 需要多模态观测分布的场景，如复杂动作识别、生物信号分析。 | 1. 比单一高斯更灵活。2. 参数更多，计算复杂度高。3. 需训练GMM成分数。 | +| **STRAY**(基于奇异值的异常检测) | 通过奇异值分解(SVD)检测高维数据中的异常点，常用于时间序列异常检测。 | 高维时间序列的异常检测，如传感器网络、IT系统监控。 | 1. 无需分布假设。2. 可处理高维数据。3. 对全局异常敏感，局部异常可能漏检。 | + +内置时序大模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | 支持超长上下文的时序大模型，通过大规模工业数据预训练增强泛化能力。 | 需利用极长历史数据的复杂工业预测，如能源、航空航天、交通等领域。 | 1. 超长上下文支持，可处理数万时间点输入。2. 多场景覆盖，支持非平稳、多变量及协变量预测。3. 基于万亿级高质量工业时序数据预训练。 | +| **Timer-Sundial** | 采用“Transformer + TimeFlow”架构的生成式基础模型，专注于概率预测。 | 需要量化不确定性的零样本预测场景，如金融、供应链、新能源发电预测。 | 1. 强大的零样本泛化能力，支持点预测与概率预测 2. 可灵活分析预测分布的任意统计特性。3. 创新生成架构，实现高效的非确定性样本生成。 | +| **Chronos-2** | 基于离散词元化范式的通用时序基础模型，将预测转化为语言建模任务。 | 快速零样本单变量预测，以及可借助协变量（如促销、天气）提升效果的场景。 | 1. 强大的零样本概率预测能力。2. 支持协变量统一建模，但对输入有严格要求：a. 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集；b. 每个历史协变量的长度必须等于目标变量的长度； c. 每个未来协变量的长度必须等于预测长度；3. 采用高效的编码器式结构，兼顾性能与推理速度。 | + + +### 4.5 删除模型 + +对于注册成功的模型，用户可以通过 SQL 进行删除，AINode 会将 user\_defined 目录下的对应模型文件夹整个删除。其 SQL 语法如下： + +```SQL +DROP MODEL +``` + +需要指定已经成功注册的模型 model\_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。 + +### 4.6 加载/卸载模型 + +为适应不同场景，AINode 提供以下两种模型加载策略： + +* 即时加载：即推理时临时加载模型，结束后释放资源。适用于测试或低负载场景。 +* 常驻加载：即将模型持久化加载在内存（CPU）或显存（GPU）中，以支持高并发推理。用户只需通过 SQL 指定加载或卸载的模型，AINode 会自动管理实例数量。当前常驻模型的状态也可随时查看。 + +下文将详细介绍加载/卸载模型的相关内容： + +1. 配置参数 + +支持通过编辑如下配置项设置常驻加载相关参数。 + +```Properties +# AINode 在推理时可使用的设备内存/显存占总量的比例 +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# AINode 每个加载的模型实例需要占用的内存比例，即模型占用*该值 +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. 展示可用的 device + +支持通过如下 SQL 命令查看所有可用的设备 ID + +```SQL +SHOW AI_DEVICES +``` + +示例 + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. 加载模型 + +支持通过如下 SQL 命令手动加载模型，系统根据硬件资源使用情况**自动均衡**模型实例数量。 + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 加载到 AINode 所在服务器的内存中。 + * **gpu\_id:** 加载到 AINode 所在服务器的对应显卡中，如 "0, 1" 表示加载到编号为 0 和 1 的两张显卡中。 + +示例 + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. 卸载模型 + +支持通过如下 SQL 命令手动卸载指定模型的所有实例，系统会**重分配**空闲出的资源给其他模型 + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 尝试从 AINode 所在服务器的内存中卸载指定模型。 + * **gpu\_id:** 尝试从 AINode 所在服务器的对应显卡中卸载指定模型，如 "0, 1" 表示尝试从编号为 0 和 1 的两张显卡卸载指定模型。 + +示例 + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. 展示加载的模型 + +支持通过如下 SQL 命令查看已经手动加载的模型实例，可通过 `device_id `指定设备。 + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # 展示指定设备中的模型实例 +``` + +示例：在内存、gpu\_0 和 gpu\_1 两张显卡加载了sundial 模型 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +说明： + +* DeviceId : 设备 ID +* ModelId ：加载的模型 ID +* Count(instances) ：每个设备中的模型实例数量（系统自动分配） + +### 4.7 时序大模型介绍 + +AINode 目前支持多种时序大模型，相关介绍及部署使用可参考[时序大模型](../AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md) + +## 5. 权限管理 + +使用 AINode 相关的功能时，可以使用IoTDB本身的鉴权去做一个权限管理，用户只有在具备 USE\_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。 + +| **权限名称** | **权限范围** | **管理员用户（默认ROOT）** | **普通用户** | +| ------------------------- | ----------------------------------------- | ---------------------------------- | -------------------- | +| USE\_MODEL | create model / show models / drop model | √ | √ | +| READ\_SCHEMA&READ\_DATA | forecast | √ | √ | diff --git a/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade.md b/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade.md new file mode 100644 index 000000000..440615354 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: TimeSeries-Large-Model_Upgrade_apache.html +--- + diff --git a/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md b/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md new file mode 100644 index 000000000..e1af1e1d0 --- /dev/null +++ b/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md @@ -0,0 +1,157 @@ + +# 时序大模型 + +## 1. 简介 + +时序大模型是专为时序数据分析设计的基础模型。IoTDB 团队长期自研时序基础模型 Timer，该模型基于 Transformer 架构，经海量多领域时序数据预训练，可支撑时序预测、异常检测、时序填补等下游任务；团队打造的 AINode 平台同时支持集成业界前沿时序基础模型，为用户提供多元选型。不同于传统时序分析技术，这类大模型具备通用特征提取能力，可通过零样本分析、微调等技术服务广泛的分析任务。 + +本文相关时序大模型领域的技术成果（含团队自研及业界前沿方向）均发表于国际机器学习顶级会议，具体内容见附录。 + +## 2. 应用场景 + +* **时序预测**：为工业生产、自然环境等领域提供时间序列数据的预测服务，帮助用户提前了解未来变化趋势。 +* **数据填补**：针对时间序列中的缺失序列段，进行上下文填补，以增强数据集的连续性和完整性。 +* **异常检测**：利用自回归分析技术，对时间序列数据进行实时监测，及时预警潜在的异常情况。 + +![](/img/LargeModel09.png) + +## 3. Timer-1 模型 + +Timer[1] 模型（非内置模型）不仅展现了出色的少样本泛化和多任务适配能力，还通过预训练获得了丰富的知识库，赋予了它处理多样化下游任务的通用能力，拥有以下特点： + +* **泛化性**：模型能够通过使用少量样本进行微调，达到行业内领先的深度模型预测效果。 +* **通用性**：模型设计灵活，能够适配多种不同的任务需求，并且支持变化的输入和输出长度，使其在各种应用场景中都能发挥作用。 +* **可扩展性**：随着模型参数数量的增加或预训练数据规模的扩大，模型效果会持续提升，确保模型能够随着时间和数据量的增长而不断优化其预测效果。 + +![](/img/model01.png) + +## 4. Timer-XL 模型 + +Timer-XL[2]基于 Timer 进一步扩展升级了网络结构，在多个维度全面突破： + +* **超长上下文支持**：该模型突破了传统时序预测模型的限制，支持处理数千个 Token（相当于数万个时间点）的输入，有效解决了上下文长度瓶颈问题。 +* **多变量预测场景覆盖**：支持多种预测场景，包括非平稳时间序列的预测、涉及多个变量的预测任务以及包含协变量的预测，满足多样化的业务需求。 +* **大规模工业时序数据集：**采用万亿大规模工业物联网领域的时序数据集进行预训练，数据集兼有庞大的体量、卓越的质量和丰富的领域等重要特质，覆盖能源、航空航天、钢铁、交通等多领域。 + +![](/img/model02.png) + +## 5. Timer-Sundial 模型 + +Timer-Sundial[3]是一个专注于时间序列预测的生成式基础模型系列，其基础版本拥有 1.28 亿参数，并在 1 万亿个时间点上进行了大规模预训练，其核心特性包括： + +* **强大的泛化性能：**具备零样本预测能力，可同时支持点预测和概率预测。 +* **灵活预测分布分析：**不仅能预测均值或分位数，还可通过模型生成的原始样本评估预测分布的任意统计特性。 +* **创新生成架构：** 采用 “Transformer + TimeFlow” 协同架构——Transformer 学习时间片段的自回归表征，TimeFlow 模块基于流匹配框架 (Flow-Matching) 将随机噪声转化为多样化预测轨迹，实现高效的非确定性样本生成。 + +![](/img/model03.png) + +## 6. Chronos-2 模型 + +Chronos-2 [4]是由 Amazon Web Services (AWS) 研究团队开发的，基于 Chronos 离散词元建模范式发展起来的通用时间序列基础模型，该模型同时适用于零样本单变量预测和协变量预测。其主要特性包括： + +* **概率性预测能力**：模型以生成式方式输出多步预测结果，支持分位数或分布级预测，从而刻画未来不确定性。 +* **零样本通用预测**：依托预训练获得的上下文学习能力，可直接对未见过的数据集执行预测，无需重新训练或参数更新。 +* **多变量与协变量统一建模**：支持在同一架构下联合建模多条相关时间序列及其协变量，以提升复杂任务的预测效果。但对输入有严格要求： + * 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集； + * 每个历史协变量的长度必须等于目标变量的长度； + * 每个未来协变量的长度必须等于预测长度； +* **高效推理与部署**：模型采用紧凑的编码器式（encoder-only）结构，在保持强泛化能力的同时兼顾推理效率。 + +![](/img/timeseries-large-model-chronos2.png) + +## 7. 效果展示 + +时序大模型能够适应多种不同领域和场景的真实时序数据，在各种任务上拥有优异的处理效果，以下是在不同数据上的真实表现： + +**时序预测：** + +利用时序大模型的预测能力，能够准确预测时间序列的未来变化趋势，如下图蓝色曲线代表预测趋势，红色曲线为实际趋势，两曲线高度吻合。 + +![](/img/LargeModel03.png) + +**数据填补**： + +利用时序大模型对缺失数据段进行预测式填补。 + +![](/img/timeseries-large-model-data-imputation.png) + +**异常检测**： + +利用时序大模型精准识别与正常趋势偏离过大的异常值。 + +![](/img/LargeModel05.png) + +## 8. 部署使用 + +1. 打开 IoTDB cli 控制台，检查 ConfigNode、DataNode、AINode 节点确保均为 Running。 + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. 联网环境下首次启动 AINode 节点会自动拉取 Timer-XL、Sundial、Chronos2 模型。 + + > 注意： + > + > * AINode 安装包不包含模型权重文件 + > * 自动拉取功能依赖部署环境具备 HuggingFace 网络访问能力 + > * AINode 支持手动上传模型权重文件，具体操作方法可参考[导入权重文件](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md#_3-3-导入内置权重文件) + +3. 检查模型是否可用。 + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### 附录 + +**[1]** Timer- Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref1) + +**[2]** TIMER-XL- LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING ,Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref2) + +**[3]** Sundial- A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ 返回](#ref3) + +**[4] **Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821.**[↩ 返回](#ref4) diff --git a/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md b/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md new file mode 100644 index 000000000..3d86bfc4f --- /dev/null +++ b/src/zh/UserGuide/latest-Table/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md @@ -0,0 +1,157 @@ + +# 时序大模型 + +## 1. 简介 + +时序大模型是专为时序数据分析设计的基础模型。IoTDB 团队长期自研时序基础模型 Timer，该模型基于 Transformer 架构，经海量多领域时序数据预训练，可支撑时序预测、异常检测、时序填补等下游任务；团队打造的 AINode 平台同时支持集成业界前沿时序基础模型，为用户提供多元选型。不同于传统时序分析技术，这类大模型具备通用特征提取能力，可通过零样本分析、微调等技术服务广泛的分析任务。 + +本文相关时序大模型领域的技术成果（含团队自研及业界前沿方向）均发表于国际机器学习顶级会议，具体内容见附录。 + +## 2. 应用场景 + +* **时序预测**：为工业生产、自然环境等领域提供时间序列数据的预测服务，帮助用户提前了解未来变化趋势。 +* **数据填补**：针对时间序列中的缺失序列段，进行上下文填补，以增强数据集的连续性和完整性。 +* **异常检测**：利用自回归分析技术，对时间序列数据进行实时监测，及时预警潜在的异常情况。 + +![](/img/LargeModel09.png) + +## 3. Timer-1 模型 + +Timer[1] 模型（非内置模型）不仅展现了出色的少样本泛化和多任务适配能力，还通过预训练获得了丰富的知识库，赋予了它处理多样化下游任务的通用能力，拥有以下特点： + +* **泛化性**：模型能够通过使用少量样本进行微调，达到行业内领先的深度模型预测效果。 +* **通用性**：模型设计灵活，能够适配多种不同的任务需求，并且支持变化的输入和输出长度，使其在各种应用场景中都能发挥作用。 +* **可扩展性**：随着模型参数数量的增加或预训练数据规模的扩大，模型效果会持续提升，确保模型能够随着时间和数据量的增长而不断优化其预测效果。 + +![](/img/model01.png) + +## 4. Timer-XL 模型 + +Timer-XL[2]基于 Timer 进一步扩展升级了网络结构，在多个维度全面突破： + +* **超长上下文支持**：该模型突破了传统时序预测模型的限制，支持处理数千个 Token（相当于数万个时间点）的输入，有效解决了上下文长度瓶颈问题。 +* **多变量预测场景覆盖**：支持多种预测场景，包括非平稳时间序列的预测、涉及多个变量的预测任务以及包含协变量的预测，满足多样化的业务需求。 +* **大规模工业时序数据集：**采用万亿大规模工业物联网领域的时序数据集进行预训练，数据集兼有庞大的体量、卓越的质量和丰富的领域等重要特质，覆盖能源、航空航天、钢铁、交通等多领域。 + +![](/img/model02.png) + +## 5. Timer-Sundial 模型 + +Timer-Sundial[3]是一个专注于时间序列预测的生成式基础模型系列，其基础版本拥有 1.28 亿参数，并在 1 万亿个时间点上进行了大规模预训练，其核心特性包括： + +* **强大的泛化性能：**具备零样本预测能力，可同时支持点预测和概率预测。 +* **灵活预测分布分析：**不仅能预测均值或分位数，还可通过模型生成的原始样本评估预测分布的任意统计特性。 +* **创新生成架构：** 采用 “Transformer + TimeFlow” 协同架构——Transformer 学习时间片段的自回归表征，TimeFlow 模块基于流匹配框架 (Flow-Matching) 将随机噪声转化为多样化预测轨迹，实现高效的非确定性样本生成。 + +![](/img/model03.png) + +## 6. Chronos-2 模型 + +Chronos-2 [4]是由 Amazon Web Services (AWS) 研究团队开发的，基于 Chronos 离散词元建模范式发展起来的通用时间序列基础模型，该模型同时适用于零样本单变量预测和协变量预测。其主要特性包括： + +* **概率性预测能力**：模型以生成式方式输出多步预测结果，支持分位数或分布级预测，从而刻画未来不确定性。 +* **零样本通用预测**：依托预训练获得的上下文学习能力，可直接对未见过的数据集执行预测，无需重新训练或参数更新。 +* **多变量与协变量统一建模**：支持在同一架构下联合建模多条相关时间序列及其协变量，以提升复杂任务的预测效果。但对输入有严格要求： + * 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集； + * 每个历史协变量的长度必须等于目标变量的长度； + * 每个未来协变量的长度必须等于预测长度； +* **高效推理与部署**：模型采用紧凑的编码器式（encoder-only）结构，在保持强泛化能力的同时兼顾推理效率。 + +![](/img/timeseries-large-model-chronos2.png) + +## 7. 效果展示 + +时序大模型能够适应多种不同领域和场景的真实时序数据，在各种任务上拥有优异的处理效果，以下是在不同数据上的真实表现： + +**时序预测：** + +利用时序大模型的预测能力，能够准确预测时间序列的未来变化趋势，如下图蓝色曲线代表预测趋势，红色曲线为实际趋势，两曲线高度吻合。 + +![](/img/LargeModel03.png) + +**数据填补**： + +利用时序大模型对缺失数据段进行预测式填补。 + +![](/img/timeseries-large-model-data-imputation.png) + +**异常检测**： + +利用时序大模型精准识别与正常趋势偏离过大的异常值。 + +![](/img/LargeModel05.png) + +## 8. 部署使用 + +1. 打开 IoTDB cli 控制台，检查 ConfigNode、DataNode、AINode 节点确保均为 Running。 + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. 联网环境下首次启动 AINode 节点会自动拉取 Timer-XL、Sundial、Chronos2 模型。 + + > 注意： + > + > * AINode 安装包不包含模型权重文件 + > * 自动拉取功能依赖部署环境具备 HuggingFace 网络访问能力 + > * AINode 支持手动上传模型权重文件，具体操作方法可参考[导入权重文件](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md#_3-3-导入内置权重文件) + +3. 检查模型是否可用。 + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### 附录 + +**[1]** Timer- Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref1) + +**[2]** TIMER-XL- LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING ,Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref2) + +**[3]** Sundial- A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ 返回](#ref3) + +**[4] **Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821.**[↩ 返回](#ref4) diff --git a/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade.md b/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade.md new file mode 100644 index 000000000..6f44068b6 --- /dev/null +++ b/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: AINode_Upgrade_apache.html +--- + \ No newline at end of file diff --git a/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade_apache.md b/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade_apache.md new file mode 100644 index 000000000..8a9fdb274 --- /dev/null +++ b/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade_apache.md @@ -0,0 +1,575 @@ + + +# AINode + +AINode 是支持时序相关模型注册、管理、调用的 IoTDB 原生节点，内置业界领先的自研时序大模型，如清华自研时序模型 Timer 系列，可通过标准 SQL 语句进行调用，实现时序数据的毫秒级实时推理，可支持时序趋势预测、缺失值填补、异常值检测等应用场景。 + +系统架构如下图所示： + +![](/img/AINode-0.png) + +三种节点的职责如下： + +* **ConfigNode**：负责分布式节点管理和负载均衡。 +* **DataNode**：负责接收并解析用户的 SQL请求；负责存储时间序列数据；负责数据的预处理计算。 +* **AINode**：负责时序模型的管理和使用。 + +## 1. 优势特点 + +与单独构建机器学习服务相比，具有以下优势： + +* **简单易用**：无需使用 Python 或 Java 编程，使用 SQL 语句即可完成机器学习模型管理与推理的完整流程。如创建模型可使用CREATE MODEL语句、使用模型进行推理可使用` CALL INFERENCE(...)` 语句等，使用更加简单便捷。 +* **避免数据迁移**：使用 IoTDB 原生机器学习可以将存储在 IoTDB 中的数据直接应用于机器学习模型的推理，无需将数据移动到单独的机器学习服务平台，从而加速数据处理、提高安全性并降低成本。 + +![](/img/h1.png) + +* **内置先进算法**：支持业内领先机器学习分析算法，覆盖典型时序分析任务，为时序数据库赋能原生数据分析能力。如： + * **时间序列预测（Time Series Forecasting）**：从过去时间序列中学习变化模式；从而根据给定过去时间的观测值，输出未来序列最可能的预测。 + * **时序异常检测（Anomaly Detection for Time Series）**：在给定的时间序列数据中检测和识别异常值，帮助发现时间序列中的异常行为。 + +## 2. 基本概念 + +* **模型（Model）**：机器学习模型，以时序数据作为输入，输出分析任务的结果或决策。模型是 AINode 的基本管理单元，支持模型的增（注册）、删、查、用（推理）。 +* **创建（Create）**: 将外部设计或训练好的模型文件或算法加载到 AINode 中，由 IoTDB 统一管理与使用。 +* **推理（Inference）**：使用创建的模型在指定时序数据上完成该模型适用的时序分析任务。 +* **内置能力（Built-in）**：AINode 自带常见时序分析场景（例如预测与异常检测）的机器学习算法或自研模型。 + +![](/img/h3.png) + +## 3. 安装部署 + +AINode 的部署可参考文档 [AINode 部署](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md) 。 + +## 4. 使用指导 + +AINode 支持模型推理和模型管理（注册、查看、删除、加载、卸载等）两大功能，下面章节将进行详细说明。 + +### 4.1 模型推理 + +SQL语法如下： + +```SQL +call inference(,inputSql,(=)*) +``` + +在完成模型的注册后（内置模型推理无需注册流程），通过call关键字，调用inference函数就可以使用模型的推理功能，其对应的参数介绍如下： + +* **model\_id**: 对应一个已经注册的模型 +* **sql**：sql查询语句，查询的结果作为模型的输入进行模型推理。查询的结果中行列的维度需要与具体模型config中指定的大小相匹配。(这里的sql不建议使用`SELECT *`子句，因为在IoTDB中，`*`并不会对列进行排序，因此列的顺序是未定义的，可以使用`SELECT s0,s1`的方式确保列的顺序符合模型输入的预期) +* **parameterName/parameterValue**：参数名/参数值，目前支持： + + | 参数名称 | 参数类型 | 参数描述 | 默认值 | + | ------------------------ | ---------- | -------------------------- | -------- | + | **generateTime** | boolean | 返回结果是否包含时间戳列 | false | + | **outputLength** | int | 指定返回结果的输出长度 | 96 | + + +说明： + +1. 使用内置时序大模型进行推理的前提条件是本地存有对应模型权重，目录为 `/IOTDB_AINODE_HOME/data/ainode/models/builtin/model_id/`。若本地没有模型权重，则会自动从 HuggingFace 拉取，请保证本地能直接访问 HuggingFace。 +2. 在深度学习应用中，经常将时间戳衍生特征（数据中的时间列）作为生成式任务的协变量，一同输入到模型中以提升模型的效果，但是在模型的输出结果中一般不包含时间列。为了保证实现的通用性，模型推理结果只对应模型的真实输出，如果模型不输出时间列，则结果中不会包含。 + +**示例** + +样本数据 [ETTh-tree](/img/ETTh-tree.csv) + +下面是使用 sundial 模型推理的一个操作示例，输入 96 行， 输出 48 行，我们通过SQL使用其进行推理。 + +```SQL +IoTDB> select OT from root.db.** ++-----------------------------+---------------+ +| Time|root.db.etth.OT| ++-----------------------------+---------------+ +|2016-07-01T00:00:00.000+08:00| 30.531| +|2016-07-01T01:00:00.000+08:00| 27.787| +|2016-07-01T02:00:00.000+08:00| 27.787| +|2016-07-01T03:00:00.000+08:00| 25.044| +|2016-07-01T04:00:00.000+08:00| 21.948| +| ...... | ...... | +|2016-07-04T19:00:00.000+08:00| 29.546| +|2016-07-04T20:00:00.000+08:00| 29.475| +|2016-07-04T21:00:00.000+08:00| 29.264| +|2016-07-04T22:00:00.000+08:00| 30.953| +|2016-07-04T23:00:00.000+08:00| 31.726| ++-----------------------------+---------------+ +Total line number = 96 + +IoTDB> call inference(sundial,"select OT from root.db.**", generateTime=True, outputLength=48) ++-----------------------------+------------------+ +| Time| output| ++-----------------------------+------------------+ +|2016-07-04T23:00:00.000+08:00|30.537494659423828| +|2016-07-04T23:59:22.500+08:00|29.619892120361328| +|2016-07-05T00:58:45.000+08:00|28.815832138061523| +|2016-07-05T01:58:07.500+08:00| 27.91131019592285| +|2016-07-05T02:57:30.000+08:00|26.893848419189453| +| ...... | ...... | +|2016-07-06T17:33:07.500+08:00| 24.40607261657715| +|2016-07-06T18:32:30.000+08:00| 25.00441551208496| +|2016-07-06T19:31:52.500+08:00|24.907312393188477| +|2016-07-06T20:31:15.000+08:00|25.156436920166016| +|2016-07-06T21:30:37.500+08:00|25.335433959960938| ++-----------------------------+------------------+ +Total line number = 48 +``` + +### 4.2 注册自定义模型 + +**符合以下要求的 Transformers 模型可以注册到 AINode 中：** + +1. AINode 目前使用 v4.56.2 版本的 transformers，构建模型时需**避免继承低版本（<4.50）接口**； +2. 模型需继承一类 AINode 的推理任务流水线（当前支持预测流水线）： + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + 在推理任务开始前对输入数据进行前处理，包括形状验证和数值转换。 + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + 在推理任务结束后对输出结果进行后处理。 + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + 在将输入数据传递给模型进行推理之前进行预处理，验证输入数据的形状和类型。 + + Args: + inputs (list[dict]): + 输入数据，字典列表，每个字典包含： + - 'targets': 形状为 (input_length,) 或 (target_count, input_length) 的张量。 + - 'past_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + - 'future_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + + infer_kwargs (dict, optional): 推理的额外关键字参数，如： + - `output_length`(int): 如果提供'future_covariates'，用于验证其有效性。 + + Raises: + ValueError: 如果输入格式不正确（例如，缺少键、张量形状无效）。 + + Returns: + 经过预处理和验证的输入数据，可直接用于模型推理。 + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + 对给定输入执行预测。 + + Parameters: + inputs: 用于进行预测的输入数据。类型和结构取决于模型的具体实现。 + **infer_kwargs: 额外的推理参数，例如： + - `output_length`(int): 模型应该生成的时间点数量。 + + Returns: + 预测输出，具体形式取决于模型的具体实现。 + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + 在推理后对模型输出进行后处理，验证输出数据的形状并确保其符合预期维度。 + + Args: + outputs: + 模型输出，2D张量列表，每个张量形状为 `[target_count, output_length]`。 + + Raises: + InferenceModelInternalException: 如果输出张量形状无效（例如，维数错误）。 + ValueError: 如果输出格式不正确。 + + Returns: + list[torch.Tensor]: + 后处理后的输出，将是一个2D张量列表。 + """ + pass + ``` +3. 修改模型配置文件 config.json，确保包含以下字段： + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // 指定模型 Config 类 + "AutoModelForCausalLM": "model.Chronos2Model" // 指定模型类 + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // 指定模型的推理流水线 + "model_type": "custom_t5", // 指定模型类型 + } + ``` + + 1. 必须通过 auto\_map 指定模型的 Config 类和模型类； + 2. 必须集成并指定推理流水线类； + 3. 对于 AINode 管理的内置（builtin）和自定义（user\_defined）模型，模型类别（model\_type）也作为不可重复的唯一标识。即，要注册的模型类别不得与任何已存在的模型类型重复。 +4. 确保要注册的模型目录包含以下文件，且模型配置文件名称和权重文件名称不支持自定义： + 1. 模型配置文件：config.json； + 2. 模型权重文件：model.safetensors； + 3. 模型代码：其它 .py 文件。 + +**注册自定义模型的 SQL 语法如下所示：** + +```SQL +CREATE MODEL USING URI +``` + +**参数说明：** + +* **model\_id**：自定义模型的唯一标识；不可重复，有以下约束： + * 允许出现标识符 [ 0-9 a-z A-Z \_ ] （字母，数字（非开头），下划线（非开头）） + * 长度限制为 2-64 字符 + * 大小写敏感 +* **uri**：包含模型代码和权重的本地 uri 地址。 + +**注册示例：** + +从本地路径上传自定义 Transformers 模型，AINode 会将该文件夹拷贝至 user\_defined 目录中。 + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +SQL执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见查看模型章节）。模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。 + +### 4.3 查看模型 + +注册成功的模型可以通过查看指令查询模型的具体信息。 + +```SQL +SHOW MODELS +``` + +除了直接展示所有模型的信息外，可以指定`model_id`来查看某一具体模型的信息。 + +```SQL +SHOW MODELS -- 只展示特定模型 +``` + +模型展示的结果中包含如下内容： + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| 模型ID | 模型类型 | 模型种类 | 模型状态 | + +其中，State 模型状态机流转示意图如下: + +![](/img/ainode-upgrade-state-apache.png) + +状态机流程说明： + +1. 启动 AINode 后，执行 `show models` 命令，仅能查看到**系统内置（BUILTIN）**的模型。 +2. 用户可导入自己的模型，这类模型的来源标识为**用户自定义（USER\_DEFINED）**；AINode 会尝试从模型配置文件中解析模型类型（ModelType），若解析失败，该字段则显示为空。 +3. 时序大模型（内置模型）权重文件不随 AINode 打包，AINode 启动时自动下载。 + 1. 下载过程中为 ACTIVATING，下载成功转变为 ACTIVE，失败则变成 INACTIVE。 + +**查看示例** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +内置传统时序模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|----------------------------------| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **ARIMA**(自回归整合移动平均模型) | 结合自回归(AR)、差分(I)和移动平均(MA)，用于预测平稳时间序列或可通过差分变为平稳的数据。 | 单变量时间序列预测，如股票价格、销量、经济指标等。| 1. 适用于线性趋势和季节性较弱的数据。2. 需要选择参数 (p,d,q)。3. 对缺失值敏感。 | +| **Holt-Winters**(三参数指数平滑) | 基于指数平滑，引入水平、趋势和季节性三个分量，适用于具有趋势和季节性的数据。 | 有明显季节性和趋势的时间序列，如月度销售额、电力需求等。 | 1. 可处理加性或乘性季节性。2. 对近期数据赋予更高权重。3. 简单易实现。 | +| **Exponential Smoothing**(指数平滑) | 通过加权平均历史数据，权重随时间指数递减，强调近期观测值的重要性。 | 无显著季节性但存在趋势的数据，如短期需求预测。 | 1. 参数少，计算简单。2. 适合平稳或缓慢变化序列。3. 可扩展为双指数或三指数平滑。 | +| **Naive Forecaster**(朴素预测器) | 使用最近一期的观测值作为下一期的预测值，是最简单的基准模型。 | 作为其他模型的比较基准，或数据无明显模式时的简单预测。 | 1. 无需训练。2. 对突发变化敏感。3. 季节性朴素变体可用前一季节同期值预测。 | +| **STL Forecaster**(季节趋势分解预测) | 基于STL分解时间序列，分别预测趋势、季节性和残差分量后组合。 | 具有复杂季节性、趋势和非线性模式的数据，如气候数据、交通流量。 | 1. 能处理非固定季节性。2. 对异常值稳健。3. 分解后可结合其他模型预测各分量。 | +| **Gaussian HMM**(高斯隐马尔可夫模型) | 假设观测数据由隐藏状态生成，每个状态的观测概率服从高斯分布。 | 状态序列预测或分类，如语音识别、金融状态识别。 | 1. 适用于时序数据的状态建模。2. 假设观测值在给定状态下独立。3. 需指定隐藏状态数量。 | +| **GMM HMM** (高斯混合隐马尔可夫模型) | 扩展Gaussian HMM，每个状态的观测概率由高斯混合模型描述，可捕捉更复杂的观测分布。 | 需要多模态观测分布的场景，如复杂动作识别、生物信号分析。 | 1. 比单一高斯更灵活。2. 参数更多，计算复杂度高。3. 需训练GMM成分数。 | +| **STRAY**(基于奇异值的异常检测) | 通过奇异值分解(SVD)检测高维数据中的异常点，常用于时间序列异常检测。 | 高维时间序列的异常检测，如传感器网络、IT系统监控。 | 1. 无需分布假设。2. 可处理高维数据。3. 对全局异常敏感，局部异常可能漏检。 | + +内置时序大模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | 支持超长上下文的时序大模型，通过大规模工业数据预训练增强泛化能力。 | 需利用极长历史数据的复杂工业预测，如能源、航空航天、交通等领域。 | 1. 超长上下文支持，可处理数万时间点输入。2. 多场景覆盖，支持非平稳、多变量及协变量预测。3. 基于万亿级高质量工业时序数据预训练。 | +| **Timer-Sundial** | 采用“Transformer + TimeFlow”架构的生成式基础模型，专注于概率预测。 | 需要量化不确定性的零样本预测场景，如金融、供应链、新能源发电预测。 | 1. 强大的零样本泛化能力，支持点预测与概率预测 2. 可灵活分析预测分布的任意统计特性。3. 创新生成架构，实现高效的非确定性样本生成。 | +| **Chronos-2** | 基于离散词元化范式的通用时序基础模型，将预测转化为语言建模任务。 | 快速零样本单变量预测，以及可借助协变量（如促销、天气）提升效果的场景。 | 1. 强大的零样本概率预测能力。2. 支持协变量统一建模，但对输入有严格要求：a. 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集；b. 每个历史协变量的长度必须等于目标变量的长度； c. 每个未来协变量的长度必须等于预测长度；3. 采用高效的编码器式结构，兼顾性能与推理速度。 | + +### 4.4 删除模型 + +对于注册成功的模型，用户可以通过 SQL 进行删除，AINode 会将 user\_defined 目录下的对应模型文件夹整个删除。其 SQL 语法如下： + +```SQL +DROP MODEL +``` + +需要指定已经成功注册的模型 model\_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。 + +### 4.5 加载/卸载模型 + +为适应不同场景，AINode 提供以下两种模型加载策略： + +* 即时加载：即推理时临时加载模型，结束后释放资源。适用于测试或低负载场景。 +* 常驻加载：即将模型持久化加载在内存（CPU）或显存（GPU）中，以支持高并发推理。用户只需通过 SQL 指定加载或卸载的模型，AINode 会自动管理实例数量。当前常驻模型的状态也可随时查看。 + +下文将详细介绍加载/卸载模型的相关内容： + +1. 配置参数 + +支持通过编辑如下配置项设置常驻加载相关参数。 + +```Properties +# AINode 在推理时可使用的设备内存/显存占总量的比例 +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# AINode 每个加载的模型实例需要占用的内存比例，即模型占用*该值 +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. 展示可用的 device + +支持通过如下 SQL 命令查看所有可用的设备 ID + +```SQL +SHOW AI_DEVICES +``` + +示例 + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. 加载模型 + +支持通过如下 SQL 命令手动加载模型，系统根据硬件资源使用情况**自动均衡**模型实例数量。 + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 加载到 AINode 所在服务器的内存中。 + * **gpu\_id:** 加载到 AINode 所在服务器的对应显卡中，如 "0, 1" 表示加载到编号为 0 和 1 的两张显卡中。 + +示例 + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. 卸载模型 + +支持通过如下 SQL 命令手动卸载指定模型的所有实例，系统会**重分配**空闲出的资源给其他模型 + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 尝试从 AINode 所在服务器的内存中卸载指定模型。 + * **gpu\_id:** 尝试从 AINode 所在服务器的对应显卡中卸载指定模型，如 "0, 1" 表示尝试从编号为 0 和 1 的两张显卡卸载指定模型。 + +示例 + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. 展示加载的模型 + +支持通过如下 SQL 命令查看已经手动加载的模型实例，可通过 `device_id `指定设备。 + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # 展示指定设备中的模型实例 +``` + +示例：在内存、gpu\_0 和 gpu\_1 两张显卡加载了sundial 模型 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +说明： + +* DeviceId : 设备 ID +* ModelId ：加载的模型 ID +* Count(instances) ：每个设备中的模型实例数量（系统自动分配） + +### 4.6 时序大模型介绍 + +AINode 目前支持多种时序大模型，相关介绍及部署使用可参考[时序大模型](../AI-capability/TimeSeries-Large-Model_Upgrade_apache.md) + +## 5. 权限管理 + +使用 AINode 相关的功能时，可以使用IoTDB本身的鉴权去做一个权限管理，用户只有在具备 USE\_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。 + +| 权限名称 | 权限范围 | 管理员用户（默认ROOT） | 普通用户 | 路径相关 | +| ------------ | ----------------------------------------- | ------------------------ | ---------- | ---------- | +| USE\_MODEL | create model / show models / drop model | √ | √ | x | +| READ\_DATA | call inference | √ | √ | √ | + +## 6. 向 IoTDB-AINode 贡献开源时序大模型 + +支持在 AINode 新增自定义内置模型，具体操作步骤如下（以 chronos2 为例）： + +* **向 [dev@iotdb.apache.org](mailto:dev@iotdb.apache.org) 邮件列表发送邮件或在项目主仓库提交 issue，发起初步讨论** +* **向主分支提交 Pull Request** + +1. 检查模型所用的开源协议，并在 IoTDB 仓库进行对应声明。 +2. 在 iotdb-core/ainode/iotdb/ainode/core/model 创建新内置模型对应的包； + 1. 确保包含模型配置类； + 2. 确保包含执行推理任务的模型类； + 3. 确保包含继承 AINode 推理任务流水线的类； + + ```Bash + root@rootMacBook-Pro model % eza --tree --level=2 . + . + ├── chronos2 + │ ├── __init__.py + │ ├── base.py + │ ├── chronos_bolt.py + │ ├── config.py + │ ├── dataset.py + │ ├── layers.py + │ ├── model.py + │ ├── pipeline_chronos2.py # 继承 AINode 推理任务流水线 + │ └── utils.py + ├── sktime + ├── sundial + └── timer_xl + ``` +3. 在 iotdb-core/ainode/iotdb/ainode/core/model/model\_info.py 新增该模型的元信息； + ```Python + BUILTIN_HF_TRANSFORMERS_MODEL_MAP = { + "chronos2": ModelInfo( + model_id="chronos2", # 模型的唯一标识 + category=ModelCategory.BUILTIN, # 模型类别，选择 BUILTIN + state=ModelStates.INACTIVE, + model_type="t5", # 模型种类，不能和其它 builtin 模型相同 + pipeline_cls="pipeline_chronos2.Chronos2Pipeline", # 继承 AINode 的推理流水线 + repo_id="amazon/chronos-2", # 【可选】Huggingface 权重 + auto_map={ + "AutoConfig": "config.Chronos2CoreConfig", # 确保指向模型的配置类 + "AutoModelForCausalLM": "model.Chronos2Model", # 确保指向推理所用的模型类 + }, + ), + } + ``` +4. 在 integration-test/src/test/java/org/apache/iotdb/ainode/utils/AINodeTestUtils.java 添加对应模型。 + ```Java + public static final Map BUILTIN_LTSM_MAP = + Stream.of( + new AbstractMap.SimpleEntry<>( + "sundial", new FakeModelInfo("sundial", "sundial", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "timer_xl", new FakeModelInfo("timer_xl", "timer", "builtin", "active")), + new AbstractMap.SimpleEntry<>( + "chronos2", new FakeModelInfo("chronos2", "t5", "builtin", "active"))) + .collect(Collectors.toMap(Map.Entry::getKey, Map.Entry::getValue)); + ``` +5. 提交 pull request，确保通过流水线测试后才能合并。 + +* **打包部署** + +1. 编译 AINode，获取安装包； + ```Bash + # 同时构建 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 + ``` +2. 在运行时确保模型能获取权重。 + 1. 若模型权重可从 Huggingface 在线获取，确保已填写`repo_id`； + 2. 否则，可在 AINode 启动前/运行时手动将模型权重放在`data/ainode/models/builtin/`。 + + ```Bash + root@rootMacBook-Pro models % eza --tree --level=3 . + . + ├── __init__.py + ├── builtin + │ ├── __init__.py + │ ├── chronos2 + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ ├── sundial + │ │ ├── __init__.py + │ │ ├── config.json + │ │ └── model.safetensors + │ └── timer_xl + │ ├── __init__.py + │ ├── config.json + │ └── model.safetensors + └── user_defined + ``` + +* **完整示例** + +完整示例可参考 https://github.com/apache/iotdb/pull/16903 diff --git a/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade_timecho.md b/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade_timecho.md new file mode 100644 index 000000000..d637cb0f6 --- /dev/null +++ b/src/zh/UserGuide/latest/AI-capability/AINode_Upgrade_timecho.md @@ -0,0 +1,563 @@ + + +# AINode + +AINode 是支持时序相关模型注册、管理、调用的 IoTDB 原生节点，内置业界领先的自研时序大模型，如清华自研时序模型 Timer 系列，可通过标准 SQL 语句进行调用，实现时序数据的毫秒级实时推理，可支持时序趋势预测、缺失值填补、异常值检测等应用场景。 + +系统架构如下图所示： + +![](/img/AINode-0.png) + +三种节点的职责如下： + +* **ConfigNode**：负责分布式节点管理和负载均衡。 +* **DataNode**：负责接收并解析用户的 SQL请求；负责存储时间序列数据；负责数据的预处理计算。 +* **AINode**：负责时序模型的管理和使用。 + +## 1. 优势特点 + +与单独构建机器学习服务相比，具有以下优势： + +* **简单易用**：无需使用 Python 或 Java 编程，使用 SQL 语句即可完成机器学习模型管理与推理的完整流程。如创建模型可使用CREATE MODEL语句、使用模型进行推理可使用 CALL INFERENCE (...) 语句等，使用更加简单便捷。 +* **避免数据迁移**：使用 IoTDB 原生机器学习可以将存储在 IoTDB 中的数据直接应用于机器学习模型的推理，无需将数据移动到单独的机器学习服务平台，从而加速数据处理、提高安全性并降低成本。 + +![](/img/h1.png) + +* **内置先进算法**：支持业内领先机器学习分析算法，覆盖典型时序分析任务，为时序数据库赋能原生数据分析能力。如： + * **时间序列预测（Time Series Forecasting）**：从过去时间序列中学习变化模式；从而根据给定过去时间的观测值，输出未来序列最可能的预测。 + * **时序异常检测（Anomaly Detection for Time Series）**：在给定的时间序列数据中检测和识别异常值，帮助发现时间序列中的异常行为。 + +## 2. 基本概念 + +* **模型（Model）**：机器学习模型，以时序数据作为输入，输出分析任务的结果或决策。模型是 AINode 的基本管理单元，支持模型的增（注册）、删、查、改（微调）、用（推理）。 +* **创建（Create）**: 将外部设计或训练好的模型文件或算法加载到 AINode 中，由 IoTDB 统一管理与使用。 +* **推理（Inference）**：使用创建的模型在指定时序数据上完成该模型适用的时序分析任务。 +* **内置能力（Built-in）**：AINode 自带常见时序分析场景（例如预测与异常检测）的机器学习算法或自研模型。 + +![](/img/h3.png) + +## 3. 安装部署 + +AINode 的部署可参考文档 [AINode 部署](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md) 。 + +## 4. 使用指导 + +TimechoDB-AINode 支持模型推理、模型微调以及模型管理（注册、查看、删除、加载、卸载等）三大功能，下面章节将进行详细说明。 + +### 4.1 模型推理 + +SQL语法如下： + +```SQL +call inference(,inputSql,(=)*) +``` + +在完成模型的注册后（内置模型推理无需注册流程），通过call关键字，调用inference函数就可以使用模型的推理功能，其对应的参数介绍如下： + +* **model\_id**: 对应一个已经注册的模型 +* **sql**：sql查询语句，查询的结果作为模型的输入进行模型推理。查询的结果中行列的维度需要与具体模型config中指定的大小相匹配。(这里的sql不建议使用`SELECT *`子句，因为在IoTDB中，`*`并不会对列进行排序，因此列的顺序是未定义的，可以使用`SELECT ot` 的方式确保列的顺序符合模型输入的预期) +* **parameterName/parameterValue**：参数名/参数值，目前支持： + + | 参数名称 | 参数类型 | 参数描述 | 默认值 | + | ------------------------ | ---------- | -------------------------- | -------- | + | **generateTime** | boolean | 返回结果是否包含时间戳列 | false | + | **outputLength** | int | 指定返回结果的输出长度 | 96 | + + +说明： + +1. 使用内置时序大模型进行推理的前提条件是本地存有对应模型权重，目录为 /TIMECHODB\_AINODE\_HOME/data/ainode/models/builtin/model\_id/。若本地没有模型权重，则会自动从 HuggingFace 拉取，请保证本地能直接访问 HuggingFace。 +2. 在深度学习应用中，经常将时间戳衍生特征（数据中的时间列）作为生成式任务的协变量，一同输入到模型中以提升模型的效果，但是在模型的输出结果中一般不包含时间列。为了保证实现的通用性，模型推理结果只对应模型的真实输出，如果模型不输出时间列，则结果中不会包含。 + +**示例** + +样本数据 [ETTh-tree](/img/ETTh-tree.csv) + +下面是使用 sundial 模型推理的一个操作示例，输入 96 行， 输出 48 行，我们通过SQL使用其进行推理。 + +```SQL +IoTDB> select OT from root.db.** ++-----------------------------+---------------+ +| Time|root.db.etth.OT| ++-----------------------------+---------------+ +|2016-07-01T00:00:00.000+08:00| 30.531| +|2016-07-01T01:00:00.000+08:00| 27.787| +|2016-07-01T02:00:00.000+08:00| 27.787| +|2016-07-01T03:00:00.000+08:00| 25.044| +|2016-07-01T04:00:00.000+08:00| 21.948| +| ...... | ...... | +|2016-07-04T19:00:00.000+08:00| 29.546| +|2016-07-04T20:00:00.000+08:00| 29.475| +|2016-07-04T21:00:00.000+08:00| 29.264| +|2016-07-04T22:00:00.000+08:00| 30.953| +|2016-07-04T23:00:00.000+08:00| 31.726| ++-----------------------------+---------------+ +Total line number = 96 + +IoTDB> call inference(sundial,"select OT from root.db.**", generateTime=True, outputLength=48) ++-----------------------------+------------------+ +| Time| output| ++-----------------------------+------------------+ +|2016-07-04T23:00:00.000+08:00|30.537494659423828| +|2016-07-04T23:59:22.500+08:00|29.619892120361328| +|2016-07-05T00:58:45.000+08:00|28.815832138061523| +|2016-07-05T01:58:07.500+08:00| 27.91131019592285| +|2016-07-05T02:57:30.000+08:00|26.893848419189453| +| ...... | ...... | +|2016-07-06T17:33:07.500+08:00| 24.40607261657715| +|2016-07-06T18:32:30.000+08:00| 25.00441551208496| +|2016-07-06T19:31:52.500+08:00|24.907312393188477| +|2016-07-06T20:31:15.000+08:00|25.156436920166016| +|2016-07-06T21:30:37.500+08:00|25.335433959960938| ++-----------------------------+------------------+ +Total line number = 48 +``` + +### 4.2 模型微调 + +AINode 支持通过 SQL 进行模型微调任务。 + +**SQL 语法** + +```SQL +createModel + | CREATE MODEL modelId=identifier (WITH HYPERPARAMETERS LR_BRACKET hparamPair (COMMA hparamPair)* RR_BRACKET)? FROM MODEL existingModelId=identifier ON DATASET LR_BRACKET trainingData RR_BRACKET + ; + +trainingData + : dataElement(COMMA dataElement)* + ; + +dataElement + : pathPatternElement (LR_BRACKET timeRange RR_BRACKET)? + ; + +pathPatternElement + : PATH path=prefixPath + ; +``` + +**参数说明** + +| 名称 | 描述 | +| ----------------- |---------------------------------------------------------------------------------------------------------------------------------------| +| modelId | 微调出的模型的唯一标识 | +| hparamPair | 微调使用的超参数 key-value 对，目前支持如下：
`train_epochs`: int 类型，微调轮数
`iter_per_epoch`: int 类型，每轮微调的迭代次数
`learning_rate`: double 类型，学习率 | +| existingModelId | 微调使用的基座模型 | +| trainingData | 微调使用的数据集 | + +**示例** + +1. 选择测点 root.db.etth.ot 中指定时间范围的数据作为微调数据集，基于 sundial 创建模型 sundialv2. + +```SQL +IoTDB> CREATE MODEL sundialv2 FROM MODEL sundial ON DATASET (PATH root.db.etth.OT([1467302400000, 1467644400000))) +Msg: The statement is executed successfully. +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| +| sundialv2| sundial| fine_tuned| training| ++---------------------+---------+-----------+---------+ +``` + +2. 微调任务后台异步启动，可在 AINode 进程看到 log；微调完成后，查询并使用新的模型 + +```SQL +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| +| sundialv2| sundial| fine_tuned| active| ++---------------------+---------+-----------+---------+ +``` + +### 4.3 注册自定义模型 + +**符合以下要求的 Transformers 模型可以注册到 AINode 中：** + +1. AINode 目前使用 v4.56.2 版本的 transformers，构建模型时需**避免继承低版本（<4.50）接口**； +2. 模型需继承一类 AINode 的推理任务流水线（当前支持预测流水线）： + 1. iotdb-core/ainode/iotdb/ainode/core/inference/pipeline/basic\_pipeline.py + + ```Python + class BasicPipeline(ABC): + def __init__(self, model_id, **model_kwargs): + self.model_info = model_info + self.device = model_kwargs.get("device", "cpu") + self.model = load_model(model_info, device_map=self.device, **model_kwargs) + + @abstractmethod + def preprocess(self, inputs, **infer_kwargs): + """ + 在推理任务开始前对输入数据进行前处理，包括形状验证和数值转换。 + """ + pass + + @abstractmethod + def postprocess(self, output, **infer_kwargs): + """ + 在推理任务结束后对输出结果进行后处理。 + """ + pass + + + class ForecastPipeline(BasicPipeline): + def __init__(self, model_info, **model_kwargs): + super().__init__(model_info, model_kwargs=model_kwargs) + + def preprocess(self, inputs: list[dict[str, dict[str, torch.Tensor] | torch.Tensor]], **infer_kwargs): + """ + 在将输入数据传递给模型进行推理之前进行预处理，验证输入数据的形状和类型。 + + Args: + inputs (list[dict]): + 输入数据，字典列表，每个字典包含： + - 'targets': 形状为 (input_length,) 或 (target_count, input_length) 的张量。 + - 'past_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + - 'future_covariates': 可选，张量字典，每个张量形状为 (input_length,)。 + + infer_kwargs (dict, optional): 推理的额外关键字参数，如： + - `output_length`(int): 如果提供'future_covariates'，用于验证其有效性。 + + Raises: + ValueError: 如果输入格式不正确（例如，缺少键、张量形状无效）。 + + Returns: + 经过预处理和验证的输入数据，可直接用于模型推理。 + """ + pass + + def forecast(self, inputs, **infer_kwargs): + """ + 对给定输入执行预测。 + + Parameters: + inputs: 用于进行预测的输入数据。类型和结构取决于模型的具体实现。 + **infer_kwargs: 额外的推理参数，例如： + - `output_length`(int): 模型应该生成的时间点数量。 + + Returns: + 预测输出，具体形式取决于模型的具体实现。 + """ + pass + + def postprocess(self, outputs: list[torch.Tensor], **infer_kwargs) -> list[torch.Tensor]: + """ + 在推理后对模型输出进行后处理，验证输出数据的形状并确保其符合预期维度。 + + Args: + outputs: + 模型输出，2D张量列表，每个张量形状为 `[target_count, output_length]`。 + + Raises: + InferenceModelInternalException: 如果输出张量形状无效（例如，维数错误）。 + ValueError: 如果输出格式不正确。 + + Returns: + list[torch.Tensor]: + 后处理后的输出，将是一个2D张量列表。 + """ + pass + ``` +3. 修改模型配置文件 config.json，确保包含以下字段： + ```JSON + { + "auto_map": { + "AutoConfig": "config.Chronos2CoreConfig", // 指定模型 Config 类 + "AutoModelForCausalLM": "model.Chronos2Model" // 指定模型类 + }, + "pipeline_cls": "pipeline_chronos2.Chronos2Pipeline", // 指定模型的推理流水线 + "model_type": "custom_t5", // 指定模型类型 + } + ``` + + 1. 必须通过 auto\_map 指定模型的 Config 类和模型类； + 2. 必须集成并指定推理流水线类； + 3. 对于 AINode 管理的内置（builtin）和自定义（user\_defined）模型，模型类别（model\_type）也作为不可重复的唯一标识。即，要注册的模型类别不得与任何已存在的模型类型重复，通过微调创建的模型将继承原模型的模型类别。 +4. 确保要注册的模型目录包含以下文件，且模型配置文件名称和权重文件名称不支持自定义： + 1. 模型配置文件：config.json； + 2. 模型权重文件：model.safetensors； + 3. 模型代码：其它 .py 文件。 + +**注册自定义模型的 SQL 语法如下所示：** + +```SQL +CREATE MODEL USING URI +``` + +**参数说明：** + +* **model\_id**：自定义模型的唯一标识；不可重复，有以下约束： + * 允许出现标识符 [ 0-9 a-z A-Z \_ ] （字母，数字（非开头），下划线（非开头）） + * 长度限制为 2-64 字符 + * 大小写敏感 +* **uri**：包含模型代码和权重的本地 uri 地址。 + +**注册示例：** + +从本地路径上传自定义 Transformers 模型，AINode 会将该文件夹拷贝至 user\_defined 目录中。 + +```SQL +CREATE MODEL chronos2 USING URI 'file:///path/to/chronos2' +``` + +SQL执行后会异步进行注册的流程，可以通过模型展示查看模型的注册状态（见查看模型章节）。模型注册完成后，就可以通过使用正常查询的方式调用具体函数，进行模型推理。 + +### 4.4 查看模型 + +注册成功的模型可以通过查看指令查询模型的具体信息。 + +```SQL +SHOW MODELS +``` + +除了直接展示所有模型的信息外，可以指定`model_id`来查看某一具体模型的信息。 + +```SQL +SHOW MODELS -- 只展示特定模型 +``` + +模型展示的结果中包含如下内容： + +| **ModelId** | **ModelType** | **Category** | **State** | +| ------------------- | --------------------- | -------------------- | ----------------- | +| 模型ID | 模型类型 | 模型种类 | 模型状态 | + +其中，State 模型状态机流转示意图如下: + +![](/img/ainode-upgrade-state-timecho.png) + +状态机流程说明： + +1. 启动 AINode 后，执行 `show models` 命令，仅能查看到**系统内置（BUILTIN）**的模型。 +2. 用户可导入自己的模型，这类模型的来源标识为**用户自定义（USER\_****DEFINED）**；AINode 会尝试从模型配置文件中解析模型类型（ModelType），若解析失败，该字段则显示为空。 +3. 时序大模型（内置模型）权重文件不随 AINode 打包，AINode 启动时自动下载。 + 1. 下载过程中为 ACTIVATING，下载成功转变为 ACTIVE，失败则变成 INACTIVE。 +4. 用户启动模型微调任务后，正在训练的模型状态为 TRAINING，训练成功变为 ACTIVE，失败则是 FAILED。 +5. 若微调任务成功，微调结束后会统计所有 ckpt （训练文件）中指标最佳的文件并自动重命名，变成用户指定的 model\_id。 + +**查看示例** + +```SQL +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| +| custom| | user_defined| active| +| timer_xl| timer| builtin| activating| +| sundial| sundial| builtin| active| +| sundialx_1| sundial| fine_tuned| active| +| sundialx_4| sundial| fine_tuned| training| +| sundialx_5| sundial| fine_tuned| failed| +| chronos2| t5| builtin| inactive| ++---------------------+--------------+--------------+-------------+ +``` + +内置传统时序模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|----------------------------------| ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| **ARIMA**(自回归整合移动平均模型) | 结合自回归(AR)、差分(I)和移动平均(MA)，用于预测平稳时间序列或可通过差分变为平稳的数据。 | 单变量时间序列预测，如股票价格、销量、经济指标等。| 1. 适用于线性趋势和季节性较弱的数据。2. 需要选择参数 (p,d,q)。3. 对缺失值敏感。 | +| **Holt-Winters**(三参数指数平滑) | 基于指数平滑，引入水平、趋势和季节性三个分量，适用于具有趋势和季节性的数据。 | 有明显季节性和趋势的时间序列，如月度销售额、电力需求等。 | 1. 可处理加性或乘性季节性。2. 对近期数据赋予更高权重。3. 简单易实现。 | +| **Exponential Smoothing**(指数平滑) | 通过加权平均历史数据，权重随时间指数递减，强调近期观测值的重要性。 | 无显著季节性但存在趋势的数据，如短期需求预测。 | 1. 参数少，计算简单。2. 适合平稳或缓慢变化序列。3. 可扩展为双指数或三指数平滑。 | +| **Naive Forecaster**(朴素预测器) | 使用最近一期的观测值作为下一期的预测值，是最简单的基准模型。 | 作为其他模型的比较基准，或数据无明显模式时的简单预测。 | 1. 无需训练。2. 对突发变化敏感。3. 季节性朴素变体可用前一季节同期值预测。 | +| **STL Forecaster**(季节趋势分解预测) | 基于STL分解时间序列，分别预测趋势、季节性和残差分量后组合。 | 具有复杂季节性、趋势和非线性模式的数据，如气候数据、交通流量。 | 1. 能处理非固定季节性。2. 对异常值稳健。3. 分解后可结合其他模型预测各分量。 | +| **Gaussian HMM**(高斯隐马尔可夫模型) | 假设观测数据由隐藏状态生成，每个状态的观测概率服从高斯分布。 | 状态序列预测或分类，如语音识别、金融状态识别。 | 1. 适用于时序数据的状态建模。2. 假设观测值在给定状态下独立。3. 需指定隐藏状态数量。 | +| **GMM HMM** (高斯混合隐马尔可夫模型) | 扩展Gaussian HMM，每个状态的观测概率由高斯混合模型描述，可捕捉更复杂的观测分布。 | 需要多模态观测分布的场景，如复杂动作识别、生物信号分析。 | 1. 比单一高斯更灵活。2. 参数更多，计算复杂度高。3. 需训练GMM成分数。 | +| **STRAY**(基于奇异值的异常检测) | 通过奇异值分解(SVD)检测高维数据中的异常点，常用于时间序列异常检测。 | 高维时间序列的异常检测，如传感器网络、IT系统监控。 | 1. 无需分布假设。2. 可处理高维数据。3. 对全局异常敏感，局部异常可能漏检。 | + +内置时序大模型介绍如下： + +| 模型名称 | 核心概念 | 适用场景 | 主要特点 | +|---------------| ---------------------------------------------------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| **Timer-XL** | 支持超长上下文的时序大模型，通过大规模工业数据预训练增强泛化能力。 | 需利用极长历史数据的复杂工业预测，如能源、航空航天、交通等领域。 | 1. 超长上下文支持，可处理数万时间点输入。2. 多场景覆盖，支持非平稳、多变量及协变量预测。3. 基于万亿级高质量工业时序数据预训练。 | +| **Timer-Sundial** | 采用“Transformer + TimeFlow”架构的生成式基础模型，专注于概率预测。 | 需要量化不确定性的零样本预测场景，如金融、供应链、新能源发电预测。 | 1. 强大的零样本泛化能力，支持点预测与概率预测 2. 可灵活分析预测分布的任意统计特性。3. 创新生成架构，实现高效的非确定性样本生成。 | +| **Chronos-2** | 基于离散词元化范式的通用时序基础模型，将预测转化为语言建模任务。 | 快速零样本单变量预测，以及可借助协变量（如促销、天气）提升效果的场景。 | 1. 强大的零样本概率预测能力。2. 支持协变量统一建模，但对输入有严格要求：a. 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集；b. 每个历史协变量的长度必须等于目标变量的长度； c. 每个未来协变量的长度必须等于预测长度；3. 采用高效的编码器式结构，兼顾性能与推理速度。 | + + +### 4.5 删除模型 + +对于注册成功的模型，用户可以通过 SQL 进行删除，AINode 会将 user\_defined 目录下的对应模型文件夹整个删除。其 SQL 语法如下： + +```SQL +DROP MODEL +``` + +需要指定已经成功注册的模型 model\_id 来删除对应的模型。由于模型删除涉及模型数据清理，操作不会立即完成，此时模型的状态为 DROPPING，该状态的模型不能用于模型推理。请注意，该功能不支持删除内置模型。 + +### 4.6 加载/卸载模型 + +为适应不同场景，AINode 提供以下两种模型加载策略： + +* 即时加载：即推理时临时加载模型，结束后释放资源。适用于测试或低负载场景。 +* 常驻加载：即将模型持久化加载在内存（CPU）或显存（GPU）中，以支持高并发推理。用户只需通过 SQL 指定加载或卸载的模型，AINode 会自动管理实例数量。当前常驻模型的状态也可随时查看。 + +下文将详细介绍加载/卸载模型的相关内容： + +1. 配置参数 + +支持通过编辑如下配置项设置常驻加载相关参数。 + +```Properties +# AINode 在推理时可使用的设备内存/显存占总量的比例 +# Datatype: Float +ain_inference_memory_usage_ratio=0.4 + +# AINode 每个加载的模型实例需要占用的内存比例，即模型占用*该值 +# Datatype: Float +ain_inference_extra_memory_ratio=1.2 +``` + +2. 展示可用的 device + +支持通过如下 SQL 命令查看所有可用的设备 ID + +```SQL +SHOW AI_DEVICES +``` + +示例 + +```SQL +IoTDB> show ai_devices ++-------------+ +| DeviceId| ++-------------+ +| cpu| +| 0| +| 1| ++-------------+ +``` + +3. 加载模型 + +支持通过如下 SQL 命令手动加载模型，系统根据硬件资源使用情况**自动均衡**模型实例数量。 + +```SQL +LOAD MODEL TO DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 加载到 AINode 所在服务器的内存中。 + * **gpu\_id:** 加载到 AINode 所在服务器的对应显卡中，如 "0, 1" 表示加载到编号为 0 和 1 的两张显卡中。 + +示例 + +```SQL +LOAD MODEL sundial TO DEVICES 'cpu,0,1' +``` + +4. 卸载模型 + +支持通过如下 SQL 命令手动卸载指定模型的所有实例，系统会**重分配**空闲出的资源给其他模型 + +```SQL +UNLOAD MODEL FROM DEVICES (, )* +``` + +参数要求 + +* **existing\_model\_id:** 指定的模型 id，当前版本仅支持 timer\_xl 和 sundial。 +* **device\_id:** 模型加载的位置。 + * **cpu:** 尝试从 AINode 所在服务器的内存中卸载指定模型。 + * **gpu\_id:** 尝试从 AINode 所在服务器的对应显卡中卸载指定模型，如 "0, 1" 表示尝试从编号为 0 和 1 的两张显卡卸载指定模型。 + +示例 + +```SQL +UNLOAD MODEL sundial FROM DEVICES 'cpu,0,1' +``` + +5. 展示加载的模型 + +支持通过如下 SQL 命令查看已经手动加载的模型实例，可通过 `device_id `指定设备。 + +```SQL +SHOW LOADED MODELS +SHOW LOADED MODELS (, )* # 展示指定设备中的模型实例 +``` + +示例：在内存、gpu\_0 和 gpu\_1 两张显卡加载了sundial 模型 + +```SQL +IoTDB> show loaded models ++-------------+--------------+------------------+ +| DeviceId| ModelId| Count(instances)| ++-------------+--------------+------------------+ +| cpu| sundial| 4| +| 0| sundial| 6| +| 1| sundial| 6| ++-------------+--------------+------------------+ +``` + +说明： + +* DeviceId : 设备 ID +* ModelId ：加载的模型 ID +* Count(instances) ：每个设备中的模型实例数量（系统自动分配） + +### 4.7 时序大模型介绍 + +AINode 目前支持多种时序大模型，相关介绍及部署使用可参考[时序大模型](../AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md) + +## 5. 权限管理 + +使用 AINode 相关的功能时，可以使用IoTDB本身的鉴权去做一个权限管理，用户只有在具备 USE\_MODEL 权限时，才可以使用模型管理的相关功能。当使用推理功能时，用户需要有访问输入模型的 SQL 对应的源序列的权限。 + +| 权限名称 | 权限范围 | 管理员用户（默认ROOT） | 普通用户 | 路径相关 | +| ------------ | ----------------------------------------- | ------------------------ | ---------- | ---------- | +| USE\_MODEL | create model / show models / drop model | √ | √ | x | +| READ\_DATA | call inference | √ | √ | √ | diff --git a/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade.md b/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade.md new file mode 100644 index 000000000..440615354 --- /dev/null +++ b/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade.md @@ -0,0 +1,23 @@ +--- +redirectTo: TimeSeries-Large-Model_Upgrade_apache.html +--- + diff --git a/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md b/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md new file mode 100644 index 000000000..e1af1e1d0 --- /dev/null +++ b/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_apache.md @@ -0,0 +1,157 @@ + +# 时序大模型 + +## 1. 简介 + +时序大模型是专为时序数据分析设计的基础模型。IoTDB 团队长期自研时序基础模型 Timer，该模型基于 Transformer 架构，经海量多领域时序数据预训练，可支撑时序预测、异常检测、时序填补等下游任务；团队打造的 AINode 平台同时支持集成业界前沿时序基础模型，为用户提供多元选型。不同于传统时序分析技术，这类大模型具备通用特征提取能力，可通过零样本分析、微调等技术服务广泛的分析任务。 + +本文相关时序大模型领域的技术成果（含团队自研及业界前沿方向）均发表于国际机器学习顶级会议，具体内容见附录。 + +## 2. 应用场景 + +* **时序预测**：为工业生产、自然环境等领域提供时间序列数据的预测服务，帮助用户提前了解未来变化趋势。 +* **数据填补**：针对时间序列中的缺失序列段，进行上下文填补，以增强数据集的连续性和完整性。 +* **异常检测**：利用自回归分析技术，对时间序列数据进行实时监测，及时预警潜在的异常情况。 + +![](/img/LargeModel09.png) + +## 3. Timer-1 模型 + +Timer[1] 模型（非内置模型）不仅展现了出色的少样本泛化和多任务适配能力，还通过预训练获得了丰富的知识库，赋予了它处理多样化下游任务的通用能力，拥有以下特点： + +* **泛化性**：模型能够通过使用少量样本进行微调，达到行业内领先的深度模型预测效果。 +* **通用性**：模型设计灵活，能够适配多种不同的任务需求，并且支持变化的输入和输出长度，使其在各种应用场景中都能发挥作用。 +* **可扩展性**：随着模型参数数量的增加或预训练数据规模的扩大，模型效果会持续提升，确保模型能够随着时间和数据量的增长而不断优化其预测效果。 + +![](/img/model01.png) + +## 4. Timer-XL 模型 + +Timer-XL[2]基于 Timer 进一步扩展升级了网络结构，在多个维度全面突破： + +* **超长上下文支持**：该模型突破了传统时序预测模型的限制，支持处理数千个 Token（相当于数万个时间点）的输入，有效解决了上下文长度瓶颈问题。 +* **多变量预测场景覆盖**：支持多种预测场景，包括非平稳时间序列的预测、涉及多个变量的预测任务以及包含协变量的预测，满足多样化的业务需求。 +* **大规模工业时序数据集：**采用万亿大规模工业物联网领域的时序数据集进行预训练，数据集兼有庞大的体量、卓越的质量和丰富的领域等重要特质，覆盖能源、航空航天、钢铁、交通等多领域。 + +![](/img/model02.png) + +## 5. Timer-Sundial 模型 + +Timer-Sundial[3]是一个专注于时间序列预测的生成式基础模型系列，其基础版本拥有 1.28 亿参数，并在 1 万亿个时间点上进行了大规模预训练，其核心特性包括： + +* **强大的泛化性能：**具备零样本预测能力，可同时支持点预测和概率预测。 +* **灵活预测分布分析：**不仅能预测均值或分位数，还可通过模型生成的原始样本评估预测分布的任意统计特性。 +* **创新生成架构：** 采用 “Transformer + TimeFlow” 协同架构——Transformer 学习时间片段的自回归表征，TimeFlow 模块基于流匹配框架 (Flow-Matching) 将随机噪声转化为多样化预测轨迹，实现高效的非确定性样本生成。 + +![](/img/model03.png) + +## 6. Chronos-2 模型 + +Chronos-2 [4]是由 Amazon Web Services (AWS) 研究团队开发的，基于 Chronos 离散词元建模范式发展起来的通用时间序列基础模型，该模型同时适用于零样本单变量预测和协变量预测。其主要特性包括： + +* **概率性预测能力**：模型以生成式方式输出多步预测结果，支持分位数或分布级预测，从而刻画未来不确定性。 +* **零样本通用预测**：依托预训练获得的上下文学习能力，可直接对未见过的数据集执行预测，无需重新训练或参数更新。 +* **多变量与协变量统一建模**：支持在同一架构下联合建模多条相关时间序列及其协变量，以提升复杂任务的预测效果。但对输入有严格要求： + * 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集； + * 每个历史协变量的长度必须等于目标变量的长度； + * 每个未来协变量的长度必须等于预测长度； +* **高效推理与部署**：模型采用紧凑的编码器式（encoder-only）结构，在保持强泛化能力的同时兼顾推理效率。 + +![](/img/timeseries-large-model-chronos2.png) + +## 7. 效果展示 + +时序大模型能够适应多种不同领域和场景的真实时序数据，在各种任务上拥有优异的处理效果，以下是在不同数据上的真实表现： + +**时序预测：** + +利用时序大模型的预测能力，能够准确预测时间序列的未来变化趋势，如下图蓝色曲线代表预测趋势，红色曲线为实际趋势，两曲线高度吻合。 + +![](/img/LargeModel03.png) + +**数据填补**： + +利用时序大模型对缺失数据段进行预测式填补。 + +![](/img/timeseries-large-model-data-imputation.png) + +**异常检测**： + +利用时序大模型精准识别与正常趋势偏离过大的异常值。 + +![](/img/LargeModel05.png) + +## 8. 部署使用 + +1. 打开 IoTDB cli 控制台，检查 ConfigNode、DataNode、AINode 节点确保均为 Running。 + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. 联网环境下首次启动 AINode 节点会自动拉取 Timer-XL、Sundial、Chronos2 模型。 + + > 注意： + > + > * AINode 安装包不包含模型权重文件 + > * 自动拉取功能依赖部署环境具备 HuggingFace 网络访问能力 + > * AINode 支持手动上传模型权重文件，具体操作方法可参考[导入权重文件](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_apache.md#_3-3-导入内置权重文件) + +3. 检查模型是否可用。 + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### 附录 + +**[1]** Timer- Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref1) + +**[2]** TIMER-XL- LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING ,Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref2) + +**[3]** Sundial- A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ 返回](#ref3) + +**[4] **Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821.**[↩ 返回](#ref4) diff --git a/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md b/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md new file mode 100644 index 000000000..3d86bfc4f --- /dev/null +++ b/src/zh/UserGuide/latest/AI-capability/TimeSeries-Large-Model_Upgrade_timecho.md @@ -0,0 +1,157 @@ + +# 时序大模型 + +## 1. 简介 + +时序大模型是专为时序数据分析设计的基础模型。IoTDB 团队长期自研时序基础模型 Timer，该模型基于 Transformer 架构，经海量多领域时序数据预训练，可支撑时序预测、异常检测、时序填补等下游任务；团队打造的 AINode 平台同时支持集成业界前沿时序基础模型，为用户提供多元选型。不同于传统时序分析技术，这类大模型具备通用特征提取能力，可通过零样本分析、微调等技术服务广泛的分析任务。 + +本文相关时序大模型领域的技术成果（含团队自研及业界前沿方向）均发表于国际机器学习顶级会议，具体内容见附录。 + +## 2. 应用场景 + +* **时序预测**：为工业生产、自然环境等领域提供时间序列数据的预测服务，帮助用户提前了解未来变化趋势。 +* **数据填补**：针对时间序列中的缺失序列段，进行上下文填补，以增强数据集的连续性和完整性。 +* **异常检测**：利用自回归分析技术，对时间序列数据进行实时监测，及时预警潜在的异常情况。 + +![](/img/LargeModel09.png) + +## 3. Timer-1 模型 + +Timer[1] 模型（非内置模型）不仅展现了出色的少样本泛化和多任务适配能力，还通过预训练获得了丰富的知识库，赋予了它处理多样化下游任务的通用能力，拥有以下特点： + +* **泛化性**：模型能够通过使用少量样本进行微调，达到行业内领先的深度模型预测效果。 +* **通用性**：模型设计灵活，能够适配多种不同的任务需求，并且支持变化的输入和输出长度，使其在各种应用场景中都能发挥作用。 +* **可扩展性**：随着模型参数数量的增加或预训练数据规模的扩大，模型效果会持续提升，确保模型能够随着时间和数据量的增长而不断优化其预测效果。 + +![](/img/model01.png) + +## 4. Timer-XL 模型 + +Timer-XL[2]基于 Timer 进一步扩展升级了网络结构，在多个维度全面突破： + +* **超长上下文支持**：该模型突破了传统时序预测模型的限制，支持处理数千个 Token（相当于数万个时间点）的输入，有效解决了上下文长度瓶颈问题。 +* **多变量预测场景覆盖**：支持多种预测场景，包括非平稳时间序列的预测、涉及多个变量的预测任务以及包含协变量的预测，满足多样化的业务需求。 +* **大规模工业时序数据集：**采用万亿大规模工业物联网领域的时序数据集进行预训练，数据集兼有庞大的体量、卓越的质量和丰富的领域等重要特质，覆盖能源、航空航天、钢铁、交通等多领域。 + +![](/img/model02.png) + +## 5. Timer-Sundial 模型 + +Timer-Sundial[3]是一个专注于时间序列预测的生成式基础模型系列，其基础版本拥有 1.28 亿参数，并在 1 万亿个时间点上进行了大规模预训练，其核心特性包括： + +* **强大的泛化性能：**具备零样本预测能力，可同时支持点预测和概率预测。 +* **灵活预测分布分析：**不仅能预测均值或分位数，还可通过模型生成的原始样本评估预测分布的任意统计特性。 +* **创新生成架构：** 采用 “Transformer + TimeFlow” 协同架构——Transformer 学习时间片段的自回归表征，TimeFlow 模块基于流匹配框架 (Flow-Matching) 将随机噪声转化为多样化预测轨迹，实现高效的非确定性样本生成。 + +![](/img/model03.png) + +## 6. Chronos-2 模型 + +Chronos-2 [4]是由 Amazon Web Services (AWS) 研究团队开发的，基于 Chronos 离散词元建模范式发展起来的通用时间序列基础模型，该模型同时适用于零样本单变量预测和协变量预测。其主要特性包括： + +* **概率性预测能力**：模型以生成式方式输出多步预测结果，支持分位数或分布级预测，从而刻画未来不确定性。 +* **零样本通用预测**：依托预训练获得的上下文学习能力，可直接对未见过的数据集执行预测，无需重新训练或参数更新。 +* **多变量与协变量统一建模**：支持在同一架构下联合建模多条相关时间序列及其协变量，以提升复杂任务的预测效果。但对输入有严格要求： + * 未来协变量的名称组成的集合必须是历史协变量的名称组成的集合的子集； + * 每个历史协变量的长度必须等于目标变量的长度； + * 每个未来协变量的长度必须等于预测长度； +* **高效推理与部署**：模型采用紧凑的编码器式（encoder-only）结构，在保持强泛化能力的同时兼顾推理效率。 + +![](/img/timeseries-large-model-chronos2.png) + +## 7. 效果展示 + +时序大模型能够适应多种不同领域和场景的真实时序数据，在各种任务上拥有优异的处理效果，以下是在不同数据上的真实表现： + +**时序预测：** + +利用时序大模型的预测能力，能够准确预测时间序列的未来变化趋势，如下图蓝色曲线代表预测趋势，红色曲线为实际趋势，两曲线高度吻合。 + +![](/img/LargeModel03.png) + +**数据填补**： + +利用时序大模型对缺失数据段进行预测式填补。 + +![](/img/timeseries-large-model-data-imputation.png) + +**异常检测**： + +利用时序大模型精准识别与正常趋势偏离过大的异常值。 + +![](/img/LargeModel05.png) + +## 8. 部署使用 + +1. 打开 IoTDB cli 控制台，检查 ConfigNode、DataNode、AINode 节点确保均为 Running。 + +```Plain +IoTDB> show cluster ++------+----------+-------+---------------+------------+--------------+-----------+ +|NodeID| NodeType| Status|InternalAddress|InternalPort| Version| BuildInfo| ++------+----------+-------+---------------+------------+--------------+-----------+ +| 0|ConfigNode|Running| 127.0.0.1| 10710| 2.0.5.1| 069354f| +| 1| DataNode|Running| 127.0.0.1| 10730| 2.0.5.1| 069354f| +| 2| AINode|Running| 127.0.0.1| 10810| 2.0.5.1|069354f-dev| ++------+----------+-------+---------------+------------+--------------+-----------+ +Total line number = 3 +It costs 0.140s +``` + +2. 联网环境下首次启动 AINode 节点会自动拉取 Timer-XL、Sundial、Chronos2 模型。 + + > 注意： + > + > * AINode 安装包不包含模型权重文件 + > * 自动拉取功能依赖部署环境具备 HuggingFace 网络访问能力 + > * AINode 支持手动上传模型权重文件，具体操作方法可参考[导入权重文件](../Deployment-and-Maintenance/AINode_Deployment_Upgrade_timecho.md#_3-3-导入内置权重文件) + +3. 检查模型是否可用。 + +```Bash +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| ++---------------------+---------+--------+--------+ +``` + +### 附录 + +**[1]** Timer- Generative Pre-trained Transformers Are Large Time Series Models, Yong Liu, Haoran Zhang, Chenyu Li, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref1) + +**[2]** TIMER-XL- LONG-CONTEXT TRANSFORMERS FOR UNIFIED TIME SERIES FORECASTING ,Yong Liu, Guo Qin, Xiangdong Huang, Jianmin Wang, Mingsheng Long. [↩ 返回](#ref2) + +**[3]** Sundial- A Family of Highly Capable Time Series Foundation Models, Yong Liu, Guo Qin, Zhiyuan Shi, Zhi Chen, Caiyin Yang, Xiangdong Huang, Jianmin Wang, Mingsheng Long, **ICML 2025 spotlight**. [↩ 返回](#ref3) + +**[4] **Chronos-2: From Univariate to Universal Forecasting, Abdul Fatir Ansari, Oleksandr Shchur, Jaris Küken, Andreas Auer, Boran Han, Pedro Mercado, Syama Sundar Rangapuram, Huibin Shen, Lorenzo Stella, Xiyuan Zhang, Mononito Goswami, Shubham Kapoor, Danielle C. Maddix, Pablo Guerron, Tony Hu, Junming Yin, Nick Erickson, Prateek Mutalik Desai, Hao Wang, Huzefa Rangwala, George Karypis, Yuyang Wang, Michael Bohlke-Schneider, **arXiv:2510.15821.**[↩ 返回](#ref4)