合成数据 SDK ✨

文档 | 技术白皮书 | 使用示例 | 免费云服务

合成数据 SDK 是一个用于生成高保真、隐私安全的 合成数据 的 Python 工具包。

• LOCAL 模式：在您自己的计算资源上本地训练和生成合成数据。
• CLIENT 模式：连接到远程的 MOSTLY AI 平台，在那里进行训练和生成合成数据。
• 在本地训练好的生成器可以轻松导入到平台上，以便进一步共享。

概述

该 SDK 允许您以编程方式创建、浏览和管理 3 种关键资源：

1. 生成器 - 使用您现有的表格或语言数据资产训练合成数据生成器
2. 合成数据集 - 使用生成器根据您的需求创建任意数量的合成样本
3. 连接器 - 连接到您组织内的任何数据源，用于读取和写入数据

https://github.com/user-attachments/assets/9e233213-a259-455c-b8ed-d1f1548b492f

主要特性

• 广泛的数据支持
  • 混合类型数据（分类、数值、地理空间、文本等）
  • 单表、多表和时间序列数据
• 多种模型类型
  • 通过 TabularARGN 实现最先进的性能
  • 基于 DNN 的图关系匹配
  • 微调 Hugging Face 托管的语言模型
  • 高效的 LSTM 从零开始进行文本合成
• 高级训练选项
  • 支持 GPU/CPU
  • 差分隐私
  • 进度监控
• 自动化质量保证
  • 用于保真度和隐私的质量指标
  • 用于可视化分析的详细 HTML 报告
• 灵活采样
  • 可以按任意数据量进行过采样
  • 基于任意列的条件模拟
  • 重新平衡代表性不足的细分群体
  • 上下文感知的数据插补
  • 统计公平性控制
  • 通过温度参数遵守规则
• 无缝集成
  • 可以连接到外部数据源（数据库、云存储）
  • 完全开放的开源许可

快速入门

通过 pip 安装 SDK（更多详情请参阅 安装）：

pip install -U mostlyai  # 或 'mostlyai[local]' 用于 LOCAL 模式

使用预训练的生成器生成合成样本：

# 初始化 SDK
from mostlyai.sdk import MostlyAI
mostly = MostlyAI()

# 导入已训练好的生成器
g = mostly.generators.import_from_file(
  "https://github.com/mostly-ai/public-demo-data/raw/dev/census/census-generator.zip"
)

# 探测 1000 个具有代表性的合成样本
df = mostly.probe(g, size=1000)
df

根据固定列值生成合成样本：

# 创建 1 万条 24 岁男性受访者记录
df = mostly.probe(g, seed=[{"age": 24, "sex": "Male"}] * 10_000)
df

现在您可以训练属于您自己的合成数据生成器：

# 加载原始数据
import pandas as pd
original_df = pd.read_csv(
  "https://github.com/mostly-ai/public-demo-data/raw/dev/titanic/titanic.csv"
)

# 使用默认配置训练单表生成器
g = mostly.train(
  name="快速入门演示 - 泰坦尼克号",
  data=original_df,
)

# 显示质量保证报告
g.reports(display=True)

# 使用默认配置生成具有代表性的合成数据集
sd = mostly.generate(g)
df = sd.data()

# 或者简单地探测一些样本
df = mostly.probe(g, size=100)
df

性能

该 SDK 的开发重点在于效率、准确性和灵活性，在这三方面均达到行业领先水平。最终的结果将取决于训练数据本身（大小、结构和内容）、可用的计算资源（CPU 对比 GPU），以及所选择的训练配置（模型、轮次、样本数等）。因此，建议采用“爬行/步行/奔跑”的方法——先用一部分样本进行短时间的训练，然后逐步扩大规模，以获得针对特定用例的最佳效果。

表格模型

SDK 中的表格模型基于 TabularARGN（arXiv:2501.12012），它在实现行业领先的合成数据质量的同时，效率比同类模型高出 1 到 2 个数量级。这种高效性使得即使在 CPU 环境中，也能在几分钟内训练并生成数百万条合成记录。

语言模型

默认的语言模型是一个基础的、未经过预训练的 LSTM (LSTMFromScratch-3m)，它特别适用于范围有限（长度较短、种类较少）且训练样本充足的文字数据。

