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 python3.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 python3.11这种写法。之后激活时也要用完整路径conda activate /data/conda_env/af3。这个技巧对磁盘空间紧张的服务器尤其好用毕竟数据库动不动就是几百GB环境文件可以放到另一块磁盘。2.3 JAX与CUDA版本匹配这是成败关键AlphaFold3的推理核心是JAX而JAX的GPU版本和CUDA版本强绑定。这一步是整个部署中最容易翻车的地方我把关键版本对应关系整理了一个简化表格基于我实际部署和社区里反馈比较稳定的组合组件推荐版本说明驱动CUDA 12.4及以上只装驱动侧即可conda环境内不需要再装系统级CUDAJAXjax[cuda12] 0.4.35左右对应JAX自带的CUDA运行时cuDNN9.xJAX通过cudnn做attention算子加速显卡驱动Linux 535过老驱动会触发“找不到cuda driver”的错误安装命令如下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约16GBUniProt约13GBRNA Central约5GBRNA相关序列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或branchedChaindialect固定填alphafold3version版本号当前一般填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_implementationtriton \ --jax_platformgpu几个参数的含义拆开解释一下json_path指向输入JSON文件支持多个文件用逗号分隔model_dir模型权重所在顶层目录output_dir预测结果输出目录flash_attention_implementationFlashAttention的实现方式可选triton或cudnn实测在NVIDIA GPU上triton更稳jax_platform强制指定使用GPU而非CPU如果想保留更强的共享内存或做跨任务并行可以给JAX加环境变量比如设置XLA_PYTHON_CLIENT_PREALLOCATEfalse来关闭显存预分配避免和别人共用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搜索深度不同而明显波动不要当成精确benchmarkGPU显存单蛋白链约200残基耗时蛋白-核酸复合物耗时RTX 309024GB10-20分钟30-60分钟RTX 409024GB5-10分钟15-30分钟A10080GB5分钟以内10-20分钟如果是更大的蛋白复合物显存低于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_PREALLOCATEfalse把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 常见问题速查表现象大概率原因快速处理办法conda activate报错conda未初始化执行conda init并重启终端运行时报GPU不存在JAX装了CPU版重装jax[cuda12]并校验推理中途OOM显存不足或种子过多加预分配假参数、减少种子数模型参数找不到model_dir路径层级错误确认路径下直接是权重文件输出结构明显错误核酸序列写了双链只写单链交给模型处理依赖版本冲突环境被复用了新建干净conda环境7. 部署完之后的几点体会AlphaFold3的conda部署难度其实不在“conda”本身而在于它把深度学习环境管理、生物信息数据库管理、GPU资源调度这些分散的问题揉在了一起。conda方案好就好在每一步都是透明可控的出了问题可以逐层定位而不是在Docker的黑盒里抓瞎。按我个人的经验如果你只是做常规的单链预测其实AlphaFold2已经够用AF3的优势场景是蛋白-核酸复合物、配体分子和共价修饰这类Multimer任务。所以部署之前先想清楚自己的研究方向是否真的需要AF3否则几小时时间加几百GB磁盘只换来一个“跑通了但用不上”的模型确实有点亏。真到了需要预测复合物结构、并且手头有A100或4090级别GPU的时候这篇文章里的流程可以直接照着抄大概率能帮你少走不少弯路。