Uni-Mol Tools CLI 全指南基于 CLI-Anything 的交互式分子性质预测工作台【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本文完整讲解 CLI-Anything 生态中面向 Uni-Mol 的官方 CLI harness ——cli-anything-unimol-tools一个将 Uni-Mol 分子预训练模型封装为命令行工具用于交互式分子性质预测属性预测、回归、多标签建模的 Agent 原生工作台。读完本文你将掌握从环境安装、项目初始化、训练预测到存储分析、模型排名、智能清理与归档的完整工作流并能基于 JSON API 将分子性质预测自动化地接入脚本与 AI Agent 管线。本文以 docs/README.md 为骨架结合 安装指南、快速开始、基本用法、交互特性指南 与 架构设计 等子文档并对照仓库源码 unimol_tools_cli.py 与 unimol_backend.py 做源码级印证确保每条命令与参数都可查、可跑、可验证。一、Uni-Mol Tools CLI 是什么Uni-Mol Tools CLI 是 CLI-Anything 框架下为 Uni-Mol Tools 打造的命令行接口 harness定位是交互式分子性质预测。它让原本面向 Python API 的 Uni-Mol 训练/预测能力变成一组直观、可脚本化、可被 AI Agent 直接调用的子命令。从源码 unimol_tools_cli.py 可以看到入口是一个基于 Click 框架的命令组核心能力包括项目化工作流每个实验对应一个project.json配置文件集中管理数据集、超参数、训练记录5 类预测任务 表示学习二分类、回归、多分类、多标签分类、多标签回归以及repr分子表示提取交互式模型管理存储分析storage、性能排名models rank、历史趋势models history、智能清理cleanup与归档archive自动模型追踪每次训练写入metric.result记录性能历史与趋势JSON API所有命令支持--json输出便于脚本与 Agent 自动化。从源码 unimol_backend.py 看后端通过UniMolBackend门面类封装unimol_tools的MolTrain、MolPredict、UniMolRepr三个核心 API隔离了 RDKit 构象生成、模型训练、预测与指标提取等底层细节。二、环境要求与安装部署2.1 系统要求项目要求说明操作系统LinuxUbuntu 20.04 已验证文档声明的主要支持平台Python3.8需满足 CLI 与 Uni-Mol 依赖CUDA11.8可选GPU 加速CPU 模式可通过CUDA_VISIBLE_DEVICES运行磁盘空间约 2GB 起Uni-Mol 权重约 1.5GB依赖约 500MB安装前先做环境自检python --version # 应为 3.8 nvidia-smi # GPU 用户检查驱动与 CUDA git --version # 需要 git2.2 六步安装流程Step 1克隆 Uni-Mol 仓库git clone gitgithub.com:deepmodeling/Uni-Mol.git cd Uni-Mol/unimol_tools注意我们真正需要的是其中的unimol_tools/子目录包含weights/、models/、setup.py、requirements.txt。Step 2下载预训练权重python -m unimol_tools.weights.weighthub该命令会下载约 1.5GB 的预训练分子表示权重到unimol_tools/weights/。验证ls unimol_tools/weights/ # 应看到: mol_pre_all_h_220816.pt, mol_pre_no_h_220816.pt 等Step 3配置权重目录环境变量export UNIMOL_WEIGHT_DIR/path/to/Uni-Mol/unimol_tools/unimol_tools/weights echo export UNIMOL_WEIGHT_DIR/path/to/your/Uni-Mol/unimol_tools/unimol_tools/weights ~/.bashrc source ~/.bashrc从源码 unimol_tools_cli.py 可见CLI 还额外提供了-w/--weight-dir选项可在不修改环境变量的情况下临时指定权重目录——这是文档未强调、但脚本化场景中非常有用的补充方式。Step 4克隆 CLI-Anything 仓库cd ~/workspace git clone gitgithub.com:HKUDS/CLI-Anything.git cd CLI-Anything/unimol_tools/agent-harnessStep 5以可编辑模式安装 CLIpip install -e .安装后会提供cli-anything-unimol-tools命令并自动关联 Click、colorama 等依赖。Step 6验证安装cli-anything-unimol-tools --version cli-anything-unimol-tools --help--help应展示如下命令组与源码中 unimol_tools_cli.py 定义的子命令一一对应Usage: cli-anything-unimol-tools [OPTIONS] COMMAND [ARGS]... Options: -p, --project PATH 路径到 project JSON 文件 -w, --weight-dir PATH 自定义权重目录或设置 UNIMOL_WEIGHT_DIR --json 以 JSON 格式输出 --version 显示版本 --help 显示帮助 Commands: project 项目管理 train 训练命令 predict 运行预测 storage 存储分析 models 模型管理 cleanup 清理旧模型 archive 管理归档模型2.3 常见安装问题速查症状原因快速修复command not found未安装或不在 PATHpip install -e .或export PATH$HOME/.local/bin:$PATH或用python -m cli_anything.unimol_tools.unimol_tools_cli权重文件找不到UNIMOL_WEIGHT_DIR未设置/指向错误核对ls $UNIMOL_WEIGHT_DIR/*.pt重新 export 或重新运行 weighthubModuleNotFoundError: unimol_toolsUni-Mol 未安装在Uni-Mol/unimol_tools下pip install -e .CUDA 版本不匹配PyTorch 与驱动 CUDA 不一致安装匹配版本如torch2.0.0cu118或export CUDA_VISIBLE_DEVICES切 CPU完整的安装说明见 01-INSTALLATION.md故障排查见 05-TROUBLESHOOTING.md。三、5 分钟快速开始药物活性二分类3.1 创建项目cli-anything-unimol-tools project new -n my_first_project -t classification这会生成my_first_project.json。任务类型-t支持的可选值从源码 unimol_tools_cli.py 可见为classification、regression、multiclass、multilabel_classification、multilabel_regression、repr表示学习。3.2 准备数据并绑定数据集CSV 必须包含SMILES列大小写敏感标签列按任务类型命名。示例cat train_data.csv EOF SMILES,label CC(C)Cc1ccc(cc1)C(C)C(O)O,1 CCN(CC)C(O)Cc1ccccc1,0 EOF cli-anything-unimol-tools -p my_first_project.json project set-dataset train train_data.csv数据集拆分SPLIT支持train/valid/test路径必须是存在的文件源码中typeclick.Path(existsTrue)校验。3.3 训练cli-anything-unimol-tools -p my_first_project.json train start --epochs 10 --batch-size 8训练流程分三步与 TRAINING-SOP.md 描述一致为每个分子生成 3D 构象conformer用 Uni-Mol 编码分子并进行训练评估并将模型保存到models/run_001/指标写入metric.result。底层调用链见 unimol_backend.pyMolTrain(task..., epochs..., batch_size..., learning_rate..., metrics..., conf_cache_level..., ...).fit(data...)支持early_stopping、kfold、remove_hs、use_cuda、use_amp、model_name等参数透传并自动读取metric.result将指标转为 JSON 可序列化格式。3.4 预测cli-anything-unimol-tools -p my_first_project.json predict run run_001 test_data.csv -o predictions.csv分类任务输出SMILES,prediction,probability三列回归任务输出SMILES,prediction两列。后端会处理 Uni-Mol「输出路径按目录处理」的怪癖当-o以.csv结尾时自动重命名到目标文件见 unimol_backend.py。完整的端到端示例含project info、models rank、storage、cleanup的演示输出见 02-QUICK-START.md。四、支持的任务类型与数据格式原文档 README.md 列出 5 类任务结合 02-QUICK-START.md 与源码补充的repr汇总如下任务类型-t取值标签格式典型场景二分类classificationlabel: 0/1药物活性active/inactive回归regressiontarget: 浮点数溶解度预测多分类multiclasslabel: 0,1,2,...毒性等级低/中/高多标签分类multilabel_classificationlabel1,label2,...: 0/1多目标药物属性多标签回归multilabel_regressionprop1,prop2,...: 浮点多个分子性质表示学习repr仅需 SMILES提取分子向量特征各任务数据格式示例# 二分类 SMILES,label CC(C)Cc1ccc(cc1)C(C)C(O)O,1 # 回归 SMILES,target CC(C)Cc1ccc(cc1)C(C)C(O)O,-2.45 # 多分类 SMILES,label CCN(CC)C(O)Cc1ccccc1,2 # 多标签分类 SMILES,label1,label2,label3 CC(C)Cc1ccc(cc1)C(C)C(O)O,1,1,0 # 多标签回归 SMILES,prop1,prop2,prop3 CC(C)Cc1ccc(cc1)C(C)C(O)O,2.45,1.23,0.87需要提醒的是文档 03-BASIC-USAGE.md 中书写为multilabel_cls/multilabel_reg而源码中 Click 校验的合法值是multilabel_classification/multilabel_regression见 unimol_tools_cli.py。实际使用时请以源码为准使用下划线全称形式。每个任务的完整数据格式说明见 03-BASIC-USAGE.md 与 02-QUICK-START.md。五、命令参考项目管理、训练与预测5.1 全局选项选项说明示例-p, --project PATH项目 JSON 文件路径-p myproject.json-w, --weight-dir PATH权重目录可替代环境变量-w /data/weights--jsonJSON 结构化输出供自动化--json--version显示版本--version5.2project项目管理# 创建项目 cli-anything-unimol-tools project new -n drug_activity -t classification # 查看项目信息数据集、模型列表、存储占用 cli-anything-unimol-tools -p drug_activity.json project info # 绑定数据集 cli-anything-unimol-tools -p drug_activity.json project set-dataset train data/train.csv cli-anything-unimol-tools -p drug_activity.json project set-dataset valid data/valid.csv cli-anything-unimol-tools -p drug_activity.json project set-dataset test data/test.csvproject new还支持-o/--output-dir指定输出目录、--model-name指定unimolv1/unimolv2、--model-size指定 v2 模型尺寸84m/164m/310m/570m/1.1B详见源码 unimol_tools_cli.py。5.3train训练# 默认参数训练 cli-anything-unimol-tools -p project.json train start # 自定义超参数 cli-anything-unimol-tools -p project.json train start \ --epochs 30 --batch-size 32 --lr 5e-5 # 查看训练记录 cli-anything-unimol-tools -p project.json train list cli-anything-unimol-tools -p project.json train show run_001源码中train start的 CLI 参数为--epochs、--batch-size、--lr、--gpusunimol_tools_cli.py会直接覆盖project.json中config字段后调用train_mod.run_training。更多底层参数dropout、conf_cache_level、early_stopping、kfold、use_amp等通过后端透传给MolTrain可在项目配置中调整。构象缓存级别conf-cache-level级别行为特点0不缓存每次重新生成最慢、磁盘占用最小1生成一次并缓存复用默认推荐2严格复用已有缓存最快要求预先生成5.4predict预测# 基本预测 cli-anything-unimol-tools -p project.json predict run run_001 test.csv # 指定输出文件 cli-anything-unimol-tools -p project.json predict run run_001 test.csv -o results.csv # 用排名最优模型预测 BEST$(cli-anything-unimol-tools --json -p project.json models rank | jq -r .models[0].run_id) cli-anything-unimol-tools -p project.json predict run $BEST new_data.csv -o output.csv预测流程DESIGN.md解析参数 → 加载 project.json → 校验 run_id →UniMolBackend.predict()加载 CSV、生成构象、加载 checkpoint、推理→ 保存 CSV → 展示结果。六、交互式模型管理存储、排名、历史、清理、归档这是该 CLI 区别于普通训练脚本的核心卖点完整文档见 04-INTERACTIVE-FEATURES.md。6.1storage存储分析cli-anything-unimol-tools -p project.json storage输出模型checkpoint.pth、构象.sdf 缓存、预测.csv三类组件的占用比例、模型明细并给出可回收空间建议。源码实现在 core/storage.py采用os.walk()快速扫描检测重复 SDF 文件并计算潜在节省空间。6.2models rank模型排名cli-anything-unimol-tools -p project.json models rank评分机制当前 100% 基于 AUCScore AUC × 10范围 0–10。状态标签阈值状态条件BestAUC ≥ 0.85 且 score ≥ 8.5GoodAUC ≥ 0.85OkAUC ≥ 0.75WeakAUC ≥ 0.65PoorAUC 0.65从源码 models_manager.py 的函数签名calculate_model_score(run, weight_auc1.0, weight_time0.0, weight_recency0.0)可推断评分算法预留了「训练时长」「新近度」的权重扩展位未来可将 AUC 加权扩展为多因子评分。6.3models history性能历史与趋势cli-anything-unimol-tools -p project.json models history按时间顺序展示 AUC 与训练时长条形图并给出趋势判断Improving最新 AUC 比首个高 0.05Declining最新 AUC 比首个低 0.05Stable变化 0.05Insufficient data不足 2 个模型。适合用于识别平台期trend 为 stable 时考虑换超参/加数据/换架构与性能回退预警可脚本化检查jq -r .trend。6.4cleanup智能清理# 交互模式推荐首次使用会展示将删除/归档/保留的清单 cli-anything-unimol-tools -p project.json cleanup # 自动模式 cli-anything-unimol-tools -p project.json cleanup --auto --keep-best2选项默认值说明--autoFalse免确认自动执行--keep-best3保留排名前 N 的模型--min-auc0.75AUC 低于阈值则删除--max-age-days7保留 N 天内的近期模型清理策略将模型分为三组删除低 AUC 旧 不在 Top N、归档中等性能但较旧、保留Top N 近期模型。交互模式的输出会在执行前展示每类清单与可节省空间选择 1-4 执行自动清理 / 全部删除 / 全部归档 / 取消。源码中cleanup命令对应 unimol_tools_cli.py。6.5archive归档管理# 列出归档 cli-anything-unimol-tools archive list # 恢复归档模型 cli-anything-unimol-tools -p project.json archive restore run_002归档机制使用 tar.gz 将 checkpoint、配置、指标压缩到约原体积的 10%如 180MB → 18MB默认存放于~/.unimol-archive/文件命名格式为{project_name}_{run_id}.tar.gz。安全性设计仅当归档成功且完整性校验通过后才删除原模型。源码见 core/cleanup.py 的delete_model/archive_model/restore_model/batch_cleanup/list_archives。七、JSON API让分子性质预测可自动化所有命令支持--json输出机器可读结构这是 Agent 与脚本接入的关键接口。# 程序化获取最优模型 BEST$(cli-anything-unimol-tools --json -p project.json models rank | jq -r .models[0].run_id) # 程序化监控存储并自动清理 USAGE$(cli-anything-unimol-tools --json -p project.json storage | jq -r .total_mb) if [ $USAGE -gt 500 ]; then cli-anything-unimol-tools -p project.json cleanup --auto fi # 批量训练多种配置 for epochs in 10 20 30; do cli-anything-unimol-tools -p project.json train start --epochs $epochs donemodels rank --json返回结构示例文档 04-INTERACTIVE-FEATURES.md{ models: [ { rank: 1, run_id: run_003, score: 9.1, auc: 0.9123, duration_sec: 26.8, status: Best, timestamp: 2024-01-15T12:34:56 } ], recommendation: { run_id: run_003, reason: Highest AUC (0.9123) } }从源码 unimol_tools_cli.py 看output()统一封装了 JSON 与人类可读两种渲染路径--json模式下错误也会以{status:error,error:...,type:...}结构返回便于上层捕获。八、架构设计与实现原理8.1 分层架构架构设计文档 描述了从用户到文件系统的五层结构User │ ▼ CLI InterfaceClick 框架命令路由 │ ▼ Core Modulesstorage.py / models_manager.py / cleanup.py │ ▼ Project Managementproject.json 状态管理 │ ▼ Uni-Mol Backendunimol_backend.py 门面层 │ ▼ Uni-Mol 库分子编码器 / 预训练权重 / 3D 构象 │ ▼ File Systemmodels/ run_001/、conformers/ *.sdf、predictions/ *.csv、~/.unimol-archive/8.2 核心模块职责对应源码模块文件路径职责CLI 入口unimol_tools_cli.py命令路由、全局选项、统一输出、错误处理存储分析core/storage.py目录扫描、重复检测、优化建议模型管理core/models_manager.py排名、历史、趋势、删除建议分类清理归档core/cleanup.py删除、归档、恢复、批量操作后端门面utils/unimol_backend.py封装 MolTrain/MolPredict/UniMolRepr、指标转换会话管理core/session.py项目文件加载与上下文项目状态core/project.py项目创建、信息展示、数据集绑定8.3 项目状态模型project.jsonproject.json是单一事实来源Repository 模式结构如下来自 DESIGN.md{ project_name: drug_discovery, task_type: classification, created: 2024-01-15T10:30:00, project_root: /path/to/project, datasets: { train: data/train.csv, valid: data/valid.csv, test: data/test.csv }, runs: [ { run_id: run_001, timestamp: 2024-01-15T11:00:00, config: {epochs: 10, batch_size: 16, learning_rate: 0.0001}, metrics: {auc: 0.8723, accuracy: 0.85, precision: 0.83, recall: 0.87}, duration_sec: 18.3, save_path: models/run_001 } ] }状态机initialized → training → trained → deployed失败时为failed。JSON 持久化保证人类可读、可版本控制、易备份。8.4 设计模式命令模式Click 装饰器实现命令结构清晰、易扩展门面模式UniMolBackend屏蔽 Uni-Mol 复杂性便于测试与后端替换策略模式cleanup 通过参数组合实现不同清理策略保守/激进仓库模式project.json 作为数据存储。8.5 测试验证仓库在 tests/ 下提供完整测试套件test_all_tasks.py、test_models_manager.py、test_cleanup.py、test_storage.py、test_full_e2e.py等。例如 test_all_tasks.py 验证了每种任务类型的完整流程创建项目 → 断言project_type/config.task/config.metrics auc→ 设置数据集 → 保存并重新加载校验。test_calculate_model_score断言 AUC 0.8723 → 得分 8.723印证了评分公式。九、进阶用法与实战工作流9.1 典型工作流实验 → 选优 → 部署# 1. 多次实验 for epochs in 10 20 30; do cli-anything-unimol-tools -p project.json train start --epochs $epochs done # 2. 查看历史与排名 cli-anything-unimol-tools -p project.json models history cli-anything-unimol-tools -p project.json models rank # 3. 选出最优模型 BEST$(cli-anything-unimol-tools --json -p project.json models rank | jq -r .models[0].run_id) # 4. 清理其余归档 cli-anything-unimol-tools -p project.json cleanup --auto --keep-best1 # 5. 部署预测 cli-anything-unimol-tools -p project.json predict run $BEST production_data.csv9.2 超参数网格搜索for lr in 1e-5 5e-5 1e-4; do for bs in 8 16 32; do for dropout in 0.0 0.1 0.2; do cli-anything-unimol-tools -p tuning.json train start \ --epochs 20 --learning-rate $lr --batch-size $bs --dropout $dropout done done done cli-anything-unimol-tools -p tuning.json models rank cli-anything-unimol-tools -p tuning.json cleanup --auto --keep-best39.3 模型对比与表示学习源码还提供了文档索引中未展开的额外命令models best展示最优模型与models compare run_001 run_002逐指标对比两个模型输出各项胜者以及repr任务类型对应的get_representation基于UniMolRepr提取分子 CLS 表示支持unimolv1/unimolv2v2 可选model_size见 unimol_backend.py。完整进阶教程见 ADVANCED.md。9.4 最佳实践清单定期监控存储训练前后运行storage实验后及时清理cleanup --auto --keep-best2用排名而非直觉选模型脚本化取models[0].run_id不确定时归档而非删除交互模式选择 Archive 选项追踪趋势models history判断是否进入平台期数据质量优先训练前用 RDKit 校验 SMILES、去重、平衡类别首轮生成构象较慢属正常缓存开启后后续轮次显著加速。十、故障排查速查表完整排查指南见 05-TROUBLESHOOTING.md核心问题速查问题快速修复命令找不到pip install -e .或补充 PATH权重缺失设置UNIMOL_WEIGHT_DIR指向含.pt文件的目录CUDA 内存不足--batch-size 4或export CUDA_VISIBLE_DEVICES训练缓慢确认构象缓存开启默认 level 1小数据先行验证head -n 51 train.csv train_small.csv指标为空{}检查models/run_001/metric.result是否存在必要时重训预测文件路径异常CLI 已自动处理.csv重命名旧问题可find . -name predict.csv手动移动SMILES 列找不到CSV 首列须为SMILES大小写敏感可用sed -i 1s/smiles/SMILES/修正清理过于激进保守参数--keep-best5 --min-auc0.60 --max-age-days30或先用交互模式预览归档恢复失败先archive list确认 run_id 精确匹配排障还支持UNIMOL_DEBUG1开启详细日志以及将训练日志输出到models/run_001/train.log。十一、文档地图与后续学习本 CLI 的完整文档体系原文档 README.md 结构docs/ ├── README.md # 本文档入口 ├── guides/ │ ├── 01-INSTALLATION.md # 完整安装指南 │ ├── 02-QUICK-START.md # 5 分钟快速上手 │ ├── 03-BASIC-USAGE.md # 全命令参考 │ ├── 04-INTERACTIVE-FEATURES.md # 交互特性详解 │ └── 05-TROUBLESHOOTING.md # 常见问题 ├── tutorials/ │ ├── CLASSIFICATION.md # 二分类完整教程含 ROC、混淆矩阵、部署 │ ├── REGRESSION.md # 回归教程 │ └── ADVANCED.md # 多分类/多标签/自动化进阶 ├── architecture/ │ ├── DESIGN.md # 架构设计 │ └── API.md # API 参考 └── workflows/ ├── TRAINING-SOP.md # 训练标准作业流程 ├── CLEANUP-SOP.md # 清理标准作业流程 └── DIAGRAMS.md # 工作流图推荐学习路径安装指南 → 快速开始 → 二分类教程CLASSIFICATION.md约 30 分钟覆盖数据准备、基线训练、超参调优、测试集评估、可视化与生产部署→ 基本用法 → 交互特性 → 架构设计。仓库还提供了可运行的演示脚本 demo_real_examples.sh 与 test_features.sh 以及测试报告文档可作为安装后自检与探索入口。无论你是手工做药物活性筛选的研究人员还是希望把分子性质预测集成进自动化管线的 Agent 开发者cli-anything-unimol-tools都提供了从「数据 → 训练 → 评估 → 选优 → 部署 → 治理」的完整闭环而这一切只需要一组简单、可组合、可脚本化的命令行。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Uni-Mol Tools CLI 全指南基于 CLI-Anything 的交互式分子性质预测工作台【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything导读本文完整讲解 CLI-Anything 生态中面向 Uni-Mol 的官方 CLI harness ——cli-anything-unimol-tools一个将 Uni-Mol 分子预训练模型封装为命令行工具用于交互式分子性质预测属性预测、回归、多标签建模的 Agent 原生工作台。读完本文你将掌握从环境安装、项目初始化、训练预测到存储分析、模型排名、智能清理与归档的完整工作流并能基于 JSON API 将分子性质预测自动化地接入脚本与 AI Agent 管线。本文以 docs/README.md 为骨架结合 安装指南、快速开始、基本用法、交互特性指南 与 架构设计 等子文档并对照仓库源码 unimol_tools_cli.py 与 unimol_backend.py 做源码级印证确保每条命令与参数都可查、可跑、可验证。一、Uni-Mol Tools CLI 是什么Uni-Mol Tools CLI 是 CLI-Anything 框架下为 Uni-Mol Tools 打造的命令行接口 harness定位是交互式分子性质预测。它让原本面向 Python API 的 Uni-Mol 训练/预测能力变成一组直观、可脚本化、可被 AI Agent 直接调用的子命令。从源码 unimol_tools_cli.py 可以看到入口是一个基于 Click 框架的命令组核心能力包括项目化工作流每个实验对应一个project.json配置文件集中管理数据集、超参数、训练记录5 类预测任务 表示学习二分类、回归、多分类、多标签分类、多标签回归以及repr分子表示提取交互式模型管理存储分析storage、性能排名models rank、历史趋势models history、智能清理cleanup与归档archive自动模型追踪每次训练写入metric.result记录性能历史与趋势JSON API所有命令支持--json输出便于脚本与 Agent 自动化。从源码 unimol_backend.py 看后端通过UniMolBackend门面类封装unimol_tools的MolTrain、MolPredict、UniMolRepr三个核心 API隔离了 RDKit 构象生成、模型训练、预测与指标提取等底层细节。二、环境要求与安装部署2.1 系统要求项目要求说明操作系统LinuxUbuntu 20.04 已验证文档声明的主要支持平台Python3.8需满足 CLI 与 Uni-Mol 依赖CUDA11.8可选GPU 加速CPU 模式可通过CUDA_VISIBLE_DEVICES运行磁盘空间约 2GB 起Uni-Mol 权重约 1.5GB依赖约 500MB安装前先做环境自检python --version # 应为 3.8 nvidia-smi # GPU 用户检查驱动与 CUDA git --version # 需要 git2.2 六步安装流程Step 1克隆 Uni-Mol 仓库git clone gitgithub.com:deepmodeling/Uni-Mol.git cd Uni-Mol/unimol_tools注意我们真正需要的是其中的unimol_tools/子目录包含weights/、models/、setup.py、requirements.txt。Step 2下载预训练权重python -m unimol_tools.weights.weighthub该命令会下载约 1.5GB 的预训练分子表示权重到unimol_tools/weights/。验证ls unimol_tools/weights/ # 应看到: mol_pre_all_h_220816.pt, mol_pre_no_h_220816.pt 等Step 3配置权重目录环境变量export UNIMOL_WEIGHT_DIR/path/to/Uni-Mol/unimol_tools/unimol_tools/weights echo export UNIMOL_WEIGHT_DIR/path/to/your/Uni-Mol/unimol_tools/unimol_tools/weights ~/.bashrc source ~/.bashrc从源码 unimol_tools_cli.py 可见CLI 还额外提供了-w/--weight-dir选项可在不修改环境变量的情况下临时指定权重目录——这是文档未强调、但脚本化场景中非常有用的补充方式。Step 4克隆 CLI-Anything 仓库cd ~/workspace git clone gitgithub.com:HKUDS/CLI-Anything.git cd CLI-Anything/unimol_tools/agent-harnessStep 5以可编辑模式安装 CLIpip install -e .安装后会提供cli-anything-unimol-tools命令并自动关联 Click、colorama 等依赖。Step 6验证安装cli-anything-unimol-tools --version cli-anything-unimol-tools --help--help应展示如下命令组与源码中 unimol_tools_cli.py 定义的子命令一一对应Usage: cli-anything-unimol-tools [OPTIONS] COMMAND [ARGS]... Options: -p, --project PATH 路径到 project JSON 文件 -w, --weight-dir PATH 自定义权重目录或设置 UNIMOL_WEIGHT_DIR --json 以 JSON 格式输出 --version 显示版本 --help 显示帮助 Commands: project 项目管理 train 训练命令 predict 运行预测 storage 存储分析 models 模型管理 cleanup 清理旧模型 archive 管理归档模型2.3 常见安装问题速查症状原因快速修复command not found未安装或不在 PATHpip install -e .或export PATH$HOME/.local/bin:$PATH或用python -m cli_anything.unimol_tools.unimol_tools_cli权重文件找不到UNIMOL_WEIGHT_DIR未设置/指向错误核对ls $UNIMOL_WEIGHT_DIR/*.pt重新 export 或重新运行 weighthubModuleNotFoundError: unimol_toolsUni-Mol 未安装在Uni-Mol/unimol_tools下pip install -e .CUDA 版本不匹配PyTorch 与驱动 CUDA 不一致安装匹配版本如torch2.0.0cu118或export CUDA_VISIBLE_DEVICES切 CPU完整的安装说明见 01-INSTALLATION.md故障排查见 05-TROUBLESHOOTING.md。三、5 分钟快速开始药物活性二分类3.1 创建项目cli-anything-unimol-tools project new -n my_first_project -t classification这会生成my_first_project.json。任务类型-t支持的可选值从源码 unimol_tools_cli.py 可见为classification、regression、multiclass、multilabel_classification、multilabel_regression、repr表示学习。3.2 准备数据并绑定数据集CSV 必须包含SMILES列大小写敏感标签列按任务类型命名。示例cat train_data.csv EOF SMILES,label CC(C)Cc1ccc(cc1)C(C)C(O)O,1 CCN(CC)C(O)Cc1ccccc1,0 EOF cli-anything-unimol-tools -p my_first_project.json project set-dataset train train_data.csv数据集拆分SPLIT支持train/valid/test路径必须是存在的文件源码中typeclick.Path(existsTrue)校验。3.3 训练cli-anything-unimol-tools -p my_first_project.json train start --epochs 10 --batch-size 8训练流程分三步与 TRAINING-SOP.md 描述一致为每个分子生成 3D 构象conformer用 Uni-Mol 编码分子并进行训练评估并将模型保存到models/run_001/指标写入metric.result。底层调用链见 unimol_backend.pyMolTrain(task..., epochs..., batch_size..., learning_rate..., metrics..., conf_cache_level..., ...).fit(data...)支持early_stopping、kfold、remove_hs、use_cuda、use_amp、model_name等参数透传并自动读取metric.result将指标转为 JSON 可序列化格式。3.4 预测cli-anything-unimol-tools -p my_first_project.json predict run run_001 test_data.csv -o predictions.csv分类任务输出SMILES,prediction,probability三列回归任务输出SMILES,prediction两列。后端会处理 Uni-Mol「输出路径按目录处理」的怪癖当-o以.csv结尾时自动重命名到目标文件见 unimol_backend.py。完整的端到端示例含project info、models rank、storage、cleanup的演示输出见 02-QUICK-START.md。四、支持的任务类型与数据格式原文档 README.md 列出 5 类任务结合 02-QUICK-START.md 与源码补充的repr汇总如下任务类型-t取值标签格式典型场景二分类classificationlabel: 0/1药物活性active/inactive回归regressiontarget: 浮点数溶解度预测多分类multiclasslabel: 0,1,2,...毒性等级低/中/高多标签分类multilabel_classificationlabel1,label2,...: 0/1多目标药物属性多标签回归multilabel_regressionprop1,prop2,...: 浮点多个分子性质表示学习repr仅需 SMILES提取分子向量特征各任务数据格式示例# 二分类 SMILES,label CC(C)Cc1ccc(cc1)C(C)C(O)O,1 # 回归 SMILES,target CC(C)Cc1ccc(cc1)C(C)C(O)O,-2.45 # 多分类 SMILES,label CCN(CC)C(O)Cc1ccccc1,2 # 多标签分类 SMILES,label1,label2,label3 CC(C)Cc1ccc(cc1)C(C)C(O)O,1,1,0 # 多标签回归 SMILES,prop1,prop2,prop3 CC(C)Cc1ccc(cc1)C(C)C(O)O,2.45,1.23,0.87需要提醒的是文档 03-BASIC-USAGE.md 中书写为multilabel_cls/multilabel_reg而源码中 Click 校验的合法值是multilabel_classification/multilabel_regression见 unimol_tools_cli.py。实际使用时请以源码为准使用下划线全称形式。每个任务的完整数据格式说明见 03-BASIC-USAGE.md 与 02-QUICK-START.md。五、命令参考项目管理、训练与预测5.1 全局选项选项说明示例-p, --project PATH项目 JSON 文件路径-p myproject.json-w, --weight-dir PATH权重目录可替代环境变量-w /data/weights--jsonJSON 结构化输出供自动化--json--version显示版本--version5.2project项目管理# 创建项目 cli-anything-unimol-tools project new -n drug_activity -t classification # 查看项目信息数据集、模型列表、存储占用 cli-anything-unimol-tools -p drug_activity.json project info # 绑定数据集 cli-anything-unimol-tools -p drug_activity.json project set-dataset train data/train.csv cli-anything-unimol-tools -p drug_activity.json project set-dataset valid data/valid.csv cli-anything-unimol-tools -p drug_activity.json project set-dataset test data/test.csvproject new还支持-o/--output-dir指定输出目录、--model-name指定unimolv1/unimolv2、--model-size指定 v2 模型尺寸84m/164m/310m/570m/1.1B详见源码 unimol_tools_cli.py。5.3train训练# 默认参数训练 cli-anything-unimol-tools -p project.json train start # 自定义超参数 cli-anything-unimol-tools -p project.json train start \ --epochs 30 --batch-size 32 --lr 5e-5 # 查看训练记录 cli-anything-unimol-tools -p project.json train list cli-anything-unimol-tools -p project.json train show run_001源码中train start的 CLI 参数为--epochs、--batch-size、--lr、--gpusunimol_tools_cli.py会直接覆盖project.json中config字段后调用train_mod.run_training。更多底层参数dropout、conf_cache_level、early_stopping、kfold、use_amp等通过后端透传给MolTrain可在项目配置中调整。构象缓存级别conf-cache-level级别行为特点0不缓存每次重新生成最慢、磁盘占用最小1生成一次并缓存复用默认推荐2严格复用已有缓存最快要求预先生成5.4predict预测# 基本预测 cli-anything-unimol-tools -p project.json predict run run_001 test.csv # 指定输出文件 cli-anything-unimol-tools -p project.json predict run run_001 test.csv -o results.csv # 用排名最优模型预测 BEST$(cli-anything-unimol-tools --json -p project.json models rank | jq -r .models[0].run_id) cli-anything-unimol-tools -p project.json predict run $BEST new_data.csv -o output.csv预测流程DESIGN.md解析参数 → 加载 project.json → 校验 run_id →UniMolBackend.predict()加载 CSV、生成构象、加载 checkpoint、推理→ 保存 CSV → 展示结果。六、交互式模型管理存储、排名、历史、清理、归档这是该 CLI 区别于普通训练脚本的核心卖点完整文档见 04-INTERACTIVE-FEATURES.md。6.1storage存储分析cli-anything-unimol-tools -p project.json storage输出模型checkpoint.pth、构象.sdf 缓存、预测.csv三类组件的占用比例、模型明细并给出可回收空间建议。源码实现在 core/storage.py采用os.walk()快速扫描检测重复 SDF 文件并计算潜在节省空间。6.2models rank模型排名cli-anything-unimol-tools -p project.json models rank评分机制当前 100% 基于 AUCScore AUC × 10范围 0–10。状态标签阈值状态条件BestAUC ≥ 0.85 且 score ≥ 8.5GoodAUC ≥ 0.85OkAUC ≥ 0.75WeakAUC ≥ 0.65PoorAUC 0.65从源码 models_manager.py 的函数签名calculate_model_score(run, weight_auc1.0, weight_time0.0, weight_recency0.0)可推断评分算法预留了「训练时长」「新近度」的权重扩展位未来可将 AUC 加权扩展为多因子评分。6.3models history性能历史与趋势cli-anything-unimol-tools -p project.json models history按时间顺序展示 AUC 与训练时长条形图并给出趋势判断Improving最新 AUC 比首个高 0.05Declining最新 AUC 比首个低 0.05Stable变化 0.05Insufficient data不足 2 个模型。适合用于识别平台期trend 为 stable 时考虑换超参/加数据/换架构与性能回退预警可脚本化检查jq -r .trend。6.4cleanup智能清理# 交互模式推荐首次使用会展示将删除/归档/保留的清单 cli-anything-unimol-tools -p project.json cleanup # 自动模式 cli-anything-unimol-tools -p project.json cleanup --auto --keep-best2选项默认值说明--autoFalse免确认自动执行--keep-best3保留排名前 N 的模型--min-auc0.75AUC 低于阈值则删除--max-age-days7保留 N 天内的近期模型清理策略将模型分为三组删除低 AUC 旧 不在 Top N、归档中等性能但较旧、保留Top N 近期模型。交互模式的输出会在执行前展示每类清单与可节省空间选择 1-4 执行自动清理 / 全部删除 / 全部归档 / 取消。源码中cleanup命令对应 unimol_tools_cli.py。6.5archive归档管理# 列出归档 cli-anything-unimol-tools archive list # 恢复归档模型 cli-anything-unimol-tools -p project.json archive restore run_002归档机制使用 tar.gz 将 checkpoint、配置、指标压缩到约原体积的 10%如 180MB → 18MB默认存放于~/.unimol-archive/文件命名格式为{project_name}_{run_id}.tar.gz。安全性设计仅当归档成功且完整性校验通过后才删除原模型。源码见 core/cleanup.py 的delete_model/archive_model/restore_model/batch_cleanup/list_archives。七、JSON API让分子性质预测可自动化所有命令支持--json输出机器可读结构这是 Agent 与脚本接入的关键接口。# 程序化获取最优模型 BEST$(cli-anything-unimol-tools --json -p project.json models rank | jq -r .models[0].run_id) # 程序化监控存储并自动清理 USAGE$(cli-anything-unimol-tools --json -p project.json storage | jq -r .total_mb) if [ $USAGE -gt 500 ]; then cli-anything-unimol-tools -p project.json cleanup --auto fi # 批量训练多种配置 for epochs in 10 20 30; do cli-anything-unimol-tools -p project.json train start --epochs $epochs donemodels rank --json返回结构示例文档 04-INTERACTIVE-FEATURES.md{ models: [ { rank: 1, run_id: run_003, score: 9.1, auc: 0.9123, duration_sec: 26.8, status: Best, timestamp: 2024-01-15T12:34:56 } ], recommendation: { run_id: run_003, reason: Highest AUC (0.9123) } }从源码 unimol_tools_cli.py 看output()统一封装了 JSON 与人类可读两种渲染路径--json模式下错误也会以{status:error,error:...,type:...}结构返回便于上层捕获。八、架构设计与实现原理8.1 分层架构架构设计文档 描述了从用户到文件系统的五层结构User │ ▼ CLI InterfaceClick 框架命令路由 │ ▼ Core Modulesstorage.py / models_manager.py / cleanup.py │ ▼ Project Managementproject.json 状态管理 │ ▼ Uni-Mol Backendunimol_backend.py 门面层 │ ▼ Uni-Mol 库分子编码器 / 预训练权重 / 3D 构象 │ ▼ File Systemmodels/ run_001/、conformers/ *.sdf、predictions/ *.csv、~/.unimol-archive/8.2 核心模块职责对应源码模块文件路径职责CLI 入口unimol_tools_cli.py命令路由、全局选项、统一输出、错误处理存储分析core/storage.py目录扫描、重复检测、优化建议模型管理core/models_manager.py排名、历史、趋势、删除建议分类清理归档core/cleanup.py删除、归档、恢复、批量操作后端门面utils/unimol_backend.py封装 MolTrain/MolPredict/UniMolRepr、指标转换会话管理core/session.py项目文件加载与上下文项目状态core/project.py项目创建、信息展示、数据集绑定8.3 项目状态模型project.jsonproject.json是单一事实来源Repository 模式结构如下来自 DESIGN.md{ project_name: drug_discovery, task_type: classification, created: 2024-01-15T10:30:00, project_root: /path/to/project, datasets: { train: data/train.csv, valid: data/valid.csv, test: data/test.csv }, runs: [ { run_id: run_001, timestamp: 2024-01-15T11:00:00, config: {epochs: 10, batch_size: 16, learning_rate: 0.0001}, metrics: {auc: 0.8723, accuracy: 0.85, precision: 0.83, recall: 0.87}, duration_sec: 18.3, save_path: models/run_001 } ] }状态机initialized → training → trained → deployed失败时为failed。JSON 持久化保证人类可读、可版本控制、易备份。8.4 设计模式命令模式Click 装饰器实现命令结构清晰、易扩展门面模式UniMolBackend屏蔽 Uni-Mol 复杂性便于测试与后端替换策略模式cleanup 通过参数组合实现不同清理策略保守/激进仓库模式project.json 作为数据存储。8.5 测试验证仓库在 tests/ 下提供完整测试套件test_all_tasks.py、test_models_manager.py、test_cleanup.py、test_storage.py、test_full_e2e.py等。例如 test_all_tasks.py 验证了每种任务类型的完整流程创建项目 → 断言project_type/config.task/config.metrics auc→ 设置数据集 → 保存并重新加载校验。test_calculate_model_score断言 AUC 0.8723 → 得分 8.723印证了评分公式。九、进阶用法与实战工作流9.1 典型工作流实验 → 选优 → 部署# 1. 多次实验 for epochs in 10 20 30; do cli-anything-unimol-tools -p project.json train start --epochs $epochs done # 2. 查看历史与排名 cli-anything-unimol-tools -p project.json models history cli-anything-unimol-tools -p project.json models rank # 3. 选出最优模型 BEST$(cli-anything-unimol-tools --json -p project.json models rank | jq -r .models[0].run_id) # 4. 清理其余归档 cli-anything-unimol-tools -p project.json cleanup --auto --keep-best1 # 5. 部署预测 cli-anything-unimol-tools -p project.json predict run $BEST production_data.csv9.2 超参数网格搜索for lr in 1e-5 5e-5 1e-4; do for bs in 8 16 32; do for dropout in 0.0 0.1 0.2; do cli-anything-unimol-tools -p tuning.json train start \ --epochs 20 --learning-rate $lr --batch-size $bs --dropout $dropout done done done cli-anything-unimol-tools -p tuning.json models rank cli-anything-unimol-tools -p tuning.json cleanup --auto --keep-best39.3 模型对比与表示学习源码还提供了文档索引中未展开的额外命令models best展示最优模型与models compare run_001 run_002逐指标对比两个模型输出各项胜者以及repr任务类型对应的get_representation基于UniMolRepr提取分子 CLS 表示支持unimolv1/unimolv2v2 可选model_size见 unimol_backend.py。完整进阶教程见 ADVANCED.md。9.4 最佳实践清单定期监控存储训练前后运行storage实验后及时清理cleanup --auto --keep-best2用排名而非直觉选模型脚本化取models[0].run_id不确定时归档而非删除交互模式选择 Archive 选项追踪趋势models history判断是否进入平台期数据质量优先训练前用 RDKit 校验 SMILES、去重、平衡类别首轮生成构象较慢属正常缓存开启后后续轮次显著加速。十、故障排查速查表完整排查指南见 05-TROUBLESHOOTING.md核心问题速查问题快速修复命令找不到pip install -e .或补充 PATH权重缺失设置UNIMOL_WEIGHT_DIR指向含.pt文件的目录CUDA 内存不足--batch-size 4或export CUDA_VISIBLE_DEVICES训练缓慢确认构象缓存开启默认 level 1小数据先行验证head -n 51 train.csv train_small.csv指标为空{}检查models/run_001/metric.result是否存在必要时重训预测文件路径异常CLI 已自动处理.csv重命名旧问题可find . -name predict.csv手动移动SMILES 列找不到CSV 首列须为SMILES大小写敏感可用sed -i 1s/smiles/SMILES/修正清理过于激进保守参数--keep-best5 --min-auc0.60 --max-age-days30或先用交互模式预览归档恢复失败先archive list确认 run_id 精确匹配排障还支持UNIMOL_DEBUG1开启详细日志以及将训练日志输出到models/run_001/train.log。十一、文档地图与后续学习本 CLI 的完整文档体系原文档 README.md 结构docs/ ├── README.md # 本文档入口 ├── guides/ │ ├── 01-INSTALLATION.md # 完整安装指南 │ ├── 02-QUICK-START.md # 5 分钟快速上手 │ ├── 03-BASIC-USAGE.md # 全命令参考 │ ├── 04-INTERACTIVE-FEATURES.md # 交互特性详解 │ └── 05-TROUBLESHOOTING.md # 常见问题 ├── tutorials/ │ ├── CLASSIFICATION.md # 二分类完整教程含 ROC、混淆矩阵、部署 │ ├── REGRESSION.md # 回归教程 │ └── ADVANCED.md # 多分类/多标签/自动化进阶 ├── architecture/ │ ├── DESIGN.md # 架构设计 │ └── API.md # API 参考 └── workflows/ ├── TRAINING-SOP.md # 训练标准作业流程 ├── CLEANUP-SOP.md # 清理标准作业流程 └── DIAGRAMS.md # 工作流图推荐学习路径安装指南 → 快速开始 → 二分类教程CLASSIFICATION.md约 30 分钟覆盖数据准备、基线训练、超参调优、测试集评估、可视化与生产部署→ 基本用法 → 交互特性 → 架构设计。仓库还提供了可运行的演示脚本 demo_real_examples.sh 与 test_features.sh 以及测试报告文档可作为安装后自检与探索入口。无论你是手工做药物活性筛选的研究人员还是希望把分子性质预测集成进自动化管线的 Agent 开发者cli-anything-unimol-tools都提供了从「数据 → 训练 → 评估 → 选优 → 部署 → 治理」的完整闭环而这一切只需要一组简单、可组合、可脚本化的命令行。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
