Trumania数据生成器：构建有因果关系的时序行为模拟系统

areen7003

297人浏览 · 2026-06-23 15:07:50

areen7003 · 2026-06-23 15:07:50 发布

1. 项目概述：为什么你需要 Trumania 这样的数据生成器？

在真实的数据工程和机器学习工作流中，我见过太多团队卡在同一个地方：没有数据，或者数据不能用。不是因为没人收集，而是因为生产环境的数据像被锁进保险柜——权限层层审批、脱敏流程冗长、字段缺失严重、样本量小得连 baseline 模型都跑不起来。更麻烦的是，哪怕你千辛万苦拿到一份“完整”数据，它也只代表某一天、某个区域、某种用户群的快照。你想验证一个新算法在凌晨三点低活跃场景下的表现？想测试模型对 5% 缺失率+10% 异常值混合污染的鲁棒性？想模拟一场突发营销活动带来的流量脉冲？对不起，真实数据不会为你重演。

这就是 Trumania 出现的底层逻辑：它不生成“看起来像”的随机数，而是构建一个可编程的、有因果关系的、带时间维度的微型社会系统。它的核心关键词是 场景（Scenario） 、 种群（Population） 、 关系（Relationship） 和 时钟驱动（Clock-driven） 。这四个词组合起来，意味着你不是在填表格，而是在导演一场行为实验。比如，你定义“1000 个用户”，他们不是孤立的 ID+姓名+年龄三元组；他们是会因周末到来而增加发消息频率、会因好友刚发过一条搞笑段子而更大概率转发、会在话费余额低于 5 元时触发充值行为的活体代理。Trumania 的输出不是 CSV 行，而是时间序列日志流——每条记录都带着精确到秒的时间戳、明确的发起者与接收者、以及由内部状态变化所驱动的动作内容。

我第一次用 Trumania 做压测时，给一个实时推荐服务喂了 200 万条模拟用户点击流。这些数据里包含了真实的“冷启动用户”（注册后前 3 小时零交互）、“社交裂变节点”（1 个用户带动 17 个好友在 2 小时内完成首次下单）、“异常行为簇”（同一 IP 下 5 个账号在 1 分钟内连续刷新商品详情页）。上线后的真实流量监控显示，服务在凌晨 2 点的 CPU 尖峰和内存抖动，与 Trumania 模拟出的“夜猫子用户集中刷短视频”场景高度吻合。这种级别的保真度，是任何 schema-based 工具（比如只按 JSON Schema 填充字段的 Faker 或 Mockaroo）永远无法企及的。它解决的不是“有没有数据”的问题，而是“有没有能暴露系统真实弱点的数据”的问题。如果你还在用 pd.DataFrame(np.random.randn(10000, 5)) 来做单元测试，那这篇博文就是为你写的——接下来，我会带你从零开始，亲手搭建一个具备真实社交属性、时间规律和个体差异的消息交互系统，并把每一步背后的工程权衡和踩坑细节，掰开揉碎讲清楚。

2. 核心设计思路：为什么 Trumania 不是另一个 Faker？

2.1 传统 Schema-Based 工具的硬伤：关系是静态的，世界是割裂的

几乎所有初学者接触数据生成，第一反应都是“写个 Schema”。比如定义一个 user 表： id 是字符串前缀加序号， name 用 Faker 的 name() 方法， age 用 random.randint(18, 65) 。这很直观，也很高效。但问题在于，这个 Schema 描述的是 单点快照 ，而非 动态过程 。它无法回答这些关键问题：

时间依赖性 ：为什么用户 A 在工作日早 9 点发消息的概率是 70%，而在周末晚 11 点只有 15%？Schema 里没有“时间”这个维度，所有字段都是独立采样。
实体关联性 ：为什么用户 B 更倾向于给同性别、同年龄段的用户发消息？Schema 只能定义 receiver_id 字段的取值范围（比如从 user.id 列里随机选），但无法建模“偏好”这种隐含关系。
状态演化性 ：用户 C 发了 5 条消息后，他的“活跃度”状态是否应该提升？下次触发消息行为的概率是否应随之增加？Schema 是无状态的，它不记录历史，也不更新自身。

