Boltz-2 生物分子相互作用与亲和力预测：从安装到首次预测的完整指南

Boltz-2 生物分子相互作用与亲和力预测：从安装到首次预测的完整指南

【免费下载链接】boltzOfficial repository for the Boltz biomolecular interaction models项目地址: https://gitcode.com/GitHub_Trending/bo/boltz

Boltz-2 是一个开源的生物分子相互作用预测模型，能同时输出蛋白质-配体复合物的三维结构和结合亲和力（log10 IC50）。它面向药物发现团队，把原本需要物理模拟算数天甚至数周的亲和力评估压缩到分钟级，代码与权重采用 MIT 协议，可自由用于学术和商业场景。对刚接触它的用户，本文给出一条最短路径：装好环境、跑通仓库自带的亲和力示例、看懂输出 JSON，再按需调参。

快速上手：3 步跑通首次预测

官方推荐用 PyPI 安装（pip install boltz[cuda] -U），也可以直接克隆仓库安装以获取每日更新。仓库自带examples/affinity.yaml示例，包含一条蛋白质序列、一个小分子 SMILES，以及properties中的affinity: binder: B配置，正好可以当首次运行的输入：

git clone https://gitcode.com/GitHub_Trending/bo/boltz cd boltz && pip install -e .[cuda] boltz predict examples/affinity.yaml --use_msa_server

环境要求 Python 3.10~3.12，建议配 NVIDIA GPU，CPU 模式明显更慢。首次运行会自动从 Hugging Face 下载模型权重，之后走本地缓存。

跑完后结果落在以输入文件命名的目录下：predictions/里有预测结构.cif（带 per-token pLDDT）、confidence_*.json（含 confidence_score、iptm、complex_plddt 等打分）、以及开启亲和力后的affinity_*.json。亲和力 JSON 里有两个关键字段：affinity_pred_value是 log10(IC50)（IC50 以 μM 计，数值越小结合越强，例如输出 0 对应 10⁻⁶ M），affinity_probability_binary是 0~1 的结合概率。前者用于比较已知活性分子之间的强弱，后者用于区分结合物与非结合物。换算提示：pIC50(kcal/mol) = (6 - y) × 1.364，y 为模型输出。

原理速览

Boltz-2 的核心架构是 ESM 风格的编码器加结构扩散模型。蛋白质序列和 MSA（多序列比对）先被编码成语义特征，配体则通过 CCD 数据库或 SMILES 解析成原子图特征，两者一起送入扩散过程逐步"去噪"出复合物的原子坐标。可以把 MSA 理解为进化的上下文：同家族蛋白哪些位置保守、哪些可变，直接暗示了结合口袋的形态，这也是为什么蛋白质输入默认要求提供 MSA。

亲和力预测挂在结构预测之上，但用了独立的输出头：一个头输出结合概率（二分类监督，训练目标是把 binder 和 decoy 分开），另一个头输出 log10(IC50) 回归值（目标是捕捉小结构改动引起的亲和力变化）。两个头训练数据不同、监督方式不同，官方建议分开使用，而不是混着解读。

结构预测部分 Boltz-2 把 AlphaFold3 的"注意力主干 + 扩散采样"流程做了开源化实现，默认 3 轮 recycling、200 步采样、1 个样本；需要更高精度时可以按 AlphaFold3 的标准配置加到 10 轮 recycling、25 个样本，代价是时间成倍增加。在 GPU 上 Boltz 还会调用 NVIDIA cuEquivariance 加速核，老卡上可关掉换稳定性。

实战场景：四种典型用法

场景一：化合物库虚拟筛选。输入一个目录，Boltz 会批量处理其中所有 YAML 文件，用affinity_probability_binary做过滤，按概率排序保留头部分子进入实验验证。筛选阶段只关心"是否结合"，所以用概率值而不是回归值。

场景二：先导化合物优化。对同一靶点的 10~20 个结构类似物各跑一次预测，比较affinity_pred_value的相对变化来指导下一轮改造。注意该字段只在活性分子之间比较才有意义，不要拿它去筛 inactive。

场景三：已知结合口袋的结构预测。在 YAML 的constraints段加pocket约束，指定 binder 链和口袋残基编号（contacts用 [链ID, 残基序号] 列表），把预测限制在真实结合位点附近。参考仓库里的examples/pocket.yaml。

场景四：大环/肽类分子筛选。加上--affinity_mw_correction对分子量做校正，避免大小分子之间因分子量差异不公平比较。配体硬上限 128 个重原子（RDKit RemoveHs 后），官方建议不要显著超过 56 个。

采样参数速查：

更多输入格式细节（模板、共价键、contact 约束、MSA 服务器鉴权）见 docs/prediction.md。

效果验证：benchmark 数字

官方在 FEP+、CASP16 等基准上报告了亲和力性能。FEP+ 4 targets 上 Boltz-2 的 Pearson 相关系数为 0.66，与 OpenFE 持平，高于 GAT（0.40）和 MM/PBSA（0.19），略低于参考方法 FEP+/ABFE（0.78/0.75）；CASP16 上 Boltz-2 达到 0.65，高于 GAT 的 0.50 和 VncDeep 的 0.47。官方表述：Boltz-2 是首个逼近物理自由能微扰（FEP）精度、同时快约 1000 倍的深度学习模型，这正是"in silico 筛选可行"的关键。

结构预测方面（含 Boltz-1/2x 全家族），测试集 Intra-Protein lDDT 上 Boltz-2 为 0.86，与 AF3 的 0.87 基本持平；Physics Validity 上 Boltz-2 达 0.97，明显高于 AF3 的 0.39，说明预测结构的物理合理性更好。Ligand-Protein lDDT 上 Boltz-2 为 0.59，与 Boltz-1 一致，低于 AF3 的 0.75——配体口袋精度仍有提升空间，这是选型时需要知道的边界。

常见报错与参数避坑

Q：老 GPU 上报 cuEquivariance 相关错误？加--no_kernels关闭加速核即可正常运行，速度略降。这是官方给出的标准解法。

Q：提示缺 MSA，但我没打算做 MSA？蛋白质输入默认要求 MSA。要么加--use_msa_server自动生成，要么在 YAML 里写msa: path/to/file.a3m。msa: empty（单序列模式）虽然支持但会降低精度，官方不建议。

Q：affinity_pred_value 和 probability_binary 用哪个？筛选活性分子用 probability（0~1，区分 binder/decoy）；比较已知活性分子之间的亲和力强弱用 pred_value（log10 IC50，越小越强）。两者训练目标和监督信号不同，不要交叉解读。

Q：两次运行结果不一致？扩散采样本身带随机性。提高--diffusion_samples_affinity（如 5→10）可获得更稳的结果；另外注意输出目录默认复用缓存，改了参数重跑要加--override。

Q：显存不够？下调--sampling_steps_affinity和--max_parallel_samples，或减少并行设备--devices；CPU 只能当验证环境用，别用于批量任务。

总结

Boltz-2 把结构预测和亲和力预测整合进同一个开源模型，用 MIT 协议向社区开放，是早期药物发现里做 in silico 筛选和先导优化的实用工具。它的适用边界也很清楚：亲和力目前只支持小分子对蛋白质（对 RNA/DNA 靶点结果不可靠），配体建议不超过 56 个重原子，配体口袋精度尚不及头部闭源模型。选对场景、看对字段，它能把原来数周的评估流程压缩到一次下班前的等待时间。

【免费下载链接】boltzOfficial repository for the Boltz biomolecular interaction models项目地址: https://gitcode.com/GitHub_Trending/bo/boltz