opendsr-std/seedfaker
GitHub: opendsr-std/seedfaker
基于 Rust 的确定性合成数据生成器，跨七种运行时输出字节级一致的测试数据，支持多表外键关联、TB 级分布式分片生成和原地匿名化替换。
Stars: 23 | Forks: 0
# seedfaker
确定性合成数据生成器。相同的 seed，相同的输出 —— 跨越 CLI、Python、Node.js、Go、PHP、Ruby、WASM。
200+ 字段，68 种语言环境，多表 FK，表达式，模板，流式处理，用于匿名化现有数据的 `replace`。
## 核心亮点
- **跨 7 个运行时保持确定性** — CLI、Python、Node、Go、PHP、Ruby、WASM。相同的 seed → 字节完全一致。`--fingerprint` 可捕捉算法漂移。[→](#determinism)
- **多表 FK** — 锚点 (`users.id:zipf`)，解引用 (`customer_id->email`)，自引用，`ctx:strict` 身份关联。[→](docs/multi-table.md)
- **分布式** — 在三台主机上执行 `--shard I/N`，拼接后的结果与单机生成在比特级别完全一致。无需协调器。[→](#distributed-generation)
- **数据库摄入** — `seedfaker | psql "\COPY"`，无需生成临时文件，内存占用恒定。[→](guides/seed-database.md)
- **TB 级规模** — 在 8 核心上仅需 9 秒即可向 Postgres 导入 1 GB 数据（[基准测试](benchmarks/payments_5gb.sh)）；1 TB 大约只需 4.3 小时。[→](guides/seed-large-database.md)
- **吞吐量** — 每核心约 90 MB/s（与 TPC-H dbgen 持平），8 线程下达 403 MB/s。可在 [`benchmarks/`](benchmarks/) 中复现。
- **原地匿名化** — `seedfaker replace email ssn < dump.csv`。相同的值 + 相同的 seed = 相同的替换结果；跨文件 join 依然有效。[→](docs/replace.md)
- **ML/LLM 数据集** — `--annotated`（字节偏移范围），`--corrupt`（15 种噪音类型），模板（prompt/completion），多表 FK（对话，RAG）。[→](guides/training-data.md)
- **语言环境感知的 PII** — Luhn 信用卡，IBAN 校验位，48 种政府 ID 格式，68 种语言环境，原生文字。[→](docs/fields.md)
## 目录
- [安装](#install)
- [库](#library)
- [CLI](#cli)
- [多表与 FK](#multi-table-and-fk)
- [分布式生成](#distributed-generation)
- [批量导入数据库](#bulk-load-into-a-database)
- [匿名化现有数据](#anonymise-existing-data)
- [用于 ML 的标注输出](#annotated-output-for-ml)
- [确定性](#determinism)
- [包与绑定](#packages-and-bindings)
- [文档](#documentation)
- [快速开始](#quick-start)
- [指南](#guides)
- [基准测试](#benchmarks)
- [许可证](#license)
## 安装
任选其一：
```
pip install seedfaker # Python
npm install @opendsr/seedfaker # Node.js
go get github.com/opendsr-std/seedfaker-go # Go
composer require opendsr/seedfaker # PHP
gem install seedfaker # Ruby
npm install @opendsr/seedfaker-wasm # Browser (WASM)
brew install opendsr-std/tap/seedfaker # CLI (macOS / Linux)
cargo install seedfaker # CLI (from source)
npm install -g @opendsr/seedfaker-cli # CLI (npm)
```
所有包都封装了相同的 Rust 核心，对于给定的 seed 会产生字节完全一致的输出。各包专属文档请参见 [包与绑定](#packages-and-bindings)。
## 库
生成单个值：
```
from seedfaker import SeedFaker
sf = SeedFaker(seed="test")
sf.field("email") # "janet.marsh@inbox.com"
sf.field("phone", e164=True) # "+14155551234"
sf.field("credit-card", space=True) # "4174 0785 8323 6433"
```
生成单条记录，使用 `ctx="strict"` 将每个字段锁定到一个身份：
```
sf.record(["name", "email", "phone"], ctx="strict")
# {"name": "Janet Marsh", "email": "janet.marsh@inbox.com", "phone": "+1 (957) 226-4272"}
```
批量生成：
```
sf.records(["name", "email", "phone"], n=1000, ctx="strict")
```
语言环境，加权混合，原生文字：
```
SeedFaker(seed="test", locale="de").field("name") # "Baldur Adler"
SeedFaker(seed="test", locale="ja").field("name") # "石本 和彦"
SeedFaker(seed="test", locale="en=7,de=2,fr=1") # weighted
```
Node.js API 完全相同：
```
const sf = new SeedFaker({ seed: "test", locale: "en" });
sf.records(["name", "email"], { n: 1000, ctx: "strict" });
```
完整 API：[docs/library](docs/library.md)。语言环境列表：[docs/context](docs/context.md)。
## CLI
```
seedfaker name email phone --seed test --until 2025 -n 1000
seedfaker name email phone --format csv --seed test --until 2025 -n 1000
seedfaker name email phone --format jsonl --seed test --until 2025 -n 1000
seedfaker name email --ctx strict -l ja,zh --abc native -n 10
```
通过管道直接导入数据库：
```
seedfaker name email phone --format sql=users -n 1000000 --seed staging --until 2025 | psql mydb
```
列间算术运算：
```
seedfaker price=amount:1..500:plain qty=integer:1..20 "total=price*qty" \
--format csv --seed ci -n 3 --until 2025
# price,qty,total
# 424.49,14,5942.86
# 459.67,3,1379.01
# 309.44,12,3713.28
```
常见日志/数据格式的预设：
```
seedfaker run nginx --rate 5000 --seed demo -n 0 > access.log
seedfaker run payment --format jsonl --seed bench -n 1000 --until 2025
```
全部标志：[docs/cli](docs/cli.md)。字段语法：[docs/fields](docs/fields.md)。配置：[docs/configs](docs/configs.md)。预设：[docs/presets](docs/presets.md)。
## 多表与 FK
```
# shop.yaml
users:
columns:
id: serial
name: first-name
email: email
options: { count: 1000, ctx: strict }
orders:
columns:
id: serial
customer_id: users.id:zipf
customer_name: customer_id->name
customer_email: customer_id->email
total: amount:usd:1..5000
options: { count: 50000 }
```
```
seedfaker run shop.yaml --all --output-dir ./data --format csv
```
- `users.id:zipf` — 具有幂律分布的 FK 锚点。使用 `:zipf=N` 可调整指数；省略则为均匀分布。
- `customer_id->email` — FK 解引用；解析为与 `customer_id` 选中的同一父行记录的 email。
- 支持自引用 FK（`employees.manager_id: employees.id`）。
详细信息：[docs/multi-table](docs/multi-table.md)，[docs/expressions](docs/expressions.md)。
有关 GB/TB 规模的真实数据库批量加载，请参见 [guides/seed-large-database](guides/seed-large-database.md)。
## 分布式生成
确定性使得无协调器的水平扩展成为可能。`--shard I/N` 会输出完整 `serial` 范围中一个互不重叠且连续的切片；在不同主机上使用相同的 seed 会生成互不重叠的输出。将所有 N 个分片拼接起来（保留第一个分片的 header，其余的使用 `--no-header`）所产生的数据，在比特级别上与 `N=1` 的单机运行完全一致。
三台主机，一个数据集：
```
# host-a
seedfaker run shop.yaml --table events --seed prod -n 1_000_000_000 \
--shard 0/3 --format csv > events.part0.csv
# host-b
seedfaker run shop.yaml --table events --seed prod -n 1_000_000_000 \
--shard 1/3 --format csv --no-header > events.part1.csv
# host-c
seedfaker run shop.yaml --table events --seed prod -n 1_000_000_000 \
--shard 2/3 --format csv --no-header > events.part2.csv
```
收集并拼接：
```
cat events.part0.csv events.part1.csv events.part2.csv > events.csv
# 相同的字节，与以下具有相同的 SHA-256：
seedfaker run shop.yaml --table events --seed prod -n 1_000_000_000 --format csv
```
主机之间没有共享状态。无需协调器。无需后期处理合并步骤。每台主机都在各自的切片上受限于 CPU 算力并独立完成计算。
单机生成还可以在 `--shard` 的基础上叠加使用 `--threads N`，结合进程级和进程内并行：
```
seedfaker ... --shard 0/3 --threads 8 --format csv > events.part0.csv
```
关于如何选择这些机制以及它们如何协同工作的详细信息：[docs/cli § Sharding and threads](docs/cli.md#sharding-and-threads)，[guides/seed-large-database](guides/seed-large-database.md)。
## 批量导入数据库
将生成的 CSV 直接通过管道导入 `COPY FROM STDIN` —— 无需中间文件，内存占用恒定：
```
seedfaker run shop.yaml --table users --format csv \
| psql "$PGURL" -q -c "\COPY users (id,name,email) FROM STDIN WITH (FORMAT csv, HEADER true)"
```
对于 GB/TB 级别的大规模加载：在第一阶段去除所有约束，加载完成后再将其添加回来。
```
CREATE UNLOGGED TABLE users (id UUID NOT NULL, name TEXT, email TEXT);
-- load rows with COPY FROM STDIN (no PK, no FK, no indexes)
ALTER TABLE users SET LOGGED;
ALTER TABLE users ADD PRIMARY KEY (id);
```
原因：在 INSERT/COPY 期间，Postgres 的约束和索引维护是按行进行的；推迟到加载后的单次扫描处理会显著加快速度。seedfaker 在结构设计上保证了 id 的唯一性，因此第一阶段的验证是无用功。
`--shard I/N` 将一张表的生成拆分为 N 个不重叠的 serial 范围。并行运行多个 `seedfaker | psql` 管道到同一张表中 —— Postgres 对每个后端进程持有 RowExclusive 锁，而不是 Exclusive 锁，因此支持对同一张表执行并发的 `COPY`。
```
# 4 个分片进入同一个表，并发
for i in 0 1 2 3; do
seedfaker run shop.yaml --table events --format csv --shard $i/4 \
| psql "$PGURL" -q -c "\COPY events (id,ts,user_id) FROM STDIN WITH (FORMAT csv, HEADER true)" &
done
wait
```
参考基准测试 [`benchmarks/payments_5gb.sh`](benchmarks/payments_5gb.sh) 端到端地实现了此模式：10 张表的支付数据集，带有调优配置的 Docker Postgres 17，按表划分的分片池，Postgres 侧的 WAL / checkpoint / cache-hit 计数器。
```
./benchmarks/payments_5gb.sh # ~100 MB, default
./benchmarks/payments_5gb.sh --scale 50 --shards 3 # ~5 GB with 3-way sharding of the big tables
./benchmarks/payments_5gb.sh --cleanup
```
完整的工作流程、调优原理、逐项参数成本表、跨引擎注意事项 (MySQL, ClickHouse, SQLite)：[guides/seed-large-database](guides/seed-large-database.md)。
## 匿名化现有数据
替换现有 CSV 或 JSONL 中的特定列，保持其他列不变并保留跨文件的引用完整性：
```
$ echo 'name,email,ssn
Alice,alice@corp.com,123-45-6789' | seedfaker replace email ssn --seed anon
name,email,ssn
Alice,nolan.moreno.xxy@icloud.com,404-16-7659
```
相同的值 + 相同的 seed 在每次运行时都会产生相同的替换结果，因此（在分别掩码处理后）对 `users.email` 和 `events.email` 进行 join 操作仍然能够匹配。详细信息：[docs/replace](docs/replace.md)。
## 用于 ML 的标注输出
`--annotated` 会输出带有字节偏移范围的 JSONL，适用于 NER / PII 训练集：
```
$ seedfaker name email ssn --annotated --seed demo -n 1 --until 2025
{"text":"Paulina Laca\tim.ivana@eunet.rs\t9580255797203","spans":[{"s":0,"e":12,"f":"name","v":"Paulina Laca"},{"s":13,"e":30,"f":"email","v":"im.ivana@eunet.rs"},{"s":31,"e":44,"f":"ssn","v":"9580255797203"}]}
```
结合 `--corrupt low|mid|high|extreme` 可生成带噪音的训练数据。详细信息：[docs/annotated](docs/annotated.md)，[docs/corruption](docs/corruption.md)。
## 确定性
每个值均派生自 `(seed, record_number, field_name)`。这意味着：
- 添加字段不会改变现有字段的值。
- 在配置中重新排列字段顺序不会改变其值。
- 在算法指纹相同的前提下，使用相同的 seed 可以在不同语言和版本间产生字节完全一致的输出。
在 CI 中固定指纹以检测算法变更：
```
seedfaker --fingerprint
# sf0-158dc9f79ce46b43
```
详细信息：[docs/determinism](docs/determinism.md)，[docs/context](docs/context.md)（身份关联）。
## 包与绑定
| 语言 / 运行时 | 安装命令 |.Registry | 本地文档 |
| ------------------ | -------------------------------------------- | -------------------------------------------------------------------------------------------------------- | ------------------------------------- |
| Python | `pip install seedfaker` | [pypi.org/project/seedfaker](https://pypi.org/project/seedfaker/) | [packages/pip](packages/pip/) |
| Node.js | `npm install @opendsr/seedfaker` | [npmjs.com/package/@opendsr/seedfaker](https://www.npmjs.com/package/@opendsr/seedfaker) | [packages/npm](packages/npm/) |
| Go | `go get github.com/opendsr-std/seedfaker-go` | [pkg.go.dev/github.com/opendsr-std/seedfaker-go](https://pkg.go.dev/github.com/opendsr-std/seedfaker-go) | [packages/go](packages/go/) |
| PHP | `composer require opendsr/seedfaker` | [packagist.org/packages/opendsr/seedfaker](https://packagist.org/packages/opendsr/seedfaker) | [packages/php](packages/php/) |
| Ruby | `gem install seedfaker` | [rubygems.org/gems/seedfaker](https://rubygems.org/gems/seedfaker) | [packages/ruby](packages/ruby/) |
| Browser (WASM) | `npm install @opendsr/seedfaker-wasm` | [npmjs.com/package/@opendsr/seedfaker-wasm](https://www.npmjs.com/package/@opendsr/seedfaker-wasm) | [packages/wasm](packages/wasm/) |
| CLI (npm) | `npm install -g @opendsr/seedfaker-cli` | [npmjs.com/package/@opendsr/seedfaker-cli](https://www.npmjs.com/package/@opendsr/seedfaker-cli) | [packages/npm-cli](packages/npm-cli/) |
| CLI (Homebrew) | `brew install opendsr-std/tap/seedfaker` | [github.com/opendsr-std/homebrew-tap](https://github.com/opendsr-std/homebrew-tap) | [docs/cli](docs/cli.md) |
| CLI (Cargo) | `cargo install seedfaker` | [crates.io/crates/seedfaker](https://crates.io/crates/seedfaker) | [docs/cli](docs/cli.md) |
所有包都封装了相同的 Rust 核心。除了各语言的原生命名习惯外，API 表面在不同语言中保持了高度一致。
## 文档
参考文档：[docs/](docs/)。
| | |
| ---------------- | --------------------------------------------------------------------------------------------------------- |
| **从这里开始** | [快速开始](docs/quick-start.md) |
| **CLI** | [命令与标志](docs/cli.md) · [确定性](docs/determinism.md) |
| **字段** | [语法与修饰符](docs/fields.md) · [字段参考 (200+)](docs/field-reference.md) |
| **配置** | [YAML 配置](docs/configs.md) · [多表](docs/multi-table.md) · [表达式](docs/expressions.md) |
| **输出** | [模板](docs/templates.md) · [标注](docs/annotated.md) · [流式处理](docs/streaming.md) |
| **数据质量** | [上下文](docs/context.md) · [数据损坏模拟](docs/corruption.md) · [替换](docs/replace.md) |
| **预设** | [内置预设](docs/presets.md) (nginx, payment, auth, postgres, syslog, medical, …) |
| **集成** | [库 API](docs/library.md) · [MCP](docs/mcp.md) |
工作流：[guides/](guides/)。可运行示例：[examples/](examples/)。
## 快速开始
```
pip install seedfaker
python -c 'from seedfaker import SeedFaker; print(SeedFaker(seed="demo").record(["name","email"]))'
```
或使用 CLI：
```
brew install opendsr-std/tap/seedfaker
seedfaker name email phone --seed demo --until 2025 -n 5
```
接下来：[docs/quick-start](docs/quick-start.md) 提供 10 分钟的演练，[docs/cli](docs/cli.md) 提供标志说明，[docs/fields](docs/fields.md) 提供字段语法定义。
## 指南
位于 [guides/](guides/) 的端到端工作流：
| | |
|----------- | ------------------------------------------------------------------------ |
| [填充数据库](guides/seed-database.md) | 带有跨表 FK 的 Postgres/MySQL 模拟数据库 |
| [填充大型数据库](guides/seed-large-database.md) | GB/TB 级批量加载 —— 并行 COPY，UNLOGGED，性能调优 |
| [分布式生成](guides/distributed-generation.md) | 无需协调器的多主机分片生成 |
| [匿名化生产数据](guides/anonymize-data.md) | 针对 CSV/JSONL 的 `replace`，保持跨文件的 FK 完整性 |
| [训练与评估数据集](guides/training-data.md) | NER/PII，LLM 微调，带有 ground truth 的评估，红蓝对抗，多语言 |
| [可复现的数据集](guides/reproducible-datasets.md) | 确定性测试固件，CI，指纹防护 |
| [库用法](guides/library-usage.md) | Python / Node.js SDK 模式 |
| [模拟 API 服务器](guides/mock-api-server.md) | Express / FastAPI 模拟 endpoint |
| [API 负载测试](guides/api-load-testing.md) | 限速流式处理，数据损坏 |
| [面向 AI 代理的 MCP](guides/mcp-ai-agents.md) | Claude / Cursor / VS Code 集成 |
## 基准测试
可复现的吞吐量测量、安装脚本、按字段细分的性能分析，以及端到端的 Postgres 加载基准测试 (`payments_5gb.sh`)：[benchmarks/](benchmarks/)。
## 许可证
MIT
标签：GNU通用公共许可证, Go语言, LLM训练数据, MCP, MITM代理, Node.js, OpenVAS, PHP, PII生成, Python, Ruby, Rust, TB级数据处理, TPC-H, WebAssembly, 个人隐私信息, 伪随机, 全量替换, 分布式生成, 可视化界面, 合成数据, 外键, 多表关联, 多语言支持, 威胁情报, 安全测试框架, 开发者工具, 数据匿名化, 数据库测试, 数据掩码, 数据流水线, 数据清洗, 数据脱敏, 文档结构分析, 无后门, 日志审计, 本地化, 机器学习数据集, 流处理, 测试数据生成, 知识库, 确定性生成, 程序破解, 网络流量审计, 逆向工具, 通知系统