PyOD 实战入门kNN 异常检测、模型组合与自适应阈值化的完整示例指南【免费下载链接】pyodA Python library for anomaly detection across tabular, time series, graph, text, image, and audio data. 60 detectors, benchmark-backed ADEngine orchestration, and an agentic workflow for AI agents.项目地址: https://gitcode.com/gh_mirrors/py/pyodPyOD 是一套面向表格、时序、图、文本、图像与音频数据的 Python 异常检测工具库其 examples 目录 提供了一整套可直接运行、可复现的入门示例。本文以官方示例文档 docs/example.rst 为核心骨架完整讲解其中最核心的三类实战场景——kNN 异常检测、多检测器输出组合Model Combination与基于 FILTER 的自适应阈值化并结合仓库源码剖析底层实现。读完本文你将掌握 PyOD 标准的数据生成、模型训练、结果评估、可视化以及提升模型稳健性的组合与阈值化技巧可以直接迁移到自己的异常检测任务中。示例概览从哪开始、如何运行仓库的 examples 目录 中存放了大量配套示例脚本每个脚本对应一个检测器或一项功能命名规则统一为模型名_example.py。本文涉及的三个核心脚本为脚本对应文档章节演示内容examples/knn_example.pykNN Example用 kNN 检测器完成生成数据 → 训练 → 预测 → 评估 → 可视化的完整流程examples/comb_example.pyModel Combination Example用 20 个不同 k 的 kNN 检测器组合打分比较 Average / Maximization / AOM / MOAexamples/threshold_example.pyThresholding Example将contaminationFILTER()接入检测器让阈值由算法自动确定这些示例脚本头部都有一段本地运行时的路径兼容代码sys.path.append(...)用于在 PyOD 尚未安装到环境中时把仓库根目录加入导入路径若已通过pip install pyod安装则无需该行。运行方式很简单在仓库根目录下直接执行即可python examples/knn_example.py python examples/comb_example.py python examples/threshold_example.pykNN 异常检测完整示例kNN 是异常检测中最直观的基线算法之一对每个样本将其到第 k 个最近邻的距离视为异常得分距离越远说明该点所在区域越稀疏、越可疑。PyOD 的 kNN 实现位于 pyod/models/knn.py完整示例见 examples/knn_example.py。第一步导入模型from pyod.models.knn import KNN # kNN detectorkNN 检测器通过pyod.models.knn.KNN导入它继承自 pyod/models/base.py 中的BaseDetector基类因此天然具备fit、predict、decision_function、labels_、decision_scores_、threshold_等统一接口。第二步生成合成样本数据PyOD 通过 pyod/utils/data.py 中的generate_data函数生成带标签的合成数据用于示例演示与算法验证from pyod.utils.data import generate_data contamination 0.1 # percentage of outliers n_train 200 # number of training points n_test 100 # number of testing points X_train, X_test, y_train, y_test generate_data( n_trainn_train, n_testn_test, contaminationcontamination)generate_data的核心参数依据 pyod/utils/data.py 源码如下n_train/n_test训练集与测试集样本数默认分别为 1000 与 500n_features特征维度默认 2便于可视化contamination异常比例取值在 (0, 0.5) 区间默认 0.1训练集与测试集中异常样本数分别为int(n_train * contamination)与int(n_test * contamination)train_only若为True则只返回X_train, y_train模型组合示例中即使用该模式offset调节高斯分布与均匀分布的取值区间默认 10behaviour返回顺序默认new返回X_train, X_test, y_train, y_test旧版old顺序已被弃用random_state随机种子示例脚本中固定为 42 以保证可复现。从源码看正常样本由多元高斯分布生成coef * random_state.randn(...) offset异常样本由均匀分布random_state.uniform(...)生成见 pyod/utils/data.py标签y中 0 表示内点、1 表示异常点。第三步初始化 kNN 检测器并完成训练与预测# train kNN detector clf_name KNN clf KNN() clf.fit(X_train) # get the prediction labels and outlier scores of the training data y_train_pred clf.labels_ # binary labels (0: inliers, 1: outliers) y_train_scores clf.decision_scores_ # raw outlier scores # get the prediction on the test data y_test_pred clf.predict(X_test) # outlier labels (0 or 1) y_test_scores clf.decision_function(X_test) # outlier scores # it is possible to get the prediction confidence as well y_test_pred, y_test_pred_confidence clf.predict(X_test, return_confidenceTrue) # outlier labels (0 or 1) and confidence in the range of [0,1]这里有几个关键概念clf.fit(X_train)是无监督拟合训练时完全不使用标签labels_是训练数据的二值标签0 内点 / 1 异常由threshold_作用于decision_scores_得到decision_scores_是训练数据的原始异常得分得分越高越异常predict(X_test)返回测试数据的二值标签decision_function(X_test)返回测试数据的原始异常得分predict(..., return_confidenceTrue)额外返回取值在 [0, 1] 的预测置信度。KNN的完整构造参数依据 pyod/models/knn.py 源码包括参数默认值说明contamination0.1数据集中异常比例用于拟合时确定decision_function的阈值n_neighbors5k 近邻查询的邻居数量methodlargest距离聚合方式largest取到第 k 个邻居的距离、mean取 k 个邻居的平均距离、median取 k 个邻居距离的中位数radius1.0radius_neighbors查询的参数空间范围algorithmauto近邻搜索算法auto/ball_tree/kd_tree/brutePyOD 已弃用该参数并统一使用 BallTreeleaf_size30BallTree 的叶子大小影响建树与查询速度及内存占用metricminkowski距离度量支持 sklearn 与 scipy 的全部距离函数p2Minkowski 距离的范数参数p1 即曼哈顿距离、p2 即欧氏距离n_jobs1近邻搜索的并行任务数-1 表示使用全部 CPU 核心三种method的底层实现可以在 pyod/models/knn.py 的_get_dist_by_method方法中看到largest取距离矩阵最后一列dist_arr[:, -1]mean对距离矩阵按行求均值median按行求中位数。fit内部先拟合NearestNeighbors再通过kneighbors计算每个样本到邻居的距离矩阵聚合后写入decision_scores_并调用_process_decision_scores()完成阈值计算。第四步用 ROC 与 Precision Rank n 评估PyOD 的evaluate_print工具函数会一次性打印两个核心指标——ROC 与 Precision Rank nfrom pyod.utils.data import evaluate_print # evaluate and print the results print(\nOn Training Data:) evaluate_print(clf_name, y_train, y_train_scores) print(\nOn Test Data:) evaluate_print(clf_name, y_test, y_test_scores)依据 pyod/utils/data.py 的实现evaluate_print内部使用roc_auc_scoreROC 曲线下面积与precision_n_scoresTop n 命中精度两个指标n 取实际异常样本数衡量的是得分最高的前 n 个样本中有多少确实是异常。它要求传入的是原始异常得分decision_scores_/decision_function的输出而非二值标签。在 examples/knn_example.py 中运行可得到类似输出On Training Data: KNN ROC:1.0, precision rank n:1.0 On Test Data: KNN ROC:0.9989, precision rank n:0.9训练集上 ROC 达到 1.0、Precision rank n 达到 1.0说明 kNN 对合成数据几乎可以完美区分内点与异常点。第五步可视化训练与测试结果所有示例脚本都内置了visualize可视化函数from pyod.utils.example import visualize visualize(clf_name, X_train, y_train, X_test, y_test, y_train_pred, y_test_pred, show_figureTrue, save_figureFalse)visualize的实现位于 pyod/utils/example.py它会生成 2×2 的四个子图训练集真实标签、训练集预测标签、测试集真实标签、测试集预测标签蓝/绿表示内点、橙/红三角表示异常点。注意该函数要求输入数据为二维n_features2否则会抛出ValueErrorshow_figure控制是否弹窗展示save_figureTrue时会以clf_name.png保存到当前目录300 dpi。模型组合示例让检测结果更稳健异常检测本质上是无监督任务单一模型对数据的假设密度、距离、分布形状等往往带来不稳定性。PyOD 官方建议将多个检测器的输出进行组合例如取平均来提升稳健性这属于异常集成outlier ensembles的范畴。完整示例见 examples/comb_example.py配套的 Jupyter Notebook 为 notebooks/Model Combination.ipynb。四种分数组合机制示例演示了四种分数组合方式它们都接收形状为(n_samples, n_estimators)的得分矩阵返回形状为(n_samples,)的组合得分Average平均对所有检测器的得分取平均Maximization最大化取所有检测器得分的最大值Average of MaximumAOM先将基检测器分成若干子组对每个子组取最大得分作为子组得分最后对所有子组得分取平均Maximum of AverageMOA先将基检测器分成若干子组对每个子组取平均得分作为子组得分最后对所有子组得分取最大值。第一步导入与加载数据from pyod.models.knn import KNN # kNN detector from pyod.models.combination import aom, moa, average, maximization from pyod.utils.data import generate_data X, y generate_data(train_onlyTrue) # load datagenerate_data(train_onlyTrue)只返回X_train, y_train。在 examples/comb_example.py 中数据加载逻辑更完整它会优先尝试读取 examples/data/cardio.mat 真实数据集文件缺失时自动回退到generate_data(train_onlyTrue)生成的合成数据随后用train_test_split(X, y, test_size0.4)划分训练与测试集。第二步初始化 20 个不同 k 的 kNN 基检测器# initialize 20 base detectors for combination k_list [10, 20, 30, 40, 50, 60, 70, 80, 90, 100, 110, 120, 130, 140, 150, 160, 170, 180, 190, 200] n_clf len(k_list) # Number of classifiers being trained train_scores np.zeros([X_train.shape[0], n_clf]) test_scores np.zeros([X_test.shape[0], n_clf]) for i in range(n_clf): k k_list[i] clf KNN(n_neighborsk, methodlargest) clf.fit(X_train_norm) train_scores[:, i] clf.decision_scores_ test_scores[:, i] clf.decision_function(X_test_norm)这里构建了 20 个 kNN 基检测器k 从 10 变化到 200均匀覆盖不同的邻域尺度。每个检测器的decision_scores_与decision_function(X_test_norm)分别写入得分矩阵的一列最终得到train_scores与test_scores两个(n_samples, 20)的得分矩阵。组合的多样性来自 k 的差异k 越小越敏感于局部密度变化k 越大越关注全局结构二者互补。第三步得分标准化——组合前至关重要的一步不同检测器输出的得分量纲与分布并不一致直接组合会使某个高分模型的输出主导结果。因此在组合前必须将得分标准化为零均值、单位方差from pyod.utils.utility import standardizer # scores have to be normalized before combination train_scores_norm, test_scores_norm standardizer(train_scores, test_scores)standardizer的实现见 pyod/utils/utility.py它在训练得分矩阵上拟合 sklearn 的StandardScalerZ-score 标准化然后用同一个标定器转换测试得分矩阵保证训练与测试处于同一尺度。keep_scalarTrue时可以额外返回标定器对象以便复用。第四步应用四种组合算法comb_by_average average(test_scores_norm) comb_by_maximization maximization(test_scores_norm) comb_by_aom aom(test_scores_norm, 5) # 5 groups comb_by_moa moa(test_scores_norm, 5) # 5 groups四种组合函数都定义在 pyod/models/combination.py 中底层封装了combo库需pip install combo的同名实现aom(scores, n_buckets5, methodstatic, bootstrap_estimatorsFalse, random_stateNone)n_buckets为子组数量默认 5methoddynamic时子组大小随机、支持有放回抽样bootstrap_estimatorsTrue并可用random_state固定随机性见 pyod/models/combination.pymoa(...)参数与aom完全一致见 pyod/models/combination.pyaverage(scores, estimator_weightsNone)支持传入权重实现加权平均见 pyod/models/combination.pymaximization(scores)逐样本取最大值见 pyod/models/combination.py。此外 pyod/models/combination.py 还提供了median取中位数与majority_vote多数投票默认二分类两种组合方式示例脚本中也会一并评估median的结果。第五步评估组合效果evaluate_print(Combination by Average, y_test, comb_by_average) evaluate_print(Combination by Maximization, y_test, comb_by_maximization) evaluate_print(Combination by AOM, y_test, comb_by_aom) evaluate_print(Combination by MOA, y_test, comb_by_moa)在 examples/comb_example.py 的注释输出中组合 20 个 kNN 检测器后AOM 与 MOA 的 ROC 表现通常优于单一模型的简单平均示例输出示例如下Combining 20 kNN detectors Combination by Average ROC:0.9194, precision rank n:0.4531 Combination by Maximization ROC:0.9198, precision rank n:0.4688 Combination by AOM ROC:0.9257, precision rank n:0.4844 Combination by MOA ROC:0.9263, precision rank n:0.4688注意这些数字依赖具体数据集与划分方式更重要的是对比四种机制的相对表现分桶策略AOM / MOA通过组内取极值、组间聚合的方式兼顾了多样性保持与噪声抑制在示例中往往能取得更优的 ROC。该流程对任意 PyOD 检测器都成立——只需把KNN换成其他检测器类收集各自得分后标准化、组合、评估即可。阈值化示例用 FILTER 自动确定异常判定阈值传统做法中检测器的contamination参数需要手动指定异常比例模型据此把得分最高的n_samples * contamination个样本标记为异常。但当真实异常比例未知或分布形态复杂时这个假设并不可靠。PyOD 支持传入阈值化器对象替代浮点数contamination让阈值由算法从得分分布中自动推断。完整示例见 examples/threshold_example.py官方文档使用 kNN 演示仓库脚本则以 KDE 检测器为例二者接口完全一致from pyod.models.knn import KNN # kNN detector from pyod.models.thresholds import FILTER # Filter thresholder contamination 0.1 # percentage of outliers n_train 200 # number of training points n_test 100 # number of testing points X_train, X_test, y_train, y_test generate_data( n_trainn_train, n_testn_test, contaminationcontamination) # train kNN detector and apply FILTER thresholding clf_name KNN clf KNN(contaminationFILTER()) clf.fit(X_train) # get the prediction labels and outlier scores of the training data y_train_pred clf.labels_ # binary labels (0: inliers, 1: outliers) y_train_scores clf.decision_scores_ # raw outlier scores关键差异仅在一处KNN(contaminationFILTER())。检测器在fit阶段不再按固定分位数切分而是把decision_scores_交给FILTER阈值化器计算thresh_得分超过该阈值的样本被判为异常。FILTER的定义见 pyod/models/thresholds.py底层基于pythresh库需pip install pythresh核心参数包括method默认savgol可选gaussian高斯滤波、savgolSavitzky-Golay 滤波、hilbert希尔伯特滤波、wiener维纳滤波、medfilt中值滤波、decimate降采样、detrend去趋势、resample重采样sigma默认auto自动取len(scores) * np.std(scores)含义随滤波类型不同而变化——对gaussian是高斯核标准差对savgol是滤波窗口大小对medfilt是核大小对decimate是降采样因子等。阈值化器家族一览PyOD 的 pyod/models/thresholds.py 还封装了二十余种来自pythresh的阈值化器全部以contamination阈值化器()的形式接入任意检测器常见选项包括阈值化器原理概要FILTER对得分做信号滤波后取最大值作为阈值IQR四分位距法第三四分位数 1.5×IQRMAD中位数绝对偏差法ZSCOREz 分数大于 1 即判为异常AUCP基于 KDE 曲线下面积的非参数方法BOOT自助抽样置信区间法支持random_state参数CLUST聚类法未归属主簇即异常支持十余种聚类算法method参数GESD广义极端学生化偏差检验支持max_outliers与alphaOCSVM用单类 SVM 学习阈值支持poly/sgd两种模型VAE变分自编码器法支持epochs、batch_size、loss等训练参数这些阈值化器不依赖对异常比例的预设适合标签稀少或分布未知的真实场景。选择建议数据近似单峰分布时IQR、ZSCORE简单高效得分分布复杂、存在多模态时FILTER、AUCP、CLUST这类非参数方法通常更稳健追求统计显著性检验时可选GESD、MAD。总结与进一步探索本文围绕官方示例文档 docs/example.rst 的三条主线展开kNN 示例展示了 PyOD 标准五步流程导入 → 生成数据 → 训练预测 → 评估 → 可视化模型组合示例展示了通过 Average / Maximization / AOM / MOA 聚合多个异构检测器来提升稳健性的完整工程路径阈值化示例展示了用FILTER等阈值化器替代固定contamination的自适应判定方案。三者的底层实现分别可追溯至 pyod/models/knn.py、pyod/models/combination.py、pyod/models/thresholds.py 与 pyod/utils 工具集。如果想继续深入可以关注仓库中的其他资源examples 目录下还有 60 余个检测器示例脚本如 examples/iforest_example.py、examples/lof_example.py、examples/ecod_example.py接口与本文完全一致换类即可复用整套流程notebooks 目录提供了 Benchmark、Compare All Models、Model Combination 等交互式 Notebook便于逐格运行与对比pyod/test 目录下的test_knn.py、test_combination.py、test_thresholds.py等测试用例可以作为接口行为与边界条件的权威参考评估指标precision_n_scores的实现细节可查阅 pyod/utils/utility.py合成数据生成函数generate_data_clusters支持低密度模式与全局异常等困难场景可查阅 pyod/utils/data.py。【免费下载链接】pyodA Python library for anomaly detection across tabular, time series, graph, text, image, and audio data. 60 detectors, benchmark-backed ADEngine orchestration, and an agentic workflow for AI agents.项目地址: https://gitcode.com/gh_mirrors/py/pyod创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考