3.1 DeepChem 的三层抽象：数据、特征化、模型

3.1.1 实验的维度与关注点分离

分子机器学习的研究很少问"这个模型有多准"，更常问"换了某个选择之后还准不准"。把实验的自由度列出来——数据集、表示、模型、划分协议、指标——至少五个维度，常见的组合动辄上百。1.3 节已经证明，仅划分协议一项就能让同一模型在同一数据上的 AUC 相差数分；表示的维度（2.4 的描述符、2.5 的指纹）与模型的维度各自都值得单独考察。科学结论住在维度之间的差值里。

耦合实现的代价恰在此处。数据读取、特征构建、训练循环、指标计算挤在一个脚本里时，"换一个变量"意味着改动波及全部代码：换图特征要重写批组装，换骨架划分要重排样本索引，换指标要在好几处同步修改口径。任何一处遗漏都不报错，只是让对照实验悄悄退化成"两个变量同时改"的混合比较——结论在无声处失效。代码量倒在其次，错误传播才是要害。

软件工程对这个问题有现成答案：关注点分离(separation of concerns)。按职责把系统切成层，每层只对相邻层承诺一个窄接口，内部实现随意替换。DeepChem 把这条原则落到分子机器学习上，切成三层（Ramsundar et al., 2019）：数据层管样本与标签的存放、划分和逐批供给；特征化层管分子到模型输入的转换；模型层管训练、预测与评估。层与层之间的接口足够窄——数据层交出 (X, y, w) 三元组，特征化层决定其中 X 的形状，模型层只认形状、不问来历——任何一层的更换都坍缩成一处替换，其余两层原样复用。

分层的收益要落在试错速度上才算数。对研究者而言，"层"就是实验变量：控制其余层不动、只换一层的成本越低，单位时间能检验的假设越多。抽象不是工程的奢侈品，是科研的方法论——它把"我可以换什么"从勇气问题变成一行代码问题。表 3.1-1 概括三层的职责契约，图 3.1-1 画出沿三层的完整数据流。

3.1.2 数据层：Dataset、权重掩码与划分

数据层的核心对象是 Dataset。它对外的承诺很少：持有特征 X、标签 y、样本权重 w，支持按批迭代，支持切分。X 与 y 的形状由数据集本身决定：单任务 y 是长度为 N 的向量；多任务 y 是 N×T 的矩阵——Tox21 有 12 个测定任务，y 便是 N×12。

真正的设计题在"缺失"如何表达。1.3 节的稀疏标签矩阵在此落地：分子 i 在任务 t 上未必有测定记录，y 的该格无值可填。Dataset 不发明新的"缺失类型"，而是把 y 全部填成实数，另设一个同为 N×T 的 0/1 矩阵 w 作权重掩码(weight mask)：w_it=1 表示标签真实存在，w_it=0 表示未知。未知的格子在 y 里填 0 即可——任何损失与指标都只统计 w=1 的格子，填进什么都不会泄漏进结果。多任务训练由此写成：

存放位置与迭代方式是数据层的另一对设计。内存后端把三个矩阵整块放进内存，随机访问、切片都快；磁盘后端把大表留在盘上，按需逐批读取，特征化也可以推迟到取批时再做。这种"用到才算"的惰性迭代(lazy iteration) 让数据集规模与内存容量解耦——百万级虚拟筛选库因此可训练。关键在：两种后端对上层的脸面完全一致，训练循环拿到的都是"下一批 (X, y, w)"，不必也不应关心它来自内存还是硬盘。

数据层还托管划分。划分器(Splitter) 把一个 Dataset 切成训练、验证、测试三个同种对象。语义差异一句话：RandomSplitter 按比例随机切，考察同分布插值；ScaffoldSplitter 按 Bemis–Murcko 骨架归类后整族划归一侧，考察结构外推。1.3 节的三种划分协议（随机、骨架、时间）在工程上就是不同的 Splitter——选哪个是科学决策，但落点只是一个对象名，紧挨着它所影响的那些数字。

切出的三个 Dataset 各司其职：训练集进 fit；验证集只给训练过程看——驱动早停、挑选超参，看多少眼都行；测试集只在一切定型之后进 evaluate 一次。这套纪律完全靠研究者自律维持，数据层不会强制——3.8 节会列举绕开它的种种手法及其代价。

