AlphaFold 3 安装部署全攻略：一步到位跑通蛋白质结构预测-CSDN博客

AlphaFold 3 安装部署全攻略：一步到位跑通蛋白质结构预测

【免费下载链接】alphafold3 AlphaFold 3 inference pipeline. 项目地址: https://gitcode.com/gh_mirrors/alp/alphafold3

拿到一段全新的蛋白质序列，想尽快知道它的三维结构，却要经历漫长的实验周期？DeepMind 开源的 AlphaFold 3 正是为解决这一痛点而生：它不仅能预测蛋白质结构，还能同时处理 RNA、DNA、小分子配体与共价修饰，把"生物分子相互作用预测"整合进同一条推理流水线。这篇 AlphaFold 3 安装部署指南，将从零带你走完环境配置、数据库下载、模型参数申请与首次运行的全流程，照着做就能把系统跑起来。

📌 这篇指南适合谁：想尽快在本地或云 GPU 机器上把 AlphaFold 3 跑起来的开发者。全文按"任务"组织，先给最短路径，再逐步拆解，最后附避坑与调优，一口气读完即可动手。

快速上手：AlphaFold 3 快速运行的 4 条命令

在进入漫长的环境搭建之前，先看清整条最短路径。AlphaFold 3 的运行逻辑很简单：代码 + 模型参数 + 遗传数据库，三者齐备后用 Docker 一条命令即可开跑。先看前置资源清单：

前置资源	作用	获取难度
Linux + NVIDIA GPU 机器	运行环境（官方验证 A100/H100）	中等，云主机可直接选型
Docker + NVIDIA 容器工具包	隔离并暴露 GPU 给容器	低
AlphaFold 3 模型参数	预测必需权重	需填官方申请表，约 2–3 个工作日
遗传数据库	同源序列与模板搜索（约 252GB 下载）	耗时长，建议后台挂着下

资源备齐后，真正动手只需 4 步：

# 1. 获取 AlphaFold 3 源码
git clone https://gitcode.com/gh_mirrors/alp/alphafold3
cd alphafold3

# 2. 构建 Docker 镜像（首次构建会拉取全部 Python 依赖，耐心等待）
docker build -t alphafold3 -f docker/Dockerfile .

# 3. 挂载输入、输出、模型参数、数据库四个目录并运行预测
docker run -it \
    --volume $HOME/af_input:/root/af_input \
    --volume $HOME/af_output:/root/af_output \
    --volume <MODEL_PARAMETERS_DIR>:/root/models \
    --volume <DB_DIR>:/root/public_databases \
    --gpus all \
    alphafold3 \
    python run_alphafold.py \
    --json_path=/root/af_input/fold_input.json \
    --model_dir=/root/models \
    --output_dir=/root/af_output

# 4. 查看结果
ls $HOME/af_output

⚠️ 注意：第一次运行会先执行"数据管线"（遗传搜索与模板搜索，纯 CPU 任务），耗时可能远超模型推理，终端长时间滚动日志是正常现象，不是卡死。

输入文件、模型参数、数据库这三样"硬通货"怎么备齐？下面按任务一步步讲清楚。

第一步：核对 AlphaFold 3 环境配置清单

动手前先对照清单自查，避免装到一半才发现硬件不达标。

硬件要求

项目	要求	官方建议
操作系统	Linux（不支持 Windows/macOS）	Ubuntu 22.04 LTS
GPU	NVIDIA，计算能力 8.0 及以上	单张 A100 80GB 或 H100 80GB
显存	越大能预测的输入越大	80GB 已验证可处理最多 5,120 tokens
内存	至少 64GB	长序列目标的遗传搜索更吃内存
磁盘	最多约 1TB	SSD 优先，显著提升搜索性能

软件要求

软件	版本	说明
NVIDIA 驱动	与 CUDA 12.6 匹配（如 550.x）	容器外的宿主机基础驱动
CUDA	12.6	Docker 容器要求宿主机装有 CUDA 12.6
Docker	最新 CE 版	官方文档基于 rootless 模式编写
NVIDIA Container Toolkit	最新	让容器内能访问 GPU

💡 提示：官方在 A100 与 H100 上验证了数值精度，其他显卡理论上可运行，但 V100 等 7.x 计算能力显卡存在已知数值问题，需要额外设置（见避坑指南）。

第二步：搭建 Docker 与 GPU 运行环境

这一步在宿主机上完成，共四段：装 Docker、启用 rootless 模式、装驱动、装容器工具包。

2.1 安装 Docker CE（Ubuntu 22.04）

# 添加 Docker 官方 GPG 密钥
sudo apt-get update
sudo apt-get install ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

# 添加 Docker apt 源并安装
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# 验证安装
sudo docker run hello-world

