Uni-Mol Tools CLI 架构设计：基于 CLI-Anything 的分子性质预测命令行工具全解析

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导读Uni-Mol Tools CLI 是基于 CLI-Anything 框架构建的命令行工具harness它为分子性质预测提供了一套完整、可交互的终端工作流从项目初始化、数据集配置、Uni-Mol 模型训练与推理到模型排行、存储分析与安全清理。本文以 架构设计文档 为主线结合仓库源码逐层拆解其分层架构、核心模块职责、数据流、设计模式、状态管理与扩展点读完可掌握该 CLI 的完整实现原理与实战使用方式。一、系统架构总览Uni-Mol Tools CLI 采用分层架构从用户到文件系统共五层各层职责单一、通过明确接口衔接这是其作为 Agent 原生工具易于自动化调用的根本保证。整体结构源自 DESIGN.md如下User │ ▼ CLI Interface —— cli-anything-unimol-toolsClick Framework │ ├─ project 命令new / info / set-dataset │ ├─ train 命令start │ ├─ predict 命令run │ ├─ storage / models / cleanup / archive 命令 ▼ Core Modules —— Storage Analyzer / Models Manager / Cleanup Manager ▼ Project Management —— project.json配置、数据集、运行历史、指标跟踪 ▼ Uni-Mol Backend —— unimol_backend.pyUniMolClassifier / UniMolRegressor 封装、构象生成、训练、预测 ▼ Uni-Mol —— Uni-Mol 库分子编码器、预训练权重、3D 构象处理 ▼ File System —— Modelsrun_xxx/、Conformers*.sdf 缓存、Predictions*.csv、Archive~/.unimol-archive/ 下的 tar.gz从源码看各层有对应的物理实现CLI 层是 unimol_tools_cli.py核心模块位于 core/后端适配器在 utils/unimol_backend.py而项目状态则落地为project.json文件。关键设计意图CLI 层只负责参数解析与展示业务逻辑沉淀在 core 模块Uni-Mol 的具体 API 被后端适配器完全隔离。这意味着更换分子模型库如替换为其他 encoder时仅需改动适配层命令行接口与用户工作流不受影响。二、CLI 接口层Click 命令路由unimol_tools_cli.py2.1 职责与框架CLI 接口层负责用户交互与命令路由基于 Python 的 Click 框架实现。入口文件为 unimol_tools_cli.py通过click.group组织命令组整体命令树与 DESIGN.md 一致cli-anything-unimol-tools ├── project (new, info, set-dataset) ├── train (start, list, show) ├── predict (run, list) ├── storage (analyze disk usage) ├── models (rank, history, best, compare) ├── cleanup (interactive / --auto 自动清理) └── archive (list, restore)2.2 全局选项与上下文传递根命令cli定义了两个全局选项unimol_tools_cli.py#L81-L97选项简写类型说明--json—flag输出 JSON 格式便于 Agent / 脚本解析--project-pPath指定项目文件project.json的路径--weight-dir-wPath自定义权重目录等价于设置环境变量UNIMOL_WEIGHT_DIR--project会触发session_mod.UniMolSession(project_path)加载会话随后通过ctx.obj[session]在各子命令间传递若未提供任何子命令则自动进入 REPL 交互模式ctx.obj[repl_mode] True。2.3 统一输出与错误处理output(data, ctx)L28-L47依据--json标志决定输出 JSON 还是人类可读的彩色文本状态字段statuscreated/loaded/saved/completed以绿色✓展示错误以红色输出。handle_error装饰器L50-L78统一捕获异常输出{status:error,error:...,type:...}在 REPL 模式下不退出进程单次命令模式下sys.exit(1)。2.4 命令组要点与 DESIGN.md 对应project new-n/--name必填、-t/--task限定classification、regression、multiclass、multilabel_classification、multilabel_regression、repr六种、-o/--output-dir默认.、--model-name默认unimolv1可选unimolv2、--model-sizev2 专用84m/164m/310m/570m/1.1B。train start支持--epochs、--batch-size、--lr、--gpus覆盖项目默认配置后调用train_mod.run_training(proj)L206-L240。predict runrun_id与data_path为必填参数-o/--output可选。cleanup--auto一键自动清理、--keep-best默认 3、--min-auc默认 0.75交互模式下提供 4 个选项自动清理 / 全部删除 / 全部归档 / 取消L649-L775。三、核心模块一Storage Analyzercore/storage.py3.1 职责存储分析器负责磁盘使用量分析与清理建议生成实现于 core/storage.py。它按三类资源统计占用资源目录内容Modelsexperiments/各 run 的 checkpoint 目录Conformersconformers/SDF 构象缓存Predictionspredictions/预测结果 CSV3.2 关键函数analyze_project_storage(project: Dict) - Dict: 分析存储占用返回 breakdown recommendations get_directory_size(path: str) - int: 递归计算目录大小os.walk 实现 format_size(size_bytes: int) - str: B/KB/MB/GB/TB 人类可读格式化 get_file_age_days(path: str) - int: 基于 mtime 计算文件年龄返回结构storage.py#L146-L158{ total_mb: 123.45, breakdown: { models: 100.0, conformers: 20.0, predictions: 3.45, models_pct: 81.0, conformers_pct: 16.2, predictions_pct: 2.8 }, models_detail: [{run_id: run_001, size_mb: 50.0, auc: 0.87, age_days: 2}], recommendations: [...] }3.3 设计原则与建议逻辑快速扫描使用os.walk()遍历而不做深度文件内容检查storage.py#L17-L27。建议生成两类启发式规则——old_models年龄 7 天的模型与low_performanceAUC 0.75 且年龄 1 天并计算potential_savings_mbstorage.py#L126-L144。CLI 层会将结果渲染为进度条█░与建议清单见 unimol_tools_cli.py#L336-L395。对应测试覆盖了格式化、目录大小递归、占比计算与建议触发等场景tests/test_storage.py。四、核心模块二Models Managercore/models_manager.py4.1 职责模型管理器负责模型排名、比较与历史趋势追踪实现于 core/models_manager.py。这是「Agent 如何从一堆训练 run 中选出最佳模型」的决策引擎。4.2 评分算法calculate_model_score设计文档明确当前评分100% 基于 AUCScore AUC × 10范围 0–10。源码实现models_manager.py#L8-L60同时预留了三个可加权维度便于扩展维度默认权重计算方式AUC1.0auc * 10缺省时回退到auroc或 0.5训练时间0.0反比归一max(0, min(10, (30 - duration) / 2))10s10 分、30s0 分时效性0.024h 内10 分超过 7 天0 分线性衰减默认总分为auc_score * 1.0 time_score * 0.0 recency_score * 0.0即纯 AUC 制调用calculate_model_score(run, weight_auc..., weight_time..., weight_recency...)可切换为复合评分。4.3 rank_models 与状态标签rank_models 为每个模型计算分数、打状态标签并排序状态划分阈值AUC 区间状态≥ 0.85 且 score ≥ 8.5Best≥ 0.85Good≥ 0.75Ok≥ 0.65Weak 0.65PoorCLI 的models rank会渲染排名表第一名显示 AUC ≥ 0.85 加 ⭐训练 16s 加 ⚡并给出生产推荐unimol_tools_cli.py#L403-L474。4.4 历史与趋势分析get_model_historyget_model_history 按时间戳排序生成 timeline通过首尾 AUC 差判定趋势last_auc first_auc 0.05→ improvinglast_auc first_auc - 0.05→ declining否则 → stable少于 2 条记录为insufficient_data同时自动生成 insights最佳模型、趋势方向、最近一次下降下降 0.02 时告警。CLI 层渲染为文本柱状图█长度 ∝ AUC。4.5 可删除模型建议suggest_deletable_models默认参数keep_best_n3, min_auc0.75, max_age_days7models_manager.py#L325-L408决策逻辑先按分数取 Top Ntop_n_ids→keep非 Top N 但age_days max_age_days→keepRecent较老且auc min_auc→deleteLow AUC较老但 AUC 尚可 →archiveOld but decent。缺失时间戳的 run 按 999 天视为极老处理避免误删风险。对应测试tests/test_models_manager.py覆盖了默认参数、keep_best_n、min_auc、max_age_days、畸形时间戳、负时长等边界情况。4.6 compare_models 与 get_best_modelcompare_models 支持auc/auroc/accuracy/precision/recall/f1_score/mcc/log_loss等多指标对比除log_loss与training_time取最小值外其余指标取最大值判定胜者最终按各指标胜场数汇总overall_winner。get_best_model 默认按auc取最优支持自定义指标。五、核心模块三Cleanup Managercore/cleanup.py5.1 职责清理管理器提供安全的模型删除与归档恢复实现于 core/cleanup.py。函数行为delete_model(project, run_id, confirmTrue)删除模型目录shutil.rmtree并从project[runs]移除记录默认需yes/y确认并显示目录与大小archive_model(project, run_id, archive_dirNone)打包为tar.gzw:gz流式压缩无临时文件默认存至~/.unimol-archive/成功后删除原目录返回压缩率restore_model(project, run_id)将归档解压回experiments/run_id更新archived/model_dir元数据batch_cleanup(project, delete_ids, archive_ids, confirmTrue)批量执行统计deleted/failed/space_freed_mb计划打印后需确认取消返回status: cancelledlist_archives(archive_dirNone)解析文件名{project}_{run_id}_{date}.tar.gz按修改时间倒序列出归档文件命名规范为{project_name}_{run_id}_{YYYYMMDD}.tar.gzcleanup.py#L99-L103DESIGN.md 提到的「约 90% 压缩率」可通过返回的compression_ratio实测验证。5.2 安全设计删除前确认单条与批量操作均要求交互确认归档优先不确定时建议archive而非delete失败自愈归档失败时清理半成品 tar.gzcleanup.py#L134-L142恢复前校验目标目录已存在时拒绝覆盖避免数据丢失。测试tests/test_cleanup.py覆盖删除更新项目状态、批量失败处理、释放空间计算与归档目录枚举等场景。六、Uni-Mol Backend后端适配器utils/unimol_backend.py6.1 职责与错误模型后端适配器封装 Uni-Mol 库MolTrain、MolPredict、UniMolRepr定义在 utils/unimol_backend.py。导入失败时UNIMOL_AVAILABLEFalse构造时抛出安装指引pip install unimol_tools --upgradehuggingface_hub。异常体系UniMolError基类DataValidationError数据/配置校验失败ModelNotFoundError模型目录不存在TrainingError训练/推理失败6.2 train训练封装UniMolBackend.train(config)unimol_backend.py#L45-L138实例化MolTrain并传入项目配置关键映射项目配置键传入 MolTrain默认值tasktask必填data_typedata_typemoleculeepochsepochs10batch_sizebatch_size16learning_ratelearning_rate1e-4early_stoppingearly_stopping20metricsmetrics按任务类型默认分类auc多分类acc回归maesplit/kfoldsplit/kfoldrandom/ 1save_pathsave_pathexperiments/run_idremove_hsremove_hsFalseconf_cache_levelconf_cache_level1target_normalizetarget_normalizeautouse_gpuuse_cudaall! none即启用use_ddp/use_ampuse_ddp/use_ampFalse / Falsemodel_namemodel_nameunimolv1model_sizemodel_size仅 v284mload_model_dirload_model_dir续训时传入上一 run 的模型目录训练完成后优先从save_path/metric.result读取 Uni-Mol 落盘的 pickle 指标经_convert_metrics_to_json将 numpy 类型递归转换为 JSON 可序列化格式unimol_backend.py#L140-L163返回{status,metrics,model_path,duration_sec}。6.3 predict推理封装UniMolBackend.predict 使用MolPredict(load_modelmodel_dir)加载模型。源码处理了 Uni-Mol 的一个关键行为predict 接收目录而非文件输出形如save_path/{input_basename}.predict.0.csv适配层会自动重命名为用户指定的--output文件unimol_backend.py#L219-L233。6.4 get_representation表征提取get_representation(data_path, model_nameunimolv1, ...)通过UniMolRepr.get_repr获取分子表征支持return_atomic_reprs返回原子级表征服务于repr任务类型。6.5 权重管理utils/weights.py 提供权重下载/列举/信息查询内置权重映射模型权重文件unimolv1mol_pre_all_h_220816.ptunimolv2-84m / 164m / 310m / 570m / 1.1Bunimol2_checkpoint_*.pt已下载则直接返回status: existsv2 系列走weighthub.weight_download_v2v1 走weight_download权重目录可用UNIMOL_WEIGHT_DIR环境变量或-w/--weight-dir指定。七、数据流训练、预测与清理的完整链路7.1 训练流Training FlowUser Command ├─ CLI 解析参数--epochs 等覆盖项目配置 ├─ 加载 project.json ├─ 校验训练数据集存在未设置则抛 Training dataset not set ├─ 生成 run_idrun_{n:03d}与 run 目录 experiments/run_id ├─ UniMolBackend.train() │ ├─ 加载 train/valid 数据集 │ ├─ 生成构象未缓存时保存到 conformers/ │ ├─ 初始化 Uni-Mol 模型 │ ├─ 训练 N 个 epochearly_stopping20 │ ├─ 验证集评估 │ └─ 保存 checkpoint 与 metric.result ├─ 从 metric.result 加载指标pickle → JSON ├─ 追加 run 记录到 project.jsontimestamp/metrics/model_dir/config/duration_sec └─ 展示结果对应编排逻辑在 core/train.py 的run_trainingresume_from参数支持从历史 run 续训自动设置load_model_dir。7.2 预测流Prediction FlowUser Command ├─ CLI 解析 run_id 与 data_path ├─ 加载 project.json校验 run_id 存在、模型目录存在 ├─ UniMolBackend.predict() │ ├─ 加载输入 CSV │ ├─ 生成构象 │ ├─ MolPredict 加载 checkpoint │ ├─ 推理输出 {input}.predict.0.csv │ └─ 重命名为目标输出文件 ├─ 保存预测结果到 predictions/自动命名 pred_{n:03d}.csv └─ 展示完成信息7.3 清理流Cleanup FlowUser Command ├─ CLI 解析--auto / --keep-best / --min-auc ├─ 加载 project.json ├─ suggest_deletable_models()排名 → 应用阈值 → 分类 delete/archive/keep ├─ 展示建议删除/归档/保留清单 ├─ 交互模式4 选 1自动模式直接执行 ├─ delete 类 → cleanup.delete_model() ├─ archive 类 → cleanup.archive_model()tar.gz → ~/.unimol-archive/ → 删原目录 ├─ 更新 project.json移除已删除 run、标记 archived └─ 展示释放空间完整的端到端演练可参考 demo_real_examples.sh 与--json模式下的集成测试tests/test_full_e2e.py 覆盖了建项目、分类/回归训练、排名、存储分析、预测与自动清理全流程。八、设计模式在代码中的落地8.1 命令模式Command Pattern通过 Click 装饰器实现每个子命令即一个命令对象cli.command(train) click.option(--epochs, defaultNone, typeint) click.pass_context handle_error def train_start(ctx, epochs): Start training a model ...收益命令结构清晰、易于扩展新增命令只需添加函数与装饰器、参数解析一致。8.2 门面模式Facade PatternUniMolBackend是 Uni-Mol 库的门面对外仅暴露train/predict/get_representation/is_available四个方法隐藏 MolTrain/MolPredict 的初始化、构象生成、权重下载与指标序列化等复杂性便于测试与后端替换。8.3 策略模式Strategy Pattern清理策略通过参数组合表达models_manager.py#L325-L344# 保守策略 suggest_deletable_models(project, keep_best_n5, min_auc0.75, max_age_days14) # 激进策略 suggest_deletable_models(project, keep_best_n1, min_auc0.85, max_age_days3)8.4 仓储模式Repository Patternproject.json作为唯一数据源Single Source of Truth读写通过 core/project.py 统一封装并引入文件锁保证并发安全core/session.pyUnixfcntl.flock独占锁 fsync落盘Windows写入临时文件后os.replace原子替换。项目文件为人类可读 JSON天然支持版本控制与备份。九、状态管理project.json 结构与状态机9.1 项目文件结构project new会在output_dir/name/下创建独立项目目录含project.json、experiments/、conformers/、predictions/。完整结构DESIGN.md 与 create_project 一致{ version: 1.0, project_type: classification, _project_dir: /path/to/project, metadata: {name: drug_discovery, created: 2024-01-15T10:30:00, modified: ..., description: }, config: { task: classification, model_name: unimolv1, model_size: null, epochs: 10, batch_size: 16, learning_rate: 0.0001, metrics: auc, split: random, kfold: 1, early_stopping: 20, use_ddp: false, use_gpu: all, use_amp: false, remove_hs: false, conf_cache_level: 1, target_normalize: auto }, datasets: {train: data/train.csv, valid: data/valid.csv, test: data/test.csv}, runs: [ { run_id: run_001, timestamp: 2024-01-15T11:00:00, status: completed, 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, model_dir: experiments/run_001 } ], predictions: [] }9.2 任务类型与默认指标create_project 按任务类型自动选择默认评估指标任务类型默认指标classification / multilabel_classificationaucmulticlassaccregression / multilabel_regressionmae9.3 状态迁移initialized → training → trained → deployed ↓ failed9.4 会话与锁定UniMolSession 管理会话状态project_path、project、history_locked_save_json提供原子化持久化所有写操作建项目、set-dataset、训练后保存、清理后保存均经由该锁定写入。十、扩展点如何给 CLI 增加能力10.1 新增命令在 unimol_tools_cli.py 中追加cli.command(my-command) click.option(--option, defaultvalue) click.pass_context handle_error def my_command(ctx, option): My custom command session ctx.obj.get(session) project session.project # Implementation output({status: ok, message: Success!})10.2 新增指标维度在calculate_model_score中扩展权重维度参考 models_manager.py#L8-L60 的多权重骨架def calculate_model_score(run, **weights): specificity run[metrics].get(specificity, 0.5) specificity_score specificity * 10 total_score ( auc_score * weights.get(weight_auc, 1.0) specificity_score * weights.get(weight_specificity, 0.0) ) return total_score10.3 自定义清理策略实现「保留所有 AUC 0.90 的模型供同行评审」def custom_cleanup_strategy(project): runs project[runs] keep [r for r in runs if r[metrics][auc] 0.90] archive [r for r in runs if r[metrics][auc] 0.90] return {keep: keep, archive: archive, delete: []}十一、性能与安全考量11.1 性能场景策略存储分析os.walk()快速扫描不读文件内容遍历时内存缓存大小模型排名全部基于已加载的 project.json 数据零磁盘 I/O排序用内建O(n log n)归档tarfile流式压缩w:gz无中间临时文件大模型可异步化构象缓存默认conf_cache_level1缓存 SDF后续 run 直接复用避免重复生成多项目可共享缓存仅对新分子生成新构象11.2 安全输入校验SMILES 校验RDKit、文件路径清洗、JSON schema 校验文件操作路径须在项目目录内、防路径穿越、加载前校验文件类型归档安全解压前校验 tar.gz 完整性、解压到已知安全位置、恢复前检查归档大小。十二、测试策略12.1 单元测试核心逻辑均有对应测试例如评分函数tests/test_models_manager.pydef test_auc_based_score(): run {metrics: {auc: 0.8723}} score calculate_model_score(run) assert score 8.7 # AUC * 10 def test_rank_by_auc(sample_project): ranked rank_models(sample_project) assert ranked[0][run_id] run_002 # 更高 AUC 排第一12.2 集成测试端到端test_full_e2e.py 通过真实 CLI 调用验证完整工作流cli-anything-unimol-tools project new -n test -t classification cli-anything-unimol-tools -p test.json project set-dataset train data.csv cli-anything-unimol-tools -p test.json train start --epochs 2 cli-anything-unimol-tools -p test.json models rank cli-anything-unimol-tools -p test.json cleanup --auto --keep-best1测试还覆盖六种任务类型test_all_tasks.py二分类、回归、多分类、多标签分类、多标签回归的项目创建与数据加载。手动全功能演练脚本见 demo_real_examples.sh。十三、依赖与后续演进13.1 依赖清单核心依赖见 pyproject.toml 与 DESIGN.mdunimol_tools 1.0.0 # Uni-Mol 库MolTrain/MolPredict/UniMolRepr click 8.0.0 # CLI 框架 colorama 0.4.0 # 终端彩色输出可选依赖matplotlib 3.5.0 # 可视化 seaborn 0.12.0 # 统计图 scikit-learn 1.0.0 # ML 指标 rdkit 2022.09.1 # 化学工具包13.2 未来增强DESIGN.md 规划的演进方向Web Dashboard 可视化、远程集群训练、超参自动调优、REST API 模型服务、多 GPU 分布式训练以及自定义分子编码器后端、ChEMBL/PubChem 外部数据接入、3D 结构查看器、项目协作与 CI/CD 自动模型验证。十四、参考资料架构设计DESIGN.mdAPI 参考API.md快速开始02-QUICK-START.md安装指南01-INSTALLATION.md交互特性04-INTERACTIVE-FEATURES.md清理 SOPCLEANUP-SOP.md核心实现unimol_tools_cli.py、core/、utils/unimol_backend.py测试tests/【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考