企业官网建设流程全解析

AlphaFold 报错排查速查：8 个高频错误一次修好的完整指南

【免费下载链接】alphafoldOpen source code for AlphaFold 2.项目地址: https://gitcode.com/GitHub_Trending/al/alphafold

跑了一整夜，结果等来一屏红字——这可能是你第一次运行 AlphaFold 的真实体验。别慌：AlphaFold 的报错其实高度模式化，超过一半的失败都集中在"找不到文件"和"显存不够"两件事上。这篇文章是一份AlphaFold 报错排查速查手册：先给你一张覆盖"装环境 → 备数据 → 跑模型 → 拿结果"全生命周期的速查表，让定位问题的时间从半小时压到三分钟；后面每个报错拆成一个独立案例，按"报错 → 原因 → 步骤 → 验证"的节奏走，你可以直接跳到跟自己那行红字对得上的部分。

全生命周期报错速查表

上表覆盖了绝大多数场景。下面按案例展开——每条案例开头有一句"什么时候会遇到"，不相关的直接跳过。

案例 01：GPU 爆内存怎么救（AlphaFold OOM）

这条报错几乎都发生在长序列或--model_preset=multimer上，多聚体 5 个模型各跑多个随机种子，显存压力是单体的数倍。

jaxlib.xla_extension.XlaRuntimeError: RESOURCE_EXHAUSTED: Out of memory while trying to allocate ...

原因：GPU 显存装不下模型张量加上 MSA 特征，长序列和随机种子数量越多，占用越大。

步骤：

1. 先确认单条序列能跑通：临时改用--model_preset=monomer，把问题从"模型太重"里剥离出来。
2. 减少单次显存需求：多聚体时用--num_multimer_predictions_per_model=2（默认 5，此参数仅对 multimer 生效）；数据库侧可用--db_preset=reduced_dbs减小 MSA 输入。
3. 显存被其他进程占满时，在启动前限制 JAX 预分配，避免它一次性吃光显存：

import jax jax.config.update('jax_gpu_memory_limit', 0.85) # 只占 85% 显存，给 relax/TF 留空间

4. 以上都不行，就是硬件上限了：AlphaFold 推荐至少 16GB 显存的 GPU，批量任务建议换卡或错峰跑。

验证：重跑时nvidia-smi里显存峰值不超过 90% 且进程正常进入模板检索阶段，说明修好了。

案例 02：数据库找不到（AlphaFold 数据库下载）

这是"备数据"阶段最高频的报错，通常是download_all_data.sh中途断过、解压不完整，或--data_dir指到了错误的层级。

ValueError: Could not find HHsearch database /path/to/pdb70/pdb70_hhm.ffindex

原因：报错里的路径是工具真实去找的位置，说明该路径下没有对应的.ffindex/.ffdata文件——要么没下载，要么文件名/层级不对。

步骤（👇 照着做就行）：

1. 用仓库自带的 一键下载脚本 补全：

bash scripts/download_all_data.sh /path/to/data_dir # 完整数据库，约 400GB bash scripts/download_all_data.sh /path/to/data_dir reduced_dbs # 只想先跑通时

2. 注意--db_preset与目录必须对应：reduced_dbs用small_bfd_database_path，full_dbs用bfd_database_path+uniref30_database_path，两者不能混。
3. 各数据库内部结构要完整，以 PDB70 为例，目录下应有pdb70_hhm.ffdata、pdb70_hhm.ffindex、pdb70_a3m.ffdata等成对文件。
4. 下载中断过的文件建议删掉重下，不要依赖断点续传——ffdata 这类大文件截断后校验很容易出错。

验证：把速查表 02 里涉及的每个*_database_path都ls一遍，.ffindex与.ffdata成对存在且大小正常，即可重跑。

案例 03：依赖工具不在 PATH（二进制缺失）

这条报错几乎都发生在第一次跑通流程时，尤其是工具装在 conda 环境而 AlphaFold 主进程跑在 base 环境的情况。

ValueError: Could not find path to the "jackhmmer" binary. Make sure it is installed on your system.

原因：run_alphafold.py启动时会用shutil.which()依次定位jackhmmer、hhblits、hhsearch、hmmsearch、hmmbuild、kalign六个二进制，任何一个找不到就立刻抛错。

步骤：

1. 逐个确认安装情况：

which jackhmmer hhblits hhsearch hmmsearch hmmbuild kalign

2. 缺失的按 官方文档 的环境要求安装（JackHMMER、HMMER、HH-suite、Kalign 四个来源）。
3. 工具在、但不在当前进程 PATH 里时，显式传参覆盖（run_alphafold.py的同名 flag 会覆盖自动探测）：

python run_alphafold.py \ --fasta_paths=input.fasta --output_dir=out --data_dir=/data \ --jackhmmer_binary_path=/opt/af/jackhmmer \ --hhblits_binary_path=/opt/af/hhblits # 其余 4 个同理

4. conda 用户最简单的办法是激活装了工具的同一个环境再启动，省得逐个传路径。

验证：重跑后不再抛Could not find path，日志里开始出现 JackHMMER/HHblits 的执行记录。

案例 04：模型预设与数据库不匹配

切换--model_preset后最常踩的坑：参数组合没有跟着预设一起换。

ValueError: pdb70_database_path must be set when running with "--model_preset=monomer".

原因：启动阶段有一个强制校验——monomer必须给pdb70_database_path，multimer必须给pdb_seqres_database_path和uniprot_database_path，而pdb70在多聚体模式下必须不传。报哪条，就是哪组没对齐。

步骤：

1. 先确定你要跑哪边：单体还是多聚体，预设一次只选一个（monomer/monomer_casp14/monomer_ptm/multimer）。
2. 按预设补齐数据库参数：

