从SMILES到DGLGraph：分子图神经网络数据预处理实战与避坑指南-北京尧图网络

1. 从SMILES到图结构为什么分子不能直接喂给图神经网络做过分子属性预测的人多半遇到过这个尴尬手里攥着一大把SMILES字符串想用图神经网络跑个溶解度或者毒性预测结果发现模型根本不认这串文本。SMILES本质上是一维的字符序列而图神经网络需要的是节点、边、节点特征、边特征这套东西。这中间的转换就是整个流程里最容易被低估、也最容易出岔子的一步。我最初做这个转换的时候觉得无非就是调个库的事结果在实际项目里被各种边界情况折腾了整整两天。原子手性丢了、芳香环变成单双键交替、氢原子数量对不上、某些含金属的分子直接报错——这些问题在标准数据集上不会暴露一旦换成真实业务数据就全冒出来了。所以这篇内容我打算把“SMILES转DGLGraph”这件事从头到尾拆开讲包括每一步为什么这么做、哪些参数不能乱设、以及我踩过的那些坑。这篇文章适合三类人看第一类是刚接触分子图神经网络想知道数据怎么从文本变成图结构的新手第二类是在做分子性质预测、虚拟筛选、反应预测等任务需要自己构建数据管线的从业者第三类是想把DGL这套图计算框架用到化学信息学场景里的工程师。我会尽量把化学信息学和图计算两边的概念都讲清楚让不同背景的人都能跟上。核心工具链其实很固定RDKit负责化学层面的解析和特征提取DGL负责把图结构封装成可以喂给模型的格式。但固定不代表简单RDKit的原子特征怎么选、键特征怎么编码、DGL的图怎么构建才高效每一个环节都有讲究。下面我按实际操作的顺序把整条链路拆成几个关键部分来讲。2. RDKit解析SMILES时那些不为人知的细节2.1 分子对象的生成与隐式氢的处理用RDKit把SMILES转成分子对象一行代码就够了Chem.MolFromSmiles(smiles)。但这一行代码背后发生的事情比大多数人想象的多。RDKit会做完整的价键校验、芳香性感知、环闭合检查如果SMILES本身有问题它会返回None而不是抛异常。这意味着你必须显式检查返回值否则后面所有操作都会在None上崩溃。隐式氢是第一个容易出问题的地方。RDKit默认不会把氢原子显式地建成图中的节点而是把它们作为重原子的属性记录下来。这在大多数图神经网络里是合理的做法因为氢原子数量太多会让图变得很大而且氢的化学环境相对简单。但如果你做的任务涉及氢键、质子转移或者需要精确的立体化学信息就得考虑用Chem.AddHs(mol)把氢显式加进来。我做过一个氢键供体/受体预测的任务不加显式氢的时候模型效果一直上不去加上之后AUC直接涨了三个点。另一个细节是芳香性的感知。RDKit在解析SMILES时会自动做芳香性感知把符合Hückel规则的环标记为芳香。但芳香性的判定标准在不同版本之间有过调整如果你在本地用某个版本生成了特征部署到另一个版本的环境里可能会得到不一致的结果。我的做法是在数据预处理阶段就把芳香性信息固化下来存成特征而不是依赖运行时重新计算。2.2 原子特征的选取逻辑与常见误区原子特征决定了每个节点携带什么信息。常见的选择包括原子类型、度、形式电荷、手性、杂化方式、是否在环内、是否芳香等。但这里有个很容易犯的错误直接把原子序数当成特征。原子序数是有序的数值但元素之间的化学相似性并不是按原子序数线性变化的。碳和硅的化学性质有相似之处但它们的原子序数差了8氮和磷也有相似性序数差了8。直接用原子序数会让模型学到错误的相似性关系。正确的做法是用one-hot编码或者可学习的嵌入。RDKit提供了Chem.GetPeriodicTable()来获取原子属性但更常用的是自己定义一个允许的原子类型列表然后做one-hot。这个列表的选择很关键如果列表太短稀有元素会被映射成未知类型丢失信息如果太长特征维度爆炸而且大部分维度都是零。我的经验是覆盖有机化学里常见的元素C、N、O、S、P、F、Cl、Br、I等再加上几个常见的金属总共20到30种就够了。手性特征也容易被忽略。RDKit的Chem.FindMolChiralCenters()可以找到所有手性中心但返回的是原子索引和手性标记。如果你不做特殊处理这些信息在转成图之后很容易丢失。对于涉及立体化学的任务比如对映体选择性预测手性特征是必须保留的。我通常会把手性编码成四类R、S、未指定、非手性中心。2.3 键特征的编码方式与边界情况键特征同样重要。最基本的包括键类型单键、双键、三键、芳香键、是否共轭、是否在环内、立体化学信息。键类型的编码不能用简单的整数因为单键、双键、三键之间没有天然的序数关系。one-hot是更安全的选择。共轭和环内信息在RDKit里可以通过bond.GetIsConjugated()和bond.GetIsInRing()获取。这两个特征对于预测分子的电子性质和反应活性很有帮助。我做过一个反应产率预测的项目加上共轭特征之后模型对共轭体系的产率预测明显更准了。边界情况主要出现在环状分子和桥环分子上。RDKit在解析环的时候如果环的闭合顺序和SMILES里的写法不一致可能会导致键的索引顺序和预期不同。这在大多数情况下不影响结果但如果你需要把图结构和原始SMILES里的原子顺序对应起来就得特别小心。我的做法是在构建图之前先用Chem.RenumberAtoms()把原子顺序固定下来这样后续的调试和可视化都会方便很多。还有一个容易被忽略的点是盐和溶剂分子的处理。很多真实数据里的SMILES会包含盐的形式比如盐酸盐、钠盐等。这些盐在化学上是有意义的但在图神经网络里它们会引入额外的节点和边干扰模型对主分子的学习。我通常会用Chem.StripSalts()把盐去掉只保留最大的有机片段。但这一步要谨慎有些任务里盐的形式本身就是重要信息比如药物的成盐形式会影响溶解度和生物利用度。3. 用DGL构建图对象从原子到节点的映射3.1 DGL图的基本构建流程DGL的图构建接口很直观dgl.graph((src, dst))其中src和dst分别是边的起点和终点列表。对于分子图来说每条化学键对应两条有向边正反各一条因为DGL默认处理的是有向图而化学键在大多数情况下是双向的。如果你不做双向处理消息传递就只能沿着一个方向进行模型会丢失一半的信息。节点特征的添加通过g.ndata[feat] node_features完成边特征通过g.edata[feat] edge_features完成。这里的node_features和edge_features必须是张量而且顺序要和节点的索引对应。RDKit里原子的索引和DGL里节点的索引默认是一致的但如果你做了原子重排或者去盐操作这个对应关系就会变需要重新建立映射。我见过很多人在这里犯错先用RDKit的原子顺序生成了特征然后去盐之后没有更新索引导致特征和节点错位。这种错误不会报错但模型学到的完全是错误的信息。我的建议是在整个流程里只做一次原子重排把重排后的索引作为唯一的参考标准后续所有操作都基于这个索引。3.2 节点特征矩阵的组装与归一化节点特征矩阵的组装看起来简单实际上有很多细节。假设你选了10种原子特征每种特征做one-hot之后维度是20那么每个节点的特征维度就是200。这个维度对于小分子来说可能还好但对于大分子或者包含很多稀有元素的分子维度会迅速膨胀。我的做法是对不同类型的特征分别处理然后在特征维度上拼接。比如原子类型用one-hot维度30度用one-hot维度6形式电荷用one-hot维度5手性用one-hot维度4杂化方式用one-hot维度5是否芳香用二值维度1是否在环内用二值维度1。这样总维度是52比无脑拼接所有特征要紧凑得多。归一化是另一个需要注意的点。数值型特征比如度、形式电荷如果不做归一化可能会主导模型的训练。我通常会把数值型特征缩放到0到1之间或者直接用one-hot编码。对于形式电荷这种有正负之分的特征one-hot比归一化更合适因为正电荷和负电荷的化学意义完全不同归一化会引入错误的序数关系。还有一个实践中的技巧把节点特征矩阵存成稀疏矩阵。分子图里大部分节点的特征都是稀疏的比如大多数原子都不是芳香性的用稀疏矩阵可以节省大量内存。DGL支持稀疏特征但在消息传递的时候可能会慢一些。我的经验是如果分子量不大原子数少于100用稠密矩阵就行如果处理的是蛋白质或者聚合物稀疏矩阵是必须的。3.3 边特征的处理与消息传递的兼容性边特征的处理和节点特征类似但有一个额外的考虑DGL的消息传递函数对边特征的维度有要求。如果你用的消息传递函数是内置的比如dgl.nn.pytorch.conv.GINConv它可能不支持边特征。这时候你有两个选择要么换一个支持边特征的卷积层要么把边特征融入到节点特征里。把边特征融入节点特征是一种常见的做法但会丢失边的独立性。比如一条双键和一条单键如果只把键类型加到节点特征里模型就无法区分“这个原子通过双键连接”和“这个原子通过单键连接”的区别。对于需要精确区分键级的任务比如反应预测边特征是必须保留的。我通常会用支持边特征的卷积层比如dgl.nn.pytorch.conv.GATConv或者自定义的消息传递函数。如果非要用不支持边特征的层我会把边特征通过一个线性层映射到和节点特征相同的维度然后在消息传递的时候加到节点特征上。这种做法虽然不完美但在很多任务上效果还不错。边的方向性也需要考虑。化学键在大多数情况下是双向的但有些任务里方向性是有意义的比如反应中的键断裂和形成。对于这类任务我会保留有向边的设置让模型自己学习方向性的信息。对于普通的分子属性预测双向边就足够了。4. 特征工程中的取舍哪些原子和键特征真正有用4.1 原子特征的重要性排序与消融实验不是所有的原子特征都对任务有帮助。我做过一组消融实验在溶解度预测任务上逐个去掉原子特征看模型性能的变化。结果发现原子类型、度、形式电荷、是否芳香这四个特征最重要去掉任何一个都会导致明显的性能下降。手性和杂化方式的影响相对较小但在涉及立体化学的任务里就变得关键了。这个结果和化学直觉是一致的溶解度主要取决于分子的极性和氢键能力而这些性质主要由原子类型、电荷和芳香性决定。手性对溶解度的影响通常很小但在手性拆分或者对映体选择性结晶的场景里就很重要了。我的建议是不要一开始就追求特征的全覆盖而是先选一组核心特征跑通流程然后根据任务特点逐步添加。核心特征我推荐原子类型、度、形式电荷、是否芳香、是否在环内。这五个特征覆盖了大多数任务的基本需求而且计算成本低。4.2 键特征的选择与任务相关性键特征的选择同样需要根据任务来定。对于分子属性预测键类型和是否共轭是最重要的。对于反应预测键类型和立体化学信息更关键。对于分子生成键类型和是否在环内都需要保留。我做过一个对比实验在毒性预测任务上只用键类型和是否共轭两个特征模型性能已经接近使用全部键特征的水平。这说明对于大多数任务键特征不需要太多关键是选对。过多的键特征不仅增加计算量还可能引入噪声让模型学到虚假的相关性。一个容易被忽略的键特征是键长和键角。RDKit可以通过Chem.GetDistanceMatrix()和Chem.Get3DDistanceMatrix()获取这些信息但需要分子有三维构象。对于二维的SMILES键长和键角是估算出来的精度有限。如果你的任务对三维结构敏感比如结合亲和力预测那么键长和键角是必须的。否则用二维的拓扑特征就够了。4.3 特征维度与模型容量的平衡特征维度直接决定了模型的输入维度进而影响模型的容量和训练速度。特征维度太高模型容易过拟合尤其是当训练数据有限的时候。特征维度太低模型可能欠拟合学不到足够的化学信息。我的经验是对于小分子原子数少于50节点特征维度控制在50到100之间比较合适。对于中等大小的分子原子数50到200可以适当增加到100到200。对于大分子可能需要200以上但这时候要考虑用图池化或者层次化的图神经网络来降低维度。还有一个技巧是用可学习的嵌入代替one-hot。比如原子类型不用one-hot而是用一个嵌入层把原子类型映射到低维向量。这样可以在保持信息量的同时降低维度。DGL和PyTorch都支持嵌入层实现起来很方便。我通常会把原子类型嵌入到32维其他特征用one-hot然后拼接起来。这样总维度可以控制在80左右比纯one-hot的200维要紧凑得多。5. 批量处理与性能优化当分子数量上万时怎么办5.1 单图构建与批量图构建的差异单个分子的图构建很简单但当你需要处理上万个分子时逐个构建图然后逐个喂给模型会非常慢。DGL提供了dgl.batch()函数可以把多个小图合并成一个大图然后一次性喂给模型。这个操作的本质是把多个图的节点和边拼接起来同时记录每个子图的边界。批量构建的关键是保证每个子图的特征维度一致。如果你的分子图有的有边特征有的没有批量操作会失败。我的做法是在数据预处理阶段就统一特征维度对于没有某种特征的分子用零向量填充。这样虽然会引入一些无效信息但保证了批量操作的可行性。另一个需要注意的是批量图的内存占用。把一万个分子合并成一个大图节点数可能达到几十万边数可能上百万。这时候GPU内存会成为瓶颈。我的做法是控制每个batch的大小通常256到512个分子比较合适。如果分子特别大batch size还要进一步减小。5.2 数据加载器的设计与多进程处理DGL和PyTorch的DataLoader可以配合使用但需要自定义collate函数来处理图数据的批量合并。默认的collate函数不认识DGL的图对象会报错。你需要写一个自定义的collate函数在里面调用dgl.batch()。多进程处理是加速数据加载的关键。RDKit的分子解析和特征提取是CPU密集型的用多进程可以显著提升速度。我通常会把num_workers设置为CPU核心数的2到4倍但要注意RDKit在某些情况下不是线程安全的多进程比多线程更安全。还有一个优化点是缓存。分子图的构建是确定性的同样的SMILES每次构建的结果都一样。所以可以把构建好的图缓存到磁盘上下次直接加载省去重复计算的时间。我通常会用PyTorch的torch.save()把图对象存成pt文件加载速度比重新构建快一个数量级。5.3 内存与速度的权衡稀疏与稠密的选择前面提到过稀疏矩阵和稠密矩阵的选择。这里展开说一下具体的权衡。稠密矩阵的优点是消息传递快因为GPU对稠密矩阵的运算有优化。缺点是内存占用大尤其是当特征维度高的时候。稀疏矩阵的优点是内存占用小缺点是消息传递慢而且不是所有的卷积层都支持稀疏输入。我的经验是如果特征维度低于100用稠密矩阵就行。如果特征维度高于200或者分子特别大考虑用稀疏矩阵。还有一个折中的方案是用半精度浮点数float16来存储特征这样内存占用减半速度也有提升但可能会损失一些精度。对于大多数任务float16的精度损失是可以接受的。还有一个容易被忽略的优化点是特征的计算。RDKit的特征计算是CPU密集型的如果你在训练循环里实时计算特征会严重拖慢训练速度。正确的做法是在数据预处理阶段就把所有特征算好存下来训练的时候直接读取。这样虽然预处理阶段会花一些时间但训练阶段会快很多。6. 踩坑实录那些让我调试到凌晨的边界情况6.1 芳香性感知不一致导致的特征错位这是我遇到过的最隐蔽的坑。同一个SMILES在不同的RDKit版本里解析出来的芳香性标记可能不一样。比如某个环在旧版本里被标记为芳香在新版本里被标记为非芳香。这会导致原子特征和键特征都发生变化模型在训练集上学到的模式和测试集上的不一致。这个问题的根源是RDKit的芳香性模型有过更新。解决办法是在数据预处理阶段就把芳香性信息固化下来存成特征而不是依赖运行时重新计算。具体做法是用Chem.SetAromaticity()显式设置芳香性模型然后把结果存下来。这样即使RDKit版本变了特征也不会变。还有一个相关的坑是芳香键的表示。RDKit里芳香键的GetBondType()返回的是AROMATIC但GetBondTypeAsDouble()返回的是1.5。如果你用后者做特征会得到一个浮点数而不是one-hot编码。我建议统一用GetBondType()然后做one-hot避免浮点数带来的问题。6.2 手性中心丢失与立体化学的保留手性中心的丢失是另一个常见问题。RDKit在解析SMILES的时候如果手性标记写得不规范可能会丢失手性信息。比如[CH]和[CH]的区别很细微写错了就会导致手性反转或者丢失。我的做法是在解析之后显式检查手性中心的数量和预期对比。如果数量不对就手动修正SMILES或者用Chem.AssignStereochemistry()重新分配。还有一个技巧是用Chem.FindMolChiralCenters()的includeUnassigned参数把未指定的手性中心也找出来这样可以发现潜在的问题。对于涉及立体化学的任务我建议用RDKit的Chem.EnumerateStereoisomers()把所有可能的立体异构体都枚举出来然后分别构建图。这样虽然会增加数据量但可以保证立体化学信息的完整性。6.3 含金属和特殊价态分子的处理含金属的分子是另一个难点。RDKit对金属有机化合物的支持有限很多金属配合物解析出来之后价态不对或者键的类型无法识别。我遇到过含铁、铜、锌的分子RDKit直接返回None或者给出错误的价态。对于这类分子我的做法是先用Chem.MolFromSmiles()尝试解析如果失败就用Chem.MolFromSmiles(smiles, sanitizeFalse)跳过价态校验然后手动设置原子和键的属性。这样做虽然麻烦但至少能保证图能构建出来。另一个选择是用Chem.rdmolops.SetBondStereo()手动设置键的立体化学信息。还有一个坑是特殊价态的原子比如硝基里的氮、亚砜里的硫。这些原子的价态超出了常规的价键规则RDKit在解析的时候可能会报错。解决办法是用Chem.SetAllowNontetrahedralChirality()允许非四面体手性或者用Chem.SetHybridization()手动设置杂化方式。6.4 大分子和聚合物图的构建策略大分子和聚合物的图构建是另一个挑战。一个蛋白质可能有几千个原子直接构建成图会非常大消息传递的效率很低。我的做法是用层次化的图表示把氨基酸残基作为粗粒度的节点原子作为细粒度的节点然后用两层图神经网络分别处理。对于聚合物重复单元的处理是关键。我通常会把重复单元识别出来然后用一个节点表示整个重复单元而不是把每个原子都建成节点。这样可以大幅减小图的规模同时保留聚合物的拓扑信息。还有一个技巧是用图池化来降低大图的维度。DGL提供了多种池化操作比如dgl.nn.pytorch.glob.TopKPooling和dgl.nn.pytorch.glob.AvgPooling。对于大分子我通常会在几层消息传递之后加一个池化层把图的规模降下来然后再做后续的处理。7. 从图到模型数据管线的完整串联7.1 数据预处理脚本的组织方式把整个流程串起来需要一个组织良好的预处理脚本。我的脚本通常分成几个模块SMILES读取和校验、分子解析和特征提取、图构建和批量处理、数据保存和加载。每个模块都有明确的输入输出方便单独测试和调试。SMILES读取和校验模块负责检查SMILES的合法性过滤掉无效的条目。我通常会记录无效SMILES的数量和原因方便后续分析。分子解析和特征提取模块负责把SMILES转成分子对象然后提取原子和键的特征。这个模块是最耗时的通常会用多进程加速。图构建和批量处理模块负责把特征组装成DGL图然后批量合并。数据保存和加载模块负责把图对象存到磁盘以及从磁盘加载。我通常会把图对象存成PyTorch的pt文件加载速度快而且兼容性好。7.2 训练集、验证集、测试集的划分策略数据划分看起来简单但对于分子数据有很多讲究。随机划分是最简单的但可能会导致数据泄漏。比如同一个分子的不同构象被分到了训练集和测试集模型在测试集上的表现会虚高。我的做法是用骨架划分scaffold split。RDKit提供了MurckoScaffold来提取分子的骨架然后按骨架划分数据集。这样可以保证训练集和测试集里的分子骨架不重叠更接近真实的应用场景。对于活性预测任务骨架划分比随机划分更能反映模型的泛化能力。还有一个策略是用时间划分。如果数据有时间戳按时间划分可以模拟真实的时间外推场景。比如用早期的数据训练用后期的数据测试。这种划分方式对于药物发现里的前瞻性预测特别有意义。7.3 图数据的持久化与版本管理图数据的持久化是保证实验可复现的关键。我通常会把预处理后的图数据存成pt文件同时保存一个元数据文件记录预处理时用的参数、RDKit版本、特征维度等信息。这样即使换了环境也能知道数据是怎么来的。版本管理也很重要。每次修改预处理脚本我都会更新版本号并把新旧版本的数据分开存放。这样可以避免因为脚本改动导致的数据不一致。我通常会用日期加版本号的方式命名比如graphs_v1.2_20240115.pt。还有一个技巧是把原始SMILES也存下来和预处理后的图数据放在一起。这样如果预处理脚本有问题可以快速重新生成而不需要重新收集数据。原始SMILES的存储成本很低但价值很高。8. 一些让流程更稳的实战习惯我在多个项目里反复做SMILES到DGLGraph的转换慢慢积累了一些习惯这些习惯让我少踩了很多坑。第一个习惯是永远先在小样本上跑通流程。拿100个分子先跑一遍检查每个环节的输出是否符合预期然后再扩展到全量数据。这样可以在早期发现大部分问题避免在几万个分子上浪费时间。第二个习惯是给每个环节加断言。比如解析SMILES之后断言分子对象不为None提取特征之后断言特征维度一致构建图之后断言节点数和原子数相等。这些断言在开发阶段可能会拖慢速度但可以及早发现问题避免错误传播到下游。第三个习惯是可视化。DGL提供了dgl.contrib里的可视化工具可以把图结构画出来。我通常会在预处理之后随机抽几个分子画出来肉眼检查节点和边的连接是否正确。这个习惯帮我发现了好几次特征错位的问题。第四个习惯是记录日志。每个环节的输入输出数量、耗时、异常情况都记录下来。这样当流程出问题的时候可以快速定位是哪个环节出了错。我通常会用Python的logging模块把日志同时输出到控制台和文件。最后一个习惯是保持特征定义的一致性。训练和推理阶段用的特征定义必须完全一致否则模型在推理时会得到错误的结果。我通常会把特征定义写成一个独立的配置文件训练和推理都从这个文件读取。这样即使特征定义需要修改也只需要改一个地方。这些习惯看起来琐碎但在实际项目里能省下大量调试时间。分子图数据的预处理是整个流程里最容易被低估的部分把它做扎实了后面的模型训练和调优才有意义。

