complexa-setup

Complexa 设置技能

在执行任何设计运行前，完成全新 Proteina-Complexa 检出所需的三个步骤：创建 .env、获取模型权重，并检查环境。先探测主机的 GPU、磁盘和工具二进制文件，避免用户在流水线中途才发现缺少依赖。最后生成一个 JSON 设置产物，方便用户（或未来的 Agent）重新读取，而不必重新推导状态。

CLI 与直接编辑文件——为每个步骤选择成本最低的方式

步骤	首选方式	原因
创建 .env（步骤 2）	编辑文件（cp .env_example .env + 替换 3 行）或 complexa init	complexa init 只是对 cp + 3 regex swaps 的薄封装（cli_runner.py 中的 _swap_runtime_in_env）。两种方式都可行；新手优先使用 CLI，Agent 优先直接编辑。
编辑 .env 值（步骤 3）	编辑文件（StrReplace LOCAL_CODE_PATH=… 等）	此步骤没有对应的 CLI——这些值是用户特定的路径。
下载模型权重（步骤 4）	CLI（complexa download --…）	它会调用 env/download_startup.sh（约 1000 行的 bash 脚本，包含 NGC URL、重试以及类似校验和的存在即跳过逻辑）。不要尝试自行复刻。
验证环境（步骤 5）	CLI（complexa validate env）或 test -f .env && test -d $DATA_PATH	CLI 会输出更清晰的报告；手动检查可安全地写成单行命令。
验证完整设计配置（选定流水线后）	CLI（complexa validate design CONFIG）	这涉及复杂的 Hydra 默认值遍历、ckpt 和环境变量检查，不值得自行复刻。

此技能可完成的工作

• 为 UV 或 Docker 运行时创建格式正确的 .env。
• 将模型检查点（Complexa 蛋白质/配体/AME 模型以及社区模型）下载到已知路径。
• 生成主机状态快照 preflight.json（GPU、磁盘、.env、ckpt、工具二进制文件）。
• 生成 run_manifest.json，准确记录所用的 complexa init 和 complexa download 调用（便于重放）。
• 通过 complexa validate env 获取通过/失败报告，并附上明确的后续步骤提示。

步骤 1：预检

在操作环境前，务必先运行共享预检。它不要求 .env 已存在——会回退到默认值——并会告知主机是否能运行 Complexa。

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

读取脚本写入的 ./complexa_setup/preflight.json，并说明以下内容：

• gpu.available——如果为 false，设计/评估步骤将失败；请警告用户。
• gpu.vram_gb——Complexa 需要 ≥40 GB（A100/H100/L40S）。
• CKPT_PATH 的 disk.free_gb——完整的 Complexa + 社区模型集至少需要约 50 GB。
• env.missing_required——此处列出的所有项目都必须在 .env 中编辑，否则验证无法通过。
• tools.{foldseek,mmseqs,dssp,hbplus,sc}.exists——缺少工具会降低评估效果，但不会阻止生成。

步骤 1b：构建 Python 环境（仅当缺少 .venv/ 时）

complexa CLI 安装在项目的 Python 环境中，默认不在系统路径下。全新克隆时，.venv/ 目录尚不存在，complexa init 会因 command not found 而失败。请先构建 UV venv：

test -d .venv || ./env/build_uv_env.sh   # first-time UV build
source .venv/bin/activate
which complexa                            # sanity check: should point inside .venv

如果 which complexa 已能解析到命令，则跳过此步骤——这表示之前的构建仍然有效。Docker 运行时完全跳过此步骤；venv 位于容器镜像内。如果用户说“我刚克隆了”，或者你发现 pyproject.toml 旁边没有 .venv/，就运行构建脚本——没有 venv 时运行 complexa init 会产生令人困惑的 command not found，而不是明确提示“请先构建 venv”。

步骤 2：创建 .env

选择运行时。UV 是默认选项，启动更快；Ubuntu 20.04 或存在 GLIBC 不匹配的系统则必须使用 Docker。

如果无法从上下文中判断，请使用 AskUserQuestion：

“你想配置哪种运行时？uv（推荐，速度更快）还是 docker（如果本地尚未构建 UV venv，请使用此选项）？”

路径 A：编辑文件（推荐供 Agent 使用）

complexa init 只执行三项操作：将 .env_example 复制为 .env，并替换 COMPLEXA_RUNTIME= 所在行，以及工具／数据／缓存路径区块中的 UV_* ↔ DOCKER_* 前缀。你可以用 cp + StrReplace 完成相同操作，跳过 CLI：