此外，也可以选择任何通过 Hugging Face Hub 提供、并支持 AutoModelForCausalLM 类的预训练语言模型，然后在提供的训练数据上进行微调。这些模型一开始就具备通用的世界知识，随后会根据训练数据进行调整，从而在数据稀疏的领域中生成高保真度的合成样本。最终的性能将再次主要取决于所选的模型配置。

无论采用哪种方式，在使用语言模型时都强烈建议使用现代 GPU。

安装

使用 pip（或更好的是 uv pip）通过 PyPI 安装官方的 mostlyai 包。需要 Python 3.10 或更高版本。

强烈建议使用 uv 在专用的虚拟环境中安装该包（详见 这里）：

# 如果尚未安装 uv，则先安装
curl -Ls https://astral.sh/uv/install.sh | bash

# 使用 uv 创建并激活一个 Python 3.12 环境
mkdir ~/synthetic-data-sdk; cd ~/synthetic-data-sdk
uv venv -p 3.12

# 激活虚拟环境
source .venv/bin/activate

# 如果尚未安装 uv，则先安装
irm https://astral.sh/uv/install.ps1 | iex

# 使用 uv 创建并激活一个 Python 3.12 环境
mkdir ~/synthetic-data-sdk; cd ~/synthetic-data-sdk
uv venv -p 3.12

# 激活虚拟环境
.venv\Scripts\activate

# SDK 安装完成后，可选择启动 Jupyter 会话
uv run --with jupyter jupyter lab

CLIENT 模式

这是仅用于以 CLIENT 模式使用 SDK 的轻量级安装。它会与 MOSTLY AI 平台通信以执行请求的任务。例如，可以访问 app.mostly.ai 获取免费托管版本。

uv pip install -U mostlyai

CLIENT + LOCAL 模式

这是用于同时以 CLIENT 和 LOCAL 模式使用 SDK 的完整安装。它包含所有依赖项，包括 PyTorch，以便在本地训练和生成合成数据。

uv pip install -U 'mostlyai[local]'

或者，对于 Linux 上的 GPU 配置（LLM 微调和推理所需）：

uv pip install -U 'mostlyai[local-gpu]'

在 Linux 上，还可以单独安装仅 CPU 版本的 PyTorch，并将其与 mostlyai[local] 一起安装：

# uv pip 安装
uv pip install --index-strategy unsafe-first-match -U torch==2.9.1+cpu torchvision==0.24.1+cpu 'mostlyai[local]' --extra-index-url https://download.pytorch.org/whl/cpu

# 标准 pip 安装
pip install -U torch==2.9.1+cpu torchvision==0.24.1+cpu 'mostlyai[local]' --extra-index-url https://download.pytorch.org/whl/cpu

Google Colab 用户请注意：安装任何本地扩展包（mostlyai[local] 或 mostlyai[local-gpu]）后，可能需要重启运行时才能使更改生效。

数据连接器

在 LOCAL 模式下，添加以下任意扩展包以支持更多数据连接器：databricks、googlebigquery、hive、mssql、mysql、oracle、postgres、redshift、snowflake。例如：

uv pip install -U 'mostlyai[local, databricks, snowflake]'

使用 Docker

作为替代方案，您也可以构建一个 Docker 镜像，为您提供一个隔离的环境来以 LOCAL 模式运行 SDK，并预先安装所有连接器依赖项。这种方法可确保在所有系统上具有一致的运行环境。在继续操作之前，请确保您的系统已安装 Docker。

from mostlyai.sdk import MostlyAI

mostly = MostlyAI(base_url="http://localhost:8080")

空气隔离环境

对于空气隔离环境（无互联网访问），您必须使用提供的 wheel 文件安装软件包，并包含所需的可选依赖项。

如果您的应用依赖于 Hugging Face 语言模型，还需要手动下载并传输模型文件。

#! uv pip install huggingface-hub
from pathlib import Path
from huggingface_hub import snapshot_download
path = snapshot_download(
    repo_id="Qwen/Qwen2.5-Coder-0.5B",  # 根据需要更改
    token=None,  # 对于受保护的模型，请插入您的 HF TOKEN
)
print(f"COPY `{Path(path).parent.parent}`")

引用

如果您觉得我们的项目有用，请考虑引用它：

