RFdiffusion 完整教學

把 protein design (蛋白質設計; PD) 從「修改既有結構」推進到「從噪音開始 generate 全新功能蛋白質」。 這份教學涵蓋：原理、安裝、6 種主要 design task、實際 contig 寫法、資安考量、與 ProteinMPNN + AlphaFold pipeline 整合。

1. 專案定位

1.1 一句話介紹

RFdiffusion = RoseTTAFold 結構預測網路 + denoising diffusion model (去噪擴散模型; DDM)。輸入「想要的條件」（motif、binding target、對稱性、長度），輸出「符合條件的 protein backbone (蛋白質骨架; PB)」coordinate。

1.2 為什麼是里程碑？

實驗驗證資料：原 paper 報導對 binder design 的 in vitro success rate ~10-25%（相比舊方法 < 1%），是目前 de novo protein design 最強路線。

1.3 適合誰？

1.4 為什麼 maintainer 在 issue 裡推 RFD3？

最新 commits 與 issue 回覆強烈引導使用者轉去 RosettaCommons/foundry/models/rfd3：

• v1 依賴 PyTorch 1.9 + CUDA 11.1（2023 年的組合），新顯卡 (RTX 4090 / 5090 / H100) 容易裝不起來
• RFD3 用更新 stack，且額外支援 ligand-aware design
• 但 v1 仍維持 — 部分 feature (cyclic peptides, scaffoldguided.target_ss/target_adj) 只在 v1 有

結論：新計畫請優先試 RFD3；本份 README 還是 v1 baseline。

1.5 數字快照（2026-05-19）

• ⭐ 2,869 stars / 616 forks（學術圈天花板級擴散度）
• 🧠 7 個官方 model checkpoint（Base / Complex_base / Complex_Fold_base / InpaintSeq / InpaintSeq_Fold / ActiveSite / Base_epoch8；可選 Complex_beta）
• 📜 12,320 LOC Python + SE3-Transformer 子模組
• 🔬 222 open issues — 反映使用社群極活躍

2. 安裝指南

2.1 4 條路徑對應使用情境

flowchart TD
    A[使用者] --> B{硬體 + 用途?}
    B -->|沒 GPU / 試水| C[Google Colab
sokrypton/ColabDesign]
    B -->|有 GPU, 想跑生產| D[Docker
rosettacommons/rfdiffusion]
    B -->|想改 code / 客製| E[Conda local install]
    B -->|新 GPU (40/50/H100)| F[改用 RFD3
RosettaCommons/foundry]
    C --> G[最快 5 分鐘]
    D --> H[一行 docker run]
    E --> I[30 分鐘 + 仔細對 CUDA]
    F --> J[更易 CUDA 12.x+ 安裝]

2.2 路徑 A：Google Colab（推薦先試）

1https://colab.research.google.com/github/sokrypton/ColabDesign/blob/v1.1.1/rf/examples/diffusion.ipynb

由 Sergey Ovchinnikov 維護的 ColabDesign repo 提供（非官方但作者掛保證）。優點：零安裝、免費 T4 GPU、直接玩 binder / motif scaffolding。缺點：runtime 限制、不適合 100+ designs 批次。

2.3 路徑 B：Docker（推薦正式使用）

 1git clone https://github.com/RosettaCommons/RFdiffusion.git
 2cd RFdiffusion
 3
 4# 1. 下載 7+1 個 model checkpoint (~5.4 GB)
 5mkdir $HOME/models
 6bash scripts/download_models.sh $HOME/models
 7
 8# 2. 建 image
 9docker build -f docker/Dockerfile -t rfdiffusion .
10
11# 3. 跑
12mkdir $HOME/inputs $HOME/outputs
13wget -P $HOME/inputs https://files.rcsb.org/view/5TPN.pdb
14
15docker run -it --rm --gpus all \
16  -v $HOME/models:$HOME/models \
17  -v $HOME/inputs:$HOME/inputs \
18  -v $HOME/outputs:$HOME/outputs \
19  rfdiffusion \
20  inference.output_prefix=$HOME/outputs/motifscaffolding \
21  inference.model_directory_path=$HOME/models \
22  inference.input_pdb=$HOME/inputs/5TPN.pdb \
23  inference.num_designs=3 \
24  'contigmap.contigs=[10-40/A163-181/10-40]'

