企业官网建设流程全解析

AlphaFold3的源码和模型权重一出来，团队里就有人开始鼓捣本地部署了。和AlphaFold2相比，AF3最大的变化不只是精度提升，而是把预测范围从单独的蛋白质结构扩展到了蛋白质-核酸复合物、配体、离子、共价修饰这类更贴近真实生物学场景的组合。也正因为引入了太多新组件，部署难度明显上了一个台阶：数据库更大、依赖更复杂、对GPU显存和驱动版本的要求也更苛刻。

这篇文章是我自己用conda方案完整跑通AlphaFold3本地推理的记录，全程不用Docker，所有Python环境和依赖都靠conda管理。适合已经跑过AlphaFold2、想迁移到AF3的选手，也适合从来没部署过深度学习推理环境、但敢于折腾的结构生物学研究者。我会把环境搭建、依赖安装、数据库下载、JSON输入文件配置、运行命令和常见报错全部讲清楚，最后再分享一些实际踩坑后的经验。

1. 为什么选择conda方案部署AlphaFold3

先聊清楚一件事：官方文档主推Docker，但我最终选择了conda，这里有两个很实际的原因。第一，很多实验室的服务器是没有root权限的，Docker要折腾用户组、sudo和镜像加速，而conda可以很干净地安装在用户目录下，权限问题少得多。第二，AlphaFold3的运行核心是Python推理脚本，只要把JAX、Haiku、Optax这些库装对版本，conda环境完全可以替代Docker镜像，而且后续调试代码、改动参数也方便很多。

如果你问我conda方案相比Docker有什么劣势，我会说主要在于复现的确定性。Docker镜像把CUDA、cuDNN、Python和所有依赖一次性锁死，而conda环境需要自己保证版本对齐，稍有疏忽就容易遇到“推理中途炸掉”的情况。不过反过来想，conda方案也逼着你把每一步依赖关系弄清楚，出了问题时定位问题的能力会比无脑用Docker强不少。

还有一点要提前说，AlphaFold3的官方代码和训练好的权重只保证在Linux下正常运行。如果你手头只有Windows机器，最省心的方式是用WSL2或者直接在服务器上操作。我在Windows的conda环境下试过，HMMER这些序列比对工具在Windows上编译和调用都会出各种幺蛾子，最后还是切到Linux才顺利跑通。

另一个支撑我选conda方案的细节是，AlphaFold3虽然自带完整的遗传数据库依赖，但如果只想验证模型能不能跑通，完全可以先用精简的测试数据集。Docker方案为了这一步有时候要拖拽好几个GB的基础镜像，conda方案只要环境建好，后面对接不同数据集都像切换目录一样灵活。

2. conda环境准备与依赖安装

2.1 miniconda安装与conda init

如果你已经装过Miniconda或者Anaconda，这一步可以跳过。如果是从零开始，我建议下载Miniconda而不是Anaconda，因为AlphaFold3用不到Anaconda自带的那些科学计算预装包，Miniconda体积小、干净，也更容易避免和后续pip安装的依赖互相干扰。

下载并安装后，有一个很多人一定会遇到的坑：终端里输入conda activate会报错“CommandNotFoundError: Your shell has not been properly configured to use 'conda activate'”，或者你搜到的热词里那个conda error: run 'conda init' before 'conda activate'，本质都是同一个问题——conda没有把自己的初始化脚本写入shell配置。解决办法很简单，在终端执行：

conda init bash

如果你用的是zsh，就把bash替换成zsh。执行完以后重新打开终端，应该能看到命令行前面出现(base)字样。

2.2 创建AlphaFold3专属conda环境

我不建议在base环境里直接装AlphaFold3，因为AF3的依赖版本很特殊，和其他项目冲突的概率极高。我习惯的做法是单独建一个名为af3的环境，Python版本锁定为3.11，这也是官方项目里pyproject.toml隐式验证过的版本。

conda create -n af3 python=3.11 -y conda activate af3

创建环境的同时，顺手把pip升级到最新版，避免后面积分依赖解析时因为pip版本过旧而卡住。实测下来Ubuntu 22.04环境下Python 3.11的兼容性是最好的，Python 3.10也不是不能用，但个别库的轮子只发布了针对3.11的预编译版本，没必要给自己添堵。

如果你平时习惯通过--prefix把环境创建到指定位置，比如D盘或者工作目录，完全可以用conda create --prefix /data/conda_env/af3 python=3.11这种写法。之后激活时也要用完整路径：conda activate /data/conda_env/af3。这个技巧对磁盘空间紧张的服务器尤其好用，毕竟数据库动不动就是几百GB，环境文件可以放到另一块磁盘。

2.3 JAX与CUDA版本匹配，这是成败关键

