openfold3

用途

OpenFold3 是 AlQuraishi 实验室发布的、基于 PyTorch 的 AlphaFold3 开源权重复现版本，用于结构预测。本技能适用于需要预测蛋白质、核酸及配体复合物结构的场景。

环境要求

项目	最低要求	推荐配置
Python	3.10+	3.11
CUDA	12.1+	12.4
GPU 显存	24GB	80GB (H100)
内存	32GB	64GB
磁盘（权重）	3GB	-

安装与权重下载

安装命令：

pip install 'openfold3[cuequivariance]==0.4.1'

默认注意力核为 DeepSpeed DS4Sci_EvoformerAttention。若 DeepSpeed 不可用，可改用 cuEquivariance 三角核（无需从源码构建），方法是在 model_config.py 中覆盖 eval 内存设置（use_deepspeed_evo_attention: False，use_cueq_triangle_kernels: True）。部分预构建环境已自带该覆盖，重新打补丁前请先检查。

权重为 Apache-2.0 许可，约 2.3 GB，来自 HF 的 OpenFold/OpenFold3。该仓库受门控（自动批准）——需在 HF 模型页面接受访问表单并完成认证（huggingface-cli login 或 HF_TOKEN）后才能下载：

export OPENFOLD_CACHE=~/.openfold3
huggingface-cli download OpenFold/OpenFold3 checkpoints/of3-p2-155k.pt \
  --local-dir "$OPENFOLD_CACHE"

若出口开放且具备 HF 凭证（HF_TOKEN 或此前已 huggingface-cli login）并已获得仓库访问权限，run_openfold 在首次运行时会自动下载到 $OPENFOLD_CACHE。交互式 setup_openfold 助手存在，但会从 stdin 提示输入；非交互式运行请优先使用上述显式下载。

运行方式

export OPENFOLD_CACHE=/path/to/cache
run_openfold predict \
  --query_json=queries.json \
  --output-dir out/ \
  --use-msa-server false \
  --use-templates false

run_openfold 会自动在 $OPENFOLD_CACHE 下发现检查点。仅当目录布局非标准或存在多个检查点需显式固定某一个时，才传入 --inference-ckpt-path <file.pt>。

若需使用 MSA + 模板（较慢但精度更高），去掉上述两个 false 标志。MSA 服务器为 api.colabfold.com；模板链 ID 重映射访问 data.rcsb.org（GraphQL）——两者均需可访问。

查询 JSON 格式

OpenFold3 不读取 FASTA。查询为经 InferenceQuerySet（pydantic，extra: forbid——未知键会被拒绝）校验的 JSON 对象：

{
  "queries": {
    "my_complex": {
      "chains": [
        {"molecule_type": "protein", "chain_ids": ["A"], "sequence": "MQIFVK…"},
        {"molecule_type": "protein", "chain_ids": ["B", "C"], "sequence": "MVLSPA…"},
        {"molecule_type": "ligand",  "chain_ids": ["L"], "smiles": "CC(=O)Oc1ccccc1C(=O)O"}
      ],
      "use_msas": true
    }
  },
  "seeds": [42]
}

• protein / dna / rna：需要必填字段 sequence
• ligand：需要 smiles 或 ccd_codes: ["HEM"]
• chain_ids 为列表——同源寡聚体可在多个链 ID 上重复同一序列
• 每链的 paired_msa_file_paths / main_msa_file_paths 可让你提供自己的 a3m，而不用服务器

关键参数

标志	默认值	说明
--num-diffusion-samples	5	每个（查询，seed）生成的结构数
--num-model-seeds	1	每个查询的模型 seed 数（与 JSON seeds 及扩散采样共同倍增输出数量）
--use-msa-server	true	ColabFold MMseqs2 服务器提供 MSA
--use-templates	true	ColabFold 模板搜索 + RCSB 重映射
--inference-ckpt-path	自动在 $OPENFOLD_CACHE 下发现	仅用于覆盖——非标准布局或固定特定检查点文件

输出格式

out/
├── summary.txt
├── model_config.json / experiment_config.json
├── inference_query_set.json
└── <query_name>/seed_<N>/
    ├── <query>_seed_<N>_sample_<k>_model.cif
    ├── <query>_seed_<N>_sample_<k>_confidences.json           # 完整 PAE/pLDDT
    ├── <query>_seed_<N>_sample_<k>_confidences_aggregated.json
    └── timing.json

*_confidences_aggregated.json 是应先读取的小文件：

{
  "avg_plddt": 78.96, "ptm": 0.667, "iptm": 0.0, "gpde": 0.73,
  "has_clash": 0.0, "sample_ranking_score": 0.133,
  "chain_ptm": {"A": 0.667}, "chain_pair_iptm": {}
}

良好输出的判断标准

• summary.txt 显示 Successful Queries: N 与输入数量一致
• avg_plddt > 70（单序列）/ > 80（使用 MSA）
• ptm > 0.6；对于复合物，iptm > 0.5
• has_clash: 0.0
• 对小蛋白，每个样本的 .cif 约 50-150 KB

验证：

grep -E 'Successful|Failed' out/summary.txt
find out -name '*_model.cif' | wc -l   # = queries x json_seeds x num-model-seeds x num-diffusion-samples

故障排查

错误	原因	修复
_deepspeed_evo_attn requires that DeepSpeed be installed	默认 eval 核在 CUDA 上为 DS4Sci	安装 deepspeed（需 nvcc + CUTLASS），或在 model_config.py 的 eval 块中设 use_deepspeed_evo_attention: False + use_cueq_triangle_kernels: True（cuEq 路径；无需构建）
CUTLASS_PATH ... not set ... cutlass_library is not installed	cuEq 路径仍需要 python cutlass_library shim	pip install nvidia-cutlass
libXrender.so.1: cannot open shared object file	rdkit（经 pdbeccdutils）需要 X11 渲染库	apt-get install libxrender1 libxext6 libsm6
ModuleNotFoundError: boto3 (或 awscrt)	即使权重在本地，openfold3.core.data.io.s3 也会急切导入	pip install boto3 awscrt
ValidationError: queries / Field required 或 Input should be an object	JSON 形状错误	顶层为 {"queries": {"<name>": {...}}}（字典，不是列表）
ValidationError ... settings / Extra inputs are not permitted	试图通过 --runner-yaml 覆盖模型配置	--runner-yaml 仅为 InferenceExperimentConfig；内核/内存设置位于 model_config.py
Failed to fetch chain ID mappings from RCSB for N entries	data.rcsb.org 不可达（允许列表/离线）	以 --use-templates false 运行，或开放对 data.rcsb.org 的出口
CUDA out of memory	大复合物 / 样本过多	减少 --num-diffusion-samples；low_mem 预设（model_setting_presets.yml）会进行更积极的卸载

适用场景与限制

适用于蛋白质、DNA、RNA 及配体复合物的结构预测，支持使用 MSA 与模板来提升精度。运行依赖较高 GPU 资源（最低 24GB 显存），MSA 与模板功能需要外部服务可达。本资料未提供收费、价格及具体预测精度承诺等信息。