使用 CLI-Anything-Uni-Mol-Tools 构建药物活性二分类模型：从数据准备、超参数调优到生产部署的完整实战指南-平芜编程栈

使用 CLI-Anything-Uni-Mol-Tools 构建药物活性二分类模型：从数据准备、超参数调优到生产部署的完整实战指南

【免费下载链接】CLI-Anything"CLI-Anything: Making ALL Software Agent-Native" -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything

本篇技术指南以 Uni-Mol Tools 的 Agent 化 CLI 为工具，完整演示如何基于 SMILES 分子结构训练"活性/非活性"二分类模型：你将掌握分类数据的组织规范、项目创建与数据集绑定、基线训练与超参数调优、测试集评估与可视化、生产预测以及模型存储清理的全流程操作。全文以分类教程为骨架，并结合本仓库源码（CLI 入口、训练编排、后端适配、模型管理与存储清理模块）讲解每条命令背后的实现原理，确保每一步既可复制运行、又知其所以然。

前置准备：安装与环境配置

在开始分类任务之前，需要确保cli-anything-unimol-toolsCLI 已正确安装，并且 Uni-Mol 预训练权重可被定位。完整的安装步骤可参考安装指南，核心要点如下：

系统要求：

操作系统：Linux（文档标注在 Ubuntu 20.04+ 上测试通过）
Python：3.8 或更高
CUDA：11.8+（GPU 加速可选，CPU 亦可运行但速度较慢）
磁盘空间：约 2GB（Uni-Mol 模型权重约 1.5GB，依赖约 500MB）

安装链路（分两步）：

克隆 Uni-Mol 官方仓库并安装其unimol_tools子包，下载预训练权重（约 1.5GB）到unimol_tools/weights/目录；
克隆 CLI-Anything 仓库，进入unimol_tools/agent-harness目录后执行pip install -e .，安装cli-anything-unimol-tools命令。

安装后需要配置权重目录环境变量，CLI 依赖它定位分子编码所需的权重文件：

# 写入 shell 配置文件（~/.bashrc 或 ~/.zshrc） export UNIMOL_WEIGHT_DIR=/path/to/Uni-Mol/unimol_tools/unimol_tools/weights # 验证 echo $UNIMOL_WEIGHT_DIR ls $UNIMOL_WEIGHT_DIR/*.pt

从源码角度看，权重目录的注入由 CLI 入口完成：在 unimol_tools_cli.py 中，--weight-dir（-w）选项会将其写入os.environ['UNIMOL_WEIGHT_DIR']，二者等价，因此你也可以在每次调用时用-w临时指定权重目录。

验证安装：

cli-anything-unimol-tools --version cli-anything-unimol-tools --help

安装成功后--help会列出全部命令组，与 unimol_tools_cli.py 中的 Click 命令树一一对应：

命令	作用	主要子命令
`project`	项目管理	`new`、`info`、`set-dataset`
`train`	模型训练	`start`、`list`、`show`
`predict`	推理预测	`run`、`list`
`models`	模型管理	`rank`、`history`、`best`、`compare`
`storage`	存储分析	—
`cleanup`	模型清理	`--auto`自动模式
`archive`	归档管理	`list`、`restore`

说明：全局选项--json用于输出结构化 JSON（方便 Agent 与脚本解析），-p/--project指定项目文件路径。不指定子命令直接运行时会进入交互式 REPL 模式（见 unimol_tools_cli.py）。

任务理解：二分类目标与 CLI 架构

Objective：训练一个分类器，预测分子对某个生物靶点是否具有活性——活性（1）或非活性（0）。这是药物发现中最典型的分子性质预测任务之一。

你将学到：

准备分类数据（CSV 格式、类别分布）
训练并调优分类器（epochs、学习率、正则化）
评估模型性能（AUC、Accuracy、Precision、Recall、F1）
部署模型进行生产预测（新化合物批量打分）

时间成本：约 30 分钟；数据集规模：10 条训练样本 + 4 条验证样本 + 4 条测试样本的迷你示例集，用于走通全流程。

