RDKit 化学信息学工具包

概述

RDKit 是一个全面的化学信息学库，提供用于分子分析和操作的 Python API。此技能提供读写分子结构、计算描述符、指纹生成、子结构搜索、化学反应、2D/3D 坐标生成和分子可视化的指导。将此技能用于药物发现、计算化学和化学信息学研究任务。

当前基线（2026-06-07 检查）： RDKit 2026.03.3 是最新的 GitHub/PyPI 版本（PyPI 上的 rdkit 2026.3.3）。官方安装文档继续推荐大多数用户使用 conda-forge，而跨平台 PyPI wheels 以 rdkit 包名发布。rdkit-pypi 是旧版 PyPI 包名，仅在维护旧环境时出现。

安装与设置

将 uv 用于现有 Python 环境：

uv pip install rdkit

对于可复现的化学环境，尤其是混合编译科学包时，conda-forge 仍是上游推荐：

conda create -c conda-forge -n my-rdkit-env rdkit
conda activate my-rdkit-env

避免在同一个环境中同时安装 conda rdkit 和 PyPI rdkit/rdkit-pypi，除非你有意调试打包行为。混合安装可能导致不清楚导入的是哪个二进制扩展。

核心能力

1. 分子 I/O 与创建

读取分子：

从各种格式读取分子结构：

from rdkit import Chem

# 从 SMILES 字符串
mol = Chem.MolFromSmiles('Cc1ccccc1')  # 返回 Mol 对象或 None

# 从 MOL 文件
mol = Chem.MolFromMolFile('path/to/file.mol')

# 从 MOL 块（字符串数据）
mol = Chem.MolFromMolBlock(mol_block_string)

# 从 InChI
mol = Chem.MolFromInchi('InChI=1S/C6H6/c1-2-4-6-5-3-1/h1-6H')

写入分子：

将分子转换为文本表示：

# 转换为规范 SMILES
smiles = Chem.MolToSmiles(mol)

# 转换为 MOL 块
mol_block = Chem.MolToMolBlock(mol)

# 转换为 InChI
inchi = Chem.MolToInchi(mol)

批量处理：

使用 Supplier/Writer 对象处理多个分子：

# 读取 SDF 文件
suppl = Chem.SDMolSupplier('molecules.sdf')
for mol in suppl:
    if mol is not None:  # 检查解析错误
        # 处理分子
        pass

# 读取 SMILES 文件
suppl = Chem.SmilesMolSupplier('molecules.smi', titleLine=False)

# 大文件或压缩数据
import gzip

with gzip.open('molecules.sdf.gz') as f:
    suppl = Chem.ForwardSDMolSupplier(f)
    for mol in suppl:
        # 处理分子
        pass

# 大数据集的多线程处理
suppl = Chem.MultithreadedSDMolSupplier('molecules.sdf')

# 写入分子到 SDF
writer = Chem.SDWriter('output.sdf')
for mol in molecules:
    writer.write(mol)
writer.close()

重要说明：

• 所有 MolFrom* 函数在失败时返回 None 并附带错误消息
• 在处理分子前始终检查 None
• 分子在导入时会自动进行清理（验证化合价、感知芳香性）

2. 分子清理与验证

RDKit 在解析过程中自动清理分子，执行 13 个步骤，包括化合价检查、芳香性感知和手性分配。

清理控制：

# 禁用自动清理
mol = Chem.MolFromSmiles('C1=CC=CC=C1', sanitize=False)

# 手动清理
Chem.SanitizeMol(mol)

# 在清理前检测问题
problems = Chem.DetectChemistryProblems(mol)
for problem in problems:
    print(problem.GetType(), problem.Message())

# 部分清理（跳过特定步骤）
Chem.SanitizeMol(mol, sanitizeOps=Chem.SANITIZE_ALL ^ Chem.SANITIZE_PROPERTIES)

常见清理问题：

• 显式化合价超过最大允许值的原子会引发异常
• 无效的芳香环会导致 kekulization 错误
• 如果没有显式指定，自由基电子可能无法正确分配

3. 分子分析与属性

访问分子结构：

