jwohlwend/boltz · 上手攻略
- 仓库：jwohlwend/boltz
- 链接：https://github.com/jwohlwend/boltz
- 分类：engineering / 生物分子相互作用预测（结构 + 亲和力）
- 作者：spark
- 更新：2026-11-05
资料核对说明：本篇基于 2026-11-05 抓取的 GitHub README 与
docs/prediction.md原文撰写，仓库最近提交 2026-05-29，Stars 4292，MIT 许可。README 中 Boltz-2 尚未提供更新版评测代码与训练代码（两处均标注 "Coming soon"），本篇如实标注该状态。模型权重、评测数值、1000× 加速等说法均为作者/论文自述，本篇未独立复现实验。pip install boltz[cuda] -U为 README 推荐的安装方式，具体最新 PyPI 版本号本轮未逐位核对。
一、它是什么
Boltz 是 MIT（Regina Barzilay 组，与 Recursion 等合作）开源的生物分子相互作用预测模型族，也是目前第一个完全开源且接近 AlphaFold3 精度的模型。
仓库现在包含两代：
- Boltz-1（2024）：首个完全开源、逼近 AlphaFold3 精度的模型，主打复合物结构预测。
- Boltz-2（2025）：新一代生物分子基础模型，在结构预测之上联合建模复合物结构与结合亲和力（binding affinity）。
Boltz-2 是真正的重头戏。README 里的说法很克制但力度很大：它是第一个接近基于物理的自由能微扰（FEP）方法精度、同时运行速度快 1000 倍的深度学习模型——这意味着早期药物发现阶段的 in silico 筛选真正变得可负担。
许可：代码与权重全部 MIT，学术与商业使用都免费。这是它相对 AlphaFold3 / Chai-1 的最大结构性优势——商业可用、无 API 限制、无算力绑定。
硬加速支持：在较新的 NVIDIA GPU 上使用 NVIDIA cuEquivariance kernel；另有一个社区 fork 支持 Tenstorrent 硬件（moritztng/tt-boltz）。
二、它解决什么问题
蛋白-配体相互作用研究里有两道长期卡着科研者的关卡：
第一关：结构预测。 知道一个蛋白和一个小分子会不会结合、结合成什么形状。AlphaFold3 把结构预测推到了新高度，但它是闭源、需申请、受限的。有 AlphaFold2 经验的人都知道，改造一个复合物结构、批量跑几十个突变体，门槛和成本都很高。
第二关：亲和力预测——真正难的那关。 结构对了不等于能结合，也不等于结合得紧。传统的 FEP 方法物理上严谨、精度高，但慢到不可用于大规模筛选。这是虚拟筛选几十年来的核心瓶颈。
Boltz 的解法是：一个模型同时输出结构和亲和力，用深度学习逼近 FEP 级别的亲和力精度，同时把速度提上来三个数量级。README 提到 Boltz-2 还加入了「实验方法条件化（experimental method conditioning）、距离约束、多链模板整合」等可控性特性。
配套的邦德亲和力输出有两个关键字段，用途完全不同——这是最容易踩坑的地方，下一节展开。
三、快速安装
推荐方式：PyPI（README 明确 recommended）
pip install boltz[cuda] -U
方式 B：从 GitHub 装（获取每日更新）
git clone https://github.com/jwohlwend/boltz.git
cd boltz
pip install -e .[cuda]
重要注意
README 原文强调："we recommend installing boltz in a fresh python environment"——务必在全新的 Python 环境里装。这套依赖（PyTorch + RDKit + CUDA 栈）冲突的概率不低，装进已有环境容易把已有项目搞坏。
CPU / 非 CUDA GPU：把命令里的 [cuda] 去掉：
pip install boltz -U
但 README 明确警告："the CPU version is significantly slower than the GPU version"——差距是「显著」级别，不是「慢一点」。跑蛋白复合物建议直接上 GPU。
四、核心用法
4.1 跑一次预测
boltz predict input_path --use_msa_server
input_path可以是一个 YAML 文件，也可以是一个目录（目录里的所有.yaml/.fasta都会批量跑）--use_msa_server：自动通过 mmseqs2 服务器生成 MSA（不需要这个 flag 就必须自己提供预计算的 MSA）- 默认运行最新版本模型（即 Boltz-2），可用
--checkpoint指定别的权重
看全部选项：
boltz predict --help
4.2 输入 YAML 格式
这是使用 Boltz 的核心。完整 schema（来自 docs/prediction.md）：
sequences:
- protein: # 或 dna / rna
id: [A, B] # 多个相同实体用列表
sequence: SEQUENCE
msa: ./examples/msa/seq1.a3m # --use_msa_server 时可省略
- ligand:
id: [C, D]
smiles: 'SMILES' # 与 ccd 二选一，不可同时给
# ccd: SAH
- ligand:
id: E
ccd: SAH
constraints:
- bond:
atom1: [CHAIN_ID, RES_IDX, ATOM_NAME]
atom2: [CHAIN_ID, RES_IDX, ATOM_NAME]
- pocket:
binder: CHAIN_ID
contacts: [[CHAIN_ID, RES_IDX], [CHAIN_ID, RES_IDX]]
max_distance: 6 # 4-20 Å，默认 6 Å
force: false
- contact:
token1: [CHAIN_ID, RES_IDX/ATOM_NAME]
token2: [CHAIN_ID, RES_IDX/ATOM_NAME]
max_distance: 6
force: false
templates:
- cif: CIF_PATH
force: true
threshold: DISTANCE_THRESHOLD
- pdb: PDB_PATH
chain_id: [CHAIN_ID]
template_id: [TEMPLATE_CHAIN_ID]
properties:
- affinity:
binder: CHAIN_ID # 要算亲和力的小分子链
关键字段说明：
ENTITY_TYPE：protein/dna/rna（给sequence）或ligand（给smiles或ccd，二者互斥）id：链标识；多个相同实体写成列表[A, B]msa：默认必须提供。用--use_msa_server则可省略；用预计算 MSA 指到.a3m文件；多链蛋白要用 CSV 格式（两列sequence+key，同 key 的行相互对齐）msa: empty：强制单序列模式——README 明确写了 "not recommended, as it reduces accuracy"modifications：修饰残基，position从 1 开始计数cyclic：聚合物链是否为环状（配体不适用）
4.3 一个完整可跑的最小例子
README 里给的例子结构：
version: 1
sequences:
- protein:
id: [A, B]
sequence: MVTPEGNVSLVDESLLVGVTDEDRAVRSAHQFYERLIGLWAPAVMEAAHELGVFAALAEAPADSGELARRLDCDARAMRVLLDALYAYDVIDRIHDTNGFRYLLSAEARECLLPGTLFSLVGKFMHDINVAWPAWRNLAEVVRHGARDTSGAESPNGIAQEDYESLVGGINFWAPPIVTTLSRKLRASGRSGDATASVLDVGCGTGLYSQLLLREFPRWTATGLDVERIATLANAQALRLGVEERFATRAGDFWRGGWGTGYDLVLFANIFHLQTPASAVRLMRHAAACLAPDGLVAVVDQIVDADREPKTPQDRFALLFAASMTNTGGGDAYTFQEYEEWFTAAGLQRIETLDTPMHRILLARRATEPSAVPEGQASENLYFQ
msa: ./examples/msa/seq1.a3m
- ligand:
id: [C, D]
ccd: SAH
- ligand:
id: [E, F]
smiles: 'N[C@@H](Cc1ccc(O)cc1)C(=O)O'
要算亲和力，就在 properties 里加 affinity: { binder: <小分子链 id> }。
4.4 亲和力输出的两个字段（最重要的一段）
README 专门用一段强调这两个字段「trained on largely different datasets, with different supervisions, and should be used in different contexts」：
| 字段 | 范围/单位 | 用途 |
|---|---|---|
affinity_probability_binary |
0 到 1 | 判定 binder 与 decoy，即「这个分子到底结合不结合」。典型场景：hit discovery（苗头发现）阶段的命中筛选 |
affinity_pred_value |
log10(IC50)，源自 μM 测量的 IC50 |
衡量不同 binder 之间的亲和力差异，以及小改动带来的变化。典型场景：hit-to-lead、lead-optimization（先导优化） |
用错字段的后果：拿 affinity_pred_value 做「是不是 binder」的二分类判断，或者拿 affinity_probability_binary 去比较不同分子的亲和力强弱——两种都是概念错误，结果不可用。
4.5 常用选项
| 选项 | 类型 | 默认 | 说明 |
|---|---|---|---|
--out_dir |
PATH | ./ |
预测结果保存路径 |
--cache |
PATH | ~/.boltz |
模型与数据下载缓存目录；环境变量 BOLTZ_CACHE 可覆盖（须为绝对路径） |
--checkpoint |
PATH | None | 指定 checkpoint，默认用 Boltz-2 |
--devices |
INTEGER | 1 |
使用的设备数 |
--accelerator |
[gpu,cpu,tpu] |
gpu |
加速器类型 |
--use_msa_server |
flag | — | 通过 mmseqs2 服务器自动生成 MSA |
--use_potentials |
flag | — | 推理时施加 potential，提升 pose 的物理合理性 |
--override |
flag | — | 忽略缓存，从头重跑。改了参数或复合物细节但没换输出目录时必须加 |
--recycling_steps 10 --diffusion_samples 25 |
— | — | 对齐 AlphaFold3 的默认参数（10 步 recycling、25 个 diffusion 样本），耗时显著增加 |
4.6 MSA 服务器需要鉴权时
README 提到 --use_msa_server 配合需要认证的服务器时，凭证有两种提供方式，细节在 docs/prediction.md 里。
五、典型适用场景
- 早期虚拟筛选：几十到几百个小分子对同一蛋白靶点批量跑，替代慢速 FEP 做第一轮淘汰。这是 Boltz-2 最被期待的用法。
- 先导优化（lead optimization）：对一个已知 binder 做小分子改动，用
affinity_pred_value看亲和力怎么变。 - 苗头发现（hit discovery）：用
affinity_probability_binary从 decoy 库里挑 binder。 - 蛋白-蛋白复合物结构预测：只需要结构的话，Boltz-1 时代就是 AlphaFold3 的开源替代品。
- 商业场景结构预测：MIT 许可 + 本地推理，没有 API 配额、没有数据出境顾虑。
- 可控生成：有已知的口袋位置或接触关系时，用
pocket/contact/templates约束把 pose 拉向预期构象。
不适合：CPU 环境下的大批量任务（慢到不可用）；需要蛋白-蛋白亲和力预测（Boltz-2 目前只支持小分子对蛋白靶点）；需要严格 FEP 级别物理精度做最终决策的场合。
六、坑与注意
- 亲和力只用小分子对蛋白靶点。README 明确写了：如果跑 RNA/DNA/辅因子靶点，代码不会崩，但输出不可靠（unreliable）。不崩这一点很危险——你不会收到报错，只会拿到看起来正常的数字。
- 配体原子数有硬限制：亲和力模块要求配体最多 128 个原子（按
RDKit RemoveHs计数，含保留的氢），但 README 明确不推荐超过 56 个原子（训练时的限制设在 56）。小分子配体很容易越界。 smiles与ccd互斥，同时给会出错。- 缓存会咬人：默认会复用输出目录里已存在的预处理文件和预测结果。改了参数或复合物细节却没加
--override，你可能拿到的是旧结果而不报错。加--override重跑。 msa: empty（单序列模式）会降低精度，README 直接标注 not recommended。预算允许就别省这一步。- 多链蛋白的 MSA 要用 CSV，不是
.a3m——CSV 需要sequence+key两列，同 key 的行相互对齐。 RES_IDX从 1 开始计数（不是 0）；max_distance支持范围 4-20 Å，默认 6 Å；ATOM_NAME用标准化原子名，可在 RCSB 该组分的 CIF 文件里核对。- RNA/DNA 亲和力不可信（见第 1 条），且 Boltz-2 论文提到的「可控生成」里的 protein-protein affinity 预测尚未落地——外部报道指出团队正扩展该能力，当前版本仍只有小分子-蛋白。
- 评测代码和训练代码都还没跟上。README 两处标注 "⚠️ Coming soon"：更新版评测代码（Boltz-2 / Boltz-1 / Chai-1 / AlphaFold3 的测试基准结构预测，以及 FEP+、CASP16、MF-PCBA 基准上的亲和力预测）和 Boltz-2 训练代码。目前训练只能用于 Boltz-1。这意味着你想横向对比多个模型、或想复现论文数值，现阶段做不了。
- 别装进已有 Python 环境（README 明确建议 fresh environment）。
- CPU 版慢得超出预期（README 用词是 "significantly slower"）。
--use_potentials会改结果。它会施加推理时 potential 提升 pose 物理质量，和你在论文里看到的默认数值可能对不上——对比实验时必须确认双方设置一致。- 引用别忘了 MSA 那篇：用了自动 MSA 生成，必须一并引用 ColabFold 论文（Mirdita et al., Nature Methods, 2022, doi: 10.1038/s41592-022-01615-2）。
七、与同类对比
| 维度 | Boltz-2 | AlphaFold3 | Chai-1 | RoseTTAFold All-Atom | 传统 FEP |
|---|---|---|---|---|---|
| 开源 | ✅ 代码+权重 MIT | ❌ 闭源，需申请 | ✅ 开源（研究许可） | ✅ 开源 | 商业软件 |
| 结构精度 | 接近 AF3（Boltz-1 时代即宣称） | 基准最高 | 接近 AF3 | 略低 | 不产结构 |
| 亲和力 | ✅ 主打能力 | ❌ | 部分支持 | ❌ | ✅ 物理级精度 |
| 速度 | 比 FEP 快约 1000× | 慢 | 慢 | 中 | 极慢 |
| 商业使用 | ✅ MIT 允许 | 受限 | 受限 | ✅ | 需商业许可 |
| 本地可跑 | ✅ | ❌（需服务器） | ✅ | ✅ | ✅ |
| 硬件 | GPU 优先，cuEquivariance 加速；社区支持 Tenstorrent | 需 A100 级 | GPU | GPU | 大量 GPU + 集群 |
| 可控性 | ✅ pocket/contact/templates/约束 | 有限 | 有限 | 有限 | — |
选型建议：
- 要结构和亲和力一体 + 商用友好 → Boltz-2
- 只追求最高结构精度基准分、且能申请到 → AlphaFold3
- 想要多模型交叉验证（但注意第 9 条：官方对比代码尚未发布） → Boltz + Chai 双跑
- 需要物理可解释、严格精度做最终决策 → 仍需 FEP，但可以用 Boltz 做前置粗筛
八、一句话推荐结论
推荐：如果你是结构生物学/药物发现方向的科研者或小团队，Boltz-2 是目前开源界对 AlphaFold3 之后结构+亲和力一体化最完整的答案——MIT 许可、可本地跑、比 FEP 快三个数量级，批量虚拟筛选真的可行。
但要清醒：亲和力模块只在小分子-蛋白靶点上有意义，配体原子数别超 56；官方评测与训练代码尚在 Coming soon，现阶段无法复现论文横向对比数。把它当粗筛与先导优化的加速器，不要当最终决策依据。
九、参考来源
- 仓库 README：https://github.com/jwohlwend/boltz —— 2026-11-05 抓取
- 预测文档
docs/prediction.md：https://raw.githubusercontent.com/jwohlwend/boltz/main/docs/prediction.md —— 2026-11-05 抓取（YAML schema、选项表、原子数限制均来自此文件） - 技术报告（README 引用，本篇未逐篇读原文）：
- Boltz-2: Passaro et al., Boltz-2: Towards Accurate and Efficient Binding Affinity Prediction, bioRxiv, doi:10.1101/2025.06.14.659707
- Boltz-1: Wohlwend et al., Boltz-1: Democratizing Biomolecular Interaction Modeling, bioRxiv, doi:10.1101/2024.11.19.624167
- ColabFold: Mirdita et al., Nature Methods, 2022
- 关联资源（README 提及，未独立抓取）：Slack https://boltz.bio/join-slack ；Tenstorrent fork https://github.com/moritztng/tt-boltz
- 仓库仓库卡片：
organized/repo_cards/4881-jwohlwend-boltz.md