合成数据生成器（SDG）是一个专门用于生成高质量结构化表格数据的框架。

合成数据不包含任何敏感信息，但保留了原始数据的基本特征，因此不受 GDPR 和 ADPPA 等隐私法规的约束。

高质量的合成数据可以在多个领域安全使用，包括数据共享、模型训练与调试、系统开发与测试等。

我们非常高兴您能加入，并期待您的贡献！请通过这份贡献概述指南开始参与项目！

💥新闻

我们目前的主要成果和时间表如下：

🔥 2024年11月21日：1）模型集成——我们已将GaussianCopula模型集成到我们的数据处理器系统中。请查看此PR中的代码示例；2）合成质量——我们实现了自动检测数据列关系并支持关系指定功能，从而提升了合成数据的质量(代码示例)；3）性能提升——我们在处理离散数据时显著降低了GaussianCopula的内存占用，使得在2C4G配置下即可训练数千个分类数据条目！

🔥 2024年5月30日：数据处理器模块正式合并。该模块将：1）帮助SDG在将数据输入模型之前转换某些数据列的格式（例如日期时间列），以避免被误认为离散类型，并将模型生成的数据反向转换回原始格式；2）对各种数据类型进行更定制化的预处理和后处理；3）轻松应对原始数据中的空值等问题；4）支持插件系统。

🔥 2024年2月20日：新增基于LLM的单表数据合成模型，查看Colab示例： LLM：数据合成和 LLM：表外特征推断。

🔧 2024年2月7日：我们改进了sdgx.data_models.metadata，以支持描述单表和多表的元数据信息，支持多种数据类型，并支持自动数据类型推断。查看Colab示例：SDG单表元数据。

🔶 2023年12月20日：发布v0.1.0版本，其中包含支持数十亿条数据处理能力的CTGAN模型，查看我们的与SDV的基准对比,SDG在内存消耗方面表现更优，并且在训练过程中未出现崩溃。具体使用方法，请查看Colab示例：支持数十亿条数据的CTGAN。

🔆 2023年8月10日：SDG代码的第一行提交。

🎉 基于LLM的合成数据生成

长期以来，LLM一直被用于理解和生成各类数据。事实上，LLM在表格数据生成方面也具备一定能力，而且它还拥有一些传统方法（基于GAN或统计方法）无法实现的功能。

我们的sdgx.models.LLM.single_table.gpt.SingleTableGPTModel实现了两项新功能：

无需数据的合成数据生成

无需任何训练数据，即可基于元数据生成合成数据，详情请参阅我们的Colab 示例。

表外特征推断

基于表中现有数据及 LLM 掌握的知识，推断新列数据，详情请参阅我们的Colab 示例。

💫 为什么选择 SDG？

• 技术进步：
  • 支持多种统计学数据合成算法，同时集成基于 LLM 的合成数据生成模型；
  • 针对大数据进行优化，有效降低内存消耗；
  • 持续跟踪学术界与工业界的最新进展，并及时引入优秀的算法与模型支持。
• 隐私增强：
  • SDG 支持差分隐私、匿名化等方法，以提升合成数据的安全性。
• 易于扩展：
  • 支持通过插件包的形式扩展模型、数据处理、数据连接器等功能。

🌀 快速入门

预构建镜像

您可以使用预构建的镜像快速体验最新功能。

docker pull idsteam/sdgx:latest

从 PyPi 安装

pip install sdgx

本地安装（推荐）

通过源码安装 SDG 来使用它。

git clone git@github.com:hitsz-ids/synthetic-data-generator.git
pip install .
# 或者从 Git 安装
pip install git+https://github.com/hitsz-ids/synthetic-data-generator.git

单表数据生成与指标的快速演示

演示代码

from sdgx.data_connectors.csv_connector import CsvConnector
from sdgx.models.ml.single_table.ctgan import CTGANSynthesizerModel
from sdgx.synthesizer import Synthesizer
from sdgx.utils import download_demo_data

# 这将下载演示数据到 ./dataset
dataset_csv = download_demo_data()

# 创建 CSV 文件的数据连接器
data_connector = CsvConnector(path=dataset_csv)

# 初始化合成器，使用 CTGAN 模型
synthesizer = Synthesizer(
    model=CTGANSynthesizerModel(epochs=1),  # 用于快速演示
    data_connector=data_connector,
)

# 拟合模型
synthesizer.fit()

# 采样
sampled_data = synthesizer.sample(1000)
print(sampled_data)

对比

真实数据如下：

>>> data_connector.read()
       age         workclass  fnlwgt  education  ...  capitalloss hoursperweek native-country  class