# 遍历原子和键
for atom in mol.GetAtoms():
    print(atom.GetSymbol(), atom.GetIdx(), atom.GetDegree())

for bond in mol.GetBonds():
    print(bond.GetBeginAtomIdx(), bond.GetEndAtomIdx(), bond.GetBondType())

# 环信息
ring_info = mol.GetRingInfo()
ring_info.NumRings()
ring_info.AtomRings()  # 返回原子索引元组

# 检查原子是否在环中
atom = mol.GetAtomWithIdx(0)
atom.IsInRing()
atom.IsInRingSize(6)  # 检查 6 元环

# 查找最小环集 (SSSR)
from rdkit.Chem import GetSymmSSSR
rings = GetSymmSSSR(mol)

立体化学：

# 查找手性中心
from rdkit.Chem import FindMolChiralCenters
chiral_centers = FindMolChiralCenters(mol, includeUnassigned=True)
# 返回 (atom_idx, chirality) 元组列表

# 从 3D 坐标分配立体化学
from rdkit.Chem import AssignStereochemistryFrom3D
AssignStereochemistryFrom3D(mol)

# 检查键立体化学
bond = mol.GetBondWithIdx(0)
stereo = bond.GetStereo()  # STEREONONE, STEREOZ, STEREOE 等

片段分析：

# 获取断开的片段
frags = Chem.GetMolFrags(mol, asMols=True)

# 在特定键上断裂
from rdkit.Chem import FragmentOnBonds
frag_mol = FragmentOnBonds(mol, [bond_idx1, bond_idx2])

# 计数环系统
from rdkit.Chem.Scaffolds import MurckoScaffold
scaffold = MurckoScaffold.GetScaffoldForMol(mol)

4. 分子描述符与属性

基本描述符：

from rdkit.Chem import Descriptors

# 分子量
mw = Descriptors.MolWt(mol)
exact_mw = Descriptors.ExactMolWt(mol)

# LogP（亲脂性）
logp = Descriptors.MolLogP(mol)

# 拓扑极性表面积
tpsa = Descriptors.TPSA(mol)

# 氢键供体/受体数量
hbd = Descriptors.NumHDonors(mol)
hba = Descriptors.NumHAcceptors(mol)

# 可旋转键数量
rot_bonds = Descriptors.NumRotatableBonds(mol)

# 芳香环数量
aromatic_rings = Descriptors.NumAromaticRings(mol)

批量描述符计算：

# 一次计算所有描述符
all_descriptors = Descriptors.CalcMolDescriptors(mol)
# 返回字典：{'MolWt': 180.16, 'MolLogP': 1.23, ...}

# 获取可用描述符名称列表
descriptor_names = [desc[0] for desc in Descriptors._descList]

利平斯基五规则：

# 检查类药性
mw = Descriptors.MolWt(mol) <= 500
logp = Descriptors.MolLogP(mol) <= 5
hbd = Descriptors.NumHDonors(mol) <= 5
hba = Descriptors.NumHAcceptors(mol) <= 10

is_drug_like = mw and logp and hbd and hba

5. 指纹与分子相似性

指纹类型：

from rdkit.Chem import rdFingerprintGenerator
from rdkit.Chem import MACCSkeys

# RDKit 拓扑指纹
rdk_gen = rdFingerprintGenerator.GetRDKitFPGenerator(minPath=1, maxPath=7, fpSize=2048)
fp = rdk_gen.GetFingerprint(mol)

# Morgan 指纹（圆形指纹，类似于 ECFP）
# 使用 rdFingerprintGenerator 的现代 API
morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fp = morgan_gen.GetFingerprint(mol)
# 基于计数的指纹
fp_count = morgan_gen.GetCountFingerprint(mol)

# MACCS 键（166 位结构键）
fp = MACCSkeys.GenMACCSKeys(mol)

# 原子对指纹
ap_gen = rdFingerprintGenerator.GetAtomPairGenerator()
fp = ap_gen.GetFingerprint(mol)

# 拓扑扭转指纹
tt_gen = rdFingerprintGenerator.GetTopologicalTorsionGenerator()
fp = tt_gen.GetFingerprint(mol)