AlphaFold3的推理核心是JAX，而JAX的GPU版本和CUDA版本强绑定。这一步是整个部署中最容易翻车的地方，我把关键版本对应关系整理了一个简化表格，基于我实际部署和社区里反馈比较稳定的组合：

安装命令如下：

pip install "jax[cuda12]==0.4.35"

这个命令会同时安装jaxlib和对应的CUDA依赖包。如果你的显卡是Ada架构（比如RTX 4090）或者Hopper架构（H100），默认版本的JAX性能表现都不错。如果是越来越常见的Ampere架构（A100、RTX 3090），同样没问题。真正要小心的是老一点的Volta架构（V100），虽然理论上能跑，但需要额外开启XLA_PYTHON_CLIENT_PREALLOCATE等环境变量来控制显存分配策略。

2.4 剩余Python依赖安装

AlphaFold3的官方仓库google-deepmind/alphafold3里带了pyproject.toml，克隆完仓库后，在af3环境里直接用pip安装即可：

git clone https://github.com/google-deepmind/alphafold3.git cd alphafold3 pip install -r dev-requirements.txt python -m pip install -e .

这套安装流程会把Haiku、Sonnet、Optax、ml-collections、sax、dm-tree等一堆依赖全部装好。我实际跑的时候遇到过一个坑：如果本地的Python环境之前装过旧版本的absl-py或protobuf，会和AlphaFold3要求的版本冲突，导致运行时报“Expected DottedTypeName”之类的诡异错误。解决办法是干脆新建一个干净环境，不要复用和生物学计算相关的其他项目环境。

另外，如果你是PyCharm用户，想在这个环境里调试脚本，记得在Project Interpreter里选择af3环境的解释器路径，一般位于~/miniconda3/envs/af3/bin/python。这样后续打断点看张量形状会方便很多，实测比用Jupyter Kernel要稳定。

3. 数据库、权重与目录结构：真正的体能战

3.1 需要准备的数据库清单

AlphaFold3的物理预测依赖两部分外部数据：遗传数据库（用于生成多序列比对MSA）和PDB模板库（用于结构模板）。完整数据库加在一起通常超过200GB，我第一次下载时没规划好磁盘，结果跑到一半遇到磁盘满，前面的下载全白费了。

我把主要的数据库列在下面，方便你对照规划磁盘空间：

• BFD（约70GB）：大容量蛋白质序列库，MSA召回率的关键
• MGnify（约9GB）：宏基因组蛋白库
• UniRef90（约16GB）
• UniProt（约13GB）
• RNA Central（约5GB）：RNA相关序列
• NT库（约30GB）：核酸序列库
• PDB mmCIF（约140GB）：模板结构的原始文件

官方仓库提供了fetch_all_databases.sh脚本，可以一次性把这些数据都拉下来。但更合理的做法是先下载一个测试版的小集合，验证整个推理链路能跑通之后再补全完整数据库。实测一个小蛋白复合物的MSA生成阶段只需要前面几个数据库的子集，没必要一开始就梭哈所有数据。

3.2 测试数据集与完整数据集的选择

如果你只想验证conda环境和模型权重是否正常工作，建议先走一轮最小化测试。AlphaFold3官方仓库里通常会有测试用的小PDB文件和对应的JSON输入，一般情况下我们只需要准备：

• 一个较小版本的PDB缓存目录
• 一个最小化的遗传数据库目录

我的做法是创建一个af3_test_db目录，复制几个必要的数据库子集进去，再配合单条短序列跑一次预测。只要能顺利走完从MSA到结构生成的完整流程，基本就能确认部署成功。等确认无误后，再单独把完整数据库放到生产目录，运行时不求快，稳才是关键。

3.3 模型权重的申请与放置

AlphaFold3的权重不是直接在GitHub上随代码下载的，而是需要去DeepMind指定的页面填写申请信息，获取一个下载链接。这一步和AlphaFold2时代类似，本质上是一个合规约束，研究者申请后通常很快就能拿到下载链接。

权重文件解压后是一组.npz或.pkl格式的模型参数文件。下载完成后，我建议放到一个独立目录中，例如：

mkdir -p /data/af3/models tar -xzf alphafold3_model_weights.tar.gz -C /data/af3/models

目录的结构要保持一致性，因为运行命令里的--model_dir参数需要指向包含模型参数文件的最外层目录。很多人在这一步把model_dir指到了多嵌套一层的位置，会导致“Cannot find model checkpoint”的错误。

3.4 推荐的目录组织方式

我把部署相关的路径统一放在一个父目录下，这样几个参数引用起来特别省心：

/data/af3 ├── af3_env_scripts # conda环境相关的脚本 ├── databases # 遗传数据库子目录 ├── pdbs # PDB模板数据库 ├── models # 模型权重 ├── input_jsons # 输入的JSON文件 ├── output # 预测结果输出目录 └── alphafold3 # 官方代码仓库

