boltzgen

BoltzGen 全原子设计

先决条件

要求	最低配置	推荐配置
Python	3.11+	3.12
CUDA	12.0+	12.1+
GPU 显存	24GB	48GB（L40S）
RAM	32GB	64GB

运行方法

第一次使用？ 请参阅入门指南，设置 Modal 和 biomodals。

选项 1：Modal（推荐）

# Clone biomodals
git clone https://github.com/hgbrian/biomodals && cd biomodals

# Run BoltzGen (requires YAML config file)
modal run modal_boltzgen.py \
  --input-yaml binder_config.yaml \
  --protocol protein-anything \
  --num-designs 50

# With custom GPU
GPU=L40S modal run modal_boltzgen.py \
  --input-yaml binder_config.yaml \
  --protocol protein-anything \
  --num-designs 100

GPU：推荐使用 L40S（48GB） | 超时：默认 120min

可用协议：protein-anything、peptide-anything、protein-small_molecule、nanobody-anything、antibody-anything

选项 2：本地安装

git clone https://github.com/HannesStark/boltzgen.git
cd boltzgen
pip install boltzgen   # or: pip install -e .

# Driven by the boltzgen CLI with a YAML design spec
boltzgen run binder_config.yaml \
  --output out/ \
  --protocol protein-anything \
  --num_designs 50

首次运行时会将模型权重（约 6GB）下载到 ~/.cache。完整运行前，请先使用 boltzgen check binder_config.yaml 验证配置。

GPU：L40S（48GB） | 耗时：每个设计约 30-60s

关键参数（CLI）

参数	默认值	说明
--input-yaml	必填	YAML 设计规格文件的路径
--protocol	protein-anything	设计协议
--num-designs	10	要生成的设计数量
--steps	all	要运行的流水线步骤（例如，design inverse_folding）

YAML 配置

BoltzGen 使用基于实体的 YAML 格式，你需要将设计的蛋白质和目标结构指定为实体。

重要说明：

• 残基索引使用 label_seq_id（从 1 开始），而不是作者残基编号
• 文件路径相对于 YAML 文件所在位置
• 目标文件应为 CIF 格式（也支持 PDB，但更推荐 CIF）
• 运行 boltzgen check config.yaml，在运行前验证配置

基础结合体配置

entities:
  # Designed protein (variable length 80-140 residues)
  - protein:
      id: B
      sequence: 80..140

  # Target from structure file
  - file:
      path: target.cif
      include:
        - chain:
            id: A
      # Specify binding site residues (optional but recommended)
      binding_types:
        - chain:
            id: A
            binding: 45,67,89

指定结合位点的结合体

entities:
  - protein:
      id: G
      sequence: 60..100

  - file:
      path: 5cqg.cif
      include:
        - chain:
            id: A
      binding_types:
        - chain:
            id: A
            binding: 343,344,251
      structure_groups: "all"

肽设计（环状）

entities:
  - protein:
      id: S
      sequence: 10..14C6C3  # With cysteines for disulfide

  - file:
      path: target.cif
      include:
        - chain:
            id: A

constraints:
  - bond:
      atom1: [S, 11, SG]
      atom2: [S, 18, SG]  # Disulfide bond

设计协议

协议	用途
protein-anything	设计可与蛋白质或肽结合的蛋白质
peptide-anything	设计可与蛋白质结合的环状肽
protein-small_molecule	设计可与小分子结合的蛋白质
nanobody-anything	设计纳米抗体 CDR
antibody-anything	设计抗体 CDR

输出格式

output/
├── sample_0/
│   ├── design.cif         # All-atom structure (CIF format)
│   ├── metrics.json       # Confidence scores
│   └── sequence.fasta     # Sequence
├── sample_1/
│   └── ...
└── summary.csv

注意：BoltzGen 输出 CIF 格式。需要时可转换为 PDB：

from Bio.PDB import MMCIFParser, PDBIO
parser = MMCIFParser()
structure = parser.get_structure("design", "design.cif")
io = PDBIO()
io.set_structure(structure)
io.save("design.pdb")

输出示例

运行成功

$ modal run modal_boltzgen.py --input-yaml binder.yaml --protocol protein-anything --num-designs 10
Running: boltzgen run binder.yaml --output /tmp/out --protocol protein-anything --num_designs 10
[INFO] Loading BoltzGen model...
[INFO] Generating designs...
[INFO] Running inverse folding...
[INFO] Running structure prediction...
[INFO] Filtering and ranking...
[INFO] Pipeline complete

Results saved to: ./out/boltzgen/2501161234/

输出目录结构：

out/boltzgen/2501161234/
├── intermediate_designs/           # Raw diffusion outputs
│   ├── design_0.cif
│   └── design_0.npz
├── intermediate_designs_inverse_folded/
│   ├── refold_cif/                 # Refolded complexes
│   └── aggregate_metrics_analyze.csv
└── final_ranked_designs/
    ├── final_10_designs/           # Top designs
    └── results_overview.pdf        # Summary plots

良好输出的特征：

• 复折叠 RMSD < 2.0A（设计的折叠符合预测）
• ipTM > 0.5（界面置信度高）
• 所有设计均成功完成流水线

决策树

Should I use BoltzGen?
│
├─ What type of design?
│  ├─ All-atom precision needed → BoltzGen ✓
│  ├─ Ligand binding pocket → BoltzGen ✓
│  └─ Standard miniprotein → RFdiffusion (faster)
│
├─ What matters most?
│  ├─ Side-chain packing → BoltzGen ✓
│  ├─ Speed / diversity → RFdiffusion
│  ├─ Highest success rate → BindCraft
│  └─ AF2 optimization → ColabDesign
│
└─ Compute resources?
   ├─ Have L40S/A100 (48GB+) → BoltzGen ✓
   └─ Only A10G (24GB) → Consider RFdiffusion

典型性能

任务规模	耗时（L40S）	费用（Modal）	备注
50 个设计	30-45 min	~$8	快速探索
100 个设计	1-1.5h	~$15	标准任务
500 个设计	5-8h	~$70	大规模任务

单个设计：典型结合体约需 30-60s。

Adaptyv 对这些模型进行的测试显示，在 7 个目标上平均每个通过验收的设计成本约为 $1.80（上述生成耗时估算未包含达到验收标准所需的额外采样和复折叠）。

---

验证

find output -name "*.cif" | wc -l  # Should match num_samples

---

故障排查

先验证配置：运行完整流水线前，务必先运行 boltzgen check config.yaml 生成缓慢：初步测试时减少设计数量，之后再增加 OOM 错误：使用 A100-80GB，或减少 --num-designs 结合位点错误：残基索引使用 label_seq_id（从 1 开始），请在 Molstar 查看器中检查

错误说明

错误	原因	解决方法
RuntimeError: CUDA out of memory	设计规模较大或蛋白质较长	使用 A100-80GB，或减少设计数量
FileNotFoundError: *.cif	未找到目标文件	文件路径相对于 YAML 文件所在位置
ValueError: invalid chain	目标中不存在该链	使用 Molstar 或 PyMOL 验证链 ID
modal: command not found	未安装 Modal CLI	运行 pip install modal && modal setup

---

下一步：使用 boltz 或 chai 验证，然后通过 protein-qc 进行筛选。