为什么你的蛋白质设计结果不可复现?RFD4-Proteina-prep的seed控制与RNG状态保持机制揭秘

原创2026-10-22 11:07:141,815 阅读
文章标签:人工智能生物信息学

为什么你的蛋白质设计结果不可复现?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):

  1. 调用前快照:np.random.get_state() 和 random.getstate() 保存当前状态;
  2. 沙盒执行:torch.random.fork_rng(devices=[]) 为 PyTorch 全局 RNG 开启一个隔离上下文,块内的所有随机数生成都不影响外部状态;
  3. 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)。

一句话总结你的检查清单:

  1. 输入 CIF 的哈希是否一致;
  2. prepare_cif(seed=...) 的 seed 是否记录;
  3. 管线 generator 是否 manual_seed;
  4. 模型 revision、Diffusers revision、helper revision 是否都固定(报告中均已记录)。

总结

RFD4-Proteina-prep 用"三路随机流固定 + 独立局部 RNG + 状态快照恢复 + 强制 generator"四层机制,把蛋白质设计里最难控的随机性变成了可审计、可复现的工程行为。下次你的设计结果"对不上"时,对照第五节的清单逐项排查,基本都能定位到元凶。想亲手验证,可以从仓库自带的示例输入 examples/inputs/protein_binder.cif 跑一遍预处理,观察两次相同 seed 的输出是否逐位一致。

登录后查看全文
RFD4-Proteina-prep