TDengine 时序预测实战使用 CES 复数指数平滑算法FORECAST【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine本指南聚焦 TDengine 内置分析平台 TDgpt 提供的CESComplex Exponential Smoothing复数指数平滑预测算法它以复数形式的状态空间方程对时间序列的水平、趋势与季节性进行联合建模并支持自动选择模型形态与置信区间输出。读完本文你将掌握 CES 在FORECAST函数中的完整调用方式、period与model参数的全部取值含义、输入数据的硬性约束以及如何从仓库源码与测试用例中验证算法行为。功能概述什么是 CESCES 是一种基于复数状态空间的指数平滑方法。与传统的 Holt-Winters、ARIMA 等实数域模型不同CES 将时间序列的水平level、趋势trend与季节性seasonal变化编码进复数状态方程用复数运算统一表达这三类动态成分从而能够刻画那些不符合常规加法或乘法模式的复杂季节性行为。在 TDgpt 中CES 以自动化建模方式落地算法根据输入时间序列自动选择最合适的模型形态无需人工指定组件结构并可直接输出未来数据的预测结果及其置信区间。从源码实现看TDgpt 的 CES 服务位于 tools/tdgpt/taosanalytics/algo/fc/ces.py核心类是_CesServiceclass _CesService(AbstractStatsForecastService): Forecast time-series data using CES. name ces desc forecast algorithm by using complex exponential smoothing _builtins True model_info CES def __init__(self): super().__init__() self.model Z def set_params(self, params: dict) - None: super().set_params(params) self.model str(params.get(model, Z)).upper() if self.model not in (N, S, P, F, Z): raise ValueError(model parameter can only be N, S, P, F or Z) def _fit_model(self, values): season_length self.period if self.period 0 else 1 model AutoCES(season_lengthseason_length, modelself.model) return model.fit(values)关键点包括服务注册名为ces即 SQL 中algoces对应的算法标识模型默认形态为Z自动选择底层拟合由 StatsForecast 库的AutoCES完成项目固定依赖statsforecast2.1.1见 tools/tdgpt/requirements_docker.txt未显式设置period时季节长度取 1等价于非季节性模型。FORECAST 函数与 CES 的调用方式CES 通过 TDgpt 的统一预测入口FORECAST函数在 SQL 中调用。FORECAST的整体语法与通用参数参见 Time-Series Forecasting 总览其形式为FORECAST(column_expr, option_expr) option_expr: { algoexpr1 [,wncheck1|0] [,confconf_val] [,everyevery_val] [,rowsrows_val] [,startstart_ts_val] [,timeouttimeout_val] [,expr2] }调用 CES 时option_expr中至少需要指定algoces并按需携带 CES 专属参数与通用参数。通用参数对 CES 同样生效核心通用参数如下参数定义默认值algo预测算法名CES 场景填cesholtwinterswncheck白噪声数据检查1开启、0关闭1conf置信水平用于_FLOW与_FHIGH伪列端到端请求须取(0, 1)如0.950.95every采样周期可小于等于输入数据采样周期输入数据的采样周期start预测数据的起始时间戳输入数据最后时间戳之后一个采样周期rows返回的预测行数最大 1024超出报错10timeout预测请求最大等待时间秒范围 11200自v3.3.6.5支持60其中rows直接决定 CES 预测的未来数据点个数conf决定置信区间的宽窄。需要注意的是预测至少需要 10 行输入数据、最多支持 40,000 行部分模型还有更严格的限制。CES 专属参数参数说明必填项period输入时间序列每个周期包含的数据点个数。不设置或设为 0 时使用非季节性模型选填modelCES 模型类型可选N、S、P、F或Z默认Z自动选择模型选填model五种取值的语义如下N非季节模型Non-seasonalS简单季节模型Simple seasonalityP部分季节模型Partial seasonalityF完整季节模型Full seasonalityZ由算法自动选择模型默认值。在 ces.py 的set_params中model参数会被强制转为大写且只接受上述五个值之一否则抛出ValueError。这一校验在 tools/tdgpt/tests/forecast_test.py 的test_ces_invalid_params中也有对应断言传入modelinvalid期望异常。输入数据的约束与底层校验CES 对输入数据有明确要求这些约束不仅在文档中说明也通过基类AbstractStatsForecastServicetools/tdgpt/taosanalytics/base.py在源码层面强制实施输入必须只包含有限数值数据中出现NaN、inf、-inf会直接报错。基类通过np.isfinite(values).all()检查错误信息为input data contains NaN or infinite values测试用例test_ces_rejects_non_finite_input逐一验证了这三种非有限值。最小数据量要求非季节性预测至少需要两个输入值当period大于 0 时输入数据至少需要包含两个完整周期。基类中的校验逻辑为min_rows max(2, self.period * 2) if self.list is None or len(self.list) min_rows: raise ValueError(number of input data is less than the required periods)时间步长与行数time_step必须大于 0rows必须为正整数period不得为负conf必须落在[0, 1)。返回结果结构CES 预测完成后返回值是一个 JSON 结构字段含义如下{ rows: rows, // 返回结果的行数 period: period, // 返回结果的周期性同输入 algo: ces, // 返回结果使用的算法 mse: mse, // 拟合输入时间序列生成模型的均方误差 (MSE) res: res // 列模式的预测结果及置信区间 }mse均方误差用于衡量模型对输入历史序列的拟合质量在基类中通过样本内拟合值predict_in_sample()计算res采用列模式组织第一列为预测时间戳其后依次为预测均值、置信区间下界与上界开启置信区间时置信水平由conf决定return_conf0时可关闭置信区间输出测试test_ces_forecast中验证了return_conf0时结果只含预测列。完整示例假设表foo含数值列i32每 12 个数据点构成一个完整周期使用 CES 自动选择模型进行预测FORECAST(i32, algoces,period12,modelZ)完整的调用 SQL 语句如下SELECT _frowts, FORECAST(i32, algoces,period12,modelZ) from foo其中_frowts是预测查询引入的伪列代表预测数据的时间戳。预测查询共引入三个伪列_FROWTS预测数据的时间戳_FLOW置信区间下界_FHIGH置信区间上界。因此可以显式取回置信区间SELECT _flow, _fhigh, _frowts, FORECAST(i32, algoces,period12,modelZ) FROM foo;CES 支持为预测结果提供置信区间因此_FLOW与_FHIGH会给出真实区间范围这与某些不支持置信区间的算法不同——那些算法的上下界会回归为与预测值相同的单点。再举一个参数组合的变体指定预测 20 行、95% 置信水平、禁白噪声检查SELECT _flow, _fhigh, _frowts, FORECAST(i32, algoces,period12,modelZ,rows20,conf0.95,wncheck0) FROM foo;如何选择CES 与 Theta、ETS 的取舍官方文档给出了 CES、Theta、ETS 三种算法的选型对照表数据特征推荐算法原因季节模式复杂或不符合常规加法/乘法模式CESCES 用复数状态表示季节行为且能自动选择模型形态序列具有清晰长期趋势、季节性较规则ThetaTheta 是紧凑的趋势聚焦方法季节振幅稳定选加法分解比例变化选乘法分解需要可解释的误差、趋势、季节组件组合ETSETS 可自动选择或显式配置加法/乘法组件并支持阻尼趋势实践建议当组件结构未知时优先使用自动选择——CES 用modelZETS 用modelZZZ。Theta 的乘法分解以及 ETS 任何显式乘法组件都要求输入严格为正对于季节预测务必设置period并提供至少两个完整周期的历史数据。源码级验证测试用例如何保证 CES 行为在 tools/tdgpt/tests/forecast_test.py 中CES 的行为被多组测试覆盖可作为使用与二次开发的参考test_ces_forecast以period12, modelZ执行预测并校验返回 10 行结果随后用return_conf0验证置信区间关闭路径test_ces_invalid_params验证非法model值抛出ValueErrortest_ces_rejects_non_finite_input验证NaN、inf输入均被拒绝错误信息匹配NaN or infinite常量输入测试对 CES、Theta、ETS 统一验证恒定输入产生有限预测且拟合 MSE 近似为 0。TDgpt 的服务注册机制会把_CesService以ces为名注册进算法仓库见 tools/tdgpt/taosanalytics/service_registry.py随后在FORECAST的执行入口do_forecasttools/tdgpt/taosanalytics/algo/forecast.py中被按名加载并依次完成设置输入、设置参数、执行预测、校验结果与可视化绘图。注意事项小结model与period均为选填参数默认modelZ自动选模不设period则按非季节模型处理输入数据必须全部为有限数值且数据量满足非季节至少 2 个值、有周期至少 2 个完整周期的下限rows上限 1024conf需在(0, 1)区间timeout范围 11200 秒置信区间输出可通过conf调整水平、通过return_conf0关闭预测的时间范围可通过start调整仅影响时间戳不影响预测数值本身。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考