# Avalon 指纹（如有）
from rdkit.Avalon import pyAvalonTools
fp = pyAvalonTools.GetAvalonFP(mol)

相似性计算：

from rdkit import DataStructs
from rdkit.Chem import rdFingerprintGenerator

# 使用生成器生成指纹
mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fp1 = mfpgen.GetFingerprint(mol1)
fp2 = mfpgen.GetFingerprint(mol2)

# 计算 Tanimoto 相似性
similarity = DataStructs.TanimotoSimilarity(fp1, fp2)

# 计算多个分子的相似性
fps = [mfpgen.GetFingerprint(m) for m in [mol2, mol3, mol4]]
similarities = DataStructs.BulkTanimotoSimilarity(fp1, fps)

# 其他相似性指标
dice = DataStructs.DiceSimilarity(fp1, fp2)
cosine = DataStructs.CosineSimilarity(fp1, fp2)

聚类与多样性：

# 基于指纹相似性的 Butina 聚类
from rdkit.ML.Cluster import Butina

# 计算距离矩阵
dists = []
mfpgen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fps = [mfpgen.GetFingerprint(mol) for mol in mols]
for i in range(len(fps)):
    sims = DataStructs.BulkTanimotoSimilarity(fps[i], fps[:i])
    dists.extend([1-sim for sim in sims])

# 使用距离阈值聚类
clusters = Butina.ClusterData(dists, len(fps), distThresh=0.3, isDistData=True)

6. 子结构搜索与 SMARTS

基本子结构匹配：

# 使用 SMARTS 定义查询
query = Chem.MolFromSmarts('[#6]1:[#6]:[#6]:[#6]:[#6]:[#6]:1')  # 苯环

# 检查分子是否包含子结构
has_match = mol.HasSubstructMatch(query)

# 获取所有匹配（返回包含原子索引的元组的元组）
matches = mol.GetSubstructMatches(query)

# 仅获取第一个匹配
match = mol.GetSubstructMatch(query)

常见 SMARTS 模式：

# 伯醇
primary_alcohol = Chem.MolFromSmarts('[CH2][OH1]')

# 羧酸
carboxylic_acid = Chem.MolFromSmarts('C(=O)[OH]')

# 酰胺
amide = Chem.MolFromSmarts('C(=O)N')

# 芳香杂环
aromatic_n = Chem.MolFromSmarts('[nR]')  # 环中的芳香氮

# 大环（> 12 个原子的环）
macrocycle = Chem.MolFromSmarts('[r{12-}]')

匹配规则：

• 查询中未指定的属性匹配目标中的任何值
• 除非显式指定，否则忽略氢原子
• 带电荷的查询原子不会匹配不带电荷的目标原子
• 芳香性查询原子不会匹配脂肪族目标原子（除非查询是通用的）

7. 化学反应

反应 SMARTS：

from rdkit.Chem import AllChem

# 使用 SMARTS 定义反应：反应物 >> 产物
rxn = AllChem.ReactionFromSmarts('[C:1]=[O:2]>>[C:1][O:2]')  # 酮还原

# 将反应应用于分子
reactants = (mol1,)
products = rxn.RunReactants(reactants)

# Products 是元组的元组（每组产物一个元组）
for product_set in products:
    for product in product_set:
        # 清理产物
        Chem.SanitizeMol(product)

反应特性：

• 原子映射保留反应物和产物之间的特定原子
• 产物中的虚拟原子被相应的反应物原子替换
• "任意"键从反应物继承键级
• 除非显式更改，否则手性保持不变

反应相似性：

# 生成反应指纹
fp = AllChem.CreateDifferenceFingerprintForReaction(rxn)

# 比较反应
similarity = DataStructs.TanimotoSimilarity(fp1, fp2)

8. 2D 和 3D 坐标生成

2D 坐标生成：

from rdkit.Chem import AllChem

# 为描绘生成 2D 坐标
AllChem.Compute2DCoords(mol)

# 将分子对齐到模板结构
template = Chem.MolFromSmiles('c1ccccc1')
AllChem.Compute2DCoords(template)
AllChem.GenerateDepictionMatching2DStructure(mol, template)