或拉官方 image：

1docker pull rosettacommons/rfdiffusion

2.4 路徑 C：Conda local（要改 code 時）

 1git clone https://github.com/RosettaCommons/RFdiffusion.git
 2cd RFdiffusion
 3
 4# 1. 下載 model
 5mkdir models && bash scripts/download_models.sh models
 6
 7# 2. SE3 Transformer + RFdiffusion
 8conda env create -f env/SE3nv.yml      # 預設 CUDA 11.1；新 GPU 須改
 9conda activate SE3nv
10cd env/SE3Transformer
11pip install --no-cache-dir -r requirements.txt
12python setup.py install
13cd ../..
14pip install -e .                        # 裝 rfdiffusion module
15
16# 3. PPI scaffolds
17tar -xvf examples/ppi_scaffolds_subset.tar.gz -C examples/
18
19# 4. 跑驗證
20./examples/design_unconditional.sh

注意：SE3nv.yml 寫死 cudatoolkit=11.1 / pytorch=1.9。RTX 30 系列以新顯卡常見 issue：

2.5 路徑 D：RFD3 / foundry（新硬體強烈建議）

1git clone https://github.com/RosettaCommons/foundry.git
2cd foundry/models/rfd3
3# 跟著 https://rosettacommons.github.io/foundry/installation_faq.html

3. 核心架構解析

3.1 高層 pipeline

flowchart LR
    A[Input PDB +
contigs + flags] --> B[Hydra config
base.yaml]
    B --> C[Sampler
SelfConditioning]
    C --> D[Load checkpoint
torch.load .pt]
    D --> E[Iterative
denoising T=50 steps]
    E --> F[Output PDB
backbone only]
    F --> G[ProteinMPNN
序列設計]
    G --> H[AlphaFold
refold validation]
    H --> I[篩出 binder
pae/pLDDT/RMSD pass]

3.2 RFdiffusion 內部模組

flowchart TB
    subgraph Net[Neural Network]
        RF[RoseTTAFoldModel
backbone trunk]
        SE3[SE3_network
equivariant blocks]
        TRK[Track_module
1D/2D/3D track融合]
        ATTN[Attention_module]
        EMB[Embeddings]
    end
    subgraph Diffuser[Diffusion]
        DIFF[diffusion.py
Gaussian noise schedule]
        IG[igso3.py
SO3 rotation diffusion]
    end
    subgraph Inf[Inference]
        RUN[run_inference.py
Hydra entry]
        SMP[inference/utils.py
Sampler selector]
        RNR[inference/model_runners.py
SelfConditioning / Symmetric]
        POT[potentials/
auxiliary objectives]
    end
    subgraph IO[I/O]
        CTG[contigs.py
parse contigmap]
        UTL[util.py
writepdb_multi]
    end
    Inf --> Net
    Inf --> Diffuser
    Inf --> IO

3.3 contigmap — 控制設計範圍的 DSL

contigmap.contigs 是 RFdiffusion 的核心 DSL，舉幾個典型：

/0 是 chainbreak token，不是序列；告訴 RFdiffusion 兩段之間在空間上是分開的 chain。

3.4 7 個 model checkpoint

inference.ckpt_override_path=models/ActiveSite_ckpt.pt 切換。

3.5 配套網路（不在 repo 內）

完整 design pipeline 通常還串：

過濾準則：自己的 backbone RMSD < 2 Å + pLDDT > 85 + interaction PAE < 10 算「在電腦上看起來會 work」。

4. Helper Scripts 詳細用法

4.1 主要進入點

 1# 用 Hydra config（base.yaml 預設）
 2python scripts/run_inference.py \
 3    inference.output_prefix=samples/design \
 4    inference.num_designs=10 \
 5    inference.input_pdb=path/to/input.pdb \
 6    'contigmap.contigs=[10-40/A163-181/10-40]'
 7
 8# 換 model
 9python scripts/run_inference.py \