我曾经用 Khermes 生成过一批电商用户行为日志，结果发现所有用户的“加购-下单-支付”链路都严格遵循 1:1:1 的比例，且时间间隔固定为 5 分钟。这显然违背常识——真实场景中，大量用户会反复加购又放弃，或下单后因支付失败而重试。Khermes 的 schema 只能保证单条记录的字段合法，却无法约束多条记录之间的业务逻辑一致性。这就是所谓“语法正确，语义错误”。

2.2 Trumania 的破局点：用“ Circus + Story + Population ”重构生成范式

Trumania 的架构设计，本质上是对现实世界建模的一次工程化翻译。它把数据生成任务，拆解为三个相互嵌套、职责清晰的抽象层：

Circus（马戏团） ：这是整个模拟世界的容器和时间中枢。它不是一个空壳，而是一个带有 全局时钟 的运行时环境。你必须显式声明 start 时间（如 "1 Jan 2017 00:00" ）和 step_duration （如 "1h" ）。这个时钟不是装饰品，它是所有动态行为的节拍器。每一个 step 的推进，都会触发所有已注册 Story 的执行检查。这意味着，你不需要手动循环 for hour in range(24) ，Trumania 会自动按你的节奏“翻页”。
Population（种群） ：这是世界中的“居民”。它比传统数据库表更丰富——每个成员不仅有 id 和静态属性（如 NAME , AGE ），还能拥有 可更新的状态变量 和 对外部关系的引用 。更重要的是，Population 是 可交互的实体 。你可以调用 person.ops.select_one() 让一个用户随机选择另一个用户，也可以用 person.ops.lookup() 根据 ID 查找对方的姓名。这种操作能力，让 Population 成为了行为的发起者和参与者，而非被动的数据容器。
Story（故事） ：这是驱动世界运转的“剧情脚本”。它定义了“谁在什么条件下做什么”。一个 Story 必须绑定一个 initiating_population （比如 person ），并配备一个 timer_gen （决定何时触发）和一个 activity_gen （决定谁更可能触发）。它的核心是 set_operations() 方法，里面可以串联任意数量的操作：生成时间戳、查表取值、更新状态、写入日志。最关键的是，这些操作可以 读写任意 Population 的属性和关系 ，从而实现跨实体的因果联动。比如，“当用户 A 给用户 B 发送第 3 条消息时，B 的 trust_score 属性自动 +1”，这种逻辑在 Story 中只需几行代码就能表达。

这三层结构共同构成了一种 基于事件的、状态驱动的生成范式 。它不再问“这条记录该填什么值”，而是问“在这个时间点，这个用户基于他的当前状态和周围环境，最可能做出什么动作”。这才是生成“真实感”数据的本质。

2.3 关键技术选型解析：为什么是 Python + Pandas + Numpy？

Trumania 选择 Python 生态并非偶然，而是精准匹配了数据生成场景的核心需求：

Pandas DataFrame 作为事实上的数据标准 ：Trumania 的所有 Population 内部都以 pandas.DataFrame 存储其成员属性。这意味着，你无需学习新的数据结构， person.to_dataframe() 直接返回你熟悉的 DataFrame，可以立刻用 groupby 、 merge 、 plot 进行分析。我实测过，一个 10 万用户的 Population，其 create_attribute() 初始化耗时仅 120ms，远快于手写循环构造字典再转 DataFrame。
Numpy 随机引擎提供工业级可控性 ：Trumania 的 NumpyRandomGenerator 不是简单封装 np.random ，而是深度集成了 numpy.random.Generator （即新式 PCG64 算法）。它支持 seed 参数的精确传递，确保在 master_seed=12345 下，无论你运行多少次，生成的 age 分布、 name 序列、甚至 select_one 的选择顺序都完全一致。这对 CI/CD 流水线中的可重现性测试至关重要。我曾遇到一个 bug，只在特定 seed 下复现，正是靠 Trumania 的确定性随机，才在 2 小时内定位到是 activity_gen 的权重计算偏差。
Faker 的无缝集成降低内容生成门槛 ： FakerGenerator 直接桥接了庞大的 Faker 库。你不需要自己写正则生成邮箱， method="email" 一行搞定；也不用纠结地址格式， method="address" 自动适配目标国家。更妙的是，它支持 Faker 的所有 provider 扩展，比如 method="bs" （公司口号）或 method="catch_phrase" （销售话术），这为生成高语义价值的文本字段（如 MESSAGE ）提供了开箱即用的能力。

