diffdock

DiffDock：使用扩散模型进行分子对接

概述

DiffDock 是一种基于扩散模型的深度学习工具，用于分子对接，可预测小分子配体与蛋白质靶标的 3D 结合构象。它代表了计算对接领域的先进水平，对基于结构的药物发现和化学生物学至关重要。

核心功能：

• 使用深度学习高精度预测配体结合构象
• 支持蛋白质结构（PDB 文件）或序列（通过 ESMFold）
• 处理单个复合物或批量虚拟筛选任务
• 生成置信度分数，用于评估预测可靠性
• 支持多种配体输入（SMILES、SDF、MOL2）

关键区别：DiffDock 预测的是结合构象（3D 结构）和置信度（预测确定性），而不是结合亲和力（ΔG、Kd）。评估亲和力时，务必结合评分函数（GNINA、MM/GBSA）。

何时使用此技能

在以下情况下应使用此技能：

• “将此配体对接到蛋白质”或“预测结合构象”
• “运行分子对接”或“执行蛋白质-配体对接”
• “虚拟筛选”或“筛选化合物库”
• “这个分子在哪里结合？”或“预测结合位点”
• 基于结构的药物设计或先导化合物优化任务
• 涉及 PDB 文件 + SMILES 字符串或配体结构的任务
• 对多个蛋白质-配体对进行批量对接

安装和环境设置

检查环境状态

开始 DiffDock 任务前，请验证环境设置：

# Use the provided setup checker
python scripts/setup_check.py

此脚本会验证 Python 版本、带 CUDA 的 PyTorch、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）不存在，会自动下载

核心工作流

工作流 1：单个蛋白质-配体对接

**使用场景：**将一个配体对接到一个蛋白质靶标

输入要求：

• 蛋白质：PDB 文件或氨基酸序列
• 配体：SMILES 字符串或结构文件（SDF/MOL2）

命令：

python -m inference \
  --config default_inference_args.yaml \
  --protein_path protein.pdb \
  --ligand "CC(=O)Oc1ccccc1C(=O)O" \
  --out_dir results/single_docking/

替代方式（蛋白质序列）：

python -m inference \
  --config default_inference_args.yaml \
  --protein_sequence "MSKGEELFTGVVPILVELDGDVNGHKF..." \
  --ligand ligand.sdf \
  --out_dir results/sequence_docking/

输出结构：

results/single_docking/
├── rank_1.sdf          # Top-ranked pose
├── rank_2.sdf          # Second-ranked pose
├── ...
├── rank_10.sdf         # 10th pose (default: 10 samples)
└── confidence_scores.txt

工作流 2：批量处理多个复合物

**使用场景：**将多个配体对接到蛋白质，执行虚拟筛选任务

步骤 1：准备批处理 CSV

使用提供的脚本创建或验证批处理输入：

# Create template
python scripts/prepare_batch_csv.py --create --output batch_input.csv

# Validate existing 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 个化合物）：

预先计算蛋白质嵌入，以加快处理速度：

# Pre-compute embeddings
python datasets/esm_embedding_preparation.py \
  --protein_ligand_csv screening_input.csv \
  --out_file protein_embeddings.pt

# Run with pre-computed embeddings
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：分析结果

对接完成后，分析置信度分数并对预测结果排序：

# Analyze all results
python scripts/analyze_results.py results/batch/

# Show top 5 per complex
python scripts/analyze_results.py results/batch/ --top 5

# Filter by confidence threshold
python scripts/analyze_results.py results/batch/ --threshold 0.0

# Export to CSV
python scripts/analyze_results.py results/batch/ --export summary.csv

# Show top 20 predictions across all complexes
python scripts/analyze_results.py results/batch/ --best 20

分析脚本会：

• 解析所有预测结果中的置信度分数
• 将结果分类为高（>0）、中（-1.5 到 0）或低（<-1.5）
• 对单个复合物内部及不同复合物之间的预测结果排序
• 生成统计摘要
• 将结果导出为 CSV，以便后续分析

置信度评分解读

评分含义：

评分范围	置信度等级	解读
> 0	高	预测可靠，很可能准确
-1.5 to 0	中	预测合理，需仔细验证
< -1.5	低	预测不确定，需要验证

重要注意事项：

1. 置信度 ≠ 亲和力：高置信度表示模型对结构的确定性高，并不代表结合能力强
2. 需结合上下文判断：调整预期时需考虑：
   • 大型配体（>500 Da）：预期置信度较低
   • 多条蛋白质链：可能降低置信度
   • 新型蛋白质家族：表现可能不佳