10    inference.ckpt_override_path=models/ActiveSite_ckpt.pt \
11    ...
12
13# 對稱
14python scripts/run_inference.py \
15    --config-name=symmetry \
16    inference.symmetry=tetrahedral \
17    ...
18
19# Deterministic（reproducibility）
20python scripts/run_inference.py \
21    inference.deterministic=True \
22    ...

4.2 19 個範例 shell script

examples/ 目錄是學最快的捷徑，每個都是 python scripts/run_inference.py ... 加好參數：

4.3 helper_scripts/

1# 從 input pdb 生 secondary-structure + adjacency .pt 檔（給 scaffoldguided 用）
2python helper_scripts/make_secstruc_adj.py \
3    --input_pdb input.pdb \
4    --out_dir scaffold_features/

4.4 inference 重要 flag

5. 應用場景

5.1 場景 A：設計 SARS-CoV-2 受體 binder

 1# 1. 拿 spike RBD (chain A) 結構
 2wget https://files.rcsb.org/view/6M0J.pdb -O spike_rbd.pdb
 3
 4# 2. RFdiffusion 設計 binder
 5python scripts/run_inference.py \
 6    inference.output_prefix=outputs/spike_binder \
 7    inference.input_pdb=spike_rbd.pdb \
 8    inference.num_designs=500 \
 9    'contigmap.contigs=[A19-228/0 60-100]' \
10    'ppi.hotspot_res=[A87,A100,A110]' \
11    inference.ckpt_override_path=models/Complex_base_ckpt.pt
12# /0 = chainbreak, 60-100 = binder 長度範圍, hotspot = 想接觸的殘基
13
14# 3. ProteinMPNN 設計序列
15python ProteinMPNN/protein_mpnn_run.py \
16    --pdb_path outputs/spike_binder_0.pdb \
17    --pdb_path_chains B \
18    --num_seq_per_target 8
19
20# 4. AlphaFold filter — 只留 RMSD < 2, pLDDT > 85, iPAE < 10

預期 500 designs → 100 過 AF filter → 表達 10-20 個 → 1-2 個會綁住（in vitro 經驗值）。

5.2 場景 B：設計新酶（含 active site）

1# 把 catalytic triad (Ser-His-Asp, 3 residues) 嵌入 100 aa scaffold
2python scripts/run_inference.py \
3    inference.output_prefix=outputs/protease \
4    inference.input_pdb=trypsin_motif.pdb \
5    inference.num_designs=100 \
6    'contigmap.contigs=[10-40/A195-195/3-8/A57-57/3-8/A102-102/10-40]' \
7    inference.ckpt_override_path=models/ActiveSite_ckpt.pt

5.3 場景 C：對稱 cage 設計（疫苗 scaffold）

1python scripts/run_inference.py \
2    --config-name=symmetry \
3    inference.symmetry=tetrahedral \
4    inference.num_designs=20 \
5    'contigmap.contigs=[100-100]' \
6    potentials.guiding_potentials=['type:olig_contacts,weight_intra:1,weight_inter:0.1']

5.4 場景 D：環肽藥物候選

1# RFpeptides macrocycle
2python scripts/run_inference.py \
3    inference.output_prefix=outputs/macrocycle \
4    inference.num_designs=200 \
5    'contigmap.contigs=[10-15]' \
6    inference.cyclic=True \
7    inference.cyc_chains='a'

6. 資安掃描報告

對 ML / bioinformatics repo 的資安重點 = 模型權重供應鏈 + pickle deserialization + inference script 隔離。

6.1 結論：🟡 MEDIUM RISK（屬於 ML repo 的典型風險）

對學術研究環境可接受，但生產 / 服務端部署需加防護。

6.2 細項

6.3 建議使用者實作

1# 在 model_runners.py 加保護
2self.ckpt = torch.load(self.ckpt_path, map_location=self.device, weights_only=True)
3# 或 PyTorch ≥ 2.6 已預設 safe（loading pure tensor state_dict）

