DiffDock：基於擴散模型的分子對接
概述
DiffDock 是一款基於擴散模型的深度學習分子對接工具，能夠預測小分子配體與蛋白質目標的 3D 結合構形。它在計算對接領域代表了最先進水準，對結構基礎藥物發現與化學生物學至關重要。
核心能力：
- 利用深度學習高精度預測配體結合構形
- 支援蛋白質結構（PDB 檔案）或序列（透過 ESMFold）
- 處理單一複合物或批次虛擬篩選任務
- 產生信心分數以評估預測可靠性
- 處理多種配體輸入格式（SMILES、SDF、MOL2）
主要區別： DiffDock 預測 結合構形（3D 結構）與 信心度（預測確定性），而非結合親和力（ΔG、Kd）。請務必搭配評分函數（GNINA、MM/GBSA）進行親和力評估。
何時使用此技能
當出現以下情況時應使用此技能：
- 「將此配體對接到蛋白質上」或「預測結合構形」
- 「執行分子對接」或「進行蛋白質-配體對接」
- 「虛擬篩選」或「篩選化合物庫」
- 「此分子結合在哪裡？」或「預測結合位點」
- 結構基礎藥物設計或先導物最佳化任務
- 涉及 PDB 檔案 + SMILES 字串或配體結構的任務
- 批次對接多個蛋白質-配體配對
安裝與環境設定
檢查環境狀態
在開始 DiffDock 任務之前，請先驗證環境設定：
# 使用提供的設定檢查工具
python scripts/setup_check.py
此腳本會驗證 Python 版本、PyTorch 與 CUDA、PyTorch Geometric、RDKit、ESM 及其他相依套件。
安裝選項
選項 1：Conda（建議）
git clone https://github.com/gcorso/DiffDock.git
cd DiffDock
conda env create --file environment.yml
conda activate diffdock
選項 2：Docker
docker pull rbgcsail/diffdock
docker run -it --gpus all --entrypoint /bin/bash rbgcsail/diffdock
micromamba activate diffdock
重要注意事項：
- 強烈建議使用 GPU（比 CPU 快 10-100 倍）
- 首次執行時會預先計算 SO(2)/SO(3) 查詢表（約需 2-5 分鐘）
- 模型檢查點（約 500MB）會在下載不足時自動下載
- 目前上游版本是 DiffDock v1.1.3；
default_inference_args.yaml中預設的模型系列是 DiffDock-L
核心工作流程
工作流程 1：單一蛋白質-配體對接
使用案例： 將一個配體對接到一個蛋白質目標
輸入需求：
- 蛋白質：PDB 檔案或胺基酸序列
- 配體：SMILES 字串或結構檔案（SDF/MOL2）
指令：
python -m inference \
--config default_inference_args.yaml \
--protein_path protein.pdb \
--ligand_description "CC(=O)Oc1ccccc1C(=O)O" \
--out_dir results/single_docking/
替代方式（使用蛋白質序列）：
python -m inference \
--config default_inference_args.yaml \
--protein_sequence "MSKGEELFTGVVPILVELDGDVNGHKF..." \
--ligand_description ligand.sdf \
--out_dir results/sequence_docking/
輸出結構：
results/single_docking/
└── complex_0/
├── rank1.sdf # 排名第一構形的便利副本
├── rank1_confidence0.87.sdf # 排名第一構形，檔名包含信心分數
├── rank2_confidence0.42.sdf # 排名第二構形
├── ...
└── rank10_confidence-1.23.sdf # 第 10 個構形（預設：10 個樣本）
目前的 inference.py 使用 --ligand_description 參數進行單一複合物執行。上游 README 中可能仍寫 --ligand，請使用 --ligand_description，除非您的本地端明確支援 --ligand 別名。
工作流程 2：批次處理多個複合物
使用案例： 將多個配體對接到多個蛋白質，虛擬篩選任務
步驟 1：準備批次 CSV
使用提供的腳本建立或驗證批次輸入：
# 建立範本
python scripts/prepare_batch_csv.py --create --output batch_input.csv
# 驗證現有 CSV
python scripts/prepare_batch_csv.py my_input.csv --validate
CSV 格式：
complex_name,protein_path,ligand_description,protein_sequence
complex1,protein1.pdb,CC(=O)Oc1ccccc1C(=O)O,
complex2,,COc1ccc(C#N)cc1,MSKGEELFT...
complex3,protein3.pdb,ligand3.sdf,
必要欄位：
complex_name：唯一識別碼protein_path：PDB 檔案路徑（若使用序列則留空）ligand_description：SMILES 字串或配體檔案路徑protein_sequence：胺基酸序列（若使用 PDB 則留空）
步驟 2：執行批次對接
python -m inference \
--config default_inference_args.yaml \
--protein_ligand_csv batch_input.csv \
--out_dir results/batch/ \
--batch_size 10
大型虛擬篩選（>100 個化合物）：
預先計算蛋白質嵌入以加速處理：
# 預先計算嵌入
python datasets/esm_embedding_preparation.py \
--protein_ligand_csv screening_input.csv \
--out_file protein_embeddings.pt
# 使用預先計算的嵌入執行
python -m inference \
--config default_inference_args.yaml \
--protein_ligand_csv screening_input.csv \
--esm_embeddings_path protein_embeddings.pt \
--out_dir results/screening/
工作流程 3：分析結果
對接完成後，分析信心分數並對預測進行排名：
# 分析所有結果
python scripts/analyze_results.py results/batch/
# 每個複合物顯示前 5 名
python scripts/analyze_results.py results/batch/ --top 5
# 依信心門檻篩選
python scripts/analyze_results.py results/batch/ --threshold 0.0
# 匯出為 CSV
python scripts/analyze_results.py results/batch/ --export summary.csv
# 顯示所有複合物中前 20 名預測
python scripts/analyze_results.py results/batch/ --best 20
分析腳本會：
- 從所有預測中解析信心分數
- 分類為高（>0）、中（-1.5 到 0）或低（<-1.5）
- 在複合物內部及之間進行預測排名
- 產生統計摘要
- 將結果匯出為 CSV 以供後續分析
信心分數解讀
了解分數：
| 分數範圍 | 信心水準 | 解讀 |
|---|---|---|
| > 0 | 高 | 強預測，可能準確 |
| -1.5 到 0 | 中 | 合理預測，需仔細驗證 |
| < -1.5 | 低 | 不確定預測，需要驗證 |
重要說明：
- 信心 ≠ 親和力：高信心表示模型對結構有把握，而非強結合
- 情境很重要：根據以下情況調整預期：
- 大配體（>500 Da）：信心可能較低
- 多條蛋白質鏈：可能降低信心
- 新穎蛋白質家族：表現可能較差
- 多個樣本：檢查前 3-5 個預測，尋找一致結果
詳細指南請參閱： 使用讀取工具閱讀 references/confidence_and_limitations.md
參數自訂
使用自訂設定
為特定使用案例建立自訂設定：
# 複製範本
cp assets/custom_inference_config.yaml my_config.yaml
# 編輯參數（參見範本中的預設值）
# 然後使用自訂設定執行
python -m inference \
--config my_config.yaml \
--protein_ligand_csv input.csv \
--out_dir results/
主要調整參數
取樣密度：
samples_per_complex: 10→ 困難案例可增加至 20-40- 更多樣本 = 更好的覆蓋率，但執行時間更長
推理步驟：
inference_steps: 20→ 增加至 25-30 以獲得更高準確度- 更多步驟 = 可能更好的品質，但速度較慢
溫度參數（控制多樣性）：
temp_sampling_tor: 7.04→ 對於柔軟配體增加（8-10）temp_sampling_tor: 7.04→ 對於剛性配體減少（5-6）- 較高溫度 = 更多樣化的構形
範本中可用的預設組合：
- 高準確度：更多樣本 + 步驟，較低溫度
- 快速篩選：較少樣本，速度更快
- 柔軟配體：增加扭轉溫度
- 剛性配體：降低扭轉溫度
完整參數參考請參閱： 使用讀取工具閱讀 references/parameters_reference.md
進階技術
集成對接（蛋白質靈活性）
對於已知具有靈活性的蛋白質，可對接到多個構形：
# 建立集成 CSV
import pandas as pd
conformations = ["conf1.pdb", "conf2.pdb", "conf3.pdb"]
ligand = "CC(=O)Oc1ccccc1C(=O)O"
data = {
"complex_name": [f"ensemble_{i}" for i in range(len(conformations))],
"protein_path": conformations,
"ligand_description": [ligand] * len(conformations),
"protein_sequence": [""] * len(conformations)
}
pd.DataFrame(data).to_csv("ensemble_input.csv", index=False)
以增加取樣量執行對接：
python -m inference \
--config default_inference_args.yaml \
--protein_ligand_csv ensemble_input.csv \
--samples_per_complex 20 \
--out_dir results/ensemble/
與評分函數整合
DiffDock 產生構形；與其他工具結合以評估親和力：
GNINA（快速神經網路評分）：
for pose in results/single_docking/complex_0/*confidence*.sdf; do
gnina -r protein.pdb -l "$pose" --score_only
done
MM/GBSA（更準確，速度較慢）： 使用 AmberTools MMPBSA.py 或 gmx_MMPBSA（需先進行能量最小化）
自由能計算（最準確）： 使用 OpenMM + OpenFE 或 GROMACS 進行 FEP/TI 計算
建議工作流程：
- DiffDock → 產生具有信心分數的構形
- 視覺檢查 → 檢查結構合理性
- GNINA 或 MM/GBSA → 重新評分並依親和力排序
- 實驗驗證 → 生化分析
限制與範圍
DiffDock 設計用於：
- 小分子配體（通常 100-1000 Da）
- 類藥物有機化合物
- 小胜肽（<20 個殘基）
- 單鏈或多鏈蛋白質
DiffDock 不應用於：
- 大型生物分子（蛋白質-蛋白質對接）→ 請使用 DiffDock-PP 或 AlphaFold-Multimer
- 大型胜肽（>20 個殘基）→ 請使用其他方法
- 共價對接 → 請使用專用共價對接工具
- 結合親和力預測 → 請搭配評分函數使用
- 膜蛋白 → 未經專門訓練，請謹慎使用
完整限制說明請參閱： 使用讀取工具閱讀 references/confidence_and_limitations.md
疑難排解
常見問題
問題：所有預測的信心分數都很低
- 原因：配體過大/不常見、結合位點不明確、蛋白質具有靈活性
- 解決方案：增加
samples_per_complex（20-40），嘗試集成對接，驗證蛋白質結構
問題：記憶體不足錯誤
- 原因：GPU 記憶體不足以處理批次大小
- 解決方案：減少
--batch_size 2或一次處理較少複合物
問題：效能緩慢
- 原因：在 CPU 而非 GPU 上執行
- 解決方案：使用
python -c "import torch; print(torch.cuda.is_available())"驗證 CUDA，使用 GPU
問題：不切實際的結合構形
- 原因：蛋白質準備不足、配體過大、結合位點錯誤
- 解決方案：檢查蛋白質是否缺少殘基，移除週邊水分子，考慮指定結合位點
問題：「找不到模組」錯誤
- 原因：缺少相依套件或環境錯誤
- 解決方案：執行
python scripts/setup_check.py進行診斷
效能最佳化
為獲得最佳結果：
- 使用 GPU（實際使用時必不可少）
- 為重複使用的蛋白質預先計算 ESM 嵌入
- 批次處理多個複合物
- 從預設參數開始，再根據需要調整
- 驗證蛋白質結構（解決缺失殘基問題）
- 對配體使用標準 SMILES
圖形使用者介面
如需互動操作，請啟動網頁介面：
python app/main.py
# 前往 http://localhost:7860
或使用線上展示（無需安裝）：
資源
輔助腳本 (scripts/)
prepare_batch_csv.py：建立與驗證批次輸入 CSV 檔案
- 使用範例條目建立範本
- 驗證檔案路徑與 SMILES 字串
- 檢查必要欄位與格式問題
analyze_results.py：分析信心分數與預測排名
- 解析單次或批次執行的結果
- 產生統計摘要
- 匯出為 CSV 以供後續分析
- 識別各複合物中的最佳預測
setup_check.py：驗證 DiffDock 環境設定
- 檢查 Python 版本與相依套件
- 驗證 PyTorch 與 CUDA 可用性
- 測試 RDKit 與 PyTorch Geometric 安裝
- 在需要時提供安裝說明
參考文件 (references/)
parameters_reference.md：完整參數文件
- 所有命令列選項與設定參數
- 預設值與接受範圍
- 控制多樣性的溫度參數
- 模型檢查點位置與版本標誌
當使用者需要時請閱讀此檔案：
- 詳細的參數說明
- 針對特定系統的微調指南
- 替代取樣策略
confidence_and_limitations.md：信心分數解讀與工具限制
- 詳細的信心分數解讀
- 何時相信預測
- DiffDock 的範圍與限制
- 與互補工具整合
- 預測品質疑難排解
當使用者需要時請閱讀此檔案：
- 協助解讀信心分數
- 了解何時不應使用 DiffDock
- 與其他工具結合的指南
- 驗證策略
workflows_examples.md：完整工作流程範例
- 詳細安裝說明
- 所有工作流程的逐步範例
- 進階整合模式
- 常見問題疑難排解
- 最佳做法與最佳化技巧
當使用者需要時請閱讀此檔案：
- 含程式碼的完整工作流程範例
- 與 GNINA、OpenMM 或其他工具整合
- 虛擬篩選工作流程
- 集成對接程序
資產 (assets/)
batch_template.csv：批次輸入 CSV 範本
custom_inference_config.yaml：自訂推論設定範本
參考文獻
@article{corso2022diffdock,
title={DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking},
author={Corso, Gabriele and Stärk, Hannes and Jing, Bowen and Barzilay, Regina and Jaakkola, Tommi},
journal={International Conference on Learning Representations (ICLR)},
year={2023}
}