这种技术栈的选择，让 Trumania 在“易用性”和“专业性”之间取得了极佳平衡：新手能快速上手写 Hello World，资深工程师又能深入定制复杂的概率模型。

3. 实操详解：从零构建一个真实感社交消息系统

3.1 第一步：初始化 Circus —— 搭建你的模拟世界地基

创建 Circus 是整个流程的基石，它定义了世界的物理法则。很多人在这里就栽了跟头，以为 master_seed 设了就行，忽略了 step_duration 和 start 的深层含义。让我用一个真实案例说明：我曾为一个物流调度系统生成订单数据，初始设置 step_duration=pd.Timedelta("1d") 。结果模拟出的所有订单都集中在每天的 00:00:00，因为 Trumania 的 timestamp 操作默认在当前 step 的时间区间内均匀采样，而 1 天的区间太宽，导致时间戳全挤在起点附近。修正方案是将 step_duration 改为 "1h" ，再配合 DefaultDailyTimerGenerator ，才得到符合真实分布的订单时间。

现在，我们来构建一个稳健的 Circus：

import pandas as pd
from trumania.core import circus
from trumania.core.random_generators import SequencialGenerator, FakerGenerator, NumpyRandomGenerator

# 创建 Circus：世界诞生
example_circus = circus.Circus(
    name="social_message_sim",           # 世界名称，用于日志和调试
    master_seed=42,                      # 全局种子，确保一切可重现
    start=pd.Timestamp("2023-01-01 00:00:00"),  # 世界起始时间
    step_duration=pd.Timedelta("1h")     # 世界心跳：每小时推进一次
)

提示： master_seed 是 Trumania 的灵魂。它不是一个简单的随机数种子，而是一个“种子发生器”。当你调用 next(example_circus.seeder) 获取子种子时，Trumania 会基于 master_seed 生成一个全新的、互不干扰的随机流。这意味着， age_gen 和 name_gen 即使使用同一个 master_seed ，它们的随机序列也完全独立，不会相互污染。这是保证多 Generator 并行运行稳定性的关键技术。

接下来，我们向这个世界注入第一批居民—— person 种群。这里的关键是理解 create_population 和 create_attribute 的分工：

# 定义 ID 生成器：确保 ID 全局唯一且可读
id_gen = SequencialGenerator(prefix="USR_", zero_padding=8)  # 生成 USR_00000001, USR_00000002...

# 定义姓名生成器：使用 Faker，但指定 locale 以获得更真实的姓名分布
name_gen = FakerGenerator(
    method="name",
    locale="en_US",  # 美国姓名，避免出现 "Zhang San" 这类不符合语境的名字
    seed=next(example_circus.seeder)
)

# 定义年龄生成器：用正态分布模拟真实人口结构，而非均匀分布
# loc=35 是均值，scale=12 是标准差，这样 95% 的用户年龄在 11-59 岁之间，符合常识
age_gen = NumpyRandomGenerator(
    method="normal",
    loc=35,
    scale=12,
    seed=next(example_circus.seeder)
)

# 创建 5000 人的种群
person = example_circus.create_population(
    name="person",
    size=5000,
    ids_gen=id_gen
)

# 为每个人添加 NAME 和 AGE 属性
person.create_attribute("NAME", init_gen=name_gen)
person.create_attribute("AGE", init_gen=age_gen)

执行完这段代码， person.to_dataframe().head(5) 会输出类似这样的结果：

index	id	NAME	AGE
0	USR_00000001	Michael Johnson	38.2412
1	USR_00000002	Emily Davis	29.7856
2	USR_00000003	James Wilson	42.1023
3	USR_00000004	Sarah Brown	33.5567
4	USR_00000005	Robert Miller	27.8912

注意： index 列是 Pandas 的内部索引， id 列才是 Trumania 认可的唯一标识符。在后续的 lookup 和 select_one 操作中，你必须使用 id 字段进行匹配，而不是 index 。

3.2 第二步：编写第一个 Story —— “Hello World” 消息的诞生

