为什么你的蛋白质设计结果不可复现?RFD4-Proteina-prep的seed控制与RNG状态保持机制揭秘
为什么你的蛋白质设计结果不可复现?RFD4-Proteina-prep的seed控制与RNG状态保持机制揭秘
RFD4-Proteina-prep 是 RFD4-Proteina 蛋白质设计模型的前端预处理包:它负责把带注释的 CIF 输入文件转换成模型可消费的特征张量,再把生成结果导回新的 annotated CIF。如果你的蛋白质设计结果每次运行都不一样,问题往往不在模型本身,而在于两处随机性没有固定住——输入准备阶段的 seed 控制和扩散采样阶段的 RNG 状态。这篇文章将带你拆解 RFD4-Proteina-prep 的完整复现机制。
一、蛋白质设计的随机性藏在哪里?
💡 一次完整的 RFD4-Proteina 设计流程中有两个独立的随机源,漏掉任何一个,结果都无法复现:
| 随机源 | 发生位置 | 由谁控制 |
|---|---|---|
| 灵活片段展开(expandable segments) | prepare_cif 预处理阶段 |
prepare_cif 的 seed 参数 |
| 扩散去噪采样 | RFD4ProteinaPipeline 生成阶段 |
传入的 generator(torch.Generator) |
输入 CIF 中标记为"可展开"的灵活片段(比如待设计的循环区域),在预处理时会被确定性地"实现"成具体残基——这一步本身是随机的,由独立的 expandable_segment_rng 驱动(见 datapipes_pipeline.py 中的 RealizeExpandableSegments 转换)。也就是说:即使扩散管线完全固定,seed 不同也会导致喂给模型的特征张量不同,最终结构自然不同。
二、seed 控制机制:prepare_cif 如何固定三路随机流
核心实现位于 processing.py。prepare_cif 接受一个必传的 seed 关键字参数,它在内部同时固定三条随机流:
with torch.random.fork_rng(devices=[]):
np.random.seed(seed % 2**32) # NumPy 全局流
random.seed(seed) # Python 标准库流
torch.random.default_generator.manual_seed(seed) # PyTorch 全局流
...
pipeline = build_design_validation_pipeline(
...,
expandable_segment_rng=np.random.default_rng(seed), # 独立的片段展开 RNG
)
🔁 注意第四个关键点:灵活片段展开并不直接消费 NumPy 全局流,而是由 np.random.default_rng(seed) 创建一个相互独立的局部 Generator(processing.py)。这意味着片段展开的随机性与其它随机操作互不干扰,行为更可预测。
在 Hub 自定义块中,seed 同样被显式暴露为一个输入参数(默认 42,见 block.py),并强制要求必须是整数——传 True 或 4.2 会直接抛错,把配置错误挡在门外。
三、RNG 状态保持:prepare_cif 为何不"污染"你的全局随机环境
这是 RFD4-Proteina-prep 一个容易被忽视但极其重要的设计:prepare_cif 结束后,调用方的 Python、NumPy、PyTorch 全局随机状态必须与调用前完全一致。实现分三步(processing.py):
- 调用前快照:
np.random.get_state()和random.getstate()保存当前状态; - 沙盒执行:
torch.random.fork_rng(devices=[])为 PyTorch 全局 RNG 开启一个隔离上下文,块内的所有随机数生成都不影响外部状态; - finally 恢复:无论成功还是抛异常,
np.random.set_state和random.setstate都会把快照还原回去。
这个保证有正式的回归测试守护:test_custom_block.py 中的 test_preparation_matches_package_and_preserves_rng 会逐一对比调用前后的三路随机状态,并断言所有特征张量逐位相等(rtol=0, atol=0)。
✅ 这个设计的实际收益:你的脚本里其它依赖全局 RNG 的逻辑(数据增强、dropout 之外的采样等)不会因为调用了一次 prepare_cif 而悄悄漂移——两次调用之间插入任何随机操作,都不会影响下一次设计的结果。
四、生成端复现:为 RFD4ProteinaPipeline 固定 generator
预处理张量固定后,还要固定扩散采样。做法是传入一个手动播种的 torch.Generator:
output = pipe(
**inputs,
conditioning_features=conditioning,
generator=torch.Generator("cuda:0").manual_seed(42),
)
需要一次生成多个候选设计时,为每个设计各配一个独立 seed,并同步复制特征(用 repeat_interleave,导出时用 row 参数逐行写出),完整写法见 README.md 的 Fine-tuning 之后一节与 tests/test_write_cif_designs.py:
generator=[torch.Generator("cuda:0").manual_seed(seed) for seed in range(designs)]
⚠️ 常见坑:特征没有按 repeat_interleave 复制就直接多行导出时,第二个设计会抛 IndexError 而不是静默写错行——这是刻意的"响亮失败"设计,宁可报错也不输出错误数据。
五、可复现工作流清单:从 seed 到报告
把上面两路随机源固定后,还差最后一环:版本与环境。项目自带的 examples/run_hub_examples.py 提供了一个完整的复现模板:
--seed(默认 42)同时用于prepare_cif和torch.Generator,一处配置,两处生效;- 输入文件下载后做 SHA-256 校验,哈希不一致直接失败,源信息与任务参数记录在 examples/manifest.json;
- 运行结束后写出带版本信息的报告,包含
helper_revision、model_revision和seed(run_hub_examples.py)。
维护手册 MAINTAINING.md 给出了可交付给下游的复现断言:
对于特征张量不变的输入,同一 checkpoint、同一 seed 下,模型输出必须逐位一致(bit-identical)。
一句话总结你的检查清单:
- 输入 CIF 的哈希是否一致;
prepare_cif(seed=...)的 seed 是否记录;- 管线
generator是否manual_seed; - 模型 revision、Diffusers revision、helper revision 是否都固定(报告中均已记录)。
总结
RFD4-Proteina-prep 用"三路随机流固定 + 独立局部 RNG + 状态快照恢复 + 强制 generator"四层机制,把蛋白质设计里最难控的随机性变成了可审计、可复现的工程行为。下次你的设计结果"对不上"时,对照第五节的清单逐项排查,基本都能定位到元凶。想亲手验证,可以从仓库自带的示例输入 examples/inputs/protein_binder.cif 跑一遍预处理,观察两次相同 seed 的输出是否逐位一致。