TDengine TDgpt 时序数据预处理机制解析白噪声检查与重采样对齐【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengineTDgpt 是 TDengine 内置的时序数据分析平台在将时序数据交给具体预测或异常检测算法之前会先执行一套统一的预处理流程。本文基于 数据分析预处理 官方文档结合tools/tdgpt下的 Python 源码实现系统讲解 TDgpt 的预处理两大核心步骤——Ljung-Box 白噪声检查与时间戳对齐/数据重采样并给出wncheck参数的使用方法与底层调用链帮助开发者在调用FORECAST、ANOMALY等分析函数时理解数据被加工的细节从而写出更高效、更符合预期的分析请求。图 1TDgpt 数据分析预处理流程示意数据先经白噪声检查预测场景还需重采样与时间戳对齐之后才进入预测或异常检测算法。分析流程预处理在算法之前、独立于算法时序数据分析之前必须经过预处理目的是为减轻分析算法的负担。整体流程可归纳为三个阶段白噪声检查White Noise Data check对所有输入数据执行判定输入序列是否只是随机数序列无分析价值。重采样与时间戳对齐仅针对预测分析执行异常检测会跳过该步骤。正式分析进入具体的预测forecast或异常检测anomaly detection算法。一个重要设计点是预处理过程不属于预测或异常检测处理逻辑的一部分。从源码结构看这一职责划分非常清晰——TDgpt 服务端在 util.py 中通过do_check_before_exec()完成输入校验与白噪声检查而具体的预测/异常检测算法则在 algo/ 目录下各自独立实现如fc/arima.py、fc/holtwinters.py、fc/prophet.py、ad/ksigma.py、ad/shesd.py等。预处理只负责把关和整形不参与算法的特征计算。此外在请求入口处还有一个前置约束validate_pay_load()util.py要求输入数据行数必须在10 到 40000 行之间且各列行数必须一致、schema 中必须包含数据列。这是预处理开始前的硬性校验也是调用分析函数时容易忽略的边界条件。白噪声检查Ljung-Box 统计量检验什么是白噪声序列白噪声时序数据可以简单地理解为由随机数构成的时间序列例如服从正态分布的随机数序列如图 2 所示。这类序列不含任何可学习的规律对其做预测或异常检测没有分析价值因此 TDgpt 会直接返回不进入后续算法。图 2白噪声数据形态示意——均值附近无规律随机波动不具备可分析的结构。Ljung-Box 检验的源码实现白噪声检查采用经典统计学方法Ljung-Box 检验统计量检验其核心实现在 util.py 的is_white_noise()函数中def is_white_noise(input_list): determine whether the input list is a white noise list or not if len(input_list) 16: # the number of items in the list is insufficient return False res acorr_ljungbox(input_list, lags[6, 12, 16], boxpierceTrue, return_dfTrue) q_lb res.lb_pvalue.array[2] return q_lb 0.05实现要点依赖直接调用statsmodels.stats.diagnostic.acorr_ljungbox见 util.py这也是计算 Ljung-Box 统计量需遍历整个输入时间序列的原因。样本量门槛当输入序列长度 ≤ 16 时直接返回False即样本不足时不判定为白噪声避免小样本下检验失效。滞后阶数同时计算lags[6, 12, 16]三组滞后阶数的统计量最终取lb_pvalue数组中第三个值即 lags16 对应的 p 值。判定阈值p 值 ≥ 0.05 判定为白噪声在 95% 置信水平下无法拒绝序列为白噪声的原假设。检查的执行时机与 wncheck 参数白噪声检查在do_check_before_exec()中执行util.py关键逻辑如下# 2. white noise data check wn_check req_json[wncheck] if wncheck in req_json else 1 ... if wn_check: data payload[data_index] is_wn is_white_noise(data) ... if is_wn: raise ValueError(white_noise_error_msg())对应的事实与用法wncheck默认值为 1请求体JSON中未显式携带该字段时默认执行白噪声检查。命中白噪声的返回一旦判定为白噪声请求直接失败并抛出错误错误消息定义在 error.pywhite noise data not processed。跳过检查如果用户能够明确确认输入序列一定不是白噪声序列可以在请求参数中增加wncheck0强制要求 TDgpt 忽略白噪声检查从而节省遍历整个序列计算统计量的计算资源。该参数在 restful_api_test.py 等测试用例中被反复验证同时存在wncheck: 1与wncheck: 0的请求样例。能力边界TDgpt 暂不提供独立的时间序列白噪声检测功能白噪声检查仅作为分析前的内置步骤存在。重采样与时间戳对齐预测前的数据整形对于预测分析预处理还需要解决真实时序数据中普遍存在的两个问题时间戳未对齐与采样频率不匹配。与之相对异常检测不受这两个问题影响因此跳过该步骤。问题一时间戳未对齐时间戳对齐由于数据生成设备或网关在赋值时间戳时并不能保证严格按照固定采样间隔真实时序数据的时间戳往往是不对齐的。例如采样频率为 1Hz 的序列其时间戳可能是[20:12:21.143, 20:12:22.187, 20:12:23.032, 20:12:24.384, 20:12:25.033]而预测返回的时间序列时间戳会严格对齐。例如请求预测两个点返回时间戳一定是[20:12:26.000, 20:12:27.000]因此上述输入序列必须先做时间戳对齐转换为[20:12:21.000, 20:12:22.000, 20:12:23.000, 20:12:24.000, 20:12:25.000]从底层实现看这种严格对齐的保证源于 TDgpt 的结果时间戳生成逻辑预测基类 base.py 与工具函数insert_ts_list()algo/forecast.py统一使用start_ts i * time_step公式生成结果序列时间戳其中start_ts预测起始时间戳对应请求参数starttime_step预测时间步长对应请求参数every且必须大于 0见 base.pyrows预测行数对应请求参数forecast_rows。参数映射关系在 algo/forecast.py 的add_forecast_params()中定义此外还支持conf置信区间默认 0.95、return_conf、prec时间精度默认ms、tz时区等可选参数。这正是文档所述预测返回的时间序列时间戳会严格对齐的实现依据。问题二输入频率高于输出频率数据重采样当用户输入时间序列的采样频率超过输出结果频率时需要重采样。例如输入序列采样间隔为 5 秒[20:12:20.000, 20:12:25.000, 20:12:30.000, 20:12:35.000, 20:12:40.000]而要求输出预测结果的采样间隔为 10 秒则重采样后作为预测输入的时间戳序列为[20:12:20.000, 20:12:30.000, 20:12:40.000]其中[20:12:25.000, 20:12:35.000]两个数据点被丢弃不参与预测。限制不支持缺失数据补齐需要特别注意的是预处理过程不支持缺失数据补齐操作。文档给出的典型场景如下假设输入时间序列为[20:12:10.113, 20:12:21.393, 20:12:29.143, 20:12:51.330]要求采样间隔为 10 秒重整对齐后的时间戳序列为[20:12:10.000, 20:12:20.000, 20:12:30.000, 20:12:50.000]由于该序列在 20:12:40 处存在明显的数据缺口且预处理不会补齐缺失点因此对该序列进行预测分析将返回错误。也就是说调用预测前应自行完成缺失数据的清洗TDgpt 的补全能力不在预处理范畴内需依赖其它手段例如业务侧数据清洗或独立的插补算法模块。与请求参数、测试用例的对应关系为了把上述机制落到实际调用这里将关键参数整理如下均以 TDgpt 分析请求 JSON 中的字段为准参数含义默认值说明wncheck是否执行白噪声检查1执行设为0可跳过 Ljung-Box 检验以节省计算资源start预测起始时间戳必填对应结果生成公式中的start_tsevery预测时间步长必填对应time_step必须大于 0forecast_rows预测行数必填对应rowsprec时间精度ms支持秒级到纳秒级精度conf置信区间0.95取值需在 0 与 1.0 之间见 base.pyreturn_conf是否返回置信区间1—tz结果时间戳时区本地时区—以上机制在仓库测试中均有覆盖白噪声判定逻辑由 unit_test.py 的test_is_white_noise用例验证同时构造了白噪声序列与非白噪声序列两组输入wncheck在 restful_api_test.py 中以0/1两种取值出现在多组 RESTful 请求样例中如 L268、L495、L1002 等用于验证开启/跳过白噪声检查时服务端的响应行为。总结TDgpt 的预处理机制可以用一句话概括先检验值不值得分析白噪声检查再整形以何种节奏分析时间戳对齐与重采样最终把一份干净、规整、对齐的序列交给具体算法。对使用者而言本文涉及的几个关键结论值得牢记白噪声序列会被直接拒绝错误消息white noise data not processed若业务上确定数据非白噪声可传wncheck0跳过检验以节省计算开销预测分析的结果时间戳严格按start_ts i * time_step对齐生成输入时间戳会自动对齐到该节奏因此不必也无法依赖输入时间戳的精确对齐当输入采样频率高于输出频率时多余数据点会被重采样丢弃反之缺失数据不会被补齐存在数据缺口的时间序列会导致预测报错需要在上游完成数据清洗。理解这些预处理细节有助于在使用 TDgpt 的预测与异常检测能力时准确预判请求行为、规避数据陷阱让分析结果更可信。【免费下载链接】TDengineHigh-performance, scalable time-series database designed for Industrial IoT (IIoT) scenarios项目地址: https://gitcode.com/GitHub_Trending/tde/TDengine创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考