从SMILES到DGLGraph：分子图神经网络数据预处理实战与避坑指南

相关推荐

养虾指南：低成本部署AI自动化服务的完整方案

OpenResearch：让机器学习实验可追溯，解决数据、代码、结论全链路管理

Git仓库本地化：从镜像克隆到自建服务的完整迁移指南

更多资讯

ESP32音乐播放器：用I2S接口软解WAV文件实战

山东省17地市矢量图获取与处理：从坐标系转换到可视化落地

代码审查自动化实践：基于open-code-review提升团队效能

基于YOLOv8与PyQt5的实时人脸表情识别系统设计与实现

DeskcommCRM：把桌面通信与客户管理融为一体的落地实践

从版本控制到代码审计：用Git精准追溯每一行代码的来龙去脉

今日更新

悟空开源无代码平台实战：从实体建模到应用设计避坑指南

基于.NET9的多租户权限系统：数据权限与动态API落地实践

场地预约小程序毕设实战：SSM+微信小程序+MySQL数据库设计到避坑

本周精选

金融AI落地指南：从调研报告到技术选型与工程实践

大模型上下文成本与注意力优化技术深度解析——为何O(n²)平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测

基于GMM的语音识别系统原理与MATLAB实现详解

本月热门

我发现了一个新思路：用 Remotion + Claude Code 像写代码一样自动化生成短视频

Windows下 Codex 中 Chrome 和 Computer Use 插件不可用问题排查及解决参考方式：TaoToken 统一 Key 配置与验证

2026 大模型集体涨价：用 Python 做企业 Token 成本测算与选型避坑（附配置）

读完文章，想聊聊您的网站？