这周终于把 AlphaFold3 在本地用 conda 完整跑通了。整个过程比想象中折腾倒不是说代码有多难装而是坑全藏在“你以为装好了、其实还没装好”的地方。如果你也想把 AlphaFold3 本地部署起来用 conda 做环境管理是目前最稳妥的一条路。这篇文章我会把从创建虚拟环境、拉源码、下载数据库、写输入 JSON到跑通第一个预测的完整过程记录下来包括我踩过的坑、报错信息和最终的处理方式。先说结论AlphaFold3 的本地部署不是一个“一条命令搞定”的事它对硬件、网络和依赖管理都有要求。尤其是 conda 环境如果一开始没有把 Python 版本、CUDA 版本和 JAX 版本对齐后面大概率要反复返工。适合什么人看呢一是做蛋白质、核酸、配体结构预测的研究生和科研人员二是想搞明白 AlphaFold3 内部运行机制、打算二次开发的工程师。纯生物背景、完全没碰过命令行的朋友也可以看我会尽量把每一步说得足够具体。1. 部署前要知道的三件事1.1 AlphaFold3 开源版和网页版到底差在哪很多人第一次接触 AlphaFold3是在 Google DeepMind 的网站上上传序列等几分钟拿到结果。网页版确实方便但它的限制也很明显单次预测的序列长度受限、不能批量处理、不能自定义模型参数、更没法接入自己的结构预测流程。本地部署的 AlphaFold3指是 DeepMind 开源的代码仓库。你可以把它理解成“把 AlphaFold3 的发动机搬到自己电脑上”输入一个 JSON 格式的任务描述它会在本地完成 MSA多序列比对生成、结构模型推理、置信度评估最后输出 PDB 格式的三维结构文件和置信度 JSON。源码、模型参数和数据库都是分开的跑通之后意味着你拥有了一条完整的本地结构预测流水线可以反复调用、批量跑任务也可以基于代码做定制。有一点必须强调本地部署不等于“完全开源无限制”。AlphaFold3 的参数文件需要通过官方渠道申请使用条款里有明确的场景限制比如非商业用途、注意引用规范等。这不影响技术部署本身但如果你要在项目里大规模使用建议先把条款读清楚。1.2 为什么是 conda 而不是直接 pipAlphaFold3 的依赖非常重涉及 Python 包、CUDA 运行时、外部比对工具HMMER 的 Jackhmmer 等多个层次。如果不做环境隔离直接往系统 Python 里 pip install轻则和现有包冲突重则把整个环境搞坏。conda 的价值在这里体现得非常直接它不仅能管理 Python 版本和 pip 包还能管理非 Python 的原生依赖一条命令就能建出一个互不干扰的独立环境。我当时选的方案是Miniconda conda 虚拟环境Python 版本固定为 3.11。为什么不选 Python 3.10 或 3.12按社区实测JAX 生态在 3.11 上兼容性最稳AlphaFold3 的依赖解析很少在 3.11 上报错。3.10 也能跑但没必要给自己添堵。3.12 对 JAX 某些原生扩展的支持还有小问题尤其是 CUDA 相关的编译环节。1.3 硬件和存储的真实门槛官方建议的 GPU 是 A100 40GB这是“能流畅预测中大型复合物”的门槛。我自己实测下来如果是几十个残基的短肽或小蛋白20GB 显存的卡勉强能跑一旦涉及蛋白-核酸复合物或者带配体的体系显存会迅速吃满。所以如果你手头的卡只有 12GB 或 16GB也不是完全不能做但要学会“裁剪序列长度、降低采样数量”后面我会专门讲调参。存储是另一个容易被忽视的点。AlphaFold3 的数据库下载下来不是小数目。常用的几个库包括 BFD、MGnify、UniRef90、UniRef30再加上 PDB 的 mmCIF 和序列库以及 RNA 相关的 RNAcentral、RFAM、NT 库全量占用空间超过 500GB 是正常的。如果你的固态硬盘只有 1TB建议先规划好空间或者只下载任务类型真正需要的子集。2. 从零开始conda 环境准备2.1 安装 Miniconda 并解决 conda init 问题第一步是安装 Miniconda。到官网下载对应你操作系统的安装包Windows 用户记得选 64 位版本。安装过程中有一个“Add to PATH”的选项建议勾上如果没勾后面所有 conda 命令都会提示找不到。安装完以后很多人第一次运行conda activate就会碰到一个经典报错CondaError: Run conda init before conda activate这个报错的本质是conda 的可执行文件虽然在 PATH 里但它没有把 shell 的初始化脚本写入当前用户的配置。解决办法很简单在终端里执行conda init bashWindows PowerShell 用户则执行conda init powershell执行完以后务必关闭当前终端窗口再重新打开然后验证conda --version如果输出了类似conda 24.x.x的版本号说明初始化成功。这个坑非常普遍尤其在 PowerShell 和 Windows Terminal 环境下别急着骂 conda先检查有没有执行 init。2.2 创建专属虚拟环境并固定 Python 版本环境名我建议起得直白一点就叫af3省得以后记不住。创建命令如下conda create -n af3 python3.11 -y-y是跳过确认直接创建。创建完成后激活conda activate af3激活成功后命令行前面会出现(af3)前缀。然后确认当前 Python 版本和路径python --version which python这里有一个细节which python的路径应该指向你 conda 环境目录下的 python而不是系统的/usr/bin/python或者 Windows 下的C:\Python311\python.exe。如果指向不对说明环境激活有问题检查上一节提到的 conda init。平时管理环境用这几个命令就够了查看所有环境conda env list删除环境conda remove -n af3 --all导出环境conda env export environment.yml导出环境这个操作建议在部署成功后就做一次后面换机器或者环境坏了可以直接用conda env create -f environment.yml秒级重建。2.3 conda 与 pip 换源不是玄学是刚需AlphaFold3 的依赖里有很多大体积包JAX 相关组件动辄几百 MB。如果不配国内镜像下载速度会让你怀疑人生。我给 conda 加的是清华源配置方式是修改用户目录下的.condarc文件或者直接执行conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/ conda config --set show_channel_urls yespip 的镜像我推荐用阿里云源配置方式pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/注意一个原则conda 和 pip 不要混用同一个环境反复安装尤其是涉及jax这种对版本敏感的包。我的策略是先让 conda 搞定 Python 和原生工具再把剩余 Python 包统一交给 pip。2.4 依赖安装的实测顺序现在进入正题。先把 AlphaFold3 源码拉到本地git clone https://github.com/google-deepmind/alphafold3.git cd alphafold3在清华/阿里源下依赖安装速度还算能接受。AlphaFold3 的依赖分为几个层次第一层是基础科学计算包包括 numpy、scipy、pandas、BioPython、gemmi处理 mmCIF 文件的底层库。第二层是深度学习框架层核心是 JAX 和 Haiku。JAX 是 AlphaFold3 的算力引擎Haiku 是 DeepMind 自己的神经网络库。第三层是化学结构相关包比如 ml_collections、dm-tree、mrcfile、chemenv 等这些负责处理配体、小分子和电子密度文件。我的安装顺序是pip install --upgrade pip pip install numpy scipy pandas biopython gemmi pip install jax[cuda12] pip install -e .其中-e .会读取项目根目录下的 pyproject.toml把 AlphaFold3 自身作为包装进当前环境并且自动解析剩余依赖。这里有个关键点jax[cuda12]里的cuda12是指 JAX 的 CUDA 插件版本它要求你的 NVIDIA 驱动版本足够新具体可以用nvidia-smi查看驱动支持的 CUDA 版本。如果驱动太老JAX 会直接跑 CPU 模式GPU 等于白装了。3. AlphaFold3 源码与数据库准备3.1 看懂源码目录结构源码拉下来以后不要急着运行先花十分钟把目录结构看一遍。AlphaFold3 的仓库根目录下有几个关键文件和目录run_alfold3.py或者类似的入口脚本所有预测任务都是从这里启动。src/核心源码AlphaFold3 的模型结构、数据处理逻辑都在这里面。testdata/官方提供的测试数据包括示例 JSON 和预期输出可以用来验证安装是否成功。docker/官方 Docker 配置。我不太推荐大家走 Docker 路线原因很简单Docker 镜像太大构建过程对国内网络不友好而且会把 GPU 透传和文件挂载这些事搞复杂。conda 方式是直接在物理系统里跑调试起来更方便。这里建议大家在alphafold3目录下新建两个子目录一个叫input一个叫output后面所有任务文件都放进去避免把临时文件堆在源码目录里。这是我踩过坑之后养成的习惯——AlphaFold3 运行时会生成大量中间文件不分开的话整个目录会变得非常乱。3.2 模型参数与数据库下载AlphaFold3 的模型参数不在 GitHub 仓库里需要通过官方渠道申请。申请通过后你会拿到一个下载链接下载下来是一个目录里面包含模型权重文件。把目录放到一个固定位置比如D:\alphafold3_models这个路径后面要用--model_dir参数指向它。数据库部分AlphaFold3 的数据库列表在源码里有对应的下载脚本。全量下载很费时间我的建议是先明确你要预测什么体系只下载必需的数据库。如果你只做蛋白质结构预测核心库是 BFD、UniRef90、UniRef30、PDB 相关库如果要做蛋白-核酸复合物还要加 RNAcentral、RFAM 和 NT 库。下载完成后数据库目录结构要保持脚本默认的样子不要手动改文件名因为源码里的路径拼接逻辑是写死的。举个例子如果脚本预期的是databases/uniref90_2022_05/uniref90_2022_05.fasta你把 fasta 文件直接丢到databases/根目录运行时一定会报找不到文件。3.3 输入 JSON 的写法与格式AlphaFold3 的输入不是 FASTA 文件而是一个 JSON。这个 JSON 描述了你想要预测什么、序列是什么、需要几个模型种子、复合物的化学计量比。下面是一个最简单的蛋白单体预测示例{ name: my_first_af3, modelSeeds: [1, 2, 3], dialect: alphafold3, version: 1, sequences: [ { proteinChain: { sequence: MAAVPAAVRG, count: 1 } } ] }字段说明name任务名会作为输出文件名的前缀。modelSeeds随机种子列表有几个种子就跑几个模型结果取平均。想快就写一个[1]。dialect固定写alphafold3。version固定写1。sequences序列数组可以同时放蛋白链、DNA链、RNA链、配体等。proteinChain下的sequence是氨基酸序列count是化学计量数比如同源二聚体就写 2。如果要加配体比如一个小分子药物和蛋白共聚可以这样写{ ligand: { smiles: CC1C(C(O)N(N1C)C2CCCCC2)CC3CCCCC3 } }配体用 SMILES 表示AlphaFold3 会自动计算它的拓扑和立体化学特征。这个功能是 AlphaFold3 相对 AlphaFold2 的一大升级它把蛋白质、核酸、小分子统一到了一个框架里。3.4 GPU 环境验证装完先自测依赖装完、参数和数据库就位之前最好先做一次 GPU 自检。打开 Python 交互环境执行import jax print(jax.devices())如果输出类似[CudaDevice(id0)]说明 JAX 正确识别了 GPU。如果输出的是[CpuDevice(id0)]说明 JAX 没有加载 CUDA 插件最常见的两个原因一是装成了 CPU 版 JAX二是驱动版本和cuda12插件不匹配。再测一下显存占用策略。JAX 默认会预分配大部分显存这会导致一个现象程序启动时显存立刻被占满看起来像内存泄漏其实是 JAX 正常行为。建议设置环境变量export XLA_PYTHON_CLIENT_PREALLOCATEfalse export XLA_PYTHON_CLIENT_MEM_FRACTION.8Windows 下用setx或者直接在运行命令前加环境变量都行。限制 JAX 最多使用 80% 显存能避免和显存里的其他程序抢资源。4. 运行第一个预测与常见报错排查4.1 命令参数与运行过程一切就绪后运行第一个预测python run_alphafold.py \ --json_pathinput/my_first_af3.json \ --model_dirD:/alphafold3_models \ --output_diroutput \ --flash_attention_implementationxla参数含义--json_path刚才写的输入 JSON 路径。--model_dir模型参数目录。--output_dir输出目录。--flash_attention_implementationFlash Attention 的实现方式xla是官方闭源版可用的实现之一在部分 GPU 上能显著加速。运行后会经历几个阶段。首先是日志输出提示 “Running MSA”这是 Jackhmmer 在做多序列比对也是第一个耗时瓶颈。数据库越大、序列越长这一步越慢。短肽的话几分钟长序列可能几个小时。然后是Running structure module这是模型推理阶段GPU 开始满载。最后是输出文件生成。输出目录下会看到以name命名的 PDB 文件预测的三维结构。summary_confidences.json整体置信度。以name命名的confidences.json残基级别和模块级别的置信度适合做进一步分析。首次运行建议直接用官方 testdata 目录里的 JSON把期望输出和实际输出对比一下确认全流程没问题再跑自己的序列。4.2 conda activate 失效、PATH 异常这些环境问题本地部署里大约有一半的时间不是花在 AlphaFold3 本身而是花在环境问题上。最常见的还是 conda activate 失效分两种情况第一种是CondaError: Run conda init before conda activate。这种基本是 conda 初始化没做按前面说的conda init走一遍即可。第二种是激活后python还是系统 Python。这种在 Windows PowerShell 下尤其常见原因是执行策略限制或 PATH 顺序问题。我个人建议直接在 Anaconda PromptMiniconda 安装后会自带这个终端里操作它能保证 PATH 正确。如果你习惯用 VS Code 或 PyCharm 的终端那就在终端设置里把默认 shell 切到 conda 的环境终端。还有个小坑不要把 conda 环境目录手动复制到别的机器上跨平台会直接崩。正确做法是用conda env export environment.yml导出再在新机器conda env create -f environment.yml。4.3 CUDA out of memory显存不够怎么办如果你用的卡不是 40GB 以上的专业卡跑复杂体系大概率会遇到RuntimeError: CUDA out of memory.碰到爆显存先不要急着加内存按下面的优先级调第一降低modelSeeds数量。每个种子都要单独推理种子从 5 个减到 1 个显存占用和耗时几乎线性下降。第二缩短序列长度。这个最直接。AlphaFold3 的显存开销和序列长度不是线性关系序列越长注意力机制的显存开销越大。如果必须预测全长蛋白可以考虑把结构域拆开分别预测再用分子对接或组装工具拼回去。第三设置XLA_PYTHON_CLIENT_PREALLOCATEfalse让显存按需分配。不设置这个JAX 会在启动时就霸占几乎所有可用显存哪怕后续用不到。第四降低--num_recycles。recycle 是结构重排次数默认值 10 次左右降到 3 次能明显省显存代价是精度略降。显存问题本质上是个取舍问题批量、速度、精度三者不可兼得。我的经验是“先短后长、先少后多”小体系验证流程再逐步上规模。4.4 数据库路径与稳定性的高频问题把部署过程中遇到的高频问题整理成一张表方便你对照排查现象原因解决办法日志提示找不到uniref90或bfd文件数据库路径不对或子目录结构缺失检查数据库目录确保 fasta 文件在脚本预期的子目录下运行到 Jackhmmer 阶段长时间卡住MSA 搜索本身很慢或数据库在机械硬盘上首次搜索耐心等待数据库放到 SSD先跑短序列提示KeyError: weights或参数加载失败模型参数目录指向错误确认--model_dir指向包含权重文件的目录而不是外层根目录JAX 使用 CPU 而不是 GPU未安装jax[cuda12]或驱动版本过老重新安装jax[cuda12]并升级 NVIDIA 驱动程序崩溃但无明确报错内存不足或临时目录空间不足检查系统内存确保输出目录所在磁盘有 20GB 以上剩余空间最后一条尤其容易被忽略。AlphaFold3 会写大量临时文件如果输出目录所在磁盘空间不足程序会以各种莫名其妙的姿势崩溃而且日志不一定直接告诉你“磁盘满了”。5. 部署完成之后的几个实用建议5.1 环境想挪到 D 盘怎么办很多人把 conda 默认环境装在 C 盘越用越大最后 C 盘红了。环境迁移的正确姿势是不要手动拖动envs目录因为里面很多脚本记录的是绝对路径直接移动会导致环境失效。推荐做法是在 D 盘直接创建前缀环境conda create --prefix D:/conda_envs/af3 python3.11 -y激活时用完整路径conda activate D:/conda_envs/af3如果你已经建好了af3环境在 C 盘想迁移稳妥的路子是导出当前环境的 package 列表在 D 盘重建。命令如下conda env export -n af3 af3_environment.yml conda env create --prefix D:/conda_envs/af3 -f af3_environment.yml这样重建虽然要重新下载一遍依赖包但路径指向正确之后不会再出一堆“找不到 Python”之类的怪病。5.2 在 PyCharm 里关联 conda 环境如果你习惯用 PyCharm 写 Python可以把刚才建好的af3环境配置进去。打开 Settings找到 Project - Python Interpreter点击 Add Interpreter - Add Local Interpreter选择 Conda Environment然后 Existing environment在 interpreter 路径里选择af3环境下的 python 可执行文件。Windows 路径一般是C:\Users\你的用户名\miniconda3\envs\af3\python.exe如果用的是--prefix方式创建在 D 盘就选D:\conda_envs\af3\python.exe配置完成后PyCharm 里的终端会自动激活这个环境而且代码补全、包管理器都会直接指向 af3省去手动敲conda activate的麻烦。5.3 关于 AlphaFold3 使用的合规提醒AlphaFold3 的本地代码是开源的但模型参数文件的获取和使用有条件。简单来说模型参数需要向官方申请申请时需要说明使用目的使用过程要遵守条款中的非商业约束并且在发表成果时按规定引用相关论文。这一点在 AlphaFold2 时代是同样的套路。我的建议是如果你是高校或科研机构可以用机构邮箱申请如果是在企业做商业应用先咨询法务。技术本身是中性的但参数文件的授权边界是明确的。个人体会最深的反而是“部署成功只是开始”。AlphaFold3 跑通之后你会开始关心 MSA 质量、模型置信度、不同 seed 的差异、recycle 次数对结果的影响——这些才是真正决定预测结果能不能用的关键。本地部署的最大价值不是让你拥有一个“能跑的 AlphaFold3”而是让你有能力对它的每一个环节进行控制和观察。最后分享一个小技巧跑正式任务之前先在 testdata 上跑一遍确认输出文件中的summary_confidences.json里各项数值都在合理区间。如果官方测试数据都能跑出异常结果那大概率不是数据问题而是环境或参数配置出了问题。这个习惯帮我省了不少排查时间建议你也试试。