@misc{mostlyai,
      title={利用开源合成数据 SDK 民主化表格数据访问},
      author={伊沃娜·克尔乔娃、玛丽亚娜·瓦尔加斯·维埃拉、马里奥·斯克里米纳奇、安德烈·西多连科},
      year={2025},
      eprint={2508.00718},
      archivePrefix={arXiv},
      primaryClass={cs.LG},
      url={https://arxiv.org/abs/2508.00718},
}

MostlyAI 合成数据 SDK 快速上手指南

MostlyAI 是一个用于生成高保真、隐私安全的合成数据的 Python 工具包。它支持在本地（LOCAL 模式）利用自有算力训练和生成数据，或连接远程 MOSTLY AI 平台（CLIENT 模式）进行处理。

1. 环境准备

• 操作系统: Linux, macOS, Windows
• Python 版本: 3.10 或更高
• 推荐工具: 建议使用 uv 管理虚拟环境和依赖，以获得更快的安装速度和更好的隔离性。
• 硬件建议:
  • 表格数据: CPU 即可高效运行。
  • 语言模型 (LLM): 强烈建议使用现代 GPU 进行微调和推理。

设置虚拟环境 (可选但推荐)

如果尚未安装 uv，请先安装：

Unix / macOS:

curl -Ls https://astral.sh/uv/install.sh | bash

Windows:

irm https://astral.sh/uv/install.ps1 | iex

创建并激活 Python 3.12 环境：

mkdir synthetic-data-sdk && cd synthetic-data-sdk
uv venv -p 3.12

# Unix/macOS
source .venv/bin/activate

# Windows
.venv\Scripts\activate

2. 安装步骤

根据使用场景选择以下一种安装方式。国内用户若遇网络问题，可配置 pip 国内镜像源（如清华源、阿里源）。

方案 A：客户端模式 (CLIENT Mode)

仅连接远程 MOSTLY AI 平台，轻量级安装。

uv pip install -U mostlyai
# 或使用标准 pip (推荐添加国内镜像)
# pip install -U mostlyai -i https://pypi.tuna.tsinghua.edu.cn/simple

方案 B：本地完整模式 (LOCAL Mode)

包含所有依赖（含 PyTorch），可在本地训练和生成数据。

uv pip install -U 'mostlyai[local]'

方案 C：本地 GPU 加速模式 (Linux)

适用于需要微调大语言模型或加速推理的场景。

uv pip install -U 'mostlyai[local-gpu]'

注意: 如果在 Google Colab 中安装了 local 或 local-gpu 扩展包，安装完成后可能需要重启运行时 (Runtime) 才能生效。

3. 基本使用

以下示例展示如何初始化 SDK、导入预训练模型、探测数据以及训练自己的生成器。

初始化与使用预训练模型

from mostlyai.sdk import MostlyAI

# 初始化 SDK (默认尝试连接本地服务或云平台，需根据实际配置调整)
mostly = MostlyAI()

# 导入一个预训练好的生成器 (此处以人口普查数据为例)
g = mostly.generators.import_from_file(
  "https://github.com/mostly-ai/public-demo-data/raw/dev/census/census-generator.zip"
)

# 探测生成 1000 条代表性合成样本
df = mostly.probe(g, size=1000)
print(df.head())

基于固定条件生成数据

可以指定特定列的值来生成符合条件的数据（例如：生成 10,000 条 24 岁男性的记录）。

# 基于种子数据生成
df = mostly.probe(g, seed=[{"age": 24, "sex": "Male"}] * 10_000)
print(df.head())

训练自己的合成数据生成器

import pandas as pd

# 1. 加载原始数据
original_df = pd.read_csv(
  "https://github.com/mostly-ai/public-demo-data/raw/dev/titanic/titanic.csv"
)

# 2. 训练单表生成器 (使用默认配置)
g = mostly.train(
  name="Quick Start Demo - Titanic",
  data=original_df,
)

# 3. 查看质量评估报告
g.reports(display=True)

# 4. 生成合成数据集
sd = mostly.generate(g)
synthetic_df = sd.data()

# 或者快速探测少量样本
sample_df = mostly.probe(g, size=100)
print(sample_df.head())

核心功能概览

• 训练生成器: g = mostly.train(config) - 基于表格或文本数据训练。
• 生成数据: sd = mostly.generate(g, config) - 生成任意数量的合成记录。
• 即时探测: df = mostly.probe(g, config) - 按需实时生成少量样本进行测试。
• 数据连接: c = mostly.connect(config) - 连接组织内部的数据库或云存储。