3D 坐标生成与构象：

# 使用 ETKDG 生成单个 3D 构象
AllChem.EmbedMolecule(mol, randomSeed=42)

# 生成多个构象
conf_ids = AllChem.EmbedMultipleConfs(mol, numConfs=10, randomSeed=42)

# 使用力场优化几何
AllChem.UFFOptimizeMolecule(mol)  # UFF 力场
AllChem.MMFFOptimizeMolecule(mol)  # MMFF94 力场

# 优化所有构象
for conf_id in conf_ids:
    AllChem.MMFFOptimizeMolecule(mol, confId=conf_id)

# 计算构象间的 RMSD
from rdkit.Chem import AllChem
rms = AllChem.GetConformerRMS(mol, conf_id1, conf_id2)

# 对齐分子
AllChem.AlignMol(probe_mol, ref_mol)

约束嵌入：

# 将分子部分约束到特定坐标进行嵌入
AllChem.ConstrainedEmbed(mol, core_mol)

9. 分子可视化

基本绘图：

from rdkit.Chem import Draw

# 将单个分子绘制为 PIL 图像
img = Draw.MolToImage(mol, size=(300, 300))
img.save('molecule.png')

# 直接绘制到文件
Draw.MolToFile(mol, 'molecule.png')

# 在网格中绘制多个分子
mols = [mol1, mol2, mol3, mol4]
img = Draw.MolsToGridImage(mols, molsPerRow=2, subImgSize=(200, 200))

突出显示子结构：

# 突出显示子结构匹配
query = Chem.MolFromSmarts('c1ccccc1')
match = mol.GetSubstructMatch(query)

img = Draw.MolToImage(mol, highlightAtoms=match)

# 自定义高亮颜色
highlight_colors = {atom_idx: (1, 0, 0) for atom_idx in match}  # 红色
img = Draw.MolToImage(mol, highlightAtoms=match,
                      highlightAtomColors=highlight_colors)

自定义可视化：

from rdkit.Chem.Draw import rdMolDraw2D

# 使用自定义选项创建绘图器
drawer = rdMolDraw2D.MolDraw2DCairo(300, 300)
opts = drawer.drawOptions()

# 自定义选项
opts.addAtomIndices = True
opts.addStereoAnnotation = True
opts.bondLineWidth = 2

# 绘制分子
drawer.DrawMolecule(mol)
drawer.FinishDrawing()

# 保存到文件
with open('molecule.png', 'wb') as f:
    f.write(drawer.GetDrawingText())

Jupyter Notebook 集成：

# 在 Jupyter 中启用内联显示
from rdkit.Chem.Draw import IPythonConsole

# 自定义默认显示
IPythonConsole.ipython_useSVG = True  # 使用 SVG 代替 PNG
IPythonConsole.molSize = (300, 300)   # 默认大小

# 分子现在自动显示
mol  # 显示分子图像

可视化指纹位：

# 显示指纹位代表的分子特征
from rdkit.Chem import Draw
from rdkit.Chem import rdFingerprintGenerator

# 对于 Morgan 指纹
additional_output = rdFingerprintGenerator.AdditionalOutput()
additional_output.AllocateBitInfoMap()
morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fp = morgan_gen.GetFingerprint(mol, additionalOutput=additional_output)
bit_info = additional_output.GetBitInfoMap()

# 绘制特定位的环境
img = Draw.DrawMorganBit(mol, bit_id, bit_info)

10. 分子修饰

添加/去除氢原子：

# 添加显式氢原子
mol_h = Chem.AddHs(mol)

# 去除显式氢原子
mol = Chem.RemoveHs(mol_h)

凯库勒化与芳香性：

# 将芳香键转换为交替单键/双键
Chem.Kekulize(mol)

# 设置芳香性
Chem.SetAromaticity(mol)

替换子结构：

# 用另一个结构替换子结构
query = Chem.MolFromSmarts('c1ccccc1')  # 苯
replacement = Chem.MolFromSmiles('C1CCCCC1')  # 环己烷

