企业官网建设流程全解析

• 人工智能
• 大模型
• 低代码
• 计算机视觉
• 深度学习
• 模型推理服务

时序异常检测用于识别时序数据中不符合预期模式、趋势或周期性规律的异常点或异常时段，这类异常可能由系统故障、外部冲击、数据录入错误或罕见事件引发，对及时响应、风险评估与业务决策至关重要。本文以 PaddleX 的时序异常检测模块为主线，完整覆盖支持模型清单与性能数据、基于create_model的快速推理集成、结果对象处理方法，以及从数据校验、格式转换、模型训练、评估到推理部署的二次开发全流程，并结合仓库源码说明底层预处理与后处理原理，帮助你直接上手将该模块集成进自己的项目。

一、模块概述与能力边界

PaddleX 将时序异常检测封装为独立的单模型推理模块，用户只需几行 Python 代码即可完成推理，也可以基于官方模型进行二次开发以追求更高精度。模块底层以 PaddleTS 生态为基础（训练需要安装 PaddleTS 插件），推理侧则由 PaddleX 的推理框架统一调度。

从源码结构看，该模块的推理链路主要由以下文件构成：

• 推理预测器：paddlex/inference/models/ts_anomaly_detection/predictor.py，其中定义了TSAdRunnerPredictor，负责构建预处理与后处理流水线；
• 后处理逻辑：paddlex/inference/models/ts_anomaly_detection/processors.py，包含GetAnomaly，将模型重建误差与阈值比较输出 0/1 异常标签；
• 结果对象：paddlex/inference/models/ts_anomaly_detection/result.py，定义TSAdResult，支持打印、保存 CSV/JSON 及可视化。

二、支持模型列表与性能参考

PaddleX 时序异常检测模块目前内置以下官方模型（推理耗时仅包含模型推理耗时，不包含前后处理耗时）：

上表中 recall / f1_score 的“A / B”格式为两种异常判定口径下的取值，实际以官方发布的模型详情为准。

测试环境说明：

• 性能测试环境
  • 测试数据集：PSM 数据集，时序输入长度为 100；
  • 硬件配置：GPU 为 NVIDIA Tesla T4，CPU 为 Intel Xeon Gold 6271C @ 2.60GHz；
  • 软件环境：Ubuntu 20.04 / CUDA 11.8 / cuDNN 8.9 / TensorRT 8.6.1.6，paddlepaddle 3.0.0 / paddlex 3.0.3。
• 推理模式说明

需要说明的是，上述指标来自官方文档给出的特定软硬件环境，实际效果会随数据与设备环境变化，应以自己环境中的实测为准。

三、快速集成：几行代码完成时序异常检测

3.1 环境准备与示例数据

在快速集成前，请先安装 PaddleX 的 wheel 包，详细请参考 PaddleX 本地安装教程。安装完成后，还需要下载示例数据 ts_ad.csv 到本地。

3.2 最小推理示例

from paddlex import create_model model = create_model(model_name="AutoEncoder_ad") output = model.predict("ts_ad.csv", batch_size=1) for res in output: res.print() res.save_to_csv(save_path="./output/") res.save_to_json(save_path="./output/res.json")

运行后，得到的结果为：

{'res': {'input_path': 'ts_ad.csv', 'anomaly': label timestamp 220226 1 220227 1 220228 0 220229 1 220230 1 ... ... 220317 1 220318 1 220319 1 220320 1 220321 1 [96 rows x 1 columns]}}

运行结果参数含义如下：

• input_path：表示输入待预测异常的时序文件路径；
• anomaly：表示时序异常检测结果，1 表示预测异常，0 表示预测正常，可以通过res.save_to_csv()将预测结果保存为 csv 文件，通过res.save_to_json()将预测结果保存为 json 文件。

从推理实现来看，TSAdRunnerPredictor.process() 返回的字典正是input_path、input_ts与anomaly三个键，与上述输出一一对应。

3.3 create_model 参数说明

create_model用于实例化时序异常检测模型（文档中以AutoEncoder_ad为例，你也可以自由切换该模块下任意模型），具体说明如下：

其中，model_name必须指定。指定model_name后，默认使用 PaddleX 内置的模型参数；在此基础上再指定model_dir时，则使用用户自定义的模型。

3.4 predict() 方法参数说明

调用时序异常检测模型的predict()方法进行推理预测，参数有input和batch_size，具体说明如下：

3.5 预测结果处理：方法与属性

每个样本的预测结果均为对应的 Result 对象，支持打印、保存为 csv 文件、保存为 json 文件等操作：

此外，也支持通过属性获取带结果的可视化时序和预测结果：