从实现上看，CLI 将任务类型硬编码为一组受支持的枚举。在 unimol_tools_cli.py 中，project new的-t/--task选项仅接受：

classification（二分类，本教程主题）
regression（回归）
multiclass（多分类）
multilabel_classification（多标签分类）
multilabel_regression（多标签回归）
repr（表示学习）

在 project.py 中，任务类型还决定了项目默认的优化指标：二分类使用auc，多分类使用acc，回归类任务使用mae。这意味着创建项目后无需手动指定指标，系统会根据任务自动选择。

Step 1：准备并检查分类数据

1.1 构造样本数据集

CLI 的数据格式要求为 CSV：第一列为SMILES（分子结构表示），第二列为label（0 或 1）。下面分别创建训练集、验证集和测试集。

训练数据（10 条）：

cat > drug_activity_train.csv << 'EOF' SMILES,label CC(C)Cc1ccc(cc1)C(C)C(O)=O,1 CCN(CC)C(=O)Cc1ccccc1,0 CC(C)NCC(COc1ccc(CCOCC(O)=O)cc1)O,1 CC(C)(C)NCC(O)COc1ccccc1CC=C,0 CCN(CC)C(=O)c1ccccc1,1 CC(C)Cc1ccc(cc1)C(C)C,0 CCc1ccccc1NC(=O)Cc1ccc(O)cc1,1 CC(C)NCC(O)c1ccc(O)c(CO)c1,0 CCN(CC)CCNC(=O)c1cc(I)c(O)c(I)c1,1 CC(C)NCC(O)COc1cccc2c1cccc2,0 EOF

验证数据（4 条）：

cat > drug_activity_valid.csv << 'EOF' SMILES,label CC(C)Cc1ccc(cc1)C(C)C(=O)O,1 CCN(CC)C(=O)Cc1ccc(Cl)cc1,0 CC(C)NCC(COc1ccc(CC(C)C)cc1)O,1 CC(C)(C)NCC(O)COc1ccc(Cl)cc1,0 EOF

测试数据（4 条）：

cat > drug_activity_test.csv << 'EOF' SMILES,label CC(C)Cc1ccc(cc1)C(C)C(=O)N,1 CCN(CC)C(=O)Cc1ccc(F)cc1,0 CC(C)NCC(COc1ccc(Br)cc1)O,1 CC(C)(C)NCC(O)COc1ccc(I)cc1,0 EOF

1.2 统计数据集

训练前先掌握数据规模与类别分布，便于判断是否存在样本量不足或类别失衡：

echo "Dataset Statistics:" echo "Train: $(tail -n +2 drug_activity_train.csv | wc -l) molecules" echo "Valid: $(tail -n +2 drug_activity_valid.csv | wc -l) molecules" echo "Test: $(tail -n +2 drug_activity_test.csv | wc -l) molecules" # Class distribution echo "" echo "Train Class Distribution:" tail -n +2 drug_activity_train.csv | cut -d',' -f2 | sort | uniq -c

预期输出为 Train: 10 molecules、Valid: 4 molecules、Test: 4 molecules，且训练集中类别 0 与类别 1 各 5 条（完全均衡）。均衡的类别分布对二分类的 Accuracy 指标解读至关重要——在不均衡数据上 Accuracy 会失真，这一点在后面的"常见问题排查"章节会再次提及。

Step 2：创建项目并绑定数据集

2.1 创建分类项目

# Create classification project cli-anything-unimol-tools project new \ -n drug_activity \ -t classification

该命令在 project.py 中完成项目目录与配置的初始化。每个项目会获得独立的目录结构：

drug_activity/ ├── project.json # 项目配置文件（含全部状态） ├── experiments/ # 训练运行的模型保存目录（run_001/run_002/...） ├── conformers/ # 3D 构象缓存 └── predictions/ # 预测结果输出

2.2 绑定训练/验证/测试数据集