new_mol = Chem.ReplaceSubstructs(mol, query, replacement)[0]

中和电荷：

# 通过添加/去除氢原子去除形式电荷
from rdkit.Chem.MolStandardize import rdMolStandardize

# 使用 Uncharger
uncharger = rdMolStandardize.Uncharger()
mol_neutral = uncharger.uncharge(mol)

11. 分子哈希与标准化

分子哈希：

from rdkit.Chem import rdMolHash

# 生成 Murcko 骨架哈希
scaffold_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.MurckoScaffold)

# 规范 SMILES 哈希
canonical_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.CanonicalSmiles)

# 区域异构体哈希（忽略立体化学）
regio_hash = rdMolHash.MolHash(mol, rdMolHash.HashFunction.Regioisomer)

随机化 SMILES：

# 生成随机 SMILES 表示（用于数据增强）
from rdkit.Chem import MolToRandomSmilesVect

random_smiles = MolToRandomSmilesVect(mol, numSmiles=10, randomSeed=42)

12. 药效团与 3D 特征

药效团特征：

from rdkit.Chem import ChemicalFeatures
from rdkit import RDConfig
import os

# 加载特征工厂
fdef_path = os.path.join(RDConfig.RDDataDir, 'BaseFeatures.fdef')
factory = ChemicalFeatures.BuildFeatureFactory(fdef_path)

# 获取药效团特征
features = factory.GetFeaturesForMol(mol)

for feat in features:
    print(feat.GetFamily(), feat.GetType(), feat.GetAtomIds())

常见工作流

类药性分析

from rdkit import Chem
from rdkit.Chem import Descriptors

def analyze_druglikeness(smiles):
    mol = Chem.MolFromSmiles(smiles)
    if mol is None:
        return None

    # 计算利平斯基描述符
    results = {
        'MW': Descriptors.MolWt(mol),
        'LogP': Descriptors.MolLogP(mol),
        'HBD': Descriptors.NumHDonors(mol),
        'HBA': Descriptors.NumHAcceptors(mol),
        'TPSA': Descriptors.TPSA(mol),
        'RotBonds': Descriptors.NumRotatableBonds(mol)
    }

    # 检查利平斯基五规则
    results['Lipinski'] = (
        results['MW'] <= 500 and
        results['LogP'] <= 5 and
        results['HBD'] <= 5 and
        results['HBA'] <= 10
    )

    return results

相似性筛选

from rdkit import Chem
from rdkit.Chem import rdFingerprintGenerator
from rdkit import DataStructs

def similarity_screen(query_smiles, database_smiles, threshold=0.7):
    query_mol = Chem.MolFromSmiles(query_smiles)
    if query_mol is None:
        return []

    morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
    query_fp = morgan_gen.GetFingerprint(query_mol)

    hits = []
    for idx, smiles in enumerate(database_smiles):
        mol = Chem.MolFromSmiles(smiles)
        if mol:
            fp = morgan_gen.GetFingerprint(mol)
            sim = DataStructs.TanimotoSimilarity(query_fp, fp)
            if sim >= threshold:
                hits.append((idx, smiles, sim))

    return sorted(hits, key=lambda x: x[2], reverse=True)

子结构过滤

from rdkit import Chem

def filter_by_substructure(smiles_list, pattern_smarts):
    query = Chem.MolFromSmarts(pattern_smarts)

    hits = []
    for smiles in smiles_list:
        mol = Chem.MolFromSmiles(smiles)
        if mol and mol.HasSubstructMatch(query):
            hits.append(smiles)

    return hits

最佳实践

错误处理

解析分子时始终检查是否为 None：

mol = Chem.MolFromSmiles(smiles)
if mol is None:
    print(f"解析失败: {smiles}")
    continue

性能优化

使用安全的存储格式：

import base64
import json
from pathlib import Path
from rdkit import Chem

# SMILES 和 SDF 等可移植交换格式对共享数据最安全。
# 对于本地缓存，RDKit 的二进制分子表示避免了通用 pickle。
payload = [base64.b64encode(mol.ToBinary()).decode("ascii") for mol in mols]
Path("molecules.rdmol.json").write_text(json.dumps(payload))

