Ummmahek/github-behaviour-anomaly-detection-

# github-behaviour-anomaly-detection- 一个端到端的机器学习系统，用于从 GitHub Archive 事件流中检测异常用户行为。 该项目展示了一个生产风格的机器学习流水线，包括 ETL、特征工程、模型训练、实验跟踪以及通过 API 进行实时推理。 特性 端到端 ML 流水线（ETL → 特征 → 模型 → API） 基于时间的行为异常检测 滚动统计、Z 分数归一化与尖峰检测 用于无监督异常检测的 IsolationForest MLflow 实验跟踪 + 超参数调优 用于实时与批量推理的 FastAPI 用于评估的合成数据生成 模块化、可生产的代码结构 🧱 项目结构 github-behavior-anomaly-detection/ ├── src/ │ ├── etl/ # 数据摄取与解析 │ ├── features/ # 特征工程 │ ├── training/ # 模型训练与调优 │ └── serving/ # FastAPI 推理 API ├── data/ # 原始与处理后的数据 ├── models/ # 保存的模型 ├── notebooks/ # 探索（可选） ├── configs/ # 配置文件 ├── tests/ # 单元测试 ├── README.md └── requirements.txt ⚙️ 流水线概述 GitHub Archive (JSON) ↓ ETL + 采样 ↓ 特征工程 (滚动均值、Z 分数、尖峰、差分) ↓ 孤立森林模型 ↓ MLflow 跟踪 ↓ FastAPI (/predict, /predict/batch) 🧠 特征工程 rolling_mean → 用户行为基线 diff → 相对于基线的偏差 spike → 归一化偏差 z_score → 用户级归一化 hour → 时间上下文 🤖 模型 算法：孤立森林 类型：无监督异常检测 污染率：0.005 将异常检测为相对于历史用户行为的偏差，而非绝对活动。 📊 实验跟踪（MLflow） 记录多次训练运行 超参数调优（20+ 次运行） 使用 MLflow UI 比较模型 基于异常稳定性选择最佳配置 运行： mlflow ui 打开：http://localhost:5000 🌐 API（FastAPI） 启动服务： uvicorn src.serving.app:app --reload 打开文档： http://127.0.0.1:8000/docs 🔹 单次预测 POST /predict { "z_score": 2.0, "spike": 1.5, "diff": 4000, "hour": 9 } 🔹 批量预测 POST /predict/batch { "records": [ {"z_score": 0.1, "spike": 0.2, "diff": 30, "hour": 10}, {"z_score": 2.5, "spike": 1.8, "diff": 5000, "hour": 3} ] } 📈 评估策略 由于异常检测是无监督的： 行为验证（检查异常） 合成异常注入 分数分布分析 ⚠️ 限制 有限的时间窗口（仅数小时数据） 部分用户活动稀疏 真实数据缺乏ground-truth标签 💡 关键收获 构建生产 ML 流水线 处理时序行为数据 设计无监督评估策略 通过 API 提供 ML 模型服务 实验跟踪与模型比较 🏁 结论 该项目展示了如何超越模型训练，迈向完整的 ML 系统设计，包括部署、监控与实验。 # GitHub 活动异常检测 一个端到端的机器学习系统，用于检测 GitHub Archive 事件数据中的异常用户行为。 旨在展示一个生产 ML 流水线：ETL → 特征工程 → 模型训练 → 服务 → 监控。 \--- ## 项目结构 ``` github-anomaly-detection/ ├── notebooks/ # Exploratory analysis and prototyping ├── src/ │ ├── etl/ # Data download, parsing, sampling │ ├── features/ # Feature engineering (rolling stats, z-scores, spikes) │ ├── training/ # Model training, evaluation, MLflow logging │ └── serving/ # FastAPI inference endpoint ├── tests/ # Unit tests for each module ├── configs/ # Hyperparameters and pipeline config (YAML) ├── models/ # Saved model artifacts (git-ignored) ├── docs/ # Architecture diagrams, design notes ├── Dockerfile ├── requirements.txt └── README.md ``` \--- ## 快速开始 ``` # 1. 安装依赖 pip install -r requirements.txt # 2. 下载数据（10 小时 GitHub Archive） python src/etl/download.py --hours 10 --date 2024-01-01 # 3. 构建特征 python src/features/build_features.py # 4. 训练模型 python src/training/train.py # 5. 提供预测 uvicorn src.serving.app:app --reload # POST http://localhost:8000/predict ``` \--- ## 流水线概览 ``` GH Archive (raw .json.gz) │ ▼ ETL / sampling ← reservoir sampling, 80k events │ ▼ Feature engineering ← rolling mean, z-score, spike, diff, hour │ ▼ IsolationForest ← contamination=0.005, 4 features │ ▼ MLflow experiment log ← params, metrics, model artifact │ ▼ FastAPI /predict ← real-time and batch inference ``` \--- ## 关键设计决策 | 决策 | 选择 | 原因 | |------|------|------| | 异常算法 | IsolationForest | 无监督，无需标签，速度快 | | 尖点指标 | `(count - rolling_mean) / (rolling_mean + 1)` | 归一化偏差，非原始比率 | | 用户过滤 | ≥ 5 个时间点 | 稳定的滚动统计，避免噪声 | | 污染率 | 0.005 | 避免强制标记弱异常 | | 特征集 | z_score, spike, diff, hour | 清晰信号，无冗余 | \--- ## 实验跟踪 所有运行记录到 MLflow。要查看： ``` mlflow ui # open http://localhost:5000 ``` \--- ## 下一步计划 * [ ] 添加数据漂移检测（特征分布上的 KS 检验） * [ ] 使用 Airflow 定期重新训练 * [ ] 在服务端点上添加 Prometheus 指标 * [ ] 使用 Docker Compose 搭建完整本地栈

标签：Apex, API服务, AV绕过, ETL, FastAPI, GitHub行为分析, IsolationForest, JavaCC, MLflow, Z-score归一化, 事件流处理, 合成数据, 实时推理, 实验跟踪, 尖峰检测, 异常检测, 数据管道, 无监督学习, 时间序列异常, 机器学习, 模块化代码, 模型训练, 模型部署, 滚动统计, 特征工程, 生产级代码结构, 用户行为异常检测, 端到端ML管道, 超参数调优, 软件工程, 逆向工具