5.1 图学习生态版图：PyG、DGL 与 Graphium

5.1.1 分层看生态：一座四层建筑

这些工具的职责既有分工，也有重叠。RDKit 提供分子解析与化学信息学操作；PyG 和 DGL 提供图数据结构与计算接口；DeepChem、Graphium 和 TorchDrug 进一步组织特定任务的模型与训练流程。下图按主要职责分层，便于理解依赖关系，但并不表示每个应用库都必须依次调用所有下层项目。

RDKit 是化学信息学领域广泛使用的开源工具，可用于 SMILES 与 MolBlock 解析、价态检查、分子标准化、描述符计算、SMARTS 匹配和骨架提取。许多分子机器学习流程通过它构建输入图，但具体清洗规则仍由任务决定。第 2 章介绍这些操作；5.1.5 节再说明 datamol 提供的便捷封装。

PyG 与 DGL 主要提供图数据结构和图上的张量计算。对图神经网络(graph neural network, GNN)而言，常用功能包括消息传递(message passing)、变长图批处理，以及图级读出函数(readout)。现成算子可以减少实现工作；需要新运算时，也可以扩展库接口或直接编写张量代码。底层接口影响实现成本，但不构成上层算法表达能力的绝对边界。

DeepChem、Graphium 和 TorchDrug 都提供面向分子任务的应用接口，但支持的任务与抽象范围不同。它们可能封装数据加载、特征化、训练、评估或预训练权重中的若干环节。蛋白质工程、反应预测和材料筛选还有专门工具，选择时应逐项检查任务支持与依赖，不能仅凭所处层级判断。

5.1.2 PyG 与 DGL：薄抽象与厚抽象

PyG 的 MessagePassing 基类允许分别定义消息、聚合和节点更新，再由 propagate 调用沿边传播（Fey & Lenssen, 2019）。它与 3.5 节的消息传递框架相对应。Data 用于存储节点、边和图级属性，Batch 组织多图批次；PyG 也提供数据集、采样和分布式相关工具。因此，可以说其核心消息传递接口便于直接实现公式，但不能把整个库等同于不管理容器或运行流程。

DGL 采用图中心(graph-centric)接口：DGLGraph 存储连接关系，ndata 与 edata 关联节点和边特征，update_all 组合消息函数与归约函数（Wang et al., 2019）。它也提供面向大图的分布式训练(distributed training)工具。后端、分布式组件和平台支持应以选定版本文档为准；这些功能不能仅由“厚抽象”一词推断。

两种库的多图批处理都把输入图组织成一张不连通的大图，并保留各图的归属信息。PyG 的 Batch继承 Data 或 HeteroData，提供 batch 向量，也支持通过 to_data_list 等接口还原单图。dgl.batch返回合并后的图，通过 batch_num_nodes 和 batch_num_edges 记录边界，并可用 dgl.unbatch 拆分。图 5.1-2 比较其接口表示，不能据此把一方描述为“只有张量、没有容器”。

两种批处理都需要正确偏移节点编号、拼接特征并保存图边界。实际选择应结合已有代码、所需算子、数据规模和团队熟悉程度；不能从“拼接”或“簿记”推导哪个库必然适合研究或生产。以下列出可用于比较的需求。

5.1.3 应用层分工：DeepChem 操场，Graphium 工业线

DeepChem 与 Graphium 都封装分子机器学习流程，但常用入口和任务重点不同。以下比较其公开功能，具体适用性仍需通过目标数据上的试运行判断。

DeepChem 提供较多教程、MoleculeNet 数据集入口和模型接口，适合学习从数据到评估的完整流程。本书按 2.8.0 接口展开；运行时应固定版本，并查阅官方发布记录。如果需要定制内部行为，应为数据处理与关键模型输出建立检查，升级后重新验证，而不应假定教程代码能直接跨版本运行。

Graphium由 datamol-io 组织发布，其公开接口包括分子特征化、GNN 结构、预训练模型和基于 PyTorch Lightning 的训练循环。它支持通过配置组织多项化学任务，可结合 3.7 节的多任务学习(multi-task learning)理解。Graphium 与 TorchDrug 的功能存在交集，但这不表示两者有官方继承关系。

3.7 节的 Tox21 示例用 12 个任务头共享表示，是一种多任务结构。更大规模的训练可以增加任务、分子和标签来源，但这些扩展需要分别评估。多保真学习(multi-fidelity learning)通常涉及精度或计算成本不同、且相互关联的信息源；把任意不同性质的量子标签和实验标签放在同一数据集中，并不自动构成有效的多保真模型。

