complexa-design

Complexa 设计技能

驱动完整的四阶段 complexa design 流程：生成（流匹配 + 搜索）-> 筛选（按奖励取前 N 个）-> 评估（使用 AF2/RF3 重新折叠）-> 分析（成功率、FoldSeek/MMseqs 多样性）。根据设计意图选择合适的流程配置，提前验证运行环境，避免用户在折叠过程中才发现缺少 ckpt，然后运行流程并生成可重放的清单 + 每个设计一行的成功情况 CSV。

此技能的功能

• 针对蛋白质靶标设计蛋白质结合剂（AF2 奖励 + ColabDesign 重新折叠）。
• 针对小分子靶标设计配体结合剂（RF3 奖励 + RF3 重新折叠）。
• 在配体上下文中搭建 AME 基序（基序 + 配体特征，RF3）。
• 基于搜索的优化：single-pass、best-of-n、beam-search、fk-steering、mcts。
• 重新折叠后端：ColabDesign（AF2）、RF3、Boltz2、ESMFold（快速迭代）。
• 基于每种 result_type 阈值进行通过率 + 多样性分析。

步骤 1：预检

启动设计前，始终运行共享预检——生成需要 GPU 和相应的检查点，评估需要 AF2/RF3 权重及工具二进制文件。如果主机无法运行所选流程，请尽早终止。

bash .claude/skills/_shared/scripts/preflight.sh

读取 ./complexa_setup/preflight.json，如果所选流程缺少以下任一项，则终止：

• gpu.available: false -> 所有流程均无法运行。
• gpu.vram_gb < 40 -> 使用默认 batch_size: 16 生成时会发生 OOM；请降至 8。
• ckpts.complexa[.ckpt] -> 蛋白质结合剂所需。
• ckpts.complexa_ligand[.ckpt] -> 配体结合剂所需。
• ckpts.complexa_ame[.ckpt] -> AME 所需。
• 缺少 env.AF2_DIR -> 蛋白质结合剂的默认评估（colabdesign）将失败。
• 缺少 env.RF3_CKPT_PATH 或 env.RF3_EXEC_PATH -> 配体结合剂 / AME 的默认评估（rf3_latest）将失败。

如果缺少 ckpt，请指引用户使用 complexa-setup，并先运行 complexa download --complexa-<variant>。

步骤 2：选择流程

Complexa 有一个默认流程（蛋白质结合剂）和两个扩展流程 （配体结合剂、AME / 酶）。流程完全由传给 complexa design 的 configs/search_*_pipeline.yaml 决定——每个 YAML 都指定自己的模型检查点、自动编码器、靶标字典、默认奖励和默认重新折叠后端。切换流程只需“替换配置路径，靶标名称则来自另一个字典”。

默认流程 — 蛋白质结合剂

complexa design configs/search_binder_local_pipeline.yaml \
    ++run_name=pdl1_v1 ++generation.task_name=02_PDL1

当用户说“为 X 设计结合剂”“PDL1 结合剂”“从头设计结合剂”“为某个靶标设计蛋白质”等时使用此流程——也就是说，靶标是蛋白质表面。该配置指定 complexa.ckpt + complexa_ae.ckpt，从 configs/targets/targets_dict.yaml 读取靶标，使用 AF2（af2folding）计算奖励，使用 SolubleMPNN 进行逆折叠，并使用 ColabDesign / AF2 进行评估。如果用户没有指定，他们想要的就是此流程。

扩展 A — 配体结合剂（小分子口袋）

complexa design configs/search_ligand_binder_local_pipeline.yaml \
    ++run_name=v11_v1 ++generation.task_name=39_7V11_LIGAND \
    ++metric.binder_folding_method=rf3_latest

当用户说“配体结合剂”“小分子口袋”“SMILES 靶标”“ATP 结合蛋白”，或提到以 _LIGAND 结尾或属于 FAD / SAM / OQO / 7V11 / 等系列的靶标时，切换到此流程。该配置还会启用 LoRA（r=32、lora_alpha=64），这是已发布配体检查点所必需的——请勿修改 lora: 块。

扩展 B — AME / 基序 + 配体（酶支架搭建）

complexa design configs/search_ame_local_pipeline.yaml \
    ++run_name=ame_chm ++generation.task_name=M0096_1chm

