deepchem

DeepChem

概述

DeepChem 是一个全面的 Python 库，可将机器学习应用于化学、材料科学和生物学。借助专用神经网络、分子特征化方法和预训练模型，实现分子性质预测、药物发现、材料设计和生物分子分析。

**版本说明：**示例面向 deepchem 2.8.0（PyPI 稳定版，2024 年 4 月）。需要 Python 3.7–3.11（PyPI 上要求 <3.12）。核心工具（加载器、特征化器、MoleculeNet）无需深度学习后端即可使用；GNN 和 Transformer 模型需要安装对应的额外依赖（torch、tensorflow 或 jax）。使用 GPU 构建版本时，请先安装后端框架。

何时使用此技能

在以下情况下应使用此技能：

• 加载和处理分子数据（SMILES 字符串、SDF 文件、蛋白质序列）
• 预测分子性质（溶解度、毒性、结合亲和力、ADMET 性质）
• 使用化学或生物数据集训练模型
• 使用 MoleculeNet 基准数据集（Tox21、BBBP、Delaney 等）
• 将分子转换为适用于机器学习的特征（指纹、图表示、描述符）
• 为分子实现图神经网络（GCN、GAT、MPNN、AttentiveFP）
• 使用预训练模型进行迁移学习（ChemBERTa、GROVER、MolFormer）
• 预测晶体或材料性质（带隙、形成能）
• 分析蛋白质或 DNA 序列

核心功能

references/core_capabilities.md 中提供了八类功能及其可运行代码：

1. 分子数据加载和处理——加载器、NumpyDataset / DiskDataset。
2. 分子特征化——循环指纹、图卷积和描述符。
3. 数据划分——随机、骨架、分层和 Butina 划分器，以及为什么骨架划分是分子的可靠默认选择。
4. 模型选择和训练——模型系列及其拟合方法。
5. MoleculeNet 基准测试——加载标准数据集及其已发布的划分。
6. 迁移学习——预训练和微调。
7. 模型评估——适用于回归和分类任务的指标。
8. 进行预测——将训练好的模型应用于新分子。

references/typical_workflows.md 中提供了三个端到端工作流。

示例脚本

此技能在 scripts/ 目录中包含三个可用于生产环境的脚本：

1. predict_solubility.py

训练和评估溶解度预测模型。适用于 Delaney 基准数据集或自定义 CSV 数据。

# Use Delaney benchmark
python scripts/predict_solubility.py

# Use custom data
python scripts/predict_solubility.py \
    --data my_data.csv \
    --smiles-col smiles \
    --target-col solubility \
    --predict "CCO" "c1ccccc1"

2. graph_neural_network.py

在分子数据上训练多种图神经网络架构。

# Train GCN on Tox21
python scripts/graph_neural_network.py --model gcn --dataset tox21

# Train AttentiveFP on custom data
python scripts/graph_neural_network.py \
    --model attentivefp \
    --data molecules.csv \
    --task-type regression \
    --targets activity \
    --epochs 100

3. transfer_learning.py

在分子性质预测任务上微调预训练模型（ChemBERTa、GROVER、MolFormer）。

# Fine-tune ChemBERTa on BBBP
python scripts/transfer_learning.py --model chemberta --dataset bbbp

# Fine-tune GROVER on custom data
python scripts/transfer_learning.py \
    --model grover \
    --data small_dataset.csv \
    --target activity \
    --task-type classification \
    --epochs 20

常见模式和最佳实践

模式 1：始终对分子使用骨架划分

# GOOD: Prevents data leakage
splitter = dc.splits.ScaffoldSplitter()
train, test = splitter.train_test_split(dataset)

# BAD: Similar molecules in train and test
splitter = dc.splits.RandomSplitter()
train, test = splitter.train_test_split(dataset)

模式 2：归一化特征和目标值

transformers = [
    dc.trans.NormalizationTransformer(
        transform_y=True,  # Also normalize target values
        dataset=train
    )
]
for transformer in transformers:
    train = transformer.transform(train)
    test = transformer.transform(test)

模式 3：从简单方法开始，再逐步扩展

1. 从随机森林 + CircularFingerprint 开始（快速基线）
2. 如果 RF 表现良好，尝试 XGBoost/LightGBM
3. 如果样本数 >5K，使用深度学习（MultitaskRegressor）
4. 如果样本数 >10K，尝试 GNN
5. 对小型数据集或新颖骨架使用迁移学习

模式 4：处理类别不平衡数据

# Option 1: Balancing transformer
transformer = dc.trans.BalancingTransformer(dataset=train)
train = transformer.transform(train)

# Option 2: Use balanced metrics
metric = dc.metrics.Metric(dc.metrics.balanced_accuracy_score)

模式 5：避免内存问题

# Use DiskDataset for large datasets
dataset = dc.data.DiskDataset.from_numpy(X, y, w, ids)

# Use smaller batch sizes
model = dc.models.GCNModel(batch_size=32)  # Instead of 128

常见问题

问题 1：药物发现中的数据泄漏

问题：使用随机划分会导致训练集和测试集中出现相似分子。 解决方案：对分子数据集始终使用 ScaffoldSplitter。

问题 2：GNN 表现不如指纹