2.2 启用 Rootless Docker

# 安装 uidmap 与 systemd-container
sudo apt-get install -y uidmap systemd-container

# 一键安装 rootless 模式并切换 context
sudo machinectl shell $(whoami)@ /bin/bash -c 'dockerd-rootless-setuptool.sh install && sudo loginctl enable-linger $(whoami) && DOCKER_HOST=unix:///run/user/1001/docker.sock docker context use rootless'

2.3 安装 NVIDIA 驱动

sudo apt-get -y install alsa-utils ubuntu-drivers-common
sudo ubuntu-drivers install
sudo nvidia-smi --gpu-reset
nvidia-smi  # 验证驱动已生效

如果弹出 "Pending kernel upgrade" 对话框，直接确认即可；若 nvidia-smi 提示无法与驱动通信，重启系统后再验证。

2.4 安装 NVIDIA Container Toolkit 并验证 GPU 容器

# 添加 NVIDIA 容器工具包源并安装
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg \
  && curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
    sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
    sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 配置 docker runtime 并重启
nvidia-ctk runtime configure --runtime=docker --config=$HOME/.config/docker/daemon.json
systemctl --user restart docker
sudo nvidia-ctk config --set nvidia-container-cli.no-cgroups --in-place

# 验证容器内能看到 GPU
docker run --rm --gpus all nvidia/cuda:12.6.0-base-ubuntu22.04 nvidia-smi

看到 nvidia-smi 输出 A100/H100 信息，说明 GPU 容器链路已打通，可以进入下一步。

第三步：获取 AlphaFold 3 源码与模型参数

3.1 拉取源码

git clone https://gitcode.com/gh_mirrors/alp/alphafold3
cd alphafold3

3.2 申请模型参数（关键前置步骤）

模型参数不随仓库分发，需要填写官方申请表向 Google 提交访问请求，通常 2–3 个工作日审批：

✅ 审批通过后，将参数下载到独立目录（下文统称 <MODEL_PARAMETERS_DIR>）。 ⚠️ 注意：模型参数只能从 Google 官方渠道获取，使用受其条款约束；参数目录与数据库目录一样，不要放在仓库目录内，否则会拖慢镜像构建。 📌 合规提醒：AlphaFold 3 源码采用 CC-BY-NC-SA 4.0（非商业）许可，模型参数另有独立使用条款，请务必先阅读并确认用途符合授权再投入生产使用。

第四步：完成 AlphaFold 3 遗传数据库下载

数据管线需要 9 类遗传数据库（BFD small、MGnify、PDB mmCIF、PDB seqres、UniProt、UniRef90、NT、RFam、RNACentral），仓库自带的 fetch_databases.sh 脚本可一键下载并解压。

# 先装依赖（Debian 系）
sudo apt install wget zstd

# 强烈建议在 tmux/screen 会话中执行，全程约 45 分钟
./fetch_databases.sh [<DB_DIR>]   # 不指定则默认下载到 $HOME/public_databases

下载完成后目录大致长这样：

mmcif_files/                          # 约 20 万份 PDB mmCIF 文件
bfd-first_non_consensus_sequences.fasta
mgy_clusters_2022_05.fa
nt_rna_2023_02_23_clust_seq_id_90_cov_80_rep_seq.fasta
pdb_seqres_2022_09_28.fasta
rfam_14_9_clust_seq_id_90_cov_80_rep_seq.fasta
rnacentral_active_seq_id_90_cov_80_linclust.fasta
uniprot_all_2021_04.fa
uniref90_2022_05.fa

三条必须遵守的注意事项：

注意项	原因
`<DB_DIR>` 不要放在 AlphaFold 3 仓库目录内	否则构建镜像时会把几百 GB 数据库复制进去，构建极慢
预留足够空间：下载约 252GB，解压后约 630GB	空间不足会导致下载中断
确保数据库目录有完整读写权限：`sudo chmod 755 --recursive <DB_DIR>`	权限不足会让 MSA 工具报出难懂的错误

第五步：构建镜像并运行第一次预测

5.1 构建 Docker 镜像

docker build -t alphafold3 -f docker/Dockerfile .

镜像内置了 JAX、Haiku、RDKit 等全部推理依赖，构建一次即可反复使用。

5.2 准备输入 JSON

AlphaFold 3 使用自定义 JSON 输入格式，支持蛋白质、RNA、DNA、配体（CCD 码或 SMILES）等实体。先用官方提供的 2PV7 示例文件练手，保存为 fold_input.json：