当用户说“在配体附近搭建基序支架”“活性位点设计”“酶支架搭建”“AME”，或提到类似 M0024_1nzy、M0096_1chm 的靶标（AME 任务命名格式为 M####_<pdb>）时，切换到此流程。该配置设置 env_vars.USE_V2_COMPLEXA_ARCH=True（CLI 运行器会将其注入子进程），并同时使用 MotifFeatures 和 LigandFeatures。默认搜索方式为 single-pass；只有在启用 CompositeRewardModel 时，才切换到 best-of-n（它在 ame_generate.yaml 中被注释掉）。

Pipeline 速查表 — 切换时的变化

选项	蛋白质结合剂（默认）	配体结合剂	AME（酶）
Pipeline YAML	configs/search_binder_local_pipeline.yaml	configs/search_ligand_binder_local_pipeline.yaml	configs/search_ame_local_pipeline.yaml
模型 ckpt	complexa.ckpt	complexa_ligand.ckpt	complexa_ame.ckpt
Autoencoder ckpt	complexa_ae.ckpt	complexa_ligand_ae.ckpt	complexa_ame_ae.ckpt
目标字典	configs/targets/targets_dict.yaml	configs/targets/ligand_targets_dict.yaml	configs/design_tasks/ame_dict_v2.yaml
任务名称格式	<NN>_<NAME>（例如 02_PDL1、22_DerF21）	<NN>_<PDB>_LIGAND（例如 39_7V11_LIGAND）	M####_<pdb>（例如 M0096_1chm）
USE_V2_COMPLEXA_ARCH	（未设置 → v1）	（未设置 → v1）	"True"（在 YAML 中设置）
LoRA	（无）	必需（r=32, alpha=64）	必需
默认搜索算法	best-of-n	best-of-n	single-pass
奖励模型	AF2（af2folding）	RF3（rf3folding）	null（默认不使用奖励模型）
逆向文件夹	soluble_mpnn	ligand_mpnn	ligand_mpnn
默认折叠评估后端	colabdesign（AF2）	rf3_latest	rf3_latest
分析 result_type	protein_binder	ligand_binder	motif_ligand_binder
所需 ckpt（complexa download）	--complexa --all（社区版包含 AF2）	--complexa-ligand --all（社区版包含 RF3）	--complexa-ame --all（社区版包含 RF3）

如需查看各 Pipeline 的完整细分（奖励权重、成功阈值、分析模式），请参阅 reference/pipelines.md。

第 3 步：收集参数

使用 AskUserQuestion 填写每次运行都会变化的四个参数。如果用户没有偏好，请采用合理的生产环境设置。

• 目标名称 — 必须是相应字典中的键（蛋白质结合剂使用 targets_dict.yaml，配体使用 ligand_targets_dict.yaml，AME 使用 ame_dict_v2.yaml）。如果用户指定的目标不在字典中，请转交给 complexa-target，先将目标添加进去。
• 运行名称 — 附加到输出目录的简短标识符（例如 pdl1_v1）。
• 搜索算法 — 生产环境默认使用 beam-search，并设置 beam_width=8 和 n_branch=4。快速冒烟测试使用 single-pass。
• 评估折叠后端 — 蛋白质结合剂默认使用 colabdesign（AF2）；配体和 AME 默认使用 rf3_latest。快速迭代可使用 esmfold（效果较差，但每个样本只需几秒）。

第 4 步：验证

运行前先进行验证。验证开销很低（几秒），可发现缺失的 ckpt、缺失的环境变量、未知的覆盖键以及缺失的目标条目；否则，这些问题会在生成数小时后导致 Pipeline 在评估中途终止。

complexa validate design configs/search_binder_local_pipeline.yaml \
    ++generation.task_name=02_PDL1 \
    ++metric.binder_folding_method=colabdesign

验证器在失败时返回非零状态码，并打印通过/失败报告。根据建议的覆盖项重新运行命令，直到验证通过。

第 5 步：运行 Pipeline

完整的 4 阶段运行应使用 complexa design — 它会将 generate → filter → evaluate → analyze 作为顺序子进程进行编排，并共享运行名称、日志目录和多 GPU 拆分（参见 src/proteinfoundation/cli/cli_runner.py 中的 run_design_pipeline）。手动重新实现会丢失各阶段的日志路由和进度输出。