PROJECT="drug_activity.json" cli-anything-unimol-tools -p $PROJECT \ project set-dataset train drug_activity_train.csv cli-anything-unimol-tools -p $PROJECT \ project set-dataset valid drug_activity_valid.csv cli-anything-unimol-tools -p $PROJECT \ project set-dataset test drug_activity_test.csv

set-dataset的底层实现在 project.py：它会校验数据集类型（仅允许train/valid/test）与文件存在性，并将路径保存为绝对路径写入project.json的datasets字段。

2.3 验证项目配置

cli-anything-unimol-tools -p $PROJECT project info

Expected Output：

📁 Project: drug_activity ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Type: classification Created: 2024-01-15 10:30:00 Status: initialized Datasets: Train: drug_activity_train.csv (10 samples) Valid: drug_activity_valid.csv (4 samples) Test: drug_activity_test.csv (4 samples) Models: 0 runs Storage: 0B

2.4 项目配置文件的默认参数

创建项目时会写入一组带默认值的训练配置（见 project.py）。理解这些默认值是后续调优的基础：

配置键	默认值	含义
`task`	`classification`	任务类型（决定指标与损失）
`model_name`	`unimolv1`	模型名称（可选`unimolv1`/`unimolv2`）
`model_size`	`None`（v1）/`84m`	v2 模型尺寸（84m/164m/310m/570m/1.1B）
`epochs`	`10`	训练轮数
`batch_size`	`16`	批大小
`learning_rate`	`1e-4`	学习率
`metrics`	`auc`	优化指标（由任务类型决定）
`split`	`random`	数据划分方式
`kfold`	`1`	交叉验证折数
`early_stopping`	`20`	早停 patience
`use_gpu`	`all`	GPU 使用策略（`none`表示 CPU）
`use_amp`	`False`	混合精度训练
`remove_hs`	`False`	是否去除氢原子
`conf_cache_level`	`1`	构象缓存级别

这些默认值会随项目配置一路传递给 Uni-Mol 的训练后端（见下文训练管线），因此你可以直接编辑project.json调整任意参数，也可以通过 CLI 开关覆盖其中一部分。

Step 3：训练基线模型

3.1 首次训练

# Train with default parameters cli-anything-unimol-tools -p $PROJECT train start \ --epochs 10 \ --batch-size 8

训练过程中发生了什么：

为每条 SMILES 生成 3D 构象（conformers）
用 Uni-Mol 编码分子（获得分子表征）
训练二分类器（在分子表征之上接分类头）
在验证集上评估（输出 AUC 等指标）

Expected Output：

🚀 Starting training... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Run ID: run_001 Save path: models/run_001 [1/3] Processing conformers... ━━━━━━━━━━━━━━━━━━ 100% [2/3] Training... Epoch 1/10: loss=0.693, auc=0.550 Epoch 2/10: loss=0.612, auc=0.650 Epoch 3/10: loss=0.523, auc=0.750 ... Epoch 10/10: loss=0.234, auc=0.875 [3/3] Evaluating... ✓ Training complete! Metrics: AUC: 0.8750 Accuracy: 0.80 Precision: 0.83 Recall: 0.75 F1 Score: 0.79 Training time: 18.3s Model saved: models/run_001/

3.2 底层调用链解析

train start命令看似简单，其背后是一条完整的三层调用链，值得拆解：

CLI 层：train start命令在 unimol_tools_cli.py 中接收--epochs/--batch-size/--lr/--gpus等选项，将非None的覆盖值写入项目配置对象，然后调用train_mod.run_training(proj)，训练结束后把更新后的项目（含新 run 记录）保存回project.json。
编排层：run_training在 train.py 中生成run_id（格式为run_001，按运行次数递增），确定保存路径<项目目录>/experiments/run_001，合并训练配置，并检查训练数据集是否已设置（未设置会抛出"Training dataset not set"错误），随后调用UniMolBackend().train(config)。
后端适配层：UniMolBackend.train在 unimol_backend.py 中实例化MolTrain（Uni-Mol 官方工具包的对象），将项目配置映射为MolTrain的构造参数（task、epochs、batch_size、learning_rate、early_stopping、metrics、split、kfold、remove_hs、conf_cache_level、target_normalize、use_cuda、use_ddp、use_amp、model_name等），随后调用clf.fit(data=...)完成训练。