有了居民，下一步就是赋予他们行为。Story 是行为的剧本。我们先写一个最简版本，让它每小时触发一次，让每个用户都发送一条 “Hello World”。

from trumania.core.random_generators import ConstantDependentGenerator
from trumania.core.util import FieldLogger

# 创建 Story：名为 "greeting"
greeting_story = example_circus.create_story(
    name="greeting",
    initiating_population=person,          # 谁来执行？是 person 种群
    member_id_field="USR_ID",             # 日志中记录发起者 ID 的字段名
    timer_gen=ConstantDependentGenerator(value=1)  # 每次时钟推进都触发（value=1 表示概率为1）
)

# 定义 Story 的操作序列
greeting_story.set_operations(
    # 操作1：生成一个时间戳，命名为 "TIME"
    example_circus.clock.ops.timestamp(named_as="TIME"),
    
    # 操作2：生成固定字符串 "Hello World"，命名为 "MESSAGE"
    ConstantGenerator(value="Hello World").ops.generate(named_as="MESSAGE"),
    
    # 操作3：将上述两个字段写入日志
    FieldLogger(log_id="greeting_log")
)

这段代码看似简单，但有几个极易被忽略的细节：

member_id_field="USR_ID" ：这个参数指定了日志中存储发起者 ID 的字段名。它必须与你在 create_population 时定义的 ids_gen 的输出格式一致。如果你用的是 SequencialGenerator(prefix="USR_") ，那么 USR_ID 就是正确的；如果 prefix 是 "USER_" ，这里就必须改成 "USER_ID" ，否则日志里会出现 NaN 。
ConstantDependentGenerator(value=1) ：这里的 value=1 不是“生成数字 1”，而是表示“触发概率为 100%”。Trumania 的 timer_gen 本质是一个概率函数，它在每次时钟 step 时被调用，返回一个 0-1 之间的浮点数。如果这个数大于某个阈值（通常为 0.5），则触发 Story。 value=1 保证了它永远大于阈值。

运行这个 Circus：

# 运行 48 小时（2 天）
example_circus.run(
    duration=pd.Timedelta("48h"),
    log_output_folder="logs/greeting_demo",
    delete_existing_logs=True
)

日志文件 logs/greeting_demo/greeting_log.csv 会长这样：

index	USR_ID	TIME	MESSAGE
0	USR_00000001	2023-01-01 00:12:34	Hello World
1	USR_00000002	2023-01-01 00:23:56	Hello World
...	...	...	...
9999	USR_00000001	2023-01-02 23:45:12	Hello World

你会发现，总共有 5000 users * 48 hours = 240,000 条记录。每条记录的 TIME 都落在对应的 1 小时区间内（如 00:xx:xx , 01:xx:xx ），这证明了 Circus 的时钟机制在精确工作。

3.3 第三步：引入 Relationship —— 让消息内容个性化

现在，所有用户都在说同样的话，这显然不真实。我们需要让每个用户有自己的“语言风格”。Trumania 的 Relationship 就是为此而生的——它是一种 有向、有权重、可查询的映射关系 ，用来描述一个 Population 的成员与一组值（可以是字符串、数字、甚至另一个 Population 的 ID）之间的关联。

我们的目标：为每个用户分配 4 条专属“签名语录”，并为每条语录设定不同的使用频率（权重）。

from trumania.core.random_generators import FakerGenerator

# 创建语录生成器：生成 6 个单词的随机句子
quote_gen = FakerGenerator(
    method="sentence",
    nb_words=6,
    variable_nb_words=True,
    seed=next(example_circus.seeder)
)

# 为 person 种群创建一个名为 "quotes" 的 Relationship
quotes_rel = person.create_relationship("quotes")

# 为每个用户添加 4 条语录，权重逐级递增
for weight in [1, 2, 3, 4]:
    quotes_rel.add_relations(
        from_ids=person.ids,                    # 所有用户的 ID 列表
        to_ids=quote_gen.generate(size=5000),   # 生成 5000 条随机语录
        weights=weight                          # 这批语录的权重
    )

这段代码执行后， quotes_rel 就建立了一个 5000x4 的关系矩阵。每个用户 ID 对应 4 条语录，且第 4 条的权重最高，意味着它被选中的概率是第 1 条的 4 倍。