{
  "name": "2PV7",
  "sequences": [
    {
      "protein": {
        "id": ["A", "B"],
        "sequence": "GMRESYANENQFGFKTINSDIHKIVIVGGYGKLGGLFARYLRASGYPISILDREDWAVAESILANADVVIVSVPINLTLETIERLKPYLTENMLLADLTSVKREPLAKMLEVHTGAVLGLHPMFGADIASMAKQVVVRCDGRFPERYEWLLEQIQIWGAKIYQTNATEHDHNMTYIQALRHFSTFANGLHLSKQPINLANLLALSSPIYRLELAMIGRLFAQDAELYADIIMDKSENLAVIETLKQTYDEALTFFENNDRQGFIDAFHKVRDWFGDYSEQFLKESRQLLQQANDLKQG"
      }
    }
  ],
  "modelSeeds": [1],
  "dialect": "alphafold3",
  "version": 1
}

关键字段说明：

字段	含义
`name`	任务名，输出目录将以它命名
`modelSeeds`	随机种子，至少一个，多个种子会生成多份采样结果
`sequences`	实体列表，可混合 protein / rna / dna / ligand
`dialect`	固定为 `alphafold3`（会自动识别并转换 AlphaFold Server 格式）
`version`	输入格式版本

把文件放进 $HOME/af_input 目录，然后运行：

docker run -it \
    --volume $HOME/af_input:/root/af_input \
    --volume $HOME/af_output:/root/af_output \
    --volume <MODEL_PARAMETERS_DIR>:/root/models \
    --volume <DB_DIR>:/root/public_databases \
    --gpus all \
    alphafold3 \
    python run_alphafold.py \
    --json_path=/root/af_input/fold_input.json \
    --model_dir=/root/models \
    --output_dir=/root/af_output

5.3 输出产物

预测结束后，输出目录下会生成以任务名命名的子目录，核心文件包括：

文件	内容
`<job_name>_model.cif`	排名最高的预测结构，兼容多数结构生物学工具
`<job_name>_summary_confidences.json`	置信度汇总
`ranking_scores.csv`	所有样本的排名得分
`seed-<seed>_sample-<n>/`	每个种子与样本的独立结果目录

📌 两个重要开关：--run_data_pipeline（默认 true，纯 CPU 的遗传/模板搜索）与 --run_inference（默认 true，需要 GPU）。数据管线与推理可分机执行，配合 --input_dir 还可以批量提交多个 JSON，详见 python run_alphafold.py --help。

第六步（可选）：用 Singularity 替代 Docker 运行

如果目标集群没有 Docker 权限，可以用 Singularity。流程是"用 Docker 构建，用 Singularity 运行"。

# 1. 安装 Singularity（Debian 系）
wget https://github.com/sylabs/singularity/releases/download/v4.2.1/singularity-ce_4.2.1-jammy_amd64.deb
sudo dpkg --install singularity-ce_4.2.1-jammy_amd64.deb
sudo apt-get install -f

# 2. 起一个本地 registry，把 Docker 镜像推上去
docker run -d -p 5000:5000 --restart=always --name registry registry:2
docker tag alphafold3 localhost:5000/alphafold3
docker push localhost:5000/alphafold3

# 3. 用 Docker 镜像构建 Singularity 镜像
SINGULARITY_NOHTTPS=1 singularity build alphafold3.sif docker://localhost:5000/alphafold3:latest

# 4. 验证镜像能访问 GPU
singularity exec --nv alphafold3.sif sh -c 'nvidia-smi'

# 5. 运行预测
singularity exec \
     --nv \
     --bind $HOME/af_input:/root/af_input \
     --bind $HOME/af_output:/root/af_output \
     --bind <MODEL_PARAMETERS_DIR>:/root/models \
     --bind <DB_DIR>:/root/public_databases \
     alphafold3.sif \
     python run_alphafold.py \
     --json_path=/root/af_input/fold_input.json \
     --model_dir=/root/models \
     --db_dir=/root/public_databases \
     --output_dir=/root/af_output

避坑指南：AlphaFold 3 常见错误解决手册

部署途中大概率会踩到下面几个坑，直接对号入座：

❌ 现象：nvidia-smi 报 "NVIDIA-SMI has failed because it couldn't communicate with the NVIDIA driver." 🔍 原因：驱动安装后未正确加载，属于常见的内核模块问题。 ✅ 解决：执行 sudo reboot now 重启系统，待 nvidia-smi 输出正常后再继续后续步骤。

❌ 现象：运行时报 error while creating mount source path ... permission denied 🔍 原因：--volume 挂载的源目录不存在或权限不足。 ✅ 解决：核对四个挂载路径是否正确，预先创建目录并执行 chmod 755 $HOME/af_input $HOME/af_output。

