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

5.2.1 依赖兼容性：解释器、框架与扩展

代码在重建环境后出现导入错误，或者同一实验在另一台机器上产生不同指标，都需要同时检查代码、数据和运行环境。分子机器学习常用 C++ 化学信息学库与深度学习扩展，因此除了 Python 包版本，还涉及二进制接口和设备运行时。所谓依赖地狱(dependency hell)，通常指多组依赖约束难以同时满足，或声明的兼容范围不足以描述实际运行条件；定位问题应从具体的约束与错误证据出发。

第一类约束来自解释器与二进制扩展。RDKit 的许多核心功能由 C++ 实现，Python 绑定需要符合解释器的应用二进制接口(application binary interface, ABI)。普通 CPython 扩展往往针对特定次版本编译；3.10 与 3.12 是 Python 3 的两个次版本，不能直接假定其扩展兼容。采用 Limited API 和 Stable ABI 的扩展则可在规定范围内跨次版本使用。发行方通过轮子(wheel)提供预构建分发包，安装器依据标签选择适合当前解释器与平台的制品。

第二类约束来自框架、算子扩展与设备。PyTorch 的 CPU 构建和各 CUDA 构建不同；torch-scatter、torch-cluster 等扩展需要与相应 PyTorch 及 CUDA 构建匹配。运行 GPU 程序还要求驱动、运行时与 GPU 架构兼容。预构建包所需的 CUDA 运行库与本机用于编译的 CUDA toolkit 应分开核对：只有在源码构建或即时编译 CUDA 扩展时，才需要进一步检查编译器和 toolkit。找不到合适轮子时，pip 在存在源码包且配置允许的情况下可能尝试构建；二进制错配则可能表现为 undefined symbol 等导入错误。

第三类约束来自各项目声明和测试的版本范围。TorchDrug 安装文档写明 Python 3.7–3.10、PyTorch ≥ 1.8.0，并未声明 PyTorch ≤ 2.0；这也不等于任意后续 PyTorch 版本都经过验证。是否能与另一个项目共用环境，应检查两者的具体版本、扩展制品和测试结果，不能仅按发布时间判断。图 5.2-1 用少量版本组合说明环境选择过程，其中标记表示本节示例的选择状态，不构成官方支持矩阵。

排障时可依次记录 Python 版本与平台、安装包及其来源、PyTorch 版本与 CUDA 构建、GPU 驱动和完整错误信息，再区分安装阶段的候选缺失与运行阶段的加载或计算失败。python -m pip debug --verbose 可辅助查看支持的轮子标签；python -m pip check 可检查已安装包的声明依赖，但不能替代导入、算子和训练测试。

pip 的回溯解析(backtracking resolution)会根据依赖元数据搜索版本组合，同时考虑 Python 要求、环境标记及兼容轮子。它能够处理版本中的本地构建标识，但不会据此完整验证 GPU 驱动或执行所有算子。如果包未充分声明二进制配对要求，求解通过后仍可能发生运行错误；约束复杂时，回溯也可能耗时较长，或明确报告无解。应根据日志缩小候选范围、提供经过核验的约束和正确制品来源，随后执行运行测试。

环境管理也属于可复现性(reproducibility)设计。实验结果所依赖的主要因素可概括为：

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

环境隔离(environment isolation)使不同实验使用独立的解释器与包目录，减少一次依赖更新对其他实验的影响。“一实验一环境”可理解为每套需要独立重建的依赖配置对应一个环境；共享同一已验证配置的实验也可引用相同环境规格。环境仍依赖宿主系统、驱动和外部文件，因此隔离本身不保证复现，也不是完整的系统隔离。

conda 或 mamba 可管理解释器及 Python、非 Python 依赖；pip 则在已有解释器中安装 Python 分发包，包括纯 Python 包和二进制轮子，来源也不限于 PyPI。混用时应先确定 conda 通道、解释器与拟由 conda 管理的包，再用环境内的 pip 安装其余依赖。后续若需修改 conda 部分，通常应更新规格并重建环境，避免两个包管理器反复替换同名文件。conda 通道(channel)是包的发布来源；使用 conda-forge 等通道时，应记录通道顺序、优先级和平台，不能仅保留包名。

环境记录应区分依赖规格、已安装版本快照与制品锁定，见表 5.2-1。文件名不决定精确度：requirements.txt 可以包含宽松约束，也可以列出精确版本；environment.yml 既可手写，也可由工具导出。应检查实际内容及生成方式，并将其与代码一起纳入版本管理。

pip freeze 报告当前安装状态，不执行新的依赖求解，也不自动生成完整的锁定文件(lock file)。若要求精确重建，应进一步固定传递依赖、制品来源和哈希，并使用安装器的哈希校验；conda 环境可另存 conda list --explicit 的同平台制品清单。显式清单不代替 pip 部分的记录。对同时出现在 conda 导出与 pip 快照中的包，应注明由谁安装，避免重建时无意重复覆盖。最后在新环境中实际重建，才能检查记录是否充分。