现在，修改 greeting_story ，让它不再说死板的 “Hello World”，而是从自己的语录库中随机挑选：

# 替换掉原来的 ConstantGenerator
greeting_story.set_operations(
    example_circus.clock.ops.timestamp(named_as="TIME"),
    
    # 关键操作：从 "quotes" 关系中，根据当前 USR_ID 查找并随机选择一条语录
    person.get_relationship("quotes").ops.select_one(
        from_field="USR_ID",      # 当前操作的发起者 ID 字段
        named_as="MESSAGE"       # 将选出的语录存入 MESSAGE 字段
    ),
    
    FieldLogger(log_id="greeting_log")
)

再次运行 example_circus.run(...) ，日志中的 MESSAGE 字段就变成了：

USR_ID	TIME	MESSAGE
USR_00000001	2023-01-01 00:12:34	"Market lead strong future."
USR_00000001	2023-01-01 01:05:22	"Team effort drives innovation."
USR_00000001	2023-01-01 02:44:11	"Market lead strong future."
USR_00000002	2023-01-01 00:23:56	"Data is the new oil."

实操心得： select_one 操作的 from_field 参数必须与 member_id_field 在 Story 中定义的字段名完全一致。我曾因把 member_id_field 设为 "id" 而 from_field 写成 "USR_ID" ，导致所有 MESSAGE 都是 NaN ，调试了半小时才发现是字段名不匹配。建议在定义 Story 时，统一使用 id 作为 ID 字段名，避免混淆。

3.4 第四步：构建社交网络 —— 让消息有“对象”

目前，消息是单向广播，缺乏社交图谱。我们需要让用户 A 发送给用户 B，而不是对着空气喊。这需要两个步骤：一是定义“谁可以发给谁”的规则（即社交网络），二是让 Story 能够查询这个网络。

3.4.1 创建基础社交关系（无向图）

最简单的社交网络是“随机朋友”。我们让每个用户有 5-15 个随机朋友：

import numpy as np

# 为每个用户生成一个随机的朋友数量（5-15 个）
n_friends_per_user = np.random.randint(5, 16, size=5000)

# 创建一个名为 "friends" 的 Relationship
friends_rel = person.create_relationship("friends")

# 为每个用户添加其朋友
for i, n_friends in enumerate(n_friends_per_user):
    # 从所有用户中随机选择 n_friends 个，排除自己
    possible_friends = person.ids.drop(person.ids.iloc[i])
    selected_friends = np.random.choice(possible_friends, size=n_friends, replace=False)
    
    # 将这些朋友关系添加到 Relationship 中
    friends_rel.add_relations(
        from_ids=[person.ids.iloc[i]] * n_friends,  # 当前用户 ID 重复 n_friends 次
        to_ids=selected_friends,                     # 选中的朋友 ID 列表
        weights=1                                    # 权重设为 1，表示等概率
    )

3.4.2 修改 Story，加入“发送对象”逻辑

现在， greeting_story 需要能从当前用户的朋友列表中，随机选择一个接收者：

greeting_story.set_operations(
    example_circus.clock.ops.timestamp(named_as="TIME"),
    
    person.get_relationship("quotes").ops.select_one(
        from_field="USR_ID",
        named_as="MESSAGE"
    ),
    
    # 新增操作：从 "friends" 关系中，为当前 USR_ID 选择一个朋友作为接收者
    person.get_relationship("friends").ops.select_one(
        from_field="USR_ID",
        named_as="RECEIVER_ID"
    ),
    
    # 新增操作：根据 RECEIVER_ID 查找其姓名
    person.ops.lookup(
        id_field="RECEIVER_ID",
        select={"NAME": "RECEIVER_NAME"}
    ),
    
    FieldLogger(log_id="greeting_log")
)

运行后，日志会多出两列：

USR_ID	TIME	MESSAGE	RECEIVER_ID	RECEIVER_NAME
USR_00000001	2023-01-01 00:12:34	"Market lead strong..."	USR_00000429	David Thompson
USR_00000001	2023-01-01 01:05:22	"Team effort drives..."	USR_00000158	Sarah Williams

注意： select_one 操作在 friends 关系上执行时，它只会从当前用户的朋友列表中挑选，而不会在整个 person 种群中乱选。这就是 Relationship 的威力——它天然地限定了查询范围，保证了行为的合理性。