训练完成后，后端会优先从 Uni-Mol 保存的metric.result文件中读取指标（若存在），否则回退使用fit()的返回值，并将其中的 NumPy 类型转换为 JSON 可序列化的 Python 原生类型（见_convert_metrics_to_json）。整个运行还会记录训练耗时duration_sec，供后续模型排名使用。

3.3 查看训练结果

cli-anything-unimol-tools -p $PROJECT models rank

models rank调用 models_manager.py 中的rank_models，对项目内全部 run 计算综合评分并按分数降序排列，同时给出状态标签：

AUC 范围	状态标签
≥ 0.85 且评分 ≥ 8.5	`Best`
≥ 0.85	`Good`
≥ 0.75	`Ok`
≥ 0.65	`Weak`
< 0.65	`Poor`

Step 4：超参数调优

基线模型（10 epochs，默认学习率）在验证集上 AUC 达到 0.875，已经可用。下一步通过调整超参数探索进一步提升空间。调优策略遵循"先加轮数、再降学习率、最后加正则"的经典顺序，便于定位瓶颈。

4.1 增加训练轮数

cli-anything-unimol-tools -p $PROJECT train start \ --epochs 20 \ --batch-size 8

4.2 调整学习率

在轮数加倍的基础上，将学习率从默认的1e-4降到5e-5，让权重更新更精细：

cli-anything-unimol-tools -p $PROJECT train start \ --epochs 20 \ --batch-size 8 \ --learning-rate 5e-5

4.3 加入正则化

若仍存在过拟合迹象，可在分类头上施加 dropout：

cli-anything-unimol-tools -p $PROJECT train start \ --epochs 20 \ --batch-size 8 \ --learning-rate 5e-5 \ --dropout 0.1

参数覆盖说明（以当前仓库源码为准）：在上述命令中，--epochs、--batch-size是 unimol_tools_cli.py 中train start直接暴露的开关；--learning-rate与--dropout属于文档演示的调参形式，当前版本 CLI 直接暴露的学习率开关为--lr，而 dropout 等更细粒度的超参数不在 CLI 开关中，需通过编辑项目文件drug_activity.json的config段传入后端。运行脚本化调参时建议优先使用--lr，其余超参数直接修改配置文件。更完整的自动化网格搜索方案（循环遍历 epochs/learning_rate/batch_size/dropout 组合并记录 AUC）可参考进阶教程中的"Batch Processing and Automation"一节。

4.4 对比各轮模型

# View performance history cli-anything-unimol-tools -p $PROJECT models history # Rank all models cli-anything-unimol-tools -p $PROJECT models rank

models history基于 models_manager.py 的get_model_history：按时间线绘制每个 run 的 AUC 条形图，并自动分析趋势（improving/declining/stable）与洞察（最佳模型、最近一次性能回落告警）。这是判断"调参是否真的在起作用"的最直观工具。

Step 5：模型评估

5.1 自动选择最佳模型

# Get best model BEST=$(cli-anything-unimol-tools --json -p $PROJECT models rank | \ jq -r '.models[0].run_id') echo "Best model: $BEST"

这里用到了全局--json选项。从 unimol_tools_cli.py 可以看到，JSON 模式下models rank输出{"models": [...]}结构，因此jq '.models[0].run_id'能取到排名第一的模型。这正是该 CLI 面向 Agent 与自动化脚本设计的体现。

综合评分score（0-10 分制）的计算逻辑在 models_manager.py 的calculate_model_score中：默认权重下主要由 AUC 决定（auc * 10），同时支持对训练时间（越快越好）与新鲜度（24 小时内为满分）的加权，可在调用处调整权重系数。

5.2 测试集推理

# Run predictions on test set cli-anything-unimol-tools -p $PROJECT predict run $BEST \ drug_activity_test.csv -o test_predictions.csv # View predictions cat test_predictions.csv

Expected Output：