cp .env_example .env
# Then StrReplace these lines in .env:
#   COMPLEXA_RUNTIME=uv          → COMPLEXA_RUNTIME=<runtime>
#   FOLDSEEK_EXEC=${UV_FOLDSEEK_EXEC}  → FOLDSEEK_EXEC=${DOCKER_FOLDSEEK_EXEC}   (and same for RF3_EXEC_PATH, SC_EXEC, HBPLUS_EXEC, MMSEQS_EXEC, DSSP_EXEC, TMOL_PATH)
#   DATA_PATH=${LOCAL_DATA_PATH} → DATA_PATH=${DOCKER_DATA_PATH}                  (and same for CACHE_DIR, CKPT_PATH)

如果继续使用 UV，则完全跳过前缀替换（.env_example 已默认使用 UV）。

路径 B：CLI

complexa init                    # UV runtime (default)
complexa init --runtime docker   # Docker runtime
complexa init --force            # Recreate .env from .env_example (drops any edits)

如果 .env 已存在且未传入 --force，则只会替换依赖运行时的行；在不同运行时之间切换时，步骤 3 中的用户编辑会保留。

无论使用哪种方式，均需验证

test -f .env && echo "OK: .env present" || echo "MISSING"
grep -E '^COMPLEXA_RUNTIME=' .env

步骤 3：编辑 .env

此步骤没有 CLI——步骤 2 只设置了运行时；你仍需手动将特定于你机器的路径写入 .env（使用 StrReplace 或编辑器）。必须修改的两项是：

LOCAL_CODE_PATH=/absolute/path/to/protein-foundation-models
LOCAL_DATA_PATH=/absolute/path/to/PFM_data

其他所有内容（缓存、ckpts、community-model 目录、工具二进制文件）默认均根据 LOCAL_CODE_PATH 推导，只有在你的目录布局不标准时才需要编辑。完整表格列出了每个键、其控制的内容，以及缺失时会导致哪些问题，请参阅 reference/env_keys.md。

大多数用户会修改的四项内容的快速决策表：

键	默认值	在以下情况下设置
LOCAL_CODE_PATH	占位符	始终设置——必填
LOCAL_DATA_PATH	/path/to/PFM_data	始终设置——必填，指向目标 PDB
HF_TOKEN	占位符	需要 ESMFold 或受限 HF 模型时
WANDB_API_KEY	占位符	希望将训练运行记录到 W&B 时

步骤 4：下载检查点

此处始终使用 CLI。 complexa download 会调用 env/download_startup.sh（约 1000 行 bash 脚本，包含 NGC URL、重试机制，以及针对约 6 类社区模型的已存在则跳过逻辑）。自己编写 wget 循环容易导致下载不完整或目标路径错误。

询问用户实际需要哪些模型——下载全部模型约需 100+ GB。从三个 Complexa 变体和社区模型集中选择。每个 Complexa 变体恰好解锁一个 complexa design 工作流；社区模型集中的 AF2 / RF3 是 evaluate（以及奖励引导搜索）在运行时所需的模型。

标志	下载内容	解锁的工作流	目标位置	大致大小
--complexa	Complexa 蛋白结合体模型 + AE（complexa.ckpt、complexa_ae.ckpt）	蛋白结合体（默认）— configs/search_binder_local_pipeline.yaml	./ckpts/	约 3 GB
--complexa-ligand	配体结合体模型 + AE（complexa_ligand.ckpt、complexa_ligand_ae.ckpt）	配体结合体 — configs/search_ligand_binder_local_pipeline.yaml	./ckpts/	约 3 GB
--complexa-ame	AME 基序支架模型 + AE（complexa_ame.ckpt、complexa_ame_ae.ckpt）	AME（酶）— configs/search_ame_local_pipeline.yaml	./ckpts/	约 3 GB
--complexa-all	全部三个 Complexa 变体	全部三个工作流	./ckpts/	约 9 GB
--all	所有社区模型（ProteinMPNN + LigandMPNN + AF2 + ESM2 + ESMFold + RF3）	evaluate / reward 所需：AF2（蛋白结合体）、RF3（配体结合体 + AME）、MPNN（所有工作流的逆折叠）。	./community_models/	约 50 GB
--everything	Complexa + 社区模型 + 可选模型（Boltz2 / Protenix）	所有内容，以及替代折叠后端	两者	100+ GB
--status	显示安装状态——不下载	（无）	（无）	不适用

各工作流的最小下载内容：