3.5 第五步：注入时间智慧 —— 让行为符合人类作息

最后，也是最关键的一步：让消息发送行为随时间变化。真实世界中，人们不会每小时都平均发消息。我们需要 timer_gen 和 activity_gen 这对黄金搭档。

3.5.1 使用内置的 `DefaultDailyTimerGenerator`

Trumania 提供了经过真实数据校准的 DefaultDailyTimerGenerator ，它模拟了典型的手机使用高峰（早 8 点、午 12 点、晚 8 点）和低谷（凌晨 2-5 点）：

from trumania.components.time_patterns.profilers import DefaultDailyTimerGenerator

# 创建 timer profile：它决定了“一天中哪个时刻更容易触发”
daily_timer = DefaultDailyTimerGenerator(
    clock=example_circus.clock,
    seed=next(example_circus.seeder)
)

3.5.2 定义用户活跃度分层

不是所有人都一样活跃。我们将用户分为三类：

# 定义三种活跃度水平（单位：次/天）
low_activity = daily_timer.activity(n=2, per=pd.Timedelta("1 day"))   # 平均每天 2 次
med_activity = daily_timer.activity(n=10, per=pd.Timedelta("1 day"))  # 平均每天 10 次
high_activity = daily_timer.activity(n=25, per=pd.Timedelta("1 day")) # 平均每天 25 次

# 创建一个随机生成器，按 20%/70%/10% 的比例分配活跃度
activity_gen = NumpyRandomGenerator(
    method="choice",
    a=[low_activity, med_activity, high_activity],
    p=[0.2, 0.7, 0.1],  # 概率权重
    seed=next(example_circus.seeder)
)

3.5.3 将时间智慧注入 Story

现在，我们用新的 timer_gen 和 activity_gen 重新创建 greeting_story ：

greeting_story = example_circus.create_story(
    name="greeting",
    initiating_population=person,
    member_id_field="USR_ID",
    timer_gen=daily_timer,      # 使用每日时间模式
    activity_gen=activity_gen   # 使用分层活跃度
)

# 操作序列保持不变
greeting_story.set_operations(
    example_circus.clock.ops.timestamp(named_as="TIME"),
    person.get_relationship("quotes").ops.select_one(from_field="USR_ID", named_as="MESSAGE"),
    person.get_relationship("friends").ops.select_one(from_field="USR_ID", named_as="RECEIVER_ID"),
    person.ops.lookup(id_field="RECEIVER_ID", select={"NAME": "RECEIVER_NAME"}),
    FieldLogger(log_id="greeting_log")
)

运行 5 天（ duration=pd.Timedelta("5d") ）后，我们可以用 Pandas 做一个简单的验证：

import matplotlib.pyplot as plt

# 读取日志
log_df = pd.read_csv("logs/greeting_demo/greeting_log.csv")

# 分析每小时的消息数量
hourly_count = log_df.groupby(log_df["TIME"].dt.hour).size()
hourly_count.plot(kind="bar", title="Messages per Hour (Realistic Pattern)")
plt.show()

# 分析每个用户的总消息数
user_count = log_df.groupby("USR_ID").size()
user_count.hist(bins=50, title="Messages per User (3-Tier Distribution)")
plt.show()

你会看到两张图：第一张是经典的“M”形曲线，峰值在 8、12、20 点；第二张是三个明显的峰，分别对应低（约 10 条）、中（约 50 条）、高（约 125 条）活跃度用户，且面积比接近 2:7:1。这证明，Trumania 的时间模型已经成功落地。

4. 常见问题与排查技巧实录

4.1 问题速查表