3. 多个样本：查看排名靠前的 3-5 个预测结果，寻找共识

**详细指南：**使用 Read 工具阅读 references/confidence_and_limitations.md

参数自定义

使用自定义配置

为特定用例创建自定义配置：

# Copy template
cp assets/custom_inference_config.yaml my_config.yaml

# Edit parameters (see template for presets)
# Then run with custom config
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）
• 温度越高，构象越多样

模板提供的预设：

1. 高准确度：增加样本和步数，降低温度
2. 快速筛选：减少样本，加快运行
3. 柔性配体：提高扭转温度
4. 刚性配体：降低扭转温度

**完整参数参考：**使用 Read 工具阅读 references/parameters_reference.md

高级技术

集合对接（蛋白质柔性）

对于已知具有柔性的蛋白质，可对接至多个构象：

# Create ensemble 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/*.sdf; do
    gnina -r protein.pdb -l "$pose" --score_only
done

MM/GBSA（更准确，但速度较慢）： 能量最小化后使用 AmberTools MMPBSA.py 或 gmx_MMPBSA

自由能计算（最准确）： 使用 OpenMM + OpenFE 或 GROMACS 进行 FEP/TI 计算

推荐工作流：

1. DiffDock → 生成构象并提供置信度评分
2. 目视检查 → 检查结构的合理性
3. GNINA 或 MM/GBSA → 重新评分并按亲和力排序
4. 实验验证 → 生化检测

局限性和适用范围

DiffDock 专为以下用途设计：

• 小分子配体（通常为 100-1000 Da）
• 类药有机化合物
• 小肽（<20 个残基）
• 单链或多链蛋白质

DiffDock 并非为以下用途设计：

• 大型生物分子（蛋白质-蛋白质对接）→ 使用 DiffDock-PP 或 AlphaFold-Multimer
• 大型多肽（>20 个残基）→ 使用替代方法
• 共价对接 → 使用专用的共价对接工具
• 结合亲和力预测 → 结合评分函数使用
• 膜蛋白 → 未经过专门训练，请谨慎使用

**完整局限性说明：**使用 Read 工具阅读 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

问题：结合姿势不合理

• 原因：蛋白质准备不当、配体过大、结合位点错误
• 解决方案：检查蛋白质是否缺少残基，移除较远的水分子，并考虑指定结合位点

问题：出现“Module not found”错误

• 原因：缺少依赖项或环境错误
• 解决方案：运行 python scripts/setup_check.py 进行诊断

性能优化

获得最佳结果：

1. 使用 GPU（实际使用的必要条件）
2. 对重复使用的蛋白质预先计算 ESM 嵌入
3. 将多个复合物批量处理
4. 从默认参数开始，必要时再进行调整
5. 验证蛋白质结构（补齐缺失的残基）
6. 配体使用规范 SMILES

图形用户界面

如需交互式使用，请启动 Web 界面：

python app/main.py
# Navigate to http://localhost:7860

也可以使用在线演示，无需安装：

• https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web

资源

辅助脚本（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：配置模板

• 包含所有参数注释的 YAML
• 针对常见用例预设的四种配置
• 解释各参数的详细注释
• 可直接自定义并使用

最佳实践

1. 始终使用 setup_check.py 检查环境，再开始大型任务
2. 使用 prepare_batch_csv.py 验证批量 CSV，及早发现错误
3. 先使用默认值，再根据系统特定需求调整参数
4. 生成多个样本（10-40 个），以获得稳健的预测
5. 在下游分析前，对排名靠前的姿势进行目视检查
6. 结合评分函数评估亲和力
7. 使用置信度分数进行初步排序，而非作出最终决策
8. 为虚拟筛选活动预先计算嵌入
9. 记录所用参数，以确保可复现性
10. 尽可能通过实验验证结果

引用

使用 DiffDock 时，请引用相应论文：

DiffDock-L（当前默认模型）：

Stärk et al. (2024) "DiffDock-L: Improving Molecular Docking with Diffusion Models"
arXiv:2402.18396

原始 DiffDock：

Corso et al. (2023) "DiffDock: Diffusion Steps, Twists, and Turns for Molecular Docking"
ICLR 2023, arXiv:2210.01776

更多资源

• GitHub 仓库：https://github.com/gcorso/DiffDock
• 在线演示：https://huggingface.co/spaces/reginabarzilaygroup/DiffDock-Web
• DiffDock-L 论文：https://arxiv.org/abs/2402.18396
• 原始论文：https://arxiv.org/abs/2210.01776