使用 ++（强制）Hydra 覆盖项；这些覆盖项适用于所有阶段。以下是最简的生产环境蛋白质结合剂调用：

complexa design configs/search_binder_local_pipeline.yaml \
    ++run_name=pdl1_v1 \
    ++generation.task_name=02_PDL1 \
    ++generation.search.algorithm=beam-search \
    ++generation.search.beam_search.beam_width=8 \
    ++metric.binder_folding_method=colabdesign

对于配体结合剂或 AME，请根据第 2 步的速查表替换 Pipeline YAML 和目标名称 — 上述其他覆盖项均与 Pipeline 无关，可直接复用。

添加 --verbose 可将日志输出到终端，而不是 ./logs/。此技能不会轮询进度 — 用户若想查看状态，需要重新调用；请引导他们使用 complexa status 和 ./logs/design_pipeline_*/。

直接调用模块（调试备用方案）

若要在不进行流水线编排的情况下调试单个阶段，请直接调用底层 Hydra 模块。complexa generate CONFIG 只是对此操作进行日志记录的子进程封装：

python -m proteinfoundation.generate \
    --config-path "$(realpath configs)" \
    --config-name search_binder_local_pipeline \
    ++run_name=debug_pdl1 \
    ++generation.task_name=02_PDL1

proteinfoundation.{filter,evaluate,analyze} 也遵循相同模式。需要挂载 ipdb、在 nsys 下运行或跳过流水线日志目录时，可使用此方式。正常的一次性运行请优先使用 complexa generate/filter/evaluate/analyze（可直接获得日志记录和并行任务拆分）。

AME 特别注意事项（使用 RF3 重新折叠 AME 时）：RF3 会根据配体的 CCD 代码尝试补齐缺失原子，这会导致 RMSD 计算出现形状错误，并生成错误的结构。在 RF3 读取 PDB 之前，将配体残基重命名为 L:0，让 RF3 将其视为通用配体并跳过原子补齐。如果 AME 生成的输出已按此方式编码配体（Complexa 标准流水线会这样处理），则无需额外操作；否则，请使用 atomworks.io 修补每个 PDB：

from atomworks.io import load_any, to_pdb_file
atom_array = load_any("my_design.pdb")[0]
ligand_mask = atom_array.chain_id == "A"
atom_array.res_name[ligand_mask] = "L:0"
to_pdb_file(atom_array, "my_design_rf3_ready.pdb")

如果使用 RF3 后端将 AME 输出传入 complexa-evaluate-pdbs 技能，也需要进行相同处理。使用 AF2/colabdesign 重新折叠，或用于非 AME 流水线时，请跳过重命名步骤。

默认设置下（nsteps=400、beam_width=8、batch_size=16、100 个 设计、使用 colabdesign 进行评估），在单张 A100/H100 上耗时约为 30–120 分钟。

步骤 6：收集结果

输出会写入两个目录。请一并提供：

ls ./inference/${CONFIG_STEM}_${TASK}_*${RUN_NAME}/   # generated PDBs + filter
ls ./evaluation_results/${RUN_NAME}/                  # per-design CSV + analysis

读取合并后的结果 CSV 并进行总结：

ls ./evaluation_results/*/binder_results_*_combined.csv
ls ./evaluation_results/*/motif_binder_results_*_combined.csv  # AME
ls ./evaluation_results/*/res_filter_*_pass_*.csv              # success rate
ls ./evaluation_results/*/res_div_foldseek_*.csv               # FoldSeek diversity

从 res_filter_binder_pass_*.csv 中提取成功率，从合并后的 CSV 中提取每个设计的指标（界面 pAE、pLDDT、scRMSD），并从 res_div_foldseek_*.csv 中提取 FoldSeek TM-score 多样性。按 i_pAE（蛋白质结合剂）或 min_ipAE（配体结合剂）列出排名前 N 的设计。

步骤 7：生成清单文件

在结果文件旁生成 JSON 清单，以便重放运行。共享辅助程序会记录命令、配置、git SHA 以及结果 CSV 的路径。

python3 .claude/skills/_shared/scripts/write_manifest.py \
    --output-dir ./evaluation_results/${RUN_NAME} \
    --command "complexa design configs/search_binder_local_pipeline.yaml ++run_name=${RUN_NAME} ++generation.task_name=${TASK}" \
    --skill complexa-design \
    --out ./run_manifest.json