在源码层面，TSAdResult 继承了BaseTSResult，其_to_csv()直接返回anomaly对应的 DataFrame；同时提供了基于 matplotlib 的visualize()函数，可绘制带异常标注的时序阶梯图（标题为 "Time Series Anomaly Detection"），将检测结果可视化输出为图片。

关于更多 PaddleX 单模型推理的 API 使用方法，可以参考 PaddleX 单模型 Python 脚本使用说明。

四、二次开发：训练更高精度的异常检测模型

如果你追求更高精度的现有模型，可以使用 PaddleX 的二次开发能力，开发更好的时序异常检测模型。在使用 PaddleX 开发时序异常模型之前，请务必安装 PaddleTS 插件，安装过程可以参考 PaddleX 本地安装教程。

4.1 数据准备

在进行模型训练前，需要准备相应任务模块的数据集。PaddleX 针对每一个模块提供了数据校验功能，只有通过数据校验的数据才可以进行模型训练。此外，PaddleX 为每一个模块都提供了 Demo 数据集，你可以基于官方提供的 Demo 数据完成后续的开发。若希望用私有数据集进行后续的模型训练，可以参考 PaddleX 时序异常检测任务模块数据标注教程。

4.1.1 Demo 数据下载

可以参考下面的命令将 Demo 数据集下载到指定文件夹：

wget https://paddle-model-ecology.bj.bcebos.com/paddlex/data/ts_anomaly_examples.tar -P ./dataset tar -xf ./dataset/ts_anomaly_examples.tar -C ./dataset/

从 PaddleTS_api/ts_ad/config.py 的_make_custom_dataset_config可以看出，时序异常检测数据集（TSADDataset）要求目录内包含train.csv与val.csv两个标注文件，这也是数据校验的基本格式约束。

4.1.2 数据校验

一行命令即可完成数据校验：

python main.py -c paddlex/configs/modules/ts_anomaly_detection/AutoEncoder_ad.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/ts_anomaly_examples

执行上述命令后，PaddleX 会对数据集进行校验，并统计数据集的基本信息，命令运行成功后会在 log 中打印出Check dataset passed !信息。校验结果文件保存在./output/check_dataset_result.json，同时相关产出会保存在当前目录的./output/check_dataset目录下，产出目录中包括示例时序序列。

校验结果文件具体内容为：

{ "done_flag": true, "check_pass": true, "attributes": { "train_samples": 22032, "train_table": [ [ "timestamp", "feature_0", "...", "feature_24", "label" ], [ 0.0, 0.7326893750079723, "...", 0.1382488479262673, 0.0 ] ], "val_samples": 198290, "val_table": [ [ "timestamp", "feature_0", "...", "feature_24", "label" ], [ 22032.0, 0.8604795809835284, "...", 0.1428571428571428, 0.0 ] ] }, "analysis": { "histogram": "" }, "dataset_path": "./dataset/ts_anomaly_examples", "show_type": "csv", "dataset_type": "TSADDataset" }

上述校验结果中，check_pass为True表示数据集格式符合要求，其他部分指标的说明如下：

• attributes.train_samples：该数据集训练集样本数量为 22032；
• attributes.val_samples：该数据集验证集样本数量为 198290；
• attributes.train_table：该数据集训练集样本示例数据前 10 行信息；
• attributes.val_table：该数据集验证集样本示例数据前 10 行信息。

注：只有通过数据校验的数据才可以训练和评估。从示例数据可以看到，时序异常检测数据集的列结构通常为timestamp（时间列）+feature_0...feature_N（特征列）+label（异常标签列，异常点为 1、正常点为 0）。

4.1.3 数据集格式转换 / 数据集划分（可选）

在完成数据校验之后，可以通过修改配置文件或是追加超参数的方式对数据集的格式进行转换，也可以对数据集的训练/验证比例进行重新划分。

（1）数据集格式转换

时序异常检测支持将xlsx和xls格式的数据集转换为csv格式。数据集校验相关的参数可以通过修改配置文件中CheckDataset下的字段进行设置：

• CheckDataset:
  • convert:
    • enable：是否进行数据集格式转换，支持xlsx和xls格式的数据集转换为 CSV 格式，默认为False；
    • src_dataset_type：如果进行数据集格式转换，无需设置源数据集格式，默认为null。

若要开启格式转换，修改配置如下：

CheckDataset: ...... convert: enable: True src_dataset_type: null ......

随后执行命令：

python main.py -c paddlex/configs/modules/ts_anomaly_detection/AutoEncoder_ad.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/ts_anomaly_examples

以上参数同样支持通过追加命令行参数的方式进行设置：

python main.py -c paddlex/configs/modules/ts_anomaly_detection/AutoEncoder_ad.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/ts_anomaly_examples \ -o CheckDataset.convert.enable=True