SMILES,prediction,probability CC(C)Cc1ccc(cc1)C(C)C(=O)N,1,0.87 CCN(CC)C(=O)Cc1ccc(F)cc1,0,0.23 CC(C)NCC(COc1ccc(Br)cc1)O,1,0.91 CC(C)(C)NCC(O)COc1ccc(I)cc1,0,0.15

预测输出包含三列：SMILES（分子）、prediction（二分类决策 0/1）、probability（活性概率，用于计算 AUC 与置信度判断）。predict run的编排实现在 predict.py：它先按run_id定位已训练模型目录，再调用后端UniMolBackend.predict。后端在 unimol_backend.py 中通过MolPredict(load_model=...)加载模型并对输入数据打分，最终将结果写入用户指定的-o路径。

5.3 计算测试集指标

将真实标签与预测结果合并，使用 scikit-learn 计算完整指标：

import pandas as pd from sklearn.metrics import ( roc_auc_score, accuracy_score, precision_score, recall_score, f1_score, confusion_matrix, classification_report ) # Load test data and predictions test = pd.read_csv('drug_activity_test.csv') pred = pd.read_csv('test_predictions.csv') # Merge merged = test.merge(pred, on='SMILES') # Calculate metrics auc = roc_auc_score(merged['label'], merged['probability']) acc = accuracy_score(merged['label'], merged['prediction']) prec = precision_score(merged['label'], merged['prediction']) rec = recall_score(merged['label'], merged['prediction']) f1 = f1_score(merged['label'], merged['prediction']) print("Test Set Metrics:") print(f" AUC: {auc:.4f}") print(f" Accuracy: {acc:.4f}") print(f" Precision: {prec:.4f}") print(f" Recall: {rec:.4f}") print(f" F1 Score: {f1:.4f}") print() # Confusion matrix cm = confusion_matrix(merged['label'], merged['prediction']) print("Confusion Matrix:") print(cm) print() # Detailed report print("Classification Report:") print(classification_report(merged['label'], merged['prediction'], target_names=['Inactive', 'Active']))

Expected Output（示例数据较小，指标可能偏乐观）：

Test Set Metrics: AUC: 0.9375 Accuracy: 1.0000 Precision: 1.0000 Recall: 1.0000 F1 Score: 1.0000 Confusion Matrix: [[2 0] [0 2]] Classification Report: precision recall f1-score support Inactive 1.00 1.00 1.00 2 Active 1.00 1.00 1.00 2 accuracy 1.00 4 macro avg 1.00 1.00 1.00 4 weighted avg 1.00 1.00 1.00 4

关于指标解读的参考标准（来自原文档的 Metrics Reference）：

AUC：0.9-1.0 优秀、0.8-0.9 良好、0.7-0.8 尚可、0.6-0.7 较差、0.5-0.6 失败（相当于随机猜测）
Accuracy：整体正确率，仅适用于类别均衡的数据集
Precision：被预测为活性的分子中，真正活性的比例（关注误报）
Recall：真实活性分子中被正确预测出的比例（关注漏报）
F1 Score：Precision 与 Recall 的调和平均

在真实项目中，请务必使用规模更大、类别更均衡的测试集验证，并同时查看混淆矩阵与分类报告，而不要只看单一指标。

Step 6：可视化结果

可视化帮助判断模型是否真正学到了有区分度的概率分布，而不仅仅是"预测对了"。

6.1 ROC 曲线

import matplotlib.pyplot as plt from sklearn.metrics import roc_curve # Calculate ROC curve fpr, tpr, thresholds = roc_curve(merged['label'], merged['probability']) # Plot plt.figure(figsize=(8, 6)) plt.plot(fpr, tpr, linewidth=2, label=f'ROC (AUC = {auc:.3f})') plt.plot([0, 1], [0, 1], 'k--', linewidth=1, label='Random') plt.xlabel('False Positive Rate') plt.ylabel('True Positive Rate') plt.title('ROC Curve - Drug Activity Classifier') plt.legend() plt.grid(alpha=0.3) plt.savefig('roc_curve.png', dpi=150, bbox_inches='tight') print("ROC curve saved: roc_curve.png")