向用户提供清单文件路径和结果 CSV。

最常用的覆盖项

以下 10 项覆盖了约 90% 的运行场景。完整参考（包含每个键、类型和默认值）请见 reference/overrides.md。

覆盖项	默认值	控制内容
++generation.task_name=<name>	（因配置而异）	要为哪个目标 / AME 任务进行设计
++run_name=<str>	（配置名称）	输出目录后缀和 CSV 标签
++generation.search.algorithm=beam-search	best-of-n（结合剂 / 配体）、single-pass（AME）	搜索策略
++generation.search.beam_search.beam_width=8	4	束搜索宽度（越大 = 设计越好，速度越慢）
++generation.args.nsteps=200	400	扩散步数（越少 = 速度越快，质量越低）
++generation.dataloader.batch_size=8	16（结合剂 / 配体 / AME）	在 40GB GPU 上可降至 8
++generation.filter.filter_samples_limit=500	1000	过滤后保留的前 N 个样本
++metric.binder_folding_method=esmfold	colabdesign（结合剂）、rf3_latest（配体 / AME）	评估时使用的重新折叠后端
++metric.num_redesign_seqs=8	2	每个设计生成的 ProteinMPNN/LigandMPNN/SolubleMPNN 序列数
++aggregation.success_thresholds.i_pAE.threshold=10.0	7.0（蛋白质结合剂）	放宽 / 收紧成功标准

硬件要求

资源	最低配置	推荐配置
GPU	1 个 CUDA GPU，40 GB VRAM	A100 / H100 / L40S，80 GB VRAM
CPU	16 核	24 核（每个流水线配置中的 ncpus_ 默认值）
磁盘	./inference/ + ./evaluation_results/ 占用 50 GB	sweep 运行需要 200 GB
RAM	32 GB	64 GB 及以上

对 100 个设计、beam_width=8、默认 nsteps=400 的典型运行时间：

• 蛋白质结合剂 + colabdesign 重折叠：在 1 个 A100/H100 上约需 60–120 分钟。
• 配体结合剂 + RF3 重折叠：约需 90–180 分钟（主要耗时在 RF3）。
• AME + RF3 重折叠：约需 120–240 分钟。
• 任意流水线 + ESMFold 重折叠：约需 30–60 分钟（适合快速迭代）。

将 gen_njobs=2 和 eval_njobs=2 调高后，在双 GPU 主机上运行时间可缩短一半。各流水线的 VRAM 表请参阅 .claude/skills/_shared/reference/hardware.md。

故障排除（常见情况）

症状	原因	修复方法
generate 中出现 CUDA out of memory	batch_size: 16 对 40 GB GPU 来说太大	++generation.dataloader.batch_size=8
evaluate 中出现 CUDA out of memory	AF2 / RF3 的批处理过于激进	++eval_njobs=1 并设置 ++metric.num_redesign_seqs=2
InterpolationKeyError: AF2_DIR	使用 colabdesign 评估，但 .env 未设置 AF2_DIR	在 .env 中设置 AF2_DIR，或设置 ++metric.binder_folding_method=esmfold
InterpolationKeyError: RF3_CKPT_PATH	使用 RF3 评估，但未安装 RF3	执行 complexa download --all，或切换评估后端
KeyError: 'task_name' not in target_dict_cfg	目标不在 targets_dict.yaml / ligand_targets_dict.yaml / ame_dict_v2.yaml 中	使用 complexa-target 技能添加
通过成功阈值的设计数为 0	对此目标而言，默认值过于严格	使用 ++aggregation.success_thresholds.* 放宽阈值

完整列表（链 ID 不匹配、热点残基、RF3 配体残基重命名、缺少逆折叠模型等）请参阅 reference/troubleshooting.md。

---

各流水线的详细信息（使用的模型、奖励、逆折叠、评估后端、result_type、LoRA 设置、USE_V2_COMPLEXA_ARCH 开关）请参阅 reference/pipelines.md。

完整的覆盖参数参考（每个 generation.*、metric.*、 aggregation.* 键的类型、默认值、示例和作用）请参阅 reference/overrides.md。

所有故障排除情况（原因 + 修复方法 + 来源）请参阅 reference/troubleshooting.md。