❌ 现象：遗传搜索阶段 MSA 工具报出晦涩难懂的外部错误。 🔍 原因：数据库目录或文件缺少完整读写权限。 ✅ 解决：执行 sudo chmod 755 --recursive <DB_DIR> 后重试。

❌ 现象：docker build 慢到离谱。 🔍 原因：数据库或模型参数放在了仓库目录内，构建时被整体复制进镜像上下文。 ✅ 解决：把数据库与参数移到仓库外，清空后重新构建。

❌ 现象：V100 等显卡预测结果全是残基冲突，排名分低至 -99。 🔍 原因：CUDA Capability 7.x 显卡存在已知数值问题。 ✅ 解决：设置环境变量 XLA_FLAGS="--xla_disable_hlo_passes=custom-kernel-fusion-rewriter"。

❌ 现象：用 SMILES 定义配体时，Cl、Br 等双字母原子解析错误。 🔍 原因：这是旧版本代码的已知缺陷（已修复）。 ✅ 解决：把源码更新到最新提交再重新构建镜像。

❌ 现象：推理阶段显存不足（OOM）。 🔍 原因：输入 token 数超过了当前 GPU 显存承载能力。 ✅ 解决：改用更大显存 GPU，或开启统一内存（见进阶调优第 5 条）。

进阶调优：让 AlphaFold 3 跑得更快

环境跑通之后，这几招可以显著改善耗时与资源利用率。

1. 数据库放 SSD，并配置多路径回退

遗传搜索的性能高度依赖磁盘速度。SSD 放常用库、大容量机械盘放剩余库，两个目录都挂载并多次指定 --db_dir，系统会优先读快的：

docker run -it \
    --volume $HOME/af_input:/root/af_input \
    --volume $HOME/af_output:/root/af_output \
    --volume <MODEL_PARAMETERS_DIR>:/root/models \
    --volume <SSD_DB_DIR>:/root/public_databases \
    --volume <DB_DIR>:/root/public_databases_fallback \
    --gpus all \
    alphafold3 \
    python run_alphafold.py \
    --json_path=/root/af_input/fold_input.json \
    --model_dir=/root/models \
    --db_dir=/root/public_databases \
    --db_dir=/root/public_databases_fallback \
    --output_dir=/root/af_output

2. 分阶段运行，物尽其用

数据管线与推理可以解耦：先在有 CPU 的便宜机器上跑 --norun_inference 生成带 MSA 的 JSON，再在 GPU 机器上跑 --norun_data_pipeline 只做推理。同一份 MSA 结果还能跨多个随机种子复用，省去重复搜索。

3. 用 --buckets 控制编译次数

模型按输入尺寸分桶编译，桶配置得当可避免每个输入都触发一次重编译。例如输入集中在 5,132–5,342 tokens 时，指定 --buckets 256,512,768,1024,1280,1536,2048,2560,3072,3584,4096,4608,5120,5376 可让多个输入共用一次编译。

4. 开启 JAX 持久化编译缓存

不同运行之间反复编译很浪费，用 --jax_compilation_cache_dir <YOUR_DIRECTORY> 把编译产物缓存下来，后续运行直接命中。

5. 显存吃紧时启用统一内存

输入超过 5,120 tokens 或显卡只有 40GB 时，可在 Dockerfile 中设置以下环境变量让显存溢出到内存（变慢但不会 OOM）：

ENV XLA_PYTHON_CLIENT_PREALLOCATE=false
ENV TF_FORCE_UNIFIED_MEMORY=true
ENV XLA_CLIENT_MEM_FRACTION=3.2

6. 性能参考（免编译推理耗时）

Tokens	1×A100 80GB	1×H100 80GB
1,024	62s	34s
2,048	275s	144s
4,096	1,434s	774s
5,120	2,547s	1,416s

同样的免编译推理，仓库的单卡 A100 80GB 配置比论文中的 16×A100 40GB 配置在全部 token 规模下至少快 2 倍，适合高吞吐场景。

最后总结

回顾整条部署链路，其实只有四件事：核对环境 → 备齐资源（模型参数 + 遗传数据库）→ 构建镜像 → 运行预测。绝大多数问题都出在权限、路径和数据库位置这三处，对照避坑指南即可快速排除。

跑通 2PV7 只是第一步。接下来可以尝试混合多链体系（蛋白 + 核酸 + 配体）、用 SMILES 定义自定义配体、指定共价键，甚至用 --input_dir 批量提交一批任务。数据库下载耗时长，建议挂到后台慢慢下，先把 Docker 环境和模型参数申请流程走起来。祝你的第一次 AlphaFold 3 预测一次成功，早日产出漂亮的结构图！

【免费下载链接】alphafold3 AlphaFold 3 inference pipeline. 项目地址: https://gitcode.com/gh_mirrors/alp/alphafold3

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考