3.1.3 特征化层：化学先验的注入点

特征化层只有一个动词：把分子变成模型能吃的输入。入口统一，出口的形状却随种类而变。ECFP 类指纹把分子压成 R^d 的定长位串（2.5 节，d 常取 1024）；描述符拼接给出更低维的连续向量（2.4 节，分子量、logP、拓扑极性表面积一类）；图特征保留变长结构——节点特征矩阵加邻接关系，把分子图原样递给模型（2.1 节）。形式化地写：

这层常被"一个字符串参数"的表象掩盖，科学含量却不在模型层之下。选什么特征化，就是在声明化学先验：毒性常与特定子结构模式相关，指纹把子结构词汇表摆到台前；溶解度对整体极性敏感，描述符直接点名拓扑极性表面积；构效关系若取决于连接方式本身，图特征保留全部拓扑，把"哪些信息重要"的判断推迟给模型去学。先验注入得越靠前，模型自由度越小、样本效率越高，偏差风险也越大；注入得越少，上限越高，数据需求随之膨胀。1.2 节的三种面貌（字符串、指纹、图）在工程上就是不同 Featurizer 的选择面。

再点破一条分界线：特征化与表示学习的边界划在何处。Featurizer 的"参数"（指纹半径、长度，描述符清单）是人定的，训练前后不变；图特征交出去之后，模型学出的逐节点表示才是数据驱动的那部分。第 3 章后半的演化故事——基线、图卷积、消息传递、注意力——可以一句话预演：把"哪些信息重要"的决定权从特征化层逐步移交给模型层。移交不是取消特征化：哪怕最彻底的图特征，原子特征清单与邻接口径仍出自人的选择（3.2 节展开）。

3.1.4 模型层：统一协议与两种包装

模型层对外只承诺三个动作：fit 吃 Dataset，predict 吐预测，evaluate 吃 Dataset 加 Metric 吐指标。协议之窄，使机理截然不同的两类模型能并列在同一个槽位。一类是 SklearnModel——包装 scikit-learn 的估计器(estimator)（Pedregosa et al., 2011）：随机森林、梯度提升树这类传统模型，训练即一次性拟合，预测即查表式推理。另一类是 TorchModel——包装 PyTorch 的模块（Paszke et al., 2019）：多层感知机、图卷积网络，训练是梯度下降的迭代循环，还带验证集上的早停(early stopping)（3.8 节）。两者的内部毫无共同之处，对上层的脸面却一致：换模型就是换一个对象，流水线的其余部分不知道、也不需要知道发生了什么。

第三个小件是 Metric 对象。它把 scikit-learn 的指标函数（如 roc_auc_score）封装成"按任务计算、按 w 过滤、对有效任务聚合"的对象。封装解决两件事。其一是口径统一：任何模型、任何流水线算出的 AUC 走同一条代码路径，"各算各的"式对比失效的风险就此消除。其二是缺失标签的自动处理：多任务下某任务在某次划分里可能没有有效正例，AUC 在该任务上无定义，聚合时按有效性取舍，而不是让一个 NaN 毁掉整张报表。指标的概率语义与多任务聚合细节留给 3.3 与 3.7。

图 3.1-2 把"换模型不换管线"画出来：同一份数据与划分、同一份 ECFP 特征，模型槽位上随机森林与多层感知机并列，指标口径不变。两条流水线的差值只能归因于模型层——其余变量被冻结在共享的方框里，这正是对照实验的结构。接口之内自由替换；跨接口的替换（图特征配随机森林）则不被形状允许，天然是两处变更。承认这条边界不是抽象的失败，而是对"实验到底改了几个变量"的诚实核算。

3.1.5 走读：Tox21 的完整数据流

molnet 的加载器把"下载、解析、特征化、划分"一次做完，返回三元组：任务名列表、三个已切分的 Dataset、标签变换器列表。把走读的每一步落到层上：

