ykus4/hazure
GitHub: ykus4/hazure
hazure 是一个轻量级的时间序列异常检测工具包，通过规则和无监督方法自动学习正常模式并定位异常时间段。
Stars: 0 | Forks: 0
# hazure
你有一个指标 —— 每秒请求数、队列深度、传感器读数 —— 你怀疑它偶尔会表现异常，但你没有记录它何时发生过。
`hazure` 负责找出那些时刻：基于规则和无监督的检测器会从序列本身学习何为“正常”，并指出它在何处偏离了正常状态。
任何带有时间轴的 pandas、polars 或 pyarrow 对象都可以作为输入，并且输出结果也会保持相同的数据格式。在运行时，它只需要 `narwhals` 和 `numpy`，别无其他；所有较重的依赖都是可选的，由需要它的算法进行延迟导入。
```
pip install hazure[pandas]
```
```
import numpy as np
import pandas as pd
from hazure.detection import SeasonalDetector
from hazure.events import to_events
# 带有每日规律的每小时流量——以及一个出错的下午。
rng = np.random.default_rng(0)
index = pd.date_range("2024-03-01", periods=24 * 21, freq="h", name="time")
daily = 40 * np.sin(2 * np.pi * np.arange(len(index)) / 24)
traffic = pd.Series(100 + daily + rng.normal(0, 3, len(index)), index=index, name="rps")
traffic.iloc[300:306] = 20.0
labels = SeasonalDetector(period=24).fit_detect(traffic)
print(to_events(labels))
# Events([2024-03-13T12:00:00..2024-03-13T17:59:59.999999999])
```
`labels` 置于 `traffic` 自身的索引上 —— `1.0` 表示异常，`0.0` 表示正常，`NaN` 表示未知 —— 并且标记出的六个小时正好是当初植入的那六个小时。
一切构建块都归属于五种可组合的组件类型之一（`Scorer`、`Threshold`、`Detector`、`Aggregator`、`Transformer`），通过 `Pipeline` 进行链式组合，并在模型出现分支时使用 `Graph` 进行组装。
## 针对仍在持续接收的数据序列
在一段你愿意称之为正常的时期内进行一次拟合，然后随着新观测的到来不断输入它们。`Stream` 会在近期历史的缓存上运行*相同的*已拟合组件，因此在线处理的结果就是批量处理的结果，而不是它的第二种实现 —— 并且 `prime` 如果发现缓存对于组件需要回顾的历史来说太短，就会拒绝启动，而不是在从未填满的窗口上默默进行计算。
```
from hazure import Stream
detector = SeasonalDetector(period=24).fit(traffic)
stream = Stream(detector, history=48).prime(traffic)
stream.update("2024-03-22T00:00", 105.0) # in line with the fortnight -> 0.0
stream.update("2024-03-22T01:00", 12.0) # not in line with it -> 1.0
```
## 在何处划定界限
每个阈值都由*某种参数*决定，而这些参数中没有一个是“我想要的答案”。这里有两种方法来获得答案。`PotThreshold` 直接采用误报概率 —— 它将广义 Pareto 分布拟合到训练分数的尾部，因此可以将边界设置在超越概率为 `1e-4` 的位置，超越了以往观测到的最大分数。此外，`budget_threshold` 完全不需要任何标签：只需告知它一周内任何人愿意阅读的警报数量，它就会在条件允许的范围内尽可能低地划定边界，绝不过火。
## 文档
标签：Python, 代码示例, 基准测试, 开源库, 异常检测, 搜索引擎爬虫, 数据分析, 无后门, 无监督学习, 时间序列, 逆向工具