容器可以保存更多用户态依赖。使用镜像摘要引用具体镜像，并保留构建文件，有助于追踪运行条件；但宿主内核、GPU 驱动、硬件和外部数据通常仍在镜像之外。是否采用容器，应由部署方式、协作规模和复现目标决定，不能把镜像摘要等同于实验全部输入。

5.2.3 三套示例环境：基础分析、历史复现与图学习

表 5.2-2 按用途给出三套环境的配置起点，图 5.2-2 说明它们的隔离关系。以下命令假设已安装并初始化 conda，使用全新且未被占用的环境名；为统一二进制条件，以 Linux x86_64 或 WSL2 中的 Ubuntu 22.04/24.04 为示例平台。这些命令尚不构成全书实验的已验证锁定文件：安装后应补齐具体模型所需依赖，完成最小训练与评估，再导出完整记录。

环境名用于标识用途，版本文件用于标识实际配置。实验笔记中应同时记录环境名称、规格文件版本、平台和验证任务；只记录 mml-main 这样的名称，无法区分后续重建或修订得到的不同环境。

mml-main 选用 Python 3.11，符合 DeepChem 2.8.0 的 Python 声明范围。RDKit 2026.3.5 提供该解释器的 Linux x86_64 轮子，要求 glibc 2.28 或更高版本。DeepChem 主包安装并不自动提供所有可选深度学习后端；例如使用依赖 TensorFlow、PyTorch 或 JAX 的模型时，还需按模型文档选择对应版本。基础导入通过后，应至少运行一次所需的特征提取、数据划分和模型拟合。

# Linux x86_64 / WSL2：基础配置示例，尚未锁定全部传递依赖
conda create -n mml-main --override-channels -c conda-forge python=3.11 pip -y
conda activate mml-main
python -m pip install rdkit==2026.3.5 deepchem==2.8.0
python -m pip check
python -c "from rdkit import Chem; import deepchem as dc; assert Chem.MolFromSmiles('CCO') is not None; print(dc.__version__)"

torchdrug-arch 用于保留可追踪的历史实现。TorchDrug 0.2.1 发布于 2023 年 7 月，其安装文档未给出 PyTorch 2.0 上限；下例采用 2.0.1 CPU 版，只是一项便于说明扩展配对的选择。配对索引中，PyTorch 2.0.* 对应目录名 torch-2.0.0+cpu.html。旧 RDKit 扩展使用 NumPy 1.x 配置，并安装 TorchDrug 声明依赖的 rdkit-pypi，同一环境中不要再并装提供同名导入模块的 rdkit 分发包。TorchDrug 的部分功能会即时编译 C++ 扩展，运行前还应准备兼容的 C++ 编译器；下例的 CPU 配置不要求 CUDA toolkit。

# Linux x86_64 / WSL2，已有可用 C++ 编译器；CPU 配置起点
conda create -n torchdrug-arch --override-channels -c conda-forge python=3.10 pip -y
conda activate torchdrug-arch
python -m pip install numpy==1.23.5 scipy==1.10.1 setuptools==68.2.2 rdkit-pypi==2022.9.5
python -m pip install torch==2.0.1 --index-url https://download.pytorch.org/whl/cpu
python -m pip install torch-scatter==2.1.2+pt20cpu torch-cluster==1.6.3+pt20cpu --no-index -f https://data.pyg.org/whl/torch-2.0.0+cpu.html
python -m pip install torchdrug==0.2.1
python -m pip check
python -c "import torch, torch_scatter, torch_cluster; from torchdrug import data; print(torch.__version__, torch.version.cuda); print(data.Molecule.from_smiles('CCO'))"

上例固定了关键旧依赖和构建工具，但其余传递依赖仍需求解；这些选择既不是原论文的完整环境，也不保证第 4 章全部工作负载通过。若改用 GPU，应同时更换 PyTorch 构建和扩展索引，并核对驱动及即时编译所需的 CUDA toolkit。完成目标任务验证后，把完整版本、构建与测试记录保存为冻结环境(frozen environment)。修订时保留原记录，建立新版本环境并比较结果。

pyg-lab 以 PyTorch 2.7.1 的 CUDA 12.6 构建为例，需要支持该构建的 NVIDIA GPU 与驱动。PyG 基础用法可不安装额外的 C++/CUDA 扩展，具体算子、采样器或性能需求决定是否补充。若需要 torch-scatter，PyTorch 2.7.* 对应的官方扩展目录是 torch-2.7.0+cu126.html，其中的 2.7.0 不应机械替换为 2.7.1。没有符合条件的 GPU 时，可将 PyTorch 索引与扩展构建同时改为 CPU，并相应调整设备测试。

# Linux x86_64 / WSL2，已具备兼容 CUDA 12.6 构建的 NVIDIA 驱动与 GPU
conda create -n pyg-lab --override-channels -c conda-forge python=3.12 pip -y
conda activate pyg-lab
python -m pip install torch==2.7.1 --index-url https://download.pytorch.org/whl/cu126
python -m pip install torch_geometric==2.7.0
# 仅在目标程序需要 torch-scatter 时执行下一行
python -m pip install torch-scatter==2.1.2+pt27cu126 --no-index -f https://data.pyg.org/whl/torch-2.7.0+cu126.html
python -m pip check
python -c "import torch, torch_geometric; print(torch.__version__, torch.version.cuda); assert torch.cuda.is_available(); x = torch.ones(2, device='cuda'); print((x + x).cpu())"

