RDKit 在 AI 化学技术栈中的定位

AI 助手可以把研究问题转化为操作，但分子计算应由可识别的化学引擎完成。RDKit 承担这一角色：其官方文档介绍了分子数据结构、二维和三维操作、描述符与指纹生成，以及化学搜索。其核心算法以 C++ 实现，并提供 Python 接口和其他封装；不应假定这些封装具有完全相同的功能覆盖范围。

RDKit 是工具包，并非现成的生物活性预测器。有效的架构会将助手的规划与分子处理、外部信息检索和结果解释分开。助手请求操作；软件执行操作；结构化结果记录实际发生的过程；助手解释结果，而不虚构缺失值。

本指南涵盖完整的结构处理流程。PubChem 智能体集成指南介绍外部信息检索；MCP、Skills、智能体与 API则说明周边组件的角色。

选择 Python、MCP 或 Skill 引导的执行方式

这些路径相互补充，并非可以互换。应根据执行控制权归属、所需化学操作以及应用对可审计性的要求来选择。

资源或路径 实际角色 适用场景 需要核实的边界
RDKit Python interface 直接访问工具包操作 明确的批处理流水线、自定义 sanitization（化学合理性检查）以及受控参数 自行定义记录模式、错误处理和环境
RDKit MCP Server (TandemAI) 向支持 MCP 的客户端提供 RDKit 工具的 Python 服务器 由助手发起工具调用 检查实际工具清单；全面覆盖是其目标，而非已证实的覆盖范围
RDKit Skill (K-Dense) 指令、参考资料和可选 Python 辅助工具 向助手传授详细的 RDKit 工作流 必须单独安装 rdkit 依赖项
rdkit-agent Skill (scottmreed) 针对独立 RDKit WASM 驱动 CLI 的指令 通过文档所述 CLI 进行验证优先的结构化交互 WASM 功能不同于 Python；文档指出不支持立体异构体枚举
Datamol Skill (K-Dense) 使用 Datamol 的指南；Datamol 是 RDKit 的 Python 抽象层 常规分子数据准备、批量分析和骨架工作流 默认设置仍需符合特定任务的化学策略
PubChem PUG REST 用于获取选定化学信息的托管 HTTP API 标识符、记录和性质信息补充 信息检索不等于本地化学计算或实验验证

加载 Skill 并不会安装其执行依赖项。不同宿主对指令加载和工具使用许可的处理也各不相同。对于 TandemAI 服务器，应先检查暴露的工具和设置，再选择客户端；依赖项声明和当前协议概述并不能证明互操作性已经过测试。化学 MCP 选择指南和化学 AI Skills 指南可帮助理清这些选择。

MCP 的连接与工具发现机制可参阅化学领域的 MCP。

定义输入和可审计的记录约定

先明确科学问题：你要比较的是提交的物质、母体分子图，还是经过有意标准化的表示？这一选择决定哪些信息可以转换，以及哪些信息必须保持原样。

K-Dense RDKit Skill 文档介绍了 SMILES、SDF、MOL 和 InChI 工作流。其 Datamol 对应 Skill 还讨论了 CSV 等表格输入。这些是文档中介绍的工作流选项，并不证明每个 MCP 工具都接受这些格式。

建议的记录约定应包括：

  • **来源：**稳定的本地记录 ID、来源标识符、输入格式，以及原始结构或文件引用。
  • **处理：**解析状态、验证发现、标准化策略 ID 和转换历史。
  • **化学信息：**保留的表示形式、盐/组分处理方式、电荷处理方式和立体化学状态。
  • **结果：**请求的描述符、指纹规格、搜索设置和返回的匹配项。
  • **溯源信息：**软件环境、执行路径、外部标识符，以及适用情况下的检索日期。
  • **失败信息：**发生阶段、诊断信息、尝试的操作和最终处置。

即使记录处理失败，也要保持来源 ID 对应关系。若仅保留通过处理的分子列表而没有拒绝记录日志，特征与来源行之间的对应关系可能会丢失。数据集溯源指南进一步介绍了如何维护这种对应关系。

先解析，再有意进行标准化

解析和 sanitization（化学合理性检查）决定结构能否进入所请求的操作。标准化则为特定任务选择一种表示形式。两者都不能证明提交的结构就是预期化合物。

K-Dense RDKit 指南明确区分了规范异构 SMILES 与互变异构体协调、质子化状态选择、脱盐或消解未指定立体化学等操作。其辅助工具被描述为能够保留来源 ID，且不会隐式脱盐或中和分子。

处理前，应作出三项决定：

  1. **组分和盐：**保留完整的提交结构、另建母体表示，还是排除不适用的多组分记录？记录任何被移除的组分。
  2. **电荷：**保留形式电荷，还是应用有依据的转换？添加氢原子并不会指定特定 pH 下的质子化状态。
  3. **立体化学：**保留已指定的信息，并标记未指定的手性中心，不要悄然补全。若增强立体化学信息很重要，应选择能够保留该信息的交换表示形式。

若自定义 sanitization（化学合理性检查）或专门算法很重要，可直接使用 RDKit。Datamol 指南可以简化常规操作，但金属断键、中和和脱盐都可能改变研究对象。对于制剂或有机金属任务，不应自动执行这些转换。

计算特征并区分搜索问题

按照选定策略接收记录后，描述符可提供数值特征。所提供的 RDKit Skill 涵盖分子量、LogP、TPSA 和氢键计数等性质。应将描述符名称和计算设置与数值一并保存。不得用虚构数值替代失败的计算，也不得悄然将缺失输出视为零。

指纹对选定的分子特征进行编码，用于比较或后续建模。记录指纹家族、参数、适用时的长度以及手性设置。Skill 介绍了 Morgan/ECFP 和 MACCS 工作流，但具体选择仍需针对任务评估。

