Privacy Tuner

Privacy Tuner 是一个通用的隐私保护数据发布工具。它通过智能参数搜索，在用户指定的隐私预算和效用目标约束下，自动寻找最优的数据扰动参数（如噪声尺度、泛化粒度、采样比例等），从而在保护隐私的同时最大化数据的实用性。最终输出净化后的数据集、最优参数组合以及可视化报告。

特性

• 模块化设计：支持可插拔的隐私机制、风险度量、效用评估和优化器，方便扩展与定制。
• 多种隐私模型：内置差分隐私（拉普拉斯、高斯）、经验风险（KNN 成员推断攻击）等，并预留接口支持 k-匿名等传统方法。
• 多种数据类型：表格数据原生支持，并预留文本、图像数据加载接口。
• 自动参数搜索：提供网格搜索、贝叶斯优化、遗传算法等多种优化器，自动探索参数空间。
• 可解释性：生成风险-效用曲线和自然语言报告，帮助理解参数选择的理由。
• 结果可复现：支持保存最优参数、扰动数据和报告，便于审计和二次使用。

安装

通过 PyPI 安装（推荐）

pip install privacy-tuner

从源码安装

如果你已经获取了项目源码（例如从本地目录或压缩包），可以在项目根目录下执行以下命令进行安装：

cd privacy_tuner   # 进入项目根目录
pip install -e .

注：-e 选项表示以可编辑模式安装，方便修改代码后立即生效。如果不需要修改源码，也可以去掉 -e 进行普通安装。

快速开始

Python API

from privacy_tuner import protect
import numpy as np

# 假设你有一个数据数组，最后一列是标签
data = np.random.randn(100, 5)  # 100个样本，5个特征
labels = (data[:, 0] > 0).astype(int)
data = np.column_stack([data, labels])

# 一键保护数据
result = protect(data, epsilon=1.0, output_dir='output')

print(f"最优参数: {result['best_params']}")
print(f"效用 (准确率): {result['best_utility']:.4f}")
print(f"风险: {result['best_risk']:.4f}")

命令行工具（安装后使用）

privacy-tuner your_data.csv --epsilon 1.0 --output results

更多示例请参考项目中的 examples 目录。

核心模块

目录结构

privacy_tuner/
├── privacy_tuner/               # 主代码包
│   ├── input/                   # 数据加载与特征分析
│   ├── core/                    # 核心模块（机制、风险、效用、优化器）
│   ├── output/                  # 数据导出与报告生成
│   ├── visualization/           # 可视化工具
│   ├── validation/              # 验证与案例库
│   └── examples/                # 使用示例
├── tests/                       # 单元测试
├── docs/                        # 文档
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── MANIFEST.in
├── setup.py
└── requirements.txt

开发与贡献

欢迎参与开发！请阅读 CONTRIBUTING.md 了解环境搭建、代码风格和测试流程。

本地开发环境

# 进入项目根目录
cd privacy_tuner

# 创建虚拟环境（可选）
python -m venv venv
source venv/bin/activate   # Linux/Mac
venv\Scripts\activate      # Windows

# 安装开发依赖
pip install -e .
pip install pytest flake8 black

运行测试

pytest tests/

许可证

本项目采用 MIT 许可证。