# 单体 python run_alphafold.py --model_preset=monomer \ --pdb70_database_path=/data/pdb70 ... # 多聚体（注意：pdb70 反而要去掉） python run_alphafold.py --model_preset=multimer \ --pdb_seqres_database_path=/data/pdb_seqres \ --uniprot_database_path=/data/uniprot ...

3. 同时检查--db_preset与 BFD/UniRef30 三件套是否成组出现（见案例 02 第 2 步），这两个 flag 是分开校验的，错一组只报一组的错。
4. 改完参数后先空跑确认校验全过（进入 MSA 阶段即算通过），再启动长任务。

验证：进程顺利通过启动校验、日志出现数据库检索动作，说明预设-参数对齐了。

案例 05：FASTA 文件名重复

批量提交多个序列时最容易中招：把几个sequence.fasta从不同目录丢进同一次命令。

ValueError: All FASTA paths must have a unique basename.

原因：AlphaFold 用 FASTA 的文件名（basename）直接命名输出子目录，重名意味着两个序列的结果会互相覆盖，所以启动时就拒绝。

步骤：

1. 重命名输入文件，保证每次提交的每个 FASTA 文件名全局唯一，如1abc.fasta、2def.fasta。
2. 检查文件内容本身：头行>后是序列 ID，下面紧跟氨基酸序列，不要混入注释行或空格行。
3. 多链蛋白放在同一个FASTA 文件里、用多个头行区分链，不要拆成多个文件再靠 flag 拼。
4. 提交前快速核对：ls *.fasta里无重名再执行。

验证：输出目录下每个输入文件对应一个独立子目录，且彼此内容不互相覆盖。

案例 06：模板结构库缺失

多聚体或单体跑到模板检索阶段才炸，往往说明只下了 MSA 数据库，漏了 mmCIF 模板库。

ValueError: Could not find CIFs in /path/to/template_mmcif_dir

原因：模板检索要求--template_mmcif_dir指向一个存有大量pdb_id.cif结构文件的目录，目录为空或不存在就抛此错。

步骤：

1. 用 模板结构下载脚本 补数据：

bash scripts/download_pdb_mmcif.sh /path/to/mmcif_dir

2. 运行命令里--template_mmcif_dir指向该目录。
3. 确认目录里确实是*.cif文件而不是 zip 压缩包没解压。
4. 历史测试集（如复现 CASP）记得加--max_template_date截断模板发布时间，避免用到"未来"结构造成信息泄露。

验证：目录内.cif文件数量在百万级量级，且运行日志进入 MSA 对齐与模板特征化阶段。

案例 07：relaxation 收敛失败（AlphaFold relaxation 错误）

这条几乎都发生在整条流程的最后一步——模型都预测完了，结构在 OpenMM 里弛豫收敛不了。

ValueError: Minimization failed after 100 attempts.

原因：relax 步骤用 OpenMM/Amber 对预测结构做立体化学优化，部分预测存在无法在迭代预算内消解的冲突，能量最小化反复失败。

步骤（先保结果，再谈质量）：

1. 最快止血：--models_to_relax=NONE跳过 relax，保留原始预测（可能有少量立体化学冲突，但总比整单失败强）；只跑--models_to_relax=BEST（默认）也比ALL省得多。
2. 需要保留 relax 时，微调 run_alphafold.py 顶部的弛豫常量（按你的预算改）：

RELAX_MAX_ITERATIONS = 200 # 默认 0（不限制），可设上限防死磕 RELAX_ENERGY_TOLERANCE = 5.0 # 默认 2.39，放宽收敛标准 RELAX_STIFFNESS = 5.0 # 默认 10.0，降低约束刚度

3. GPU relax 有兼容性问题时，用--use_gpu_relax关闭，回退到 CPU 弛豫，慢但稳。
4. 检查输入是否含罕见氨基酸/修饰残基——RELAX_EXCLUDE_RESIDUES里排除掉问题残基，能避开不少无效迭代。

验证：输出目录里relax_metrics.json正常生成，relaxed版 PDB 与原始 PDB 并存。

案例 08：输出文件不完整

"跑完了却没有 ranked_0.pdb"——这类问题不是模型问题，而是进程没真正跑完。

# 现象：输出目录里只有 log 和部分 json，缺少 ranked_0.pdb / plddt 文件

原因：三类典型诱因——进程被 OOM killer 杀掉、磁盘写满、输出目录残留上次失败的中间状态。

步骤：

1. 翻run.log末尾，找Killed、异常堆栈或中断信号，确定死因而不是猜。
2. 磁盘空间核查：df -h看数据盘和输出盘，大蛋白单条输出可到数百 MB。
3. 换一个全新的空--output_dir重跑，避免与上次残留文件混淆。
4. 如果死因是显存不足，回到案例 01 的降配方案再跑。

验证：输出目录里ranked_0.pdb、plddt_{model}.txt、metrics.json三类文件齐全且 PDB 可正常打开。

从报错到修复：排查路径图

仍然解决不了怎么办

• 带着报错首行去翻仓库的 README 和 文档，大部分边界情况都有对应说明。
• 用报错的完整原句（含路径）去官方 issue 区搜，关键词加引号，命中率远高于截断的半句话。
• 复现步骤尽量按"命令 + 预设 + 序列长度"三要素描述，社区帮你定位的速度会快很多。

报错不是终点，只是流程在提醒你哪一步的契约没对上——把速查表贴在手边，逐个案例核对，红字总会变成绿色的ranked_0.pdb。

【免费下载链接】alphafoldOpen source code for AlphaFold 2.项目地址: https://gitcode.com/GitHub_Trending/al/alphafold