cached = json.loads(Path("molecules.rdmol.json").read_text())
mols = [Chem.Mol(base64.b64decode(item)) for item in cached]

不要从未受信任的来源加载 Python pickle 文件。Pickle 反序列化可以执行任意代码；对于数据交换，优先使用 SMILES/SDF；对于受信任的本地缓存，使用 RDKit 二进制负载。

使用批量操作：

from rdkit import DataStructs
from rdkit.Chem import rdFingerprintGenerator

# 一次计算所有分子的指纹
morgan_gen = rdFingerprintGenerator.GetMorganGenerator(radius=2, fpSize=2048)
fps = [morgan_gen.GetFingerprint(mol) for mol in mols]

# 使用批量相似性计算
similarities = DataStructs.BulkTanimotoSimilarity(fps[0], fps[1:])

版本敏感行为

当精确的分子标识符或数值特征作为持久化数据集、模型特征管道或受监管报告的一部分时，请固定 RDKit 版本。最近的版本在多个 Python 接口领域更改或记录了行为：

• 规范 SMILES 和立体化学： 2026.03 更改了规范双键处理以避免立体化学损坏，因此一些包含立体化学的 SMILES 可能与旧版本不同。
• 描述符和哈希： 2024.09 修正了非支链烷烃片段描述符 SMARTS，并更改了某些互变异构/原体哈希输出。
• 绘图： 旧的 rdkit.Chem.Draw 画布模块和函数（如 MolToImageFile、MolToMPL 和 MolToQPixmap）已被移除；请使用 Draw.MolToFile、Draw.MolToImage 或 rdMolDraw2D。
• MolStandardize： 使用 rdkit.Chem.MolStandardize.rdMolStandardize；旧的 Python MolStandardize 实现已被移除。
• 相似性图： GetSimilarityMapFromWeights()、GetSimilarityMapForFingerprint() 和 GetSimilarityMapForModel() 现在需要 rdMolDraw2D 绘图对象。

线程安全

RDKit 操作通常在以下方面是线程安全的：

• 分子 I/O（SMILES、mol 块）
• 坐标生成
• 指纹生成和描述符
• 子结构搜索
• 反应
• 绘图

非线程安全： 同时访问的 MolSuppliers。

内存管理

对于大型数据集：

# 使用 ForwardSDMolSupplier 避免加载整个文件
with open('large.sdf') as f:
    suppl = Chem.ForwardSDMolSupplier(f)
    for mol in suppl:
        # 一次处理一个分子
        pass

# 使用 MultithreadedSDMolSupplier 进行并行处理
suppl = Chem.MultithreadedSDMolSupplier('large.sdf', numWriterThreads=4)

常见陷阱

1. 忘记检查 None： 解析后始终验证分子
2. 清理失败： 使用 DetectChemistryProblems() 进行调试
3. 缺少氢原子： 在计算依赖氢原子的属性时使用 AddHs()
4. 2D vs 3D： 在可视化或 3D 分析之前生成适当的坐标
5. SMARTS 匹配规则： 记住未指定的属性匹配任何值
6. MolSuppliers 的线程安全： 不要在线程间共享 supplier 对象

资源

references/

此技能包括详细的 API 参考文档：

• api_reference.md - RDKit 模块、函数和类的全面列表，按功能组织
• descriptors_reference.md - 可用分子描述符的完整列表及描述
• smarts_patterns.md - 官能团和结构特征的常见 SMARTS 模式

在需要特定 API 细节、参数信息或模式示例时加载这些参考文件。

只有 references/ 和 scripts/ 下列出的文件是捆绑的本地资源。rdkit、datamol、scipy 和 sklearn 等名称指的是可安装的 Python 包，而非此技能中的本地文件。

scripts/

常见 RDKit 工作流的示例脚本：

• molecular_properties.py - 计算全面的分子属性和描述符
• similarity_search.py - 执行基于指纹的相似性筛选
• substructure_filter.py - 按子结构模式过滤分子

这些脚本可以直接执行或用作自定义工作流的模板。