基于 CLI-Anything 的 Uni-Mol Tools 分子性质预测实战指南：从项目创建到模型清理的 Agent-Native CLI 全流程

基于 CLI-Anything 的 Uni-Mol Tools 分子性质预测实战指南从项目创建到模型清理的 Agent-Native CLI 全流程【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-AnythingUni-Mol Tools 是一套面向分子性质预测的框架提供训练与推理的易用接口而本仓库中的 CLI-Anything harness 将其封装为可通过对话式 AI 直接驱动的命令行工具支持二分类、回归、多分类、多标签分类与多标签回归等任务。读完本文你将掌握从安装配置、项目创建、数据准备、模型训练、性能排名、存储清理到批量预测的完整操作流程并理解每个命令背后的源码实现原理可直接投入药物活性预测、溶解度回归等实际分子研究场景。一、概览Uni-Mol Tools 与 Agent-Native CLI 的架构定位Uni-Mol Tools 提供MolTrain、MolPredict、UniMolRepr等 Python API分别对应训练、预测与分子表征抽取本仓库在 unimol_tools/agent-harness 之上构建了一层 CLI harness让 LLM Agent 或人工终端用户都能通过统一命令完成分子建模。从源码结构看整条调用链为unimol_tools_cli.pyClick 命令解析→core/各模块项目、训练、预测、存储、清理、会话→utils/unimol_backend.py后端适配器→ 上游unimol_tools框架。核心入口 unimol_tools_cli.py 定义了顶层选项--json、--project/-p、--weight-dir/-w并挂载了project、train、predict、models、storage、cleanup、archive等命令组。支持的任务类型任务类型用途示例CLI 中的 task 取值二分类Binary Classification分子活性/非活性classification回归Regression结合亲和力、溶解度等连续性质regression多分类Multiclass Classification毒性等级低/中/高multiclass多标签分类Multilabel Classification同时标注多个 0/1 性质multilabel_classification多标签回归Multilabel Regression同时预测多个连续性质multilabel_regression另外源码 unimol_tools_cli.py 的project new还支持repr表征学习任务类型可用于分子表示抽取。二、安装与环境准备前置条件根据 01-INSTALLATION.md系统要求为LinuxUbuntu 20.04 测试通过、Python 3.8、GPU 场景需 CUDA 11.8、磁盘空间约 2GB其中 Uni-Mol 模型权重约 1.5GB。安装步骤要点克隆 Uni-Mol 官方仓库并进入unimol_tools子目录下载预训练权重python -m unimol_tools.weights.weighthub配置权重目录环境变量写入~/.bashrc或~/.zshrcexport UNIMOL_WEIGHT_DIR/path/to/Uni-Mol/unimol_tools/unimol_tools/weights在 unimol_tools/agent-harness 目录执行pip install -e .安装cli-anything-unimol-tools命令。验证cli-anything-unimol-tools --version cli-anything-unimol-tools --help除了环境变量方式CLI 入口也支持--weight-dir/-w显式指定权重目录见 unimol_tools_cli.py且该选项会同步写入UNIMOL_WEIGHT_DIR环境变量供后端调用。后端可用性检查后端适配器 unimol_backend.py 在初始化时检查unimol_tools是否可导入缺失时提示pip install unimol_tools --upgrade其is_available()静态方法还会探测 PyTorch 与 CUDA 状态torch.cuda.is_available()与显卡数量。三、项目管理SOP 第 1 步创建项目注意原文档 SOP 中写作project create而源码实际注册的子命令为project new且-n/--name与-t/--task均为必填项见 unimol_tools_cli.py。以源码为准真实命令为# 安装后的入口 cli-anything-unimol-tools project new -n my_first_project -t classification # 或通过模块方式执行 python3 -m cli_anything.unimol_tools --json project new --name my_first_project --task classificationproject new的完整选项包括-o/--output-dir输出目录默认当前目录.--model-nameunimolv1默认或unimolv2--model-size仅unimolv2生效可选84m/164m/310m/570m/1.1B从 project.py 的create_project实现看每个项目拥有独立目录保存为project.jsonmy_first_project/ ├── project.json # 项目配置与全部运行记录 ├── experiments/ # 训练实验模型检查点 ├── conformers/ # 3D 构象缓存SDF 文件 └── predictions/ # 预测结果 CSV项目默认配置源码级创建时写入config的默认值见 project.py配置项默认值说明epochs10训练轮数batch_size16批大小原文档 Performance Optimization 章节描述为 32源码创建逻辑实际默认 16learning_rate1e-4学习率metrics按任务自动选择二分类/多标签分类用auc多分类用acc回归类用maesplitrandom数据划分方式kfold1交叉验证折数early_stopping20早停轮数use_gpuallGPU 使用策略none则退化为 CPUremove_hsFalse是否去除氢原子conf_cache_level1构象缓存级别target_normalizeauto目标值归一化这些默认配置会原样透传给后端MolTrain见 unimol_backend.py。查看与配置项目# 查看项目信息类型、模型、数据集、运行/预测计数 cli-anything-unimol-tools -p my_first_project/project.json project info # 绑定训练数据train/valid/test 三类 cli-anything-unimol-tools -p my_first_project/project.json project set-dataset train train_data.csvset_dataset的合法类型仅train/valid/test且会校验文件存在见 project.py。四、数据格式要求CSV 基本结构所有输入 CSV 必须包含SMILES列分子结构与目标列训练用。示例如下SMILES,target CCO,1 CCCO,0 CC(C)O,1任务特定格式任务目标值要求二分类0/1 或 True/False回归浮点数多分类整数0, 1, 2, ...多标签分类多列目标各列 0/1多标签回归多列目标各列为浮点数多标签示例SMILES,label1,label2,label3 CC(C)Cc1ccc(cc1)C(C)C(O)O,1,1,0 CCN(CC)C(O)Cc1ccccc1,1,0,1更多数据准备细节可参考 tutorials/CLASSIFICATION.md 与 tutorials/REGRESSION.md。五、训练模型训练命令# 二分类药物活性预测 cli-anything-unimol-tools -p my_first_project/project.json \ train start --epochs 10 --batch-size 8 # 回归溶解度预测 cli-anything-unimol-tools -p my_first_project/project.json \ train start --epochs 10 --learning-rate 0.0001train start支持--epochs、--batch-size、--lr、--gpus四个覆盖参数见 unimol_tools_cli.py覆盖值会写回项目config并持久化。--gpus 0对应后端use_gpunone即纯 CPU 训练。训练流程的源码实现core/train.py 的run_training执行以下步骤校验train数据集已设置否则抛出ValueError自动生成运行 IDrun_{n:03d}如run_001模型保存至experiments/run_001/将项目配置合并save_path、data_path、valid_data_path后交给UniMolBackend.train训练结束后把run_id、timestamp、metrics、model_dir、duration_sec追加到project[runs]。后端 unimol_backend.py 调用MolTrain(...).fit(data...)并在训练后优先从save_path/metric.resultpickle 文件读取 Uni-Mol 落盘的指标再通过_convert_metrics_to_json将 numpy 数值转换为 JSON 可序列化格式。典型输出包含 AUC、Accuracy 与训练时长。查看训练记录# 列出所有训练运行 cli-anything-unimol-tools -p my_first_project/project.json train list # 查看指定运行详情 cli-anything-unimol-tools -p my_first_project/project.json train show run_001六、模型管理与性能排名排名与筛选# 按综合评分排名所有模型 cli-anything-unimol-tools -p my_first_project/project.json models rank排名算法位于 models_manager.py 的calculate_model_score以 AUC×10 为主评分0-10 分叠加训练时长分越快越高与新鲜度分24 小时内满分7 天后归零。状态阈值models_manager.py为AUC ≥ 0.85 为 Best/Good≥ 0.75 为 Ok≥ 0.65 为 Weak其余为 Poor。排第一的模型会获得 Use for production 推荐。其他模型管理命令# 查看最佳模型 cli-anything-unimol-tools -p my_first_project/project.json models best # 对比两个模型的逐指标胜负 cli-anything-unimol-tools -p my_first_project/project.json models compare run_001 run_002 # 查看性能随时间的变化趋势与洞察 cli-anything-unimol-tools -p my_first_project/project.json models historycompare会逐项比较auc/auroc/accuracy/acc/precision/recall/f1_score/mcc/log_loss与训练时长其中log_loss越小越好其余越大越好并按获胜次数给出overall_winner见 models_manager.py。七、存储管理与清理存储分析cli-anything-unimol-tools -p my_first_project/project.json storagestorage.py 的analyze_project_storage分别统计experiments/模型、conformers/3D 构象、predictions/预测结果三部分占用输出总量、各组件占比柱状图与清理建议。自动推荐规则为超过 7 天的旧模型、AUC 0.75 且超过 1 天的低性能模型。智能清理# 自动清理保留最佳 3 个AUC 阈值 0.75 cli-anything-unimol-tools -p my_first_project/project.json cleanup --auto # 自定义保留策略 cli-anything-unimol-tools -p my_first_project/project.json \ cleanup --auto --keep-best2 --min-auc0.8cleanup的判定逻辑位于 models_manager.py 的suggest_deletable_models保留 Top N 与近 7 天模型低 AUC 旧模型删除表现尚可的旧模型归档。--auto模式会直接执行batch_cleanup并报告释放空间不带--auto时进入交互选择自动清理/全部删除/全部归档/取消。归档管理# 列出归档 cli-anything-unimol-tools -p my_first_project/project.json archive list # 恢复归档模型到项目 cli-anything-unimol-tools -p my_first_project/project.json archive restore run_002归档默认压缩为 tar.gz 存放在~/.unimol-archive/详见 core/cleanup.py。八、预测推理# 使用指定模型对测试集预测输出到指定文件 cli-anything-unimol-tools -p my_first_project/project.json \ predict run run_001 test_data.csv -o predictions.csv # 不指定输出路径自动生成 predictions/pred_001.csv cli-anything-unimol-tools -p my_first_project/project.json \ predict run run_001 test_data.csv从 core/predict.py 看run_prediction会校验run_id存在且模型目录有效未指定-o时自动生成pred_{n:03d}.csv并记录pred_id/run_id/data_path/output_path/timestamp到项目。后端 unimol_backend.py 使用MolPredict(load_modelmodel_dir)先由上游产出{basename}.predict.0.csv再按需重命名为用户指定文件名。预测输入只需SMILES列如test_data.csv输出结果形如SMILES,prediction CC(C)Cc1ccc(cc1)C(C)C,0.87 CCN(CC)C(O)Cc1ccc,0.23九、会话管理与两种运行模式CLI 会在会话中维护以下状态见 UNIMOL_TOOLS.md当前项目通过-p/--project加载近期训练模型命令历史存储统计交互模式REPL# 不指定子命令即进入交互式 REPL python3 -m cli_anything.unimol_tools # 或安装后直接运行 cli-anything-unimol-tools入口代码在无子命令时创建ReplSkin并进入带unimol-tools提示符的交互循环见 unimol_tools_cli.py适合对话式 AI Agent 与人工逐步探索。一次性模式One-Shotpython3 -m cli_anything.unimol_tools --json command [options]顶层--json标志启用统一 JSON 输出见 unimol_tools_cli.py所有命令的返回结构status/message/数据字段被序列化为 JSON便于jq等工具做自动化管道BEST$(cli-anything-unimol-tools --json -p production/project.json models rank | jq -r .models[0].run_id) cli-anything-unimol-tools -p production/project.json predict run $BEST new_compounds.csv -o results.csv错误处理统一由handle_error装饰器完成JSON 模式输出{status:error,error:...,type:...}非 REPL 模式退出码为 1见 unimol_tools_cli.py。项目文件保存采用文件锁Unixfcntl或原子替换Windows避免并发写坏见 core/session.py。十、最佳实践为不同实验创建独立项目按研究目标组织模型project new会为每个项目分配独立目录与配置。定期监控存储使用storage分析磁盘占用重点关注experiments/目录。及时清理低性能模型用cleanup --auto删除欠佳模型、归档表现尚可的旧模型。用models rank比较性能以 0-10 综合评分 AUC 状态标签做生产模型选型依据。自动化场景启用--json为 Agent 调用与脚本管道提供结构化输出。多运行对比工作流依次用不同--epochs/--batch-size训练多轮再models compare/models rank择优。完整训练流程可参考 docs/workflows/TRAINING-SOP.md清理流程见 docs/workflows/CLEANUP-SOP.md。十一、故障排查现象解决方案训练报 CUDA out of memory减小--batch-size如 4或使用 CPU 模式export CUDA_VISIBLE_DEVICES后再训练CSV 文件无法识别确认存在SMILES列且格式正确检查project set-dataset路径有效模型找不到先运行models rank/models best确认正确的run_id存储空间不足运行cleanup --auto清理低性能模型或对旧模型执行archive归档权重文件找不到检查UNIMOL_WEIGHT_DIR是否正确指向含.pt文件的目录或用--weight-dir指定后端 ImportError确认已安装unimol_toolspip install unimol_tools --upgrade更多场景见 docs/guides/05-TROUBLESHOOTING.md。十二、性能调优建议Batch Size从默认配置源码中为 16起步出现显存不足时逐级调小至 8/4。Epochs默认 10欠拟合时可增至 20同时留意early_stopping默认 20 轮避免过拟合。Learning Rate默认0.0001依据损失曲线调整。数据划分默认随机划分训练/验证集可通过--kfold交叉验证增强评估可靠性构象通过conf_cache_level缓存到conformers/多次运行可显著提速。十三、测试验证仓库提供了完整的自动化测试可在 docs/test 目录运行# 单元测试无需后端 cd unimol_tools/agent-harness/docs/test bash run_tests.sh --unit -v # 完整测试套件含端到端 bash run_tests.sh --full -v单元测试覆盖项目管理核心逻辑例如 tests/test_core.py 验证了项目创建project.json生成、任务类型写入、加载不存在项目抛FileNotFoundError、数据集绑定与非法类型拒绝另有 test_all_tasks.py、test_models_manager.py、test_storage.py、test_cleanup.py 与 test_full_e2e.py 分别覆盖任务类型、模型排名、存储统计与清理流程。测试报告见 docs/test/TEST_REPORT.md。十四、扩展阅读快速上手教程docs/guides/02-QUICK-START.md基础命令参考docs/guides/03-BASIC-USAGE.md交互特性详解docs/guides/04-INTERACTIVE-FEATURES.mdAPI 参考docs/architecture/API.md架构设计docs/architecture/DESIGN.md高级用法docs/tutorials/ADVANCED.mdAgent 技能描述cli_anything/unimol_tools/SKILL.md【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考