1# 自己 verify checkpoint
2sha256sum models/*.pt
3# 對比 RosettaCommons 官方公告（issue / release notes）

6.4 給 lab / 機構的建議

1. 集中下載 + verify：在 lab server 一次下載 checkpoint，verify hash 後 mount 到 user container
2. 氣隔 (air-gap)：inference 跑在沒外網的 container，避免 model 被替換
3. dual-use review：對應 institutional biosafety review；設計 toxin / vaccine antigen / SARS-related sequence 前先報 IBC

7. FAQ

Q1：跑一次需要多少 GPU 記憶體？ A：基本 monomer 100 aa 大約 8 GB；binder + target 300+ aa 需 16-24 GB。empty_cache_per_design=True 可降約 20%。CPU 也能跑但慢 100×。

Q2：要不要學 ProteinMPNN？ A：強烈建議。RFdiffusion 只出 backbone (Cα coordinate) 沒有序列；要實際表達必過 ProteinMPNN（或同類序列設計工具）。

Q3：Issue #440 那個「RFD 設計位置 vs AF3 預測位置不符」怎麼辦？ A：maintainer 解釋是 ML model memorization bias（看過太多同源結構，AF 把 binder 預設到「常見」位置）。三招：

1. negative design（加 clash potential 把不想要的位置堵死）
2. 用物理 docking (Rosetta / MD) 二次驗證
3. 拿來實驗測 — 計算預測不準 ≠ 實驗會失敗

Q4：v1 跟 RFD3 我選哪個？ A：

• 新 GPU (CUDA 12+) / 想要 ligand-aware → RFD3
• 需要 cyclic peptide / scaffoldguided target_ss/target_adj → v1
• 學習 / 教學 → v1（README 詳盡，社群討論多）

Q5：可商用嗎？ A：repo 寫 BSD 但 UW IPD 對「production / commercial use」加了 NC 條款（non-commercial）。商業 R&D 須跟 IPD 取得授權。學界自由用。

Q6：deterministic 模式準到位元組嗎？ A：inference.deterministic=True 固定 numpy / torch / random seed，但 GPU cuDNN nondeterministic algorithm 仍可能造成微小差異。同機 same driver 通常一致。

8. 進階技巧

8.1 用 ckpt_override_path 跑 A/B test

1for ckpt in Base_ckpt.pt Complex_base_ckpt.pt Base_epoch8_ckpt.pt; do
2  python scripts/run_inference.py \
3    inference.output_prefix=outputs/abtest_${ckpt%.pt} \
4    inference.ckpt_override_path=models/$ckpt \
5    inference.num_designs=50 \
6    'contigmap.contigs=[100-100]'
7done

8.2 加 auxiliary potential

1# 要求 radius of gyration < 20
2python scripts/run_inference.py \
3    potentials.guiding_potentials=['type:monomer_ROG,weight:0.5,min_dist:20'] \
4    potentials.guide_scale=2.0 \
5    potentials.guide_decay='constant' \
6    ...

支援 type 包括 monomer_ROG / binder_ROG / monomer_contacts / interface_ncontacts / olig_contacts。

8.3 Fold conditioning (scaffoldguided)

 1# 1. 先把 scaffold pdb 預處理
 2python helper_scripts/make_secstruc_adj.py \
 3    --input_pdb scaffold.pdb \
 4    --out_dir scaffold_features/
 5
 6# 2. 跑 fold-conditioned
 7python scripts/run_inference.py \
 8    scaffoldguided.scaffoldguided=True \
 9    scaffoldguided.target_ss=scaffold_features/scaffold_ss.pt \
10    scaffoldguided.target_adj=scaffold_features/scaffold_adj.pt \
11    inference.ckpt_override_path=models/Complex_Fold_base_ckpt.pt \
12    ...

8.4 大量平行（HPC / SLURM）

1#!/bin/bash
2#SBATCH --array=0-99
3#SBATCH --gres=gpu:1
4python scripts/run_inference.py \
5    inference.output_prefix=outputs/batch_${SLURM_ARRAY_TASK_ID} \
6    inference.design_startnum=$((SLURM_ARRAY_TASK_ID * 100)) \
7    inference.num_designs=100 \
8    'contigmap.contigs=[100-100]'

8.5 自訂 noise schedule

diffuser 子 config 改 T (step count) 與 noise_scale_ca / frame。實驗顯示 T=200 + lower noise 對小蛋白更穩，但慢 4×。

9. 整合進其他工作流

9.1 與本專案 (AI-knowledge_template) 的位置

flowchart LR
    A[paper-search
抓 RFdiffusion 相關 paper] --> B[inbox/Paper/]
    B --> C[paper-qa-lite
本地 RAG 問答]
    D[gh-tutorial-qd
本份 tutorial] --> E[inbox/ + projects/RFdiffusion/]
    E --> F[quarkdown
HTML 排版]
    F --> G[kami
選用：PDF]
    H[graphify
知識圖] --> I[未來：把 paper +
tutorial 串成 knowledge graph]

對應典型使用：先用 paper-search 蒐集 RFdiffusion 領域近期 paper，再用 paper-qa-lite 問「最新 binder design SOTA 是什麼」，最後跑 RFdiffusion 自己實驗 → 結果寫成新 paper。

9.2 與其他 protein design pipeline 整合

sequenceDiagram
    participant U as User
    participant RF as RFdiffusion
    participant MPNN as ProteinMPNN
    participant AF as AlphaFold/Boltz
    participant Lab as Wet Lab

    U->>RF: target.pdb + contigs
    RF->>MPNN: backbone .pdb (Cα only)
    MPNN->>AF: sequence (8 per design)
    AF->>U: pae/pLDDT/RMSD report
    U->>U: filter (pae<10 + pLDDT>85)
    U->>Lab: 表達 top 20 candidates
    Lab->>U: in vitro affinity data

每階段都會丟掉大量 candidate：1000 RFdiffusion designs → 200 過 ProteinMPNN → 50 過 AlphaFold filter → 10-20 表達 → 1-3 真的會綁。

9.3 與 BakerLab 後續工具

10. 重點摘要 Checklist

• RFdiffusion = RoseTTAFold + diffusion，protein backbone generation SOTA
• 6 種主要任務：motif scaffold / unconditional / symmetric / binder / partial diffusion / macrocycle
• contigs DSL 是核心：[10-40/A163-181/10-40] 控制 design 範圍與 motif
• 配套 ProteinMPNN + AlphaFold 才是完整 pipeline
• 7 個 checkpoint，依任務 ckpt_override_path 切換
• 安裝路徑 4 條：Colab / Docker / Conda / RFD3 (foundry, 新硬體強推)
• 資安 🟡 MEDIUM — torch.load 預設 pickle、model weight 來自 HTTP；研究 OK，prod 要加保護
• License BSD + UW NC clause — 學術自由 / 商用須授權
• dual-use 考量 — toxin / pathogen-related 設計須走 IBC review
• 222 open issues，活躍社群 + maintainer 主動引導去 RFD3

11. 進一步閱讀

• GitHub repo (v1)：https://github.com/RosettaCommons/RFdiffusion
• 後續版 RFD3 (foundry)：https://github.com/RosettaCommons/foundry/tree/production/models/rfd3
• 官方 documentation：https://sites.google.com/omsf.io/rfdiffusion/overview
• Foundry 文件站：https://rosettacommons.github.io/foundry/
• 原始論文（Watson, Juergens, Bennett et al. 2023, Nature）：https://www.biorxiv.org/content/10.1101/2022.12.09.519842v1
• ColabDesign（Sergey Ovchinnikov）：https://github.com/sokrypton/ColabDesign
• 官方 Docker image：https://hub.docker.com/r/rosettacommons/rfdiffusion
• ProteinMPNN：https://github.com/dauparas/ProteinMPNN
• LigandMPNN：https://github.com/dauparas/LigandMPNN
• AlphaFold：https://github.com/google-deepmind/alphafold
• BakerLab：https://www.bakerlab.org/
• UW IPD：https://www.ipd.uw.edu/

Captured：2026-05-19 by gh-tutorial-qd workflow（depth=full / lang=zh-tw / qd_preset=report / security=on）。