问题：图神经网络的表现不如简单指纹。 解决方案：

• 确保数据集规模足够大（通常 >10K 个样本）
• 增加训练轮数（50–100）
• 尝试不同的架构（使用 AttentiveFP、DMPNN 替代 GCN）
• 使用预训练模型（GROVER）

问题 3：小数据集上的过拟合

问题：模型会记住训练数据。 解决方案：

• 使用更强的正则化（将 dropout 提高到 0.5）
• 使用更简单的模型（使用 Random Forest，而不是深度学习）
• 应用迁移学习（ChemBERTa、GROVER）
• 收集更多数据

问题 4：导入错误

问题：出现 No module named 'torch' / No module named 'tensorflow' 警告，或模型类导入失败。 解决方案：DeepChem 会延迟加载——安装与模型匹配的后端，然后添加对应的 extra：

uv pip install deepchem              # loaders, featurizers, MoleculeNet only
uv pip install 'deepchem[torch]'       # GCN, GAT, AttentiveFP, HuggingFaceModel, GroverModel
uv pip install 'deepchem[tensorflow]'  # legacy Keras models
uv pip install 'deepchem[jax]'         # Haiku/JAX models

使用 GPU 时，请先安装带正确 CUDA 构建的 PyTorch 或 TensorFlow，再安装 extra。在 zsh 中为 extras 加引号：'deepchem[torch]'。

**Conda + PyTorch 用户：**如果 import deepchem 因 undefined symbol: iJIT_NotifyEvent 而失败，请将 MKL 版本固定在 2025 以下（conda install "mkl<2025"）——PyTorch wheel 可能与 MKL 2025.0.0 不兼容。

参考文档

此技能包含全面的参考文档：

references/api_reference.md

完整的 API 文档，包括：

• 所有数据加载器及其使用场景
• 数据集类及各自的适用情况
• 完整的特征化器目录及选择指南
• 按类别整理的模型目录（50 多个模型）
• MoleculeNet 数据集说明
• 指标和评估函数
• 常见代码模式

何时查阅：需要具体的 API 详情、参数名称或了解可用选项时，请搜索此文件。

references/workflows.md

八个详细的端到端工作流：

1. 从 SMILES 预测分子属性
2. 使用 MoleculeNet 基准测试
3. 超参数优化
4. 使用预训练模型进行迁移学习
5. 使用 GAN 生成分子
6. 材料属性预测
7. 蛋白质序列分析
8. 自定义模型集成

何时查阅：将这些工作流用作实现完整解决方案的模板。

安装

核心软件包（数据加载器、特征化器、MoleculeNet、scikit-learn 封装器）：

uv pip install deepchem

添加与模型后端匹配的 extra（GPU 构建请先安装 PyTorch/TensorFlow/JAX）：

uv pip install 'deepchem[torch]'       # GNNs, TorchModel, HuggingFaceModel, GroverModel
uv pip install 'deepchem[tensorflow]'  # Keras/TensorFlow models
uv pip install 'deepchem[jax]'         # JAX/Haiku models
uv pip install 'deepchem[dqc]'         # Differentiable quantum chemistry (torch + xitorch)

夜间构建：uv pip install --pre deepchem（使用 --pre 时同样适用这些 extras）。

可查看安装指南和软性依赖要求，了解各模型类的可选依赖。

其他资源

• 官方文档：https://deepchem.readthedocs.io/
• GitHub 仓库：https://github.com/deepchem/deepchem
• 教程：https://deepchem.readthedocs.io/en/latest/get_started/tutorials.html
• 论文：“MoleculeNet：分子机器学习基准”

Agent 操作流程

1. 检查环境。 确认工具包版本和输入格式（SMILES、SDF、PDB、CIF），并在计算前清理分子。
2. 明确输入。 根据数据或用户确认格式、标识符和参数。任何会影响结果的值都应询问，不要猜测。
3. 先运行小规模任务。 先处理少量分子或一个目标，并检查输出。
4. 按照上述说明和参考资料执行完整任务。
5. 验证结果。 检查结构是否有效、单位是否一致，以及预测模型的适用域。
6. 报告。 说明运行了什么（版本、命令、参数）、检查了什么，以及哪些内容仍不确定。

如果发生这种情况	请这样做
分子无法解析或清理	说明原因并跳过；绝不静默丢弃或更改结构。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查阅已安装版本自己的文档（help()、--help、官方文档），进行适配并告知用户。绝不虚构 API。
必需的输入、标识符或参数不明确	询问用户，或在运行前明确说明假设。

完整性规则

• 绝不捏造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请明确说明。
• 计算预测是待验证的假设，而非实验结果；应明确标注。
• 此处与版本相关的细节可能已过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，请先征求同意。

相关技能

• torchdrug：构建和排查 TorchDrug 0.2.1 工作流，涵盖分子图、属性预测、自监督预训练、分子生成…
• pytdc：使用 PyTDC 软件包（导入 tdc，Therapeutics Data Commons），从 tdc.metadata 中发现治疗领域的 ML 任务，规划并加载获准的 d…
• molfeat：使用 molfeat（0.11.0）将 SMILES 字符串或 RDKit/datamol 分子转换为数值特征；它提供计算器、scikit-learn…