5.2.4 Windows 与 WSL2：按工作负载选择平台

WSL2(Windows Subsystem for Linux 2)在轻量虚拟机中运行 Linux 内核和发行版，可用于依赖 Linux 脚本、系统库或编译工具的工作流。它与原生 Linux 的使用方式有许多共同点，但仍有虚拟化、文件系统和设备支持差异，环境测试需要注明平台。CUDA on WSL 通过 Windows 侧的 NVIDIA 驱动提供 GPU 支持；按 NVIDIA 文档配置时，不应在 WSL 内再安装 Linux 显示驱动。需要编译 CUDA 扩展时，应另选适合 WSL 的 toolkit 安装方式。WSLg 用于 Linux 图形应用，并非训练程序使用 GPU 的前提。

原生 Windows 也可用于 RDKit、PyTorch 和多种 PyG 工作负载，这些项目提供相应的 Windows 轮子或安装路径。是否使用 WSL2，应检查目标版本、CPU 架构、扩展编译条件、脚本和部署平台。TorchDrug 官方文档也包含 Windows 安装说明，其中即时编译需要额外配置 Visual Studio 工具链。已有工作负载在 Windows 上通过验证时，无需仅因它含二进制扩展而迁移。

在 WSL2 中，可由发行版包管理器安装系统依赖，由独立 conda 环境管理实验用 Python 栈。日常包安装使用当前环境的 python -m pip，避免以 sudo pip 修改系统解释器。编译器、环境变量、缓存路径及 WSL 版本也应记录，尤其是在与原生 Linux 结果比较时。

本节安装条件与示例版本依据 2026 年 9 月 5 日查阅的官方资料整理。重建历史实验时保留其原始规格；建立新环境时重新核对下载文件、依赖范围和设备要求，并注明检查日期。

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

复现应先约定比较标准：检查点或输出逐位一致、关键数值在给定容差内一致，或多次独立运行的指标满足预先规定的统计标准。PyTorch 不保证跨版本、平台或 CPU/GPU 的完全一致，即使使用相同种子。随机状态记录应覆盖实际调用的随机数生成器：Python random、NumPy 全局生成器及单独创建的 Generator、PyTorch 生成器，以及数据加载工作进程。torch.manual_seed 可设置 CPU 与 CUDA 的种子；DataLoader 的生成器和 worker_init_fn 则应结合加载逻辑配置。

确定性(determinism)需要在指定环境与操作范围内讨论。torch.use_deterministic_algorithms(True) 会为所覆盖的操作选用确定性实现，或在已知非确定且无替代实现时报告错误；它不控制所有第三方扩展与外部随机源。torch.backends.cudnn.benchmark = False 可固定卷积算法选择过程，但算法本身是否确定仍须检查；部分 CUDA 操作还需要按文档设置 CUBLAS_WORKSPACE_CONFIG。无法消除的非确定性应记录，并纳入结果比较方案。

固定种子、控制执行条件和记录依赖版本分别减少不同来源的差异，任何一项都不能单独保证复现。验证应覆盖当前机器上的重复运行与独立环境的重建，并保留失败日志。若改动软件或硬件，先重新运行基线，确认差异是否超过约定容差，再解释方法改进。

数据记录应包含版本、原始文件哈希、预处理代码与参数，以及实际训练、验证和测试集合的成员。MoleculeNet 加载流程中的划分器与种子只有在数据、顺序和实现一致等条件下才可能重现同一划分，因此直接保存划分文件更便于核验。使用 ChEMBL 等数据库时应注明具体 release。每个运行目录还应记录代码提交及未提交改动、配置、数据与划分清单、环境规格和平台信息，使结果能够追溯到对应输入。

全流程验证应在新目录和独立环境中进行，并指定单独的缓存位置或禁用复用已有预处理产物，保留原实验文件。先完成导入和关键算子检查，再从明确的数据版本运行最小训练、评估及所需的完整实验。重建成功说明该路径经过检验，但不证明所有平台、隐藏依赖或随机条件都已覆盖；对失败应保存日志并修订复现说明。

可重运行的程序也可能包含数据泄漏。Kapoor 与 Narayanan（2023）讨论了泄漏对机器学习科学结论的影响；3.8 节已介绍相关检查方法。环境验证关注计算过程能否重建，泄漏审查关注评价是否使用了不应获得的信息，两者都需要纳入实验审核。

式 (5.2-1) 提醒我们将影响结果的条件显式记录。环境隔离便于控制变更，版本与制品记录便于重建，任务测试则提供实际证据。进入 5.3 节的数据和方法陷阱检查时，仍应保留环境排查路径，不能仅凭完成清单就排除环境因素。