• 蛋白结合体（默认）：complexa download --complexa --all
• 配体结合体：complexa download --complexa-ligand --all
• AME / 酶：complexa download --complexa-ame --all
• 全部三个：complexa download --everything

如需查看按模型划分的完整目标位置明细和按标志划分的 NGC 来源，请参阅 reference/downloads.md。

选择能够满足用户目标的最小命令，然后运行：

complexa download --complexa            # protein binder only
complexa download --complexa-all        # all three Complexa variants
complexa download --all                 # community models only
complexa download --everything          # everything

不带参数时，complexa download 会启动交互式向导——在 Agent 模式下优先使用显式标志。

验证下载结果：

complexa download --status

状态输出按系列（Complexa / 社区模型 / 可选模型）分组，并为每个 ckpt 显示“已安装”或“缺失”。如果 ckpt 被标记为缺失，请重新运行对应的标志。

步骤 5：验证

最后检查 .env 是否可加载，以及所需路径是否有效：

complexa validate env

validate env 会检查：（1）.env 是否存在；（2）是否已设置 DATA_PATH，且其指向的目录是否存在。它不会检查 ckpt 文件——选择好工作流配置后，可通过 complexa validate design <config> 检查这些文件。

常见问题及解决方法：

症状	原因	解决方法
.env file: No .env file found	尚未运行 complexa init	先运行 complexa init
DATA_PATH: Not set in .env	未编辑占位值	编辑 .env 中的 LOCAL_DATA_PATH
DATA_PATH: Directory not found	已编辑路径，但磁盘上不存在该目录	运行 mkdir -p $LOCAL_DATA_PATH，或将目标数据复制到该目录
Hydra 错误 InterpolationKeyError: AF2_DIR	奖励/评估配置需要 AF2，但 .env 未定义该变量	下载 AF2 权重，或从配置中移除 AF2

步骤 6：生成设置产物

在 ./complexa_setup/ 中放置一个 JSON 清单文件，以便用户通过单个文件了解最终状态。共享辅助程序会为你生成该文件：

mkdir -p ./complexa_setup
python .claude/skills/_shared/scripts/write_manifest.py \
    --kind setup \
    --runtime "$(grep -E '^COMPLEXA_RUNTIME=' .env | cut -d= -f2)" \
    --preflight ./complexa_setup/preflight.json \
    --out ./complexa_setup/run_manifest.json

向用户展示生成的文件：

ls -la ./complexa_setup/

预期内容：

complexa_setup/
├── preflight.json      # GPU / disk / .env / ckpt / tool snapshot
└── run_manifest.json   # init + download invocations + git SHA + runtime

硬件要求

资源	最低要求	推荐配置
GPU	1× CUDA GPU，≥24 GB VRAM	A100 / H100 / L40S，40–80 GB VRAM
CUDA	12.0	12.4+
磁盘（CKPT_PATH）	50 GB	150 GB（可满足 --everything 的需求）
RAM	16 GB	64 GB+
操作系统	Ubuntu 22.04+（UV）	Ubuntu 22.04+，或在任意主机上使用 Docker

Ubuntu 20.04 在 UV 运行时下会出现 GLIBC 错误——在这些主机上使用 complexa init --runtime docker。有关各流水线（binder、ligand 和 AME）的要求，请参阅 .claude/skills/_shared/reference/hardware.md。

故障排查

症状	原因	解决方法
complexa: command not found	当前环境未安装软件包	先运行 source .venv/bin/activate，再运行 pip install -e .
complexa init 提示 .env_example not found	在仓库根目录之外运行	使用 cd 切换到项目根目录（即 .env_example 所在目录）
.env_example not found. Cannot initialize .env.	当前目录不是项目根目录	切换到 protein-foundation-models/ 目录后重试
complexa download 从 NGC URL 下载失败	位于防火墙后方／无法连接互联网	为下载脚本配置代理，或从主 README.md 中链接的 NGC 页面手动下载模型 .ckpt 文件，并放入 ./ckpts/
complexa download --status 显示 ckpt 文件已存在，但 validate 失败	.env 中的 CKPT_PATH 指向其他位置	移动 ckpt 文件，或编辑 .env 中的 LOCAL_CHECKPOINT_PATH
导入时出现 GLIBC 错误	在 Ubuntu 20.04 上使用 UV 运行时	重新运行 complexa init --runtime docker，并使用 ./env/docker-ops.sh run

---

完整的 .env 参考（所有键、默认值和故障情形），请参阅 reference/env_keys.md。

完整的下载标志选项矩阵、NGC URL 和目标目录布局，请参阅 reference/downloads.md。