预训练还可以形成供下游任务迁移的基础模型(foundation model)。Sypetkowski 等（2024）研究模型规模、数据量和预训练任务对分子 GNN 的影响，并报告 MolGPS 在所评估的 38 项下游任务中有 26 项超过论文所比较的既有最好结果，见原论文。这一结果支持在相应协议下研究规模效应，不能直接推广为所有任务都应优先采用大模型；从头训练与迁移学习仍应使用相同划分和预算进行比较。

5.1.4 TorchDrug 的历史定位与迁移

本书用 TorchDrug 0.2.1 展示性质预测与分子生成的任务接口。2026 年 9 月核对的官方安装文档声明 Python 3.7–3.10、PyTorch ≥ 1.8.0，没有给出 PyTorch 2.0 上限。文档范围、发行版本与仓库维护状态是不同信息，不能用版本号推断项目已永久停止维护。环境选择见 5.2 节。第 4 章所用算法也有原作者代码，但应逐个核对实现框架与训练设置。

跨库迁移可以复用分子图、消息传递、读出、损失和评估等概念，但实现需要逐项核对。原子编码、边方向、自环、归一化、批处理和默认训练参数的差异都可能改变结果。表 5.1-1 给出功能对应关系，作为迁移检查清单，而非接口可以直接替换的保证。

以批处理为例，TorchDrug 的 Molecule.pack 返回 PackedMolecule，PyG 的 DataLoader 可以返回 Batch。两者都提供合并图和归属信息；以下片段展示接口形态，假定 smiles 和相应模型已经定义，完整训练流程还需补充标签、损失与优化器。

# TorchDrug 0.2.1：分子打包与图编码器接口示例
from torchdrug import data, models
mols = [data.Molecule.from_smiles(text) for text in smiles]
batch = data.Molecule.pack(mols)  # 返回 PackedMolecule
encoder = models.GIN(batch.node_feature.shape[-1], hidden_dims=[64, 64])
output = encoder(batch, batch.node_feature.float())
graph_feature = output["graph_feature"]  # 任务预测还需读出后的预测头

# PyG：同一概念的形态——Data 单图，Batch 拼接
graphs = [smiles_to_data(s) for s in smiles]            # 每个分子一张 Data
loader = DataLoader(graphs, batch_size=32, shuffle=True)
batch = next(iter(loader))                              # collate 时拼成大图
pred = model(batch.x, batch.edge_index, batch.batch)    # batch 向量标记归属

TorchDrug与 PyG 都保留批次中的图边界。其模型调用约定不同：TorchDrug 的许多编码器接收图对象及节点输入，PyG 的自定义模型则可以接收节点张量、边索引和图归属。迁移除分子转换函数外，还可能涉及边特征、模型结构、池化、损失及评估，不能只改一个函数便假定数值等价。

5.1.5 数据周边：datamol 与 MoleculeNet 数据集

datamol 对 RDKit 的常用操作提供便捷封装，可用于分子标准化、片段处理和描述符计算。选择这类高层函数时仍需检查默认参数，因为去盐、互变异构体处理和立体化学保留方式会改变输入。Graphium 与 datamol 同在 datamol-io 组织，但是否采用相同预处理流程应由任务和复现要求决定。

数据集方面，MoleculeNet 家族（Wu et al., 2018）——ESOL、FreeSolv、Lipophilicity、BBBP、Tox21、SIDER、HIV、BACE——是分子性质预测的通用货币。在 PyG 生态，torch_geometric.datasets.MoleculeNet 直接提供加载接口，数据文件历史上经 DeepChem 渠道分发。换言之，三个库在同一批数据上汇合，第 3 层的应用库与第 2 层的算子库在数据通道上本就互通。

一句提醒：同一数据集在不同库里的默认划分、特征化与单位口径可能不同，跨库比较数字时要回到原始文献核对协议。第 3 章反复强调的评估纪律——划分方式先于模型——在生态问题上原样成立。

5.1.6 选库原则：问题定义先于工具

熟悉一个框架有助于提高实现效率，但也可能形成框架忠诚度(framework loyalty)，使工具约定被误认为方法要求。本书以 RDKit、DeepChem 和 TorchDrug 的实例解释原理，最后讨论生态与迁移，是为了将概念、数据协议和实现细节区分开来。5.3 节将这些原则整理为可执行的学习与复现检查。