目录结构本身不强制，但建议保持清晰，因为后续运行命令里--json_path、--output_dir、--model_dir这几个参数都要频繁引用。我见过有人把数据库和权重放在同一层目录里，结果误把模型目录指向了数据库目录，白白浪费了几个小时。

4. 输入JSON与运行参数解析

4.1 输入JSON的字段说明

AlphaFold3和AlphaFold2的输入方式有一个本质区别：AF2主要用--fasta_paths传入序列文件，而AF3要求一份结构化的JSON配置，里面除了序列信息，还包括配体、离子、共价修饰、模型随机种子等完整的输入定义。

核心字段如下：

• name：任务名称，输出目录会以它为基础创建子目录
• modelSeeds：随机种子数组，多个种子可以生成多个预测样本
• sequences：序列条目数组，每一条可以是proteinChain、dnaChain、rnaChain、ligand或branchedChain
• dialect：固定填alphafold3
• version：版本号，当前一般填2

需要注意，序列条目里除了长字符串sequence，还包含count字段。count表示同一条序列在复合物中出现的拷贝数。比如一个同源二聚体，count就要设成2，而不是把序列重复写两遍。

4.2 几个典型输入示例

最基础的单条蛋白质链，JSON可以这样写：

{ "name": "single_protein", "modelSeeds": [1], "sequences": [ { "proteinChain": { "sequence": "MVLSPADKTNVKAAWGKVGAHAGEYGAEALERMFLSFPTTKTYFPHFDLSHGSAQVKGHGKKVADALTNAVAHVDDMPNALSALSDLHAHKLRVDPVNFKLLSHCLLVTLAAHLPAEFTPAVHASLDKFLASVSTVLTSKYR", "count": 1 } } ], "dialect": "alphafold3", "version": 2 }

如果是一个蛋白质与DNA结合的复合物，就在sequences数组里同时加入proteinChain和dnaChain条目：

{ "name": "protein_dna_complex", "modelSeeds": [1], "sequences": [ { "proteinChain": { "sequence": "MAPKKKKK...", "count": 1 } }, { "dnaChain": { "sequence": "TAGCTAGCTAG", "count": 1 } } ], "dialect": "alphafold3", "version": 2 }

这里有一个非常容易踩的细节：核酸链的序列只写单链就行，不需要自己补互补链，AlphaFold3内部会自动生成双链并处理配对关系。我第一次尝试时把DNA双链都写进去了，结果输出结构明显重复，后来单独看文档才发现问题。

4.3 运行命令与参数含义

环境准备好、输入文件就位后，跑预测的命令长这样：

python run_alphafold.py \ --json_path=/data/af3/input_jsons/single_protein.json \ --model_dir=/data/af3/models \ --output_dir=/data/af3/output \ --flash_attention_implementation=triton \ --jax_platform=gpu

几个参数的含义拆开解释一下：

• json_path：指向输入JSON文件，支持多个文件用逗号分隔
• model_dir：模型权重所在顶层目录
• output_dir：预测结果输出目录
• flash_attention_implementation：FlashAttention的实现方式，可选triton或cudnn，实测在NVIDIA GPU上triton更稳
• jax_platform：强制指定使用GPU而非CPU

如果想保留更强的共享内存或做跨任务并行，可以给JAX加环境变量，比如设置XLA_PYTHON_CLIENT_PREALLOCATE=false来关闭显存预分配，避免和别人共用GPU时出现显存冲突。这个技巧在实验室服务器上尤其有用。

5. 完整实操流程（conda方案）

5.1 从零到第一次运行的时间线

我把整个部署过程按时间顺序捋一遍，方便你对照自己的进度判断走到哪一步了。第一阶段是conda环境搭建和Python依赖安装，顺利的话半小时内能完成，卡点主要在JAX版本匹配。第二阶段是数据库下载，哪怕有高速网络，完整数据库也建议留出半天时间。第三阶段是权重申请和解压，这个取决于对方的审批速度。

实际部署时，我发现一个很值得推荐的顺序：先把模型权重下载好、验证一个简单输入能跑通，再去补全大数据库。因为权重申请往往有延迟，数据库下载又是纯粹的时间消耗，两条线完全可以并行推进。我当时是先提交了权重申请，然后一边下载测试数据库，一边等权重链接，最后同时就位，几乎没有浪费时间。

5.2 MSA与推理逻辑

AlphaFold3的完整流程可以粗略分成两大段：前段是MSA（多序列比对）生成，后段是结构预测推理。

