KRISHNA07KY/PIVOT-Privacy-Invariant-Observability-Toolkit-

# PIVOT — 面向漂移检测的隐私不变观测工具包 面向联邦学习的隐私优先的 ML 观测。   **PIVOT — Privacy‑Invariant Observability Toolkit** 一个在严格隐私约束下检测数据漂移的联邦 ML 观测系统。  PIVOT 是一个可复现的研究级概念验证方案，用于在保护个体客户端隐私的同时测量 联邦数据中的分布漂移。它模拟客户端与基准总体，在客户端侧计数上应用 局部差分隐私（Local Differential Privacy, LDP）机制（拉普拉斯噪声），聚合 噪声统计量，并计算分布漂移分数，使从业者能够 可视化并权衡隐私—效用关系。 ## 概述 ### 本项目的作用 PIVOT 运行可配置的实验，模拟联邦监控工作流：生成基准数据与客户端数据，在客户端侧对计数 应用 LDP 机制，中心化聚合噪声贡献，然后计算分布距离（Wasserstein）以检测漂移。它 输出控制台指标与可直接发布的图表，展示不同隐私预算（ε）对检测能力与效用的影响。 ### 解决的问题 在去中心化场景下检测分布漂移很难，因为你无法（或不应该）集中化原始用户数据。团队需要 回答：“如果加入隐私噪声，我们还能否发现显著的漂移？” PIVOT 量化这一隐私—效用权衡， 让数据科学家与隐私工程师可以选择合理的隐私参数，并在不暴露原始客户端记录的情况下 监控模型或数据流水线。 ### 使用者 - 在隐私约束下评估漂移检测器的数据科学家与 ML 工程师。 - 比较 LDP 机制与聚合策略的隐私研究人员。 - 构建必须明确考虑隐私预算的联邦监控或分析流水线的产品团队。 - 希望通过可复现实验展示 LDP 如何影响检测能力的评委、评审员与教育工作者。 ## 为何这很重要 现代 ML 系统运行在去中心化数据上。PIVOT 展示了如何在不访问原始用户数据的情况下 监控分布漂移，从而实现符合隐私规范的模型监控、合规性要求以及更安全的部署决策。 ## 核心特性 - 联邦模拟：基准总体 + 可配置的客户端集合。 - 基于客户端计数的局部差分隐私（Laplace 机制）。 - 使用直方图上的 Wasserstein-1 距离进行聚合与漂移评分。 - 可配置的实验与 ε 扫描以可视化权衡。 - 简洁的 CLI 入口点，以及可选的 API/Web 集成。 ## 快速开始（Windows） 创建虚拟环境，激活（Windows PowerShell），安装依赖并运行实验（PowerShell 命令）： ``` python -m venv .venv .\.venv\Scripts\Activate.ps1 pip install -r requirements.txt python main.py ``` 说明： - `main.py` 运行核心模拟并将图表/指标保存到工作目录。 - `app.py` 包含一个轻量级 Web/演示运行器；`api_pivot.py` 可用于通过 API 暴露核心功能。 ## 克隆与运行 验证项目是否能从全新克隆成功运行，执行以下命令： ``` git clone https://github.com/KRISHNA07KY/PIVOT-Privacy-Invariant-Observability-Toolkit- cd PIVOT-Privacy-Invariant-Observability-Toolkit- pip install -r requirements.txt python main.py ``` 这将确认项目能从干净检出成功运行。 ## Python 版本 - 推荐：Python 3.10 或 3.11 - 注意：Python 3.13 可能导致 NumPy 的依赖问题；若使用 3.13，请验证包兼容性或优先在虚拟环境中使用 3.10/3.11。 ## 技术栈 - **语言：** Python 3.10+（在 Python 3.13.3 上测试） - **核心库：** NumPy, SciPy, pandas, Matplotlib - **API：** FastAPI + Uvicorn - **演示/UI：** Streamlit（可选） - **测试：** pytest, httpx（TestClient）, requests - **绘图：** Matplotlib - **操作系统：** Windows、Linux、macOS ## 使用示例 运行实验： ``` python main.py ``` 运行 Streamlit 演示： ``` streamlit run app.py ``` 运行 API（开发模式）： ``` uvicorn api_pivot:app --reload --host 127.0.0.1 --port 8000 curl "http://127.0.0.1:8000/api/run-experiment?epsilon=1.0" ``` 运行冒烟测试： ``` python scripts/test_api.py ``` `python main.py` 产生的示例控制台输出： ``` ╔══════════════════════════════════════════════════╗ ║ PIVOT – Federated Drift Detection Results ║ ╚══════════════════════════════════════════════════╝ ε=0.05 | Drift=26409.0628 | Utility (inverse drift)=3.79e-05 ε=0.10 | Drift=26471.7327 | Utility (inverse drift)=3.78e-05 ε=0.50 | Drift=25724.6016 | Utility (inverse drift)=3.89e-05 ε=1.00 | Drift=25829.4748 | Utility (inverse drift)=3.87e-05 ε=5.00 | Drift=26760.0667 | Utility (inverse drift)=3.74e-05 ε=10.00 | Drift=26775.0635 | Utility (inverse drift)=3.73e-05 Figure saved → privacy_tradeoff.png ``` ## 预期输出 - 控制台输出：每个 ε 值对应的 Wasserstein 距离与汇总效用指标。 - 一个三面板可视化（通常保存为 `privacy_tradeoff.png`），包含： - 基准分布 - 带噪声的客户端分布 - 跨 ε 值计算的漂移分数 ## 示例输出 ``` ε=0.05 | Drift=26409.0628 | Utility=3.79e-05 ε=1.00 | Drift=25829.4748 | Utility=3.87e-05 ε=10.00 | Drift=26775.0635 | Utility=3.73e-05 ``` - 效用（漂移的倒数）以科学计数法显示以提升清晰度 - 展示跨 ε 值的隐私—效用权衡 ## 工作原理（高层概览） 1. 生成基准分布与每个客户端的样本。 2. 每个客户端使用校准到选定 ε 的拉普拉斯噪声对其计数进行私有扰动。 3. 服务器聚合来自多个客户端的噪声计数并构建直方图。 4. 计算基准与聚合直方图之间的 Wasserstein-1 距离以量化漂移。 5. 遍历一组 ε 值以构建隐私—效用曲线。 ## 架构 ``` flowchart LR A["Raw Client Data"] --> B["Laplace Noise (LDP)"] B --> C["Noisy Counts"] C --> D["Server Aggregation"] D --> E["Wasserstein Drift Score"] ``` ## 配置 在 `src/config.py` 中编辑实验参数以更改样本大小、直方图分箱或用于扫描的 `epsilons` 列表。关键文件： - `src/data.py` — 数据生成与客户端采样。 - `src/ldp.py` — 拉普拉斯机制实现。 - `src/federation.py` — 客户端聚合与漂移评分逻辑。 - `src/viz.py` — 三面板图表的绘图工具。 ## 项目结构 ``` pivot-federated-v2/ ├── main.py # CLI entrypoint that runs experiments ├── app.py # optional demo/web runner ├── api_pivot.py # minimal API wrapper (optional) ├── pivot_theme.py # plotting theme helpers ├── requirements.txt ├── README.md └── src/ ├── __init__.py ├── config.py # experiment parameters and epsilon list ├── data.py # baseline & client data generation ├── ldp.py # Laplace LDP mechanism and helpers ├── federation.py # aggregation & drift scoring └── viz.py # plotting and export ``` ## 科学与评估细节 - 基准：10,000 个样本，从参考分布中抽取。 - 漂移场景：许多客户端具有偏移的局部分布，以及一小部分具有更强偏移（“冲击”）。 - LDP：应用于客户端计数的拉普拉斯噪声，尺度 = 1/ε；负计数在聚合前被截断为零。 - 指标：直方图上的 Wasserstein‑1 距离（默认：60 个分箱）。 - 典型 ε 扫描：[0.05, 0.1, 0.5, 1.0, 5.0, 10.0]。 这些参数旨在展示广泛的隐私预算范围；请根据领域特定实验在 `src/config.py` 中调整数值。 ## 扩展代码库 - 通过在 `src/ldp.py` 中实现新机制并将其接入 `src/federation.py` 的主流程来添加新的 LDP 机制。 - 在新模块中添加新的漂移指标（例如 KS、MMD），并更新 `main.py` 以同时评估 Wasserstein。 - 要重现论文图表，在 `src/config.py` 中设置随机种子并运行多次试验。 ## 限制 - 使用模拟数据（非真实数据集） - 仅限基于直方图的漂移检测 - 无实时流处理或生产部署 ## 后续改进 - 实时联邦监控 - 新增漂移指标（KS、MMD） - 云部署与可扩展基础设施 ## 贡献 欢迎提交问题与拉取请求。请附上简要说明你所做的更改及原因；若添加实验，请包含预期输出或生成图表的示例。 ## 许可证 根据 MIT 许可证分发。详见 [许可证文件](LICENSE)。

标签：Apex, API集成, AV绕过, FastAPI, Kubernetes, LDP, MIT许可, ML监控, Mutation, Python, Python3.10, Wasserstein距离, ε, 中心化数据, 仪表盘, 分布比较, 去中心化, 可复现, 可观测性, 可视化, 实时检测, 实验模拟, 差分隐私, 开源, 数据漂移, 数据漂移检测, 数据科学, 数据科学家, 无后门, 本地差分隐私, 机器学习, 监控, 研究级, 统计检验, 网络安全, 联邦, 联邦学习, 资源验证, 逆向工具, 隐私保护, 隐私工程师, 隐私-效用权衡, 隐私预算