1. 加载与特征化（数据层 × 特征化层）。SMILES 与 12 列标签表读入，Featurizer 把每个分子映成特征；y 的缺失格由 w 记账。特征化在加载时一并完成，此后三层各自拿到的是定型好的对象。
2. 划分（数据层）。ScaffoldSplitter 按骨架整族切出训练、验证、测试（约 8:1:1），三个仍是同种 Dataset。1.3 节的结论在此生效：这一刀切下去，指标衡量的就是结构外推而非插值。
3. 训练（模型层）。fit 只认 Dataset：随机森林一次拟合即返回；图卷积按批迭代、按验证损失早停。训练循环不接触分子，它见到的只是形状确定的批。
4. 评估（模型层协议 × Metric）。evaluate 对测试集逐任务算 AUC（只统计 w=1），再对有效任务取平均。同一个 Metric 对象对任何模型一视同仁。

下面两段骨架代码印证走读，细节以注释与省略折叠。第一段是完整流水线：ECFP 特征加随机森林基线；第二段换掉特征化与模型两层，换成图特征与图卷积——注意这是两处变更，接口联动使然；若要严格的单层对照，应在同一份 ECFP 向量上把随机森林换成多层感知机（图 3.1-2 的情形）。

import deepchem as dc

# 数据层 + 特征化层：加载 Tox21，一次完成解析、特征化与骨架划分（tf 为标签变换器，3.7 展开）
tasks, (train, valid, test), tf = dc.molnet.load_tox21(featurizer='ECFP',
                                                       splitter='scaffold')
# 模型层：SklearnModel 包装的随机森林；协议统一为 fit / evaluate
model = dc.models.RandomForestClassifier(n_estimators=500)
model.fit(train)
# Metric：封装 roc_auc_score——按任务计算、按 w 过滤、对有效任务取平均
metric = dc.metrics.Metric(dc.metrics.roc_auc_score)
print(model.evaluate(test, [metric]))          # 12 项任务的平均 AUC

# 换图卷积：特征形状变了，特征化层与模型层一起换（跨接口的替换天然是两处变更）
tasks, (train, valid, test), tf = dc.molnet.load_tox21(featurizer='GraphConv',
                                                       splitter='scaffold')
model = dc.models.GCNModel(n_tasks=len(tasks), graph_batch_size=200,
                           learning_rate=0.001)
model.fit(train, nb_epoch=30)                  # 数据层与指标口径：原样复用
print(model.evaluate(test, [metric]))          # 同一条流水线，同一个口径

两段代码合起来看，"三层"不是三个函数，而是三处可以独立指认的决策点：第一行的两个字符串（特征化、划分）各定一层，model 一行定一层。骨架划分下 Tox21 的基线成绩显著低于随机划分——1.3 节的机理分析在此得到复现：查表通道被关闭，剩下的才是化学泛化的成绩。GCN 在这份数据上能否胜过指纹基线，正是 3.4 节要拆解的问题。

3.1.6 抽象的代价：默认值、流畅性与版本

分层的第一笔成本是间接层。学习者面对的不再是"一个脚本"，而是若干抽象类与包装器；报错要在包装层与底层库之间转译，调试者须同时懂 scikit-learn 与 PyTorch 的习惯。这是学费，尚可付清。更深的代价藏在便捷本身。

教程式流水线还有第二重陷阱：跑通不等于理解。"几分钟得到一个 AUC"的流畅体验，容易把注意力全部吸进模型层——那里最有"新意"，也最容易刷分；而科学含量最高的选择往往在另外两层。1.3 节的量化已经说明，仅划分协议一项就能解释数分的指标差；本节的论证补上另一半：特征化决定了模型的可见世界。层间的拼接是工程便利，层内的选择才是科学问题。

最后交代版本现状。DeepChem 的稳定版停留在 2.8.0（2024 年 4 月发布），此后 nightly 版持续演进，接口细节时有变动（2026 年 8 月核实）；本节的类名与参数以 2.8 系列文档为准。本教材的立场是学抽象而非学版本：三层抽象、w 掩码、统一协议这些设计自库的早期（Ramsundar et al., 2019）延续至今，未随版本漂移；TorchDrug（第 4 章）与更广的生态（第 5 章）各有一套同名不同形的实现，对号入座靠的正是层与接口的理解，而非记忆某个版本的 API。具体类名随时可查文档，分层的眼光才是可迁移的资产。

数据怎么变成向量与张量、原子与键各带什么特征、图如何成批——3.2 节把特征化层单独拿出来，走到管线尽头。