6.2 预测概率分布

# Separate by class inactive = merged[merged['label'] == 0]['probability'] active = merged[merged['label'] == 1]['probability'] # Plot fig, ax = plt.subplots(figsize=(10, 6)) ax.hist(inactive, bins=20, alpha=0.5, label='Inactive (0)', color='red') ax.hist(active, bins=20, alpha=0.5, label='Active (1)', color='green') ax.axvline(0.5, color='black', linestyle='--', linewidth=2, label='Threshold') ax.xlabel('Predicted Probability') ax.ylabel('Count') ax.title('Prediction Probability Distribution') ax.legend() plt.savefig('probability_distribution.png', dpi=150, bbox_inches='tight') print("Distribution saved: probability_distribution.png")

概率分布图的价值在于观察 0.5 阈值两侧两个类别的重叠程度：若两个分布高度重叠，说明模型置信度不足，可能需要调整决策阈值或补充训练数据；若存在明显分离（活性类集中于 0.8+，非活性类集中于 0.2-），则模型判别力良好。

Step 7：部署到生产环境

7.1 对新化合物批量打分

训练好的模型可以直接用于预测全新化合物（文件只需SMILES列，不需要标签）：

cat > new_compounds.csv << 'EOF' SMILES CC(C)Cc1ccc(cc1)C(C)C(=O)Cl CCN(CC)C(=O)Cc1ccc(NO2)cc1 CC(C)NCC(COc1ccc(CN)cc1)O CC(C)(C)NCC(O)COc1ccc(OH)cc1 EOF

cli-anything-unimol-tools -p $PROJECT predict run $BEST \ new_compounds.csv -o production_predictions.csv cat production_predictions.csv

7.2 解读预测结果

对生产输出进行置信度分级与语义化解读：

import pandas as pd pred = pd.read_csv('production_predictions.csv') # Classify confidence def classify_confidence(prob): if prob < 0.3 or prob > 0.7: return "High" elif prob < 0.4 or prob > 0.6: return "Medium" else: return "Low" pred['confidence'] = pred['probability'].apply(classify_confidence) # Add interpretation def interpret(row): if row['prediction'] == 1: return f"Active ({row['probability']:.2%} confidence)" else: return f"Inactive ({1-row['probability']:.2%} confidence)" pred['interpretation'] = pred.apply(interpret, axis=1) print(pred[['SMILES', 'prediction', 'probability', 'confidence', 'interpretation']])

置信度分级的思路是：概率远离 0.5 的判断可信度高（High），靠近 0.5 的判断可信度低（Low）——这类样本通常需要实验验证而非直接采信。这在药物筛选场景中尤为实用：优先选择概率极高（如 > 0.7）的化合物进入湿实验，低置信度化合物则可以放到后续轮次。

Step 8：存储管理与模型清理

每次训练都会在experiments/run_XXX/下生成一份完整模型，多次调参后磁盘占用会快速累积，需要定期治理。

8.1 查看存储占用

cli-anything-unimol-tools -p $PROJECT storage

storage命令在 storage.py 中实现：统计experiments/（模型）、conformers/（构象缓存）、predictions/（预测结果）三个目录的占用并给出百分比条形图，同时自动生成清理建议——例如"N 个模型超过 7 天未更新"或"N 个模型 AUC < 0.75"，并估算可释放空间。

8.2 仅保留最佳模型

# Automatic cleanup - keep best 1 model cli-anything-unimol-tools -p $PROJECT cleanup --auto --keep-best=1

cleanup的决策逻辑在 models_manager.py 的suggest_deletable_models中：先按综合评分排序保留 Top N（由--keep-best指定，默认 3），近期训练（7 天内）的模型也保留；对既不在 Top N 又不够新的模型，按 AUC 阈值（--min-auc，默认 0.75）分为"删除"（低分）与"归档"（尚可但陈旧）两类。--auto模式会跳过交互确认直接执行批量清理（见 unimol_tools_cli.py），并汇报删除数量与释放空间。