（2）数据集划分

数据集重新划分相关参数同样位于CheckDataset下：

• CheckDataset:
  • convert:
    • enable：是否进行数据集格式转换，为True时进行数据集格式转换，默认为False；
    • src_dataset_type：如果进行数据集格式转换，时序异常检测仅支持将 xlsx 标注文件转换为 csv，无需设置源数据集格式，默认为null；
  • split:
    • enable：是否重新划分数据集，为True时进行数据集划分，默认为False；
    • train_percent：如果重新划分数据集，需设置训练集的百分比，类型为 0-100 之间的任意整数，需要保证与val_percent的值之和为 100；
    • val_percent：如果重新划分数据集，需设置验证集的百分比，类型为 0-100 之间的任意整数，需要保证与train_percent的值之和为 100。

例如，你想重新划分数据集为训练集占比 90%、验证集占比 10%，则需将配置文件修改为：

CheckDataset: ...... split: enable: True train_percent: 90 val_percent: 10 ......

随后执行命令：

python main.py -c paddlex/configs/modules/ts_anomaly_detection/AutoEncoder_ad.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/ts_anomaly_examples

数据划分执行之后，原有标注文件会被在原路径下重命名为xxx.bak。以上参数同样支持通过追加命令行参数的方式进行设置：

python main.py -c paddlex/configs/modules/ts_anomaly_detection/AutoEncoder_ad.yaml \ -o Global.mode=check_dataset \ -o Global.dataset_dir=./dataset/ts_anomaly_examples \ -o CheckDataset.split.enable=True \ -o CheckDataset.split.train_percent=90 \ -o CheckDataset.split.val_percent=10

4.2 模型训练

一条命令即可完成模型的训练，此处以时序异常检测模型（AutoEncoder_ad）的训练为例：

python main.py -c paddlex/configs/modules/ts_anomaly_detection/AutoEncoder_ad.yaml \ -o Global.mode=train \ -o Global.dataset_dir=./dataset/ts_anomaly_examples

需要如下几步：

• 指定模型的.yaml配置文件路径（此处为AutoEncoder_ad.yaml，训练其他模型时，需要指定相应的配置文件，模型和配置文件的对应关系可以查阅 PaddleX 模型列表（CPU/GPU））；
• 指定模式为模型训练：-o Global.mode=train；
• 指定训练数据集路径：-o Global.dataset_dir；
• 其他相关参数均可通过修改.yaml配置文件中的Global和Train下的字段来进行设置，也可以通过在命令行中追加参数来调整。如指定前 2 卡 GPU 训练：-o Global.device=gpu:0,1；设置训练轮次数为 10：-o Train.epochs_iters=10。更多可修改的参数及其详细解释，可以查阅 PaddleX 时序任务模型配置文件参数说明。

以仓库自带的 AutoEncoder_ad.yaml 为例，训练相关的核心字段包括：

新特性：Paddle 3.0 版本支持了 CINN 神经网络编译器，在使用 GPU 设备训练时，不同模型有不同程度的训练加速效果。在 PaddleX 中训练模型时，可通过指定参数-o Train.dy2st=True开启。

更多说明：

• 模型训练过程中，PaddleX 会自动保存模型权重文件，默认为output，如需指定保存路径，可通过配置文件中-o Global.output字段进行设置；
• PaddleX 对用户屏蔽了动态图权重和静态图权重的概念。在模型训练的过程中，会同时产出动态图和静态图的权重，在模型推理时，默认选择静态图权重推理；
• 在完成模型训练后，所有产出保存在指定的输出目录（默认为./output/）下，通常有以下产出：
  • train_result.json：训练结果记录文件，记录了训练任务是否正常完成，以及产出的权重指标、相关文件路径等；
  • train.log：训练日志文件，记录了训练过程中的模型指标变化、loss 变化等；
  • config.yaml：训练配置文件，记录了本次训练的超参数配置；
  • best_accuracy.pdparams.tar、scaler.pkl、.checkpoints、.inference：模型权重相关文件，包括网络参数、优化器、EMA、静态图网络参数、静态图网络结构等。

4.3 模型评估

在完成模型训练后，可以对指定的模型权重文件在验证集上进行评估，验证模型精度。使用 PaddleX 进行模型评估，一条命令即可完成：

python main.py -c paddlex/configs/modules/ts_anomaly_detection/AutoEncoder_ad.yaml \ -o Global.mode=evaluate \ -o Global.dataset_dir=./dataset/ts_anomaly_examples

与模型训练类似，需要如下几步：