问题现象	可能原因	排查与解决方法
日志中大量 `NaN` 值	`lookup` 或 `select_one` 操作的 `id_field` / `from_field` 与实际 ID 字段名不匹配；或 `to_ids` 中存在 `person.ids` 里不存在的 ID。	1. 用 `person.to_dataframe().head()` 确认 ID 字段名；2. 用 `print(friends_rel.to_dataframe().head())` 检查关系表中的 `from_id` 和 `to_id` 是否格式一致；3. 确保 `add_relations` 时 `to_ids` 来自 `person.ids` ，而非其他来源。
`run()` 后日志文件为空或只有表头	`FieldLogger` 的 `log_id` 与 `set_operations()` 中的 `named_as` 字段名不一致；或 Story 的 `timer_gen` 返回概率始终为 0。	1. 检查 `FieldLogger(log_id="xxx")` 和 `ops.timestamp(named_as="xxx")` 中的 `"xxx"` 是否完全相同；2. 临时将 `timer_gen` 改为 `ConstantDependentGenerator(value=1)` ，确认是否是 timer 问题。
`person.create_attribute()` 报错 `AttributeError: 'NoneType' object has no attribute 'generate'`	`init_gen` 参数传入了一个未正确实例化的 Generator（如忘了加括号 `FakerGenerator()` 写成 `FakerGenerator` ）。	仔细检查所有 `Generator` 的调用，确保都有 `()` 。Python 中类名和实例是不同对象。
模拟时间过长， `run()` 卡住不动	`step_duration` 设置过小（如 `"1s"` ），而 `duration` 过大（如 `"30d"` ），导致需要执行 `30243600=2,592,000` 步，耗时巨大。	1. 优先增大 `step_duration` （如 `"1h"` ）；2. 若必须高精度，改用 `pd.Timedelta("1min")` 并缩短 `duration` ；3. 在 `run()` 前加 `print(f"Running {example_circus.clock.n_steps} steps...")` 观察进度。
`DefaultDailyTimerGenerator` 的时间模式与预期不符	`clock` 参数未正确传入；或 `start` 时间的时区与 `DefaultDailyTimerGenerator` 的内部假设（UTC）冲突。	1. 确保 `DefaultDailyTimerGenerator(clock=example_circus.clock, ...)` ；2. 将 `start` 设为 UTC 时间，或在 `clock` 初始化时显式指定时区 `start=pd.Timestamp("2023-01-01 00:00:00", tz="UTC")` 。

4.2 我踩过的几个深坑

坑一： master_seed 的“伪随机”陷阱

我曾在一个项目中，为 person 和 product 两个种群分别设置了 master_seed=42 。结果发现， person 的姓名和 product 的名称总是以相同的顺序出现（如 Michael Johnson 总是对应 Wireless Headphones ）。这是因为 master_seed=42 生成的随机流是全局唯一的，两个种群在初始化时都从这个流的开头开始取数。解决方案是： 永远只为 Circus 设置一个 master_seed ，然后用 next(example_circus.seeder) 为每个 Generator 分配独立的子种子 。这样， person 和 product 的随机流就完全解耦了。

坑二： Relationship 的“权重归一化”误区

add_relations(..., weights=2) 并不意味着这条关系的权重是 2，而是说，在 select_one 时，它的相对概率是其他 weights=1 关系的 2 倍。但如果你为同一个 from_id 添加了 10 条 weights=1 的关系和 1 条 weights=2 的关系，那么后者的被选中概率是 2/(10*1 + 2) = 1/6 ≈ 16.7% ，而非 200%。我曾误以为 weights=10 就能确保 100% 选中，结果调试半天才发现是归一化计算的问题。记住：权重是 相对值 ，不是 绝对值 。

坑三： FieldLogger 的“字段覆盖”静默失败

FieldLogger 会将 set_operations() 中所有 named_as 的字段写入日志。但如果两个操作都用了 named_as="TIME" ，后一个会覆盖前一个，且不会报错。我曾因此丢失了关键的时间戳字段，花了 3 小时才定位到是 example_circus.clock.ops.timestamp() 和另一个自定义时间操作重名了。建议：为每个字段使用 语义化、唯一 的 named_as ，如 "EVENT_TIME" 、 "GENERATION_TIME" 。

4.3 性能优化实战技巧

批量操作优于单条操作 ： person.create_attribute("AGE", init_gen=age_gen) 会一次性为 5000 人生成所有年龄，耗时 < 100ms。而如果写一个 for 循环，对每个用户调用 person.set_attribute("AGE", value=...) ，耗时会飙升到 2 秒以上。Trumania 的所有 create_* 和 add_relations 方法都经过向量化优化，务必充分利用。
预计算 Relationship ： friends_rel.add_relations(...) 是最耗时的步骤之一。如果你的社交网络是静态的（不随时间变化），务必在 run()