此外还提供归档机制：archive list可查看所有已归档模型（默认存放于~/.unimol-archive/下的tar.gz压缩包），archive restore <run_id>可将归档模型解压还原到experiments/目录继续使用，相关实现见 cleanup.py。

8.3 清理后验证

cli-anything-unimol-tools -p $PROJECT project info cli-anything-unimol-tools -p $PROJECT storage

常见问题排查

问题一：AUC 表现差（< 0.70）

可能原因：

训练数据不足
类别不平衡
SMILES 质量差（存在无法解析的分子）
训练轮数不足

解决方案：

# 增加训练轮数 cli-anything-unimol-tools -p $PROJECT train start --epochs 30 # 检查数据质量 python << EOF import pandas as pd from rdkit import Chem data = pd.read_csv('drug_activity_train.csv') print(f"Total: {len(data)}") print(f"Class 0: {(data['label']==0).sum()}") print(f"Class 1: {(data['label']==1).sum()}") # Validate SMILES invalid = [] for smi in data['SMILES']: if Chem.MolFromSmiles(smi) is None: invalid.append(smi) print(f"Invalid SMILES: {len(invalid)}") EOF

问题二：过拟合（训练 AUC 高、验证 AUC 低）

解决方案：增加 dropout 正则化：

cli-anything-unimol-tools -p $PROJECT train start \ --epochs 20 \ --dropout 0.2

（同样地，当前源码中dropout需要通过编辑项目配置drug_activity.json的config段传入，详见 Step 4 的参数覆盖说明。）

问题三：模型把所有样本预测为同一类别

原因：严重的类别不平衡。

解决方案：对多数类进行欠采样，构造均衡数据集：

import pandas as pd data = pd.read_csv('drug_activity_train.csv') # Separate classes class_0 = data[data['label'] == 0] class_1 = data[data['label'] == 1] # Undersample majority class min_size = min(len(class_0), len(class_1)) class_0_balanced = class_0.sample(min_size, random_state=42) class_1_balanced = class_1.sample(min_size, random_state=42) # Combine and shuffle balanced = pd.concat([class_0_balanced, class_1_balanced]) balanced = balanced.sample(frac=1, random_state=42).reset_index(drop=True) balanced.to_csv('drug_activity_train_balanced.csv', index=False)

最佳实践

1. 数据质量

训练前校验所有 SMILES 能否被 RDKit 解析
去除重复分子
尽量保持类别均衡
保证数据量充足（经验上每类 > 100 条分子）

2. 训练策略

先以默认参数训练基线（10 epochs），建立参考点
欠拟合时增加训练轮数
过拟合时添加 dropout 正则
始终使用验证集进行模型选择（不要用测试集调参）

3. 评估规范

始终在独立的测试集（held-out test set）上做最终评估
查看混淆矩阵定位错误模式
可视化 ROC 曲线确认判别能力
生产场景下考虑概率校准

4. 部署维护

为每个生产模型记录性能档案
根据业务场景设定决策阈值（如宁可漏报也要低误报）
上线后持续监控预测分布
定期用新数据重训，跟踪模型漂移

额外练习数据集（更大规模的真实公开数据）：MoleculeNet 系列中的 BACE（血脑屏障渗透，1522 分子）、BBBP（β-分泌酶抑制剂，1513 分子）、Tox21（毒性预测，7831 分子），均采用与本文相同的SMILES,labelCSV 格式，可用于替换示例数据验证全流程。

总结清单

准备类别均衡的分类数据（train/valid/test 三份 CSV）
创建并配置项目（project new+project set-dataset）
训练基线模型（train start，10 epochs）
调整超参数（epochs / 学习率 / dropout）
基于验证 AUC 选择最佳模型（models rank+--json）
在测试集上评估（AUC / Accuracy / Precision / Recall / F1 / 混淆矩阵）
可视化结果（ROC 曲线、概率分布）
部署生产预测（新化合物批量打分 + 置信度分级）
清理旧模型（storage分析 +cleanup --auto --keep-best）