• 指定模型的.yaml配置文件路径（此处为AutoEncoder_ad.yaml）；
• 指定模式为模型评估：-o Global.mode=evaluate；
• 指定验证数据集路径：-o Global.dataset_dir。

其他相关参数均可通过修改.yaml配置文件中的Global和Evaluate下的字段来进行设置，详细请参考 PaddleX 时序任务模型配置文件参数说明。

更多说明：

• 在模型评估时，需要指定模型权重文件路径，每个配置文件中都内置了默认的权重保存路径（如Evaluate.weight_path: "output/best_model/model.pdparams"），如需要改变，只需通过追加命令行参数的形式进行设置即可，如-o Evaluate.weight_path=./output/best_model/model.pdparams；
• 在完成模型评估后，会产出evaluate_result.json，其记录了评估的结果，具体来说，记录了评估任务是否正常完成，以及模型的评估指标，包含f1、recall和precision。

4.4 模型推理与模型集成

在完成模型的训练和评估后，即可使用训练好的模型权重进行推理预测或者进行 Python 集成。

4.4.1 模型推理

通过命令行的方式进行推理预测，只需如下一条命令。运行前请下载示例数据到本地：

python main.py -c paddlex/configs/modules/ts_anomaly_detection/AutoEncoder_ad.yaml \ -o Global.mode=predict \ -o Predict.model_dir="./output/inference" \ -o Predict.input="ts_ad.csv"

与模型训练和评估类似，需要如下几步：

• 指定模型的.yaml配置文件路径（此处为AutoEncoder_ad.yaml）；
• 指定模式为模型推理预测：-o Global.mode=predict；
• 指定模型权重路径：-o Predict.model_dir="./output/inference"；
• 指定输入数据路径：-o Predict.input="..."。

其他相关参数均可通过修改.yaml配置文件中的Global和Predict下的字段来进行设置，详细请参考 PaddleX 时序任务模型配置文件参数说明。

4.4.2 模型集成

模型可以直接集成到 PaddleX 产线中，也可以直接集成到你自己的项目中。

1. 产线集成

时序异常检测模块可以集成的 PaddleX 产线有时序异常检测，只需要替换模型路径即可完成时序异常检测的模型更新。在产线集成中，你可以使用服务化部署来部署你得到的模型。仓库中也提供了对应的产线 API 示例，可参考 api_examples/pipelines/test_ts_anomaly_detection.py，其中通过create_pipeline(pipeline="ts_anomaly_detection")创建产线并调用pipeline.predict("./test_samples/ts_ad.csv")完成推理。

2. 模块集成

你产出的权重可以直接集成到时序异常检测模块中，可以参考快速集成的 Python 示例代码，只需要将模型替换为你训练得到的模型路径即可，即通过create_model(model_name="AutoEncoder_ad", model_dir="你的模型路径")指定自定义模型。

你也可以利用 PaddleX 高性能推理插件来优化模型的推理过程，进一步提升效率，详细的流程请参考 PaddleX 高性能推理指南。

五、推理链路源码解读：异常标签是怎么算出来的

为帮助理解模型输出的含义，这里结合源码对推理链路做一次透视。在 TSAdRunnerPredictor._build() 中，预处理阶段按顺序构建了以下算子：

1. ReadTS：读取输入时序文件；
2. TSCutOff：按size（即input_len）对时序序列做截断切分；
3. TSNormalize（可选）：读取模型目录下的scaler.pkl对序列做归一化，若找不到该文件会直接报错；
4. BuildTSDataset：按info_params构建模型输入数据集；
5. TimeFeature（可选）：按time_feat配置生成时间特征；
6. TStoArray/TStoBatch：将数据转为数组并组织为 batch，随后交给runner执行模型推理。

推理完成后进入后处理算子GetAnomaly（见 paddlex/inference/models/ts_anomaly_detection/processors.py）。其核心逻辑是：对每个时间点计算模型重建/预测值与原始序列的均方误差作为异常分数anomaly_score = mean((pred - ts)^2)，再将异常分数与模型阈值model_threshold比较，anomaly_score >= model_threshold的点标记为 1（异常），否则为 0（正常），最终以timestamp为索引、label为列名输出异常标签 DataFrame——这正是快速集成示例中anomaly字段的由来。理解这一点有助于你调整model_threshold相关的敏感性：阈值越低，越容易把正常点误判为异常，反之则越容易漏报。

至此，从模型选型、快速推理、结果处理，到数据准备、训练、评估、推理部署与源码原理，PaddleX 时序异常检测模块的完整使用路径已全部打通，你可以据此直接在自己的业务数据上开展异常检测实验与落地。

• 人工智能
• 大模型
• 低代码
• 计算机视觉
• 深度学习
• 模型推理服务