相似性搜索会根据指定的指纹和度量，查找表示形式相近的分子。它不是身份鉴定：RDKit Skill 提醒，指纹可能发生碰撞，手性设置也会影响结果。子结构搜索则根据特定匹配规则，判断 SMARTS 查询是否匹配分子图。保存查询、设置、匹配计数和结果数量限制，以便解释结果。

对于数据库工作流，RDKit 的 PostgreSQL cartridge 支持相似性和子结构搜索以及描述符计算。这是单独的部署路径，并不能证明 MCP 封装暴露了该 cartridge。指纹也可以输入独立的预测模型；它本身不会提供标签，也不能单独证明预测有效性。

建议示例：可追溯的阿司匹林邻近分子搜索

以下是建议的评估工作流，并非已执行计算的报告。目标是检索参考结构、准备一个小型本地集合，并生成便于审查的相似分子候选列表。

**输入：**包含稳定行 ID 和提交 SMILES 的本地表格，以及作为参考标识符的 PubChem CID 2244。应刻意纳入格式错误、带电、多组分和立体化学未指定的记录，以检验错误处理。

  1. 获取文档中的 CID 2244 SDF 示例。保存响应、标识符和检索日期；在本地验证返回的结构。
  2. 解析本地输入，同时保留每一行原始记录。将格式错误或为空的结构隔离，不要猜测其身份。
  3. 应用声明的示例策略：保留完整的提交分子图、保留形式电荷、保留已指定的立体化学，并让未指定的立体化学保持未解析状态。第一轮不脱盐，也不选择互变异构体。
  4. 为通过处理的记录和参考分子计算选定的描述符集合及参数一致的 Morgan 指纹。如果手性与比较有关，应明确启用手性选项。
  5. 使用所选相似性度量为通过处理的记录排序，并返回数量受限的候选列表。如果问题涉及特定基团，则另行运行经审查的 SMARTS 查询；不要将基团匹配与指纹排序混为一谈。
  6. 在解释候选列表前审查多组分记录。如果之后有理由仅比较母体，则创建单独标注的分支，而不是覆盖第一轮结果。

**输出：**通过处理的记录特征、排序后的邻近分子、按需生成的子结构结果、转换日志和拒绝记录。**决策点：**参考结构是否成功解析、每条记录是否符合策略，以及选定的表示形式是否能回答科学问题。此处不声称任何相似性分数或描述符结果。

添加智能体调用和范围受限的 PubChem 信息补充

建议的架构如下：

用户问题 → 助手规划 → 结构化验证请求 → 化学计算执行 → 结果检查 → 可选 PubChem 信息补充 → 基于溯源信息的说明。

这是建议的集成模式，并非经过测试的互操作方案。化学层负责计算，助手负责选择获准的操作并解释返回的证据。

rdkit-agent Skill 建议检查 overall_pass、corrected_values 和 fix_suggestions，使用 JSON 交互，并限制返回字段或匹配项数量。应将修复建议视为需要检查的候选更改，而非替换原始结构的授权。对于 TandemAI，应检查工具输入输出模式，而不要假定其提供整个 RDKit API。

PubChem PUG REST 支持化合物标识符、选定性质和面向结构的搜索。例如，文档中的分子式和 InChIKey 请求可用于补充参考记录。将检索到的性质与本地计算结果明确区分；若二者不一致，应调查原因，而不是悄然择一使用。

应遵守公开的请求限制和动态限流机制，并将重试次数控制在合理范围内。本教程将 PUG REST 定位为针对性检索工具，而非数百万次单独请求的工具；批量收集需要采用适当的批量下载工作流。

处理失败和科学局限

区分无效化学结构、不支持的操作、格式错误的工具请求和服务故障。针对每种情况采取可执行的处理方式：隔离、修正请求、明确选择其他引擎，或推迟检索。不要反复重试化学上无效的输入。

rdkit-agent Skill 描述的标准 WASM 构建在立体异构体枚举时会返回 NOT_SUPPORTED_IN_WASM。若需要枚举，应单独评估 Python 路径。可选的三维阶段也需要失败检查门槛：RDKit 指南指出，嵌入失败时不得继续进行力场优化。对于聚类，Datamol Skill 提醒，完整的成对距离矩阵可能超出内存限制；扩展规模前应评估有界替代方案。

描述符阈值、QED 和结构警示属于研究启发式指标，并非效力、安全性或合成可行性的证据。RDKit 辅助工具中历史遗留的 pains 选项仅包含示例基序，并非已发表的完整 PAINS 目录。TandemAI 的评估套件和 LLMJudge 可用于评估智能体行为，但它们的存在并不能证明科学准确性。

在重新分发 Skill 材料前，应厘清其许可范围：K-Dense RDKit 和 Datamol 文件声明的许可与集合级 MIT 许可不同。这些尚未解决的声明不会改变计算结果的含义，但在打包指令或辅助工具时很重要。仅仅能够查看源代码并不意味着获得许可授权。

读者检查清单

  • 明确科学研究对象，并保留原始结构和 ID。
  • 确认已安装依赖、暴露的工具和必需的输入模式。
  • 明确记录盐、电荷、互变异构体和立体化学方面的决定。
  • 使失败记录与来源行保持对应；接受修复前先检查。
  • 将描述符、指纹和搜索设置与输出一并保存。
  • 区分本地计算结果与检索到的 PubChem 数值。
  • 扩大规模或加入预测模型前，先评估小型挑战集。
  • 检查不支持的功能、内存限制、限流机制和再分发条款。

继续阅读相关指南：化学 AI 应用中的科学 API：PubChem 与 RCSB PDB 入门。

来源