MSA阶段会调用jackhmmer这类外部二进制工具，对输入序列在遗传数据库里搜索同源序列，生成多序列比对结果。这也是为什么会额外依赖HMMER等工具，而且官方把MSA逻辑做了并行化，多核CPU对这一步的加速非常明显。我第一次跑时只分配了8核，MSA阶段的耗时占到了整体的一大半，后来加到32核，速度明显提升。

推理阶段则是把MSA特征、模板特征连同输入序列的token信息一起喂给模型，经过一次扩散生成过程输出三维结构。这一步对GPU的依赖极高，显存不够时哪怕前面MSA跑得再快也白搭。

在实际使用中，如果只想快速看结果，可以在JSON里不提供msa相关路径或者使用跳过MSA的选项，直接以单序列模式运行，但精度会下降。我的建议是，测试链路用单序列模式，正式预测还是老老实实跑完整MSA。

5.3 性能参考与硬件建议

整理了身边朋友在几种GPU上的表现，供你大致参考。注意这些时间会因为序列长度、配体数量、MSA搜索深度不同而明显波动，不要当成精确benchmark：

如果是更大的蛋白复合物，显存低于16GB基本没法跑，建议直接用Deepspeed相关的显存优化分支。官方代码虽然做了显存优化，但16GB以下体验会很痛苦，经常在扩散去噪阶段出现OOM。

6. 常见问题与排查技巧实录

6.1 conda init报错

前面提到过，conda activate后提示run 'conda init' before 'conda activate'是新手最容易碰到的问题。这个报错看起来吓人，实际解决方式很粗暴：在shell里执行对应的conda init，然后重新启动终端。还有一种边缘情况是用户手动改了.bashrc，把conda的初始化脚本注释掉了，这时需要编辑配置文件恢复。

如果你使用的是Windows的conda环境，注意在PowerShell里直接执行conda命令时也可能出现环境未被初始化的情况。处理方式和Linux一致，用conda init powershell初始化即可。

6.2 显存不足（OOM）

推理过程中最常见的两个OOM触发点，一个是MSA后特征拼接阶段，另一个是扩散模型去噪阶段。实测下来，最有效的手段是：

• 在运行命令前设置XLA_PYTHON_CLIENT_PREALLOCATE=false
• 把modelSeeds从默认的5个减少到1个，因为每个种子都会额外占用推理资源
• 缩短输入序列长度来排查问题边界

如果序列长度不可压缩，那就只能考虑更高级的优化分支或者换更大显存的卡。我在排查阶段就用过一个很实用的技巧：把JSON里的序列逐步减半，从原本的900残基减到450再减到225，看OOM是否还出现，这样就能快速判断显存瓶颈到底是模型自身还是序列长度导致的。

6.3 JAX找不到GPU

运行时报cuda driver is not initialized或No GPU found，绝大多数原因是jax安装成了CPU版本。检查命令很简单：

python -c "from jax.lib import xla_client; print(xla_client.get_plugin_device_client('gpu'))"

如果输出报错，就说明JAX的GPU支持没装好。重新执行pip install "jax[cuda12]==0.4.35"，然后重启Python进程。还有一个容易被忽略的点：如果你做了SSH远程连接，需要确认CUDA_VISIBLE_DEVICES环境变量没有把GPU屏蔽掉。有一次我明明所有依赖都正常，结果发现是tmux会话继承了一个错误的CUDA_VISIBLE_DEVICES环境变量，白白排查了很久。

6.4 数据库路径或模板目录错误

报错信息通常会直接指出某个数据库文件不存在，但更有迷惑性的一个问题是：目录存在、但里面的文件是空的，或者子目录层级不对。AlphaFold3对数据库目录的层级是有固定预期的，不能随便自定义嵌套方式。

我的建议是严格按照官方fetch_all_databases.sh脚本生成的目录结构来安排数据库，不要手动重建。如果你是从百度网盘或者实验室拷贝的数据，注意检查文件是否完整下载，我遇到过FTP传输出错导致解压时文件缺失的情况，浪费了更多时间。

6.5 常见问题速查表

7. 部署完之后的几点体会

AlphaFold3的conda部署难度其实不在“conda”本身，而在于它把深度学习环境管理、生物信息数据库管理、GPU资源调度这些分散的问题揉在了一起。conda方案好就好在每一步都是透明可控的，出了问题可以逐层定位，而不是在Docker的黑盒里抓瞎。

按我个人的经验，如果你只是做常规的单链预测，其实AlphaFold2已经够用，AF3的优势场景是蛋白-核酸复合物、配体分子和共价修饰这类Multimer任务。所以部署之前先想清楚自己的研究方向是否真的需要AF3，否则几小时时间加几百GB磁盘只换来一个“跑通了但用不上”的模型，确实有点亏。真到了需要预测复合物结构、并且手头有A100或4090级别GPU的时候，这篇文章里的流程可以直接照着抄，大概率能帮你少走不少弯路。