0        2         State-gov   77516  Bachelors  ...            0            2  United-States  <=50K
1        3  Self-emp-not-inc   83311  Bachelors  ...            0            0  United-States  <=50K
2        2           Private  215646    HS-grad  ...            0            2  United-States  <=50K
3        3           Private  234721       11th  ...            0            2  United-States  <=50K
4        1           Private  338409  Bachelors  ...            0            2           Cuba  <=50K
...    ...               ...     ...        ...  ...          ...          ...            ...    ...
48837    2           Private  215419  Bachelors  ...            0            2  United-States  <=50K
48838    4               NaN  321403    HS-grad  ...            0            2  United-States  <=50K
48839    2           Private  374983  Bachelors  ...            0            3  United-States  <=50K
48840    2           Private   83891  Bachelors  ...            0            2  United-States  <=50K
48841    1      Self-emp-inc  182148  Bachelors  ...            0            3  United-States  <=50K

[48842行 x 15列]

合成数据如下：

>>> sampled_data
     age workclass  fnlwgt     education  ...  capitalloss hoursperweek native-country  class
0      1       NaN   28219  Some-college  ...            0            2    Puerto-Rico  <=50K
1      2   Private  250166       HS-grad  ...            0            2  United-States   >50K
2      2   Private   50304       HS-grad  ...            0            2  United-States  <=50K
3      4   Private   89318     Bachelors  ...            0            2    Puerto-Rico   >50K
4      1   Private  172149     Bachelors  ...            0            3  United-States  <=50K
..   ...       ...     ...           ...  ...          ...          ...            ...    ...
995    2       NaN  208938     Bachelors  ...            0            1  United-States  <=50K
996    2   Private  166416     Bachelors  ...            2            2  United-States  <=50K
997    2       NaN  336022       HS-grad  ...            0            1  United-States  <=50K
998    3   Private  198051       Masters  ...            0            2  United-States   >50K
999    1       NaN   41973       HS-grad  ...            0            2  United-States  <=50K

[1000行 x 15列]

👩‍🎓 相关工作

• CTGAN：使用条件 GAN 建模表格数据
• C3-TGAN：C3-TGAN——可控的表格数据合成，具备显式相关性和属性约束
• TVAE：使用条件 GAN 建模表格数据
• table-GAN：基于生成对抗网络的数据合成
• CTAB-GAN：CTAB-GAN：高效的表格数据合成
• OCT-GAN：OCT-GAN：基于神经 ODE 的条件表格 GAN

🤝 加入社区

SDG 项目由哈尔滨工业大学数据安全研究所发起。如果您对我们的项目感兴趣，欢迎加入我们的社区。我们欢迎所有致力于通过开源方式保护和保障数据安全的组织、团队和个人：

• 在提交 Pull Request 之前，请先阅读 CONTRIBUTING。
• 通过查看 View Good First Issue 提交 issue，或直接提交 Pull Request。
• 通过二维码加入我们的微信交流群。

📄 许可协议

SDG 开源项目采用 Apache-2.0 许可协议，详情请参阅 LICENSE。

synthetic-data-generator 快速上手指南

环境准备

系统要求

• 操作系统：支持 Linux、macOS 或 Windows（推荐使用 Linux 或 macOS）
• Python 版本：3.8 及以上版本
• 内存建议：至少 4GB RAM，生成大规模数据时建议更高配置

前置依赖

确保已安装以下工具：

• git
• docker（如需使用预构建镜像）
• pip（用于安装 Python 包）

安装步骤

方法一：使用 PyPi 安装（推荐）

pip install sdgx

如果你在国内，可以使用国内镜像源加速安装，例如：

pip install sdgx -i https://pypi.tuna.tsinghua.edu.cn/simple

方法二：本地安装（推荐开发使用）

git clone git@github.com:hitsz-ids/synthetic-data-generator.git
pip install .
# 或者直接从 Git 安装
pip install git+https://github.com/hitsz-ids/synthetic-data-generator.git

方法三：使用预构建 Docker 镜像

docker pull idsteam/sdgx:latest

基本使用

以下是一个最简单的单表数据合成示例：

from sdgx.data_connectors.csv_connector import CsvConnector
from sdgx.models.ml.single_table.ctgan import CTGANSynthesizerModel
from sdgx.synthesizer import Synthesizer
from sdgx.utils import download_demo_data

# 下载示例数据到当前目录下的 dataset 文件夹
dataset_csv = download_demo_data()

# 创建 CSV 数据连接器
data_connector = CsvConnector(path=dataset_csv)

# 初始化合成器，使用 CTGAN 模型
synthesizer = Synthesizer(
    model=CTGANSynthesizerModel(epochs=1),  # 为快速演示设置较少的训练轮数
    data_connector=data_connector,
)

# 训练模型
synthesizer.fit()

# 生成 1000 条合成数据
sampled_data = synthesizer.sample(1000)
print(sampled_data)

运行后将输出类似如下格式的合成数据：

     age workclass  fnlwgt     education  ...  capitalloss hoursperweek native-country  class
0      1       NaN   28219  Some-college  ...            0            2    Puerto-Rico  <=50K
1      2   Private  250166       HS-grad  ...            0            2  United-States   >50K
...

通过此流程，你可以快速体验 synthetic-data-generator 的基本功能。更多高级用法请参考官方文档或项目中的示例代码。