5.2 环境与复现：从 conda 到 WSL 的工程实践

5.2.1 依赖地狱的机理：三重耦合

同一段代码，上月能跑，重装机器后报错；换一台工作站，指标差出零点几个百分点。多数时候代码无辜，是环境变了。分子机器学习的工具栈比一般 Python 项目更脆，根源在于它同时踩着三层彼此咬合的约束，任何一层滑动都会牵动其余两层。把约束本身看清，依赖地狱(dependency hell)就从玄学变成可推理的对象。

第一重：二进制扩展与解释器的 ABI。RDKit 的本体是一个庞大的 C++ 库，Python 里 import 到的只是绑定层。绑定层编译时就与解释器的应用二进制接口(application binary interface, ABI)锁死：对象布局、调用约定、错误处理都按特定 CPython 版本敲定，而 CPython 不承诺大版本之间的 ABI 兼容。3.10 下编译的扩展放进 3.12 解释器，import 当即崩溃。发行方因此按“Python 版本 × 平台”逐个发布轮子(wheel)，文件名里的 cp310、cp312 就是 ABI 记号。“升了 Python 之后 RDKit 装不上”，报错说是找不到版本，病根在标签不匹配。

第二重：框架生态的三角约束。深度框架不是孤立的包：torch 的每个版本按 CUDA 工具链分别构建，轮子带 cu118、cu126 一类的构建标签；torch-scatter、torch-sparse 这些 C++/CUDA 算子包又要针对特定 torch 构建编译，官方按“torch 版本 + CUDA 构建”成对发布配对轮子；三角的第三条边是显卡驱动，它决定本机可用的 CUDA 上限。装错配对有两种典型症状：pip 找不到匹配轮子，退回源码编译，动辄半小时且常失败；或者装得上，import 时以 undefined symbol 告终。

第三重：Python 版本本身的时间差。老项目冻结在 3.9/3.10——TorchDrug 的官方兼容上限即 Python 3.10；新库只发 3.12+ 的轮子。生态的新旧两个时代各自收缩，想用一个解释器同时伺候 2022 年的冻结栈与 2026 年的新库，约束无解，只剩隔离一条路。三重约束叠出的可行域画在图 5.2-1 里：行是解释器，列是框架，格内还要再过一遍 CUDA 配对。

三重约束的相对位置值得记牢：ABI 是硬边界，撞上即崩，没有协商余地；CUDA 配对介于软硬之间，查表即得却常被跳过；Python 版本时间差是慢变量，一年只移动一格，却把冻结项目一步步逼进角落。排障时按这个次序排查，比对着报错倒着猜快得多。

于是可以回答那个经典问题：pip 为什么会“解出”一个运行时才崩的组合。pip 的回溯式解析器（20.3 起）只在各包元数据声明的版本范围里搜索：它读得到“deepchem 声明支持哪个区间的 tensorflow”，读不到“这个轮子的 cp 标签是否与当前解释器一致”“+cu126 的构建是否与驱动相容”“torch-scatter 该配哪个 torch”——后三者是环境级属性，写在文档里，不写在 install_requires 里。解析器交出的组合在元数据层面自洽，崩在元数据之外。另一类失败来得更早：约束交叉时回溯搜索组合爆炸，终端停在 resolving 上数小时不动（pip 文档对此有专门章节）。这不是 pip 愚笨，是问题本身越出了它的视野；视野之外的部分，只能靠人来锁定。

最后把这件事放到可复现性(reproducibility)的账上。实验输出是四个输入的函数：

5.2.2 隔离与锁定：一实验一环境

看清机理，对策只有两条：让约束不互相接触（隔离），让每次接触都留档（锁定）。环境隔离(environment isolation)的粒度是实验，不是机器。共享环境里一次顺手升级，等于同时改写所有依赖该包的实验，而这类改动不出现在任何一次代码提交里，事后无从追溯。一实验一环境的代价只是磁盘上几个 GB，换来的却是：每个实验的输入清单闭包完整，式 (5.2-1) 里的“环境”一项从此可以指名道姓。

隔离之上是分层。分子栈的习惯分工：conda 或 mamba 管二进制层——Python 解释器本体、RDKit 及其 C++ 依赖、CUDA toolkit；pip 管纯 Python 层——PyPI 上的包。分工的依据是求解器的视野：conda 的包配方携带非 Python 依赖，能在同一次求解里一并敲定 Python 版本；pip 只见 PyPI。两条规则把分层做稳：其一，conda 先定解释器与重二进制，随后才轮到 pip 装其余；其二，pip 装过之后不再回头 conda install——两个求解器交替操作同一环境，会互相覆盖对方的决议。conda 的求解器在大环境上偏慢，社区普遍改用同接口的 mamba，这只是速度差别，原则不变。通道也是决策：conda 通道(channel)中以 conda-forge 为科学计算的主通道，混用多个通道等于给求解器添变量，锁定时应写明。

锁定有三个层次，精确度递增，见表 5.2-1。宽松文件声明意图（要什么），精确文件记录事实（装了什么），environment.yml 连同通道与解释器版本一并入档（在哪种地基上装）。三者都放进版本库，与代码同过评审：复现一次实验，先复现它的环境。

只锁 requirements.txt 不锁后两者，等于只留下菜名不留配方：一个月后重新求解，解析器在已经平移的可行域里选出另一组版本，结果随之漂移，而代码一行未改。Wilson et al.（2017）把“软件环境入库”列为六条最低限度实践之一，理由正在于此——锁定文件(lock file)是实验记录的一部分，与原始数据同级。三份文件的分工可用一句话记住：requirements.txt 给人读，requirements-lock.txt 给机器读，environment.yml 给两年后的自己读。

锁定的极端形态是容器：把解释器、二进制层与包目录整体打成镜像，环境退化为一个内容哈希。课程规模用不到这一步，但原理一脉相承——复现的单位越大，锁定的层级越高；反过来，六周课程里三份文本文件已经够用，工具的重量不必超过问题本身。

5.2.3 本书的三套环境：主力、沙箱与现代栈

按上述原则，本书全程维护三套互不借贷的环境，口径汇总于表 5.2-2，隔离结构见图 5.2-2。三套环境对应三个时代的主力栈：现役主力、冻结考古、前沿图学习。

命名也是文档的一部分：mml-main 标角色，torchdrug-arch 标时代，pyg-lab 标用途。环境名一旦写进论文与实验笔记，就不再只是本地习惯；含糊的名字（env、test、new2）等于把式 (5.2-1) 的一个自变量匿名化，事后无从对账。

主力环境 mml-main 跑第 1–3 章的一切：RDKit 2026.03 系列（2026-08 已迭代至 2026.03.5）三大平台轮子齐备，pip 直装；DeepChem 稳定版停在 2.8.0（2024-04），nightly 以 2.8.1.dev 持续构建，本书锁 2.8.0 而不追 nightly——课程要的是可复现，不是最新。Python 取 3.11：为这批 2024 年前后的轮子留足覆盖面。

# 主力环境：解释器与二进制层先定，其余交给 pip
conda create -n mml-main python=3.11 -y
conda activate mml-main
pip install "rdkit==2026.*" deepchem==2.8.0

沙箱 torchdrug-arch 是刻意为之的考古环境。TorchDrug 冻结于 v0.2.1（约 2022 年），官方兼容上限 Python 3.10、torch ≤ 2.0；第 4 章的生成实验全部在此复现。冻结环境(frozen environment)的含义是三条纪律：版本整体钉死、不再升级、修复方式是“再冻一层”而不是顺手升级任何一个包。冻结项目要配冻结环境——用 2026 年的 torch 伺候 2022 年的代码，既跑不动，也失掉了复现的原义。

# 冻结沙箱：整层一起钉死，TorchDrug 停在 2022 年的栈上
conda create -n torchdrug-arch python=3.10 -y
conda activate torchdrug-arch
pip install torch==2.0.1 torchdrug==0.2.1

现代图学习环境 pyg-lab 面向 5.1 节的 PyG 生态与新课题：新 Python、最新 torch。这里的习惯动作是先查配对表、再装包：torch-scatter 一类扩展轮子按“torch 版本＋CUDA 构建”成对发布，装之前先到官方配对索引核对组合，再按同一组合安装。PyG 自 2.3 起核心包已纯 Python 化，直接 pip 可装；扩展算子包可选，但图规模一大便值得配上。

# 现代图学习：先锁 torch 与 CUDA 构建，再按配对表装扩展轮子
pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu126
pip install torch_geometric
pip install torch-scatter -f https://data.pyg.org/whl/torch-2.7.1+cu126.html

5.2.4 Windows 用户的现实路径：WSL2 的角色

分子机器学习工具链的一等公民平台是 Linux：mamba 的二进制包、torch 的 CUDA 轮子、PyG 的配对轮子都先到 Linux，官方教程与 CI 也以 Ubuntu 为默认口径。Windows 用户的省力路线不是绕开 Linux，而是把它装进 Windows：WSL2(Windows Subsystem for Linux 2)在轻量虚拟机里运行一个完整发行版（社区默认 Ubuntu），与 Windows 并存互通，本书三套环境在其上与原生 Linux 无异。GPU 也不需要双份：CUDA on WSL 把 Windows 侧的 NVIDIA 驱动透传进 WSL2，WSLg 直接运行 Linux 图形程序，训练与推理可以整个留在 WSL2 内完成。

原生 Windows 并非总是不够用，边界在二进制层的厚度。纯 RDKit 场景——描述符计算、子结构检索、SMILES 批处理、教学练习——官方为 Windows 发布平台轮子，pip 即装即用，不必动用 WSL。一旦进入深度训练、需要 PyG 配对轮子或 mamba 的二进制包，生态覆盖明显偏向 Linux，此时迁入 WSL2 是收益最高的动作。判断口诀只有一句：依赖里出现“需要配对的二进制”时，就该换到 Linux 侧。

WSL2 内部的纪律与原生 Linux 相同：选一个 LTS 发行版（Ubuntu LTS 为主），系统包交给 apt，Python 栈交给 conda 与 pip，两侧不越界；永远不用 sudo 安装 Python 包——那会把包装进系统解释器，一处越界，整台“机器”的隔离根基即告失效。

版本口径随时间平移，本节全部版本号以 2026 年 8 月核实为准。半年后重读，先把三套环境的锚点版本逐一核对再动手——这个动作本身，就是 5.2.5 节清单的第 0 项。

5.2.5 复现清单：把环境纳入实验记录

复现的语义先立清楚：同代码、同数据、同环境、同种子，得到同一结果。跨硬件时逐位一致并不总可达——GPU 并行归约的浮点累加次序依实现而定——退一档的要求是统计一致：多次重启的结果分布重合。固定种子要覆盖四处：Python 的 random、numpy、torch 的 CPU 与 GPU 两侧，外加 DataLoader 工作进程的种子；漏掉任何一处，第 4 章的生成实验就会在重启后给出不同的分子。

CUDA 的确定性(determinism)开关有其局限，须当作已知边界写进实验记录。torch.use_deterministic_algorithms(True) 能压住大部分非确定源，但个别算子没有确定性实现，开关一开反而报错，此时要么换计算路径，要么显式接受非确定并在文档声明；cuDNN 的自动基准选择也是常被忽略的非确定来源。确定性不是开关一打就有的默认属性，而是一条要么满足、要么注明例外的规格。

种子与确定性解决“同机重启一致”，锁定解决“异机重建一致”，两者合起来才是完整意义的复现。只做前者，论文数值在自己机器上稳定，别人却重建不出；审稿人遇到的失败，多是后一种。

数据同样有版本。MoleculeNet 的固定划分由划分脚本与种子决定，DeepChem 加载器按 splitter 类型与 seed 复现同一划分，记录时三者缺一不可；ChEMBL 每个 release 的化合物集合都不同，引用必须带版本号（如 ChEMBL 33），第 3 章的口径在此落地为操作。配套动作是数据清单：来源、下载日期、文件哈希一并入库。环境侧照 5.2.2 锁定三层文件；结果侧每个运行目录记三项哈希——代码提交、数据清单、环境文件——做到结果可反查输入，代码、数据、结果三对应。

清单的最后一项是一次性全流程验证：清空缓存（__pycache__、数据缓存目录），在新目录从锁定文件重建环境，从零跑通全流程。这是复现的验收测试，也常是发现隐藏随机性与隐式本地依赖的唯一机会。它之所以放在最后，因为前六项任何一处不实，这一步必然失败——失败在这里反而是收获：问题被拦在发表之前。

复现危机并不只在环境。Kapoor 与 Narayanan 清点了 17 个领域、294 篇受数据泄漏影响的论文，指出泄漏与不可复现在方法学上同根（Kapoor & Narayanan, 2023）；3.8 节已给出泄漏的分类学，此处只需记住：环境清单盖住的是“机器知道什么”，泄漏审查盖住的是“模型不该知道什么”，两份清单都过，复现才有意义。

回看式 (5.2-1)：本节的全部操作——隔离、分层、锁定、清单——目的只有一个，把四个自变量逐一变成显式输入。环境这项做完之后，剩下的漂移来源只有硬件差异与算法非确定性，前者可以注明，后者已经写进实验记录；至此，5.3 节的陷阱清单里再没有“环境”这一类，可以腾出手对付更要紧的数据问题。