Uni-Mol Tools CLI 故障排查实战指南安装、CUDA、训练、预测与数据问题的系统性解决方案【免费下载链接】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 Tools CLI 排障文档 为骨架结合 CLI 源码 与 测试用例 的实现细节系统讲解cli-anything-unimol-tools分子性质预测 CLI在安装、权重加载、CUDA 环境、模型训练、预测推理、数据清洗与存储清理等环节的常见故障根因与解决路径。读完本文你将能够快速定位 CLI 命令缺失、权重文件找不到、显存溢出、指标为空、SMILES 解析失败等高频问题掌握UNIMOL_WEIGHT_DIR、CUDA_VISIBLE_DEVICES、UNIMOL_DEBUG等关键环境变量的正确用法并具备编写一键诊断脚本、制定安全清理策略的实战能力。一、故障排查总览先看症状再定位根因CLI-Anything 的 Uni-Mol Tools Harness 是一个将 Uni-Mol 分子表示学习框架 封装为命令行接口的中间层上层是cli-anything-unimol-tools命令中层是 core 目录 中的train.py、predict.py、cleanup.py、storage.py、models_manager.py等编排模块底层则是 utils/unimol_backend.py 中封装的MolTrain/MolPredict/UniMolReprAPI。这一分层决定了故障也通常分三层出现CLI 层命令找不到、项目文件不合法、参数遗漏如忘记-p依赖层unimol_tools未安装、PyTorch CUDA 版本不匹配、权重文件缺失数据/运行层SMILES 列缺失、SMILES 非法、训练中断、checkpoint 损坏、磁盘空间耗尽。原排障文档按「安装 → CUDA/GPU → 训练 → 预测 → 数据 → 存储清理 → 项目 → 性能 → 常见错误」的组织顺序逐项给出症状、根因与解决方案本文保持这一骨架并在每一节补充对应的源码级证据与可验证命令方便你按图索骥。二、安装与环境类故障2.1cli-anything-unimol-tools: command not found症状$ cli-anything-unimol-tools --version bash: cli-anything-unimol-tools: command not found根因CLI 未安装或可执行文件所在目录不在PATH中。该命令由 agent-harness/setup.py 在pip install -e .时注册为入口脚本若安装失败或安装到了~/.local/bin等非默认目录就会出现此错误。解决方案 1重新安装 CLI开发模式安装便于跟随仓库迭代cd /path/to/CLI-Anything/unimol_tools/agent-harness pip install -e . # 验证 which cli-anything-unimol-tools解决方案 2将 pip 安装目录加入 PATH# 查找 pip 安装位置 pip show cli-anything-unimol-tools | grep Location # 将 bin 目录加入 PATH export PATH$HOME/.local/bin:$PATH # 永久生效写入 ~/.bashrc 或 ~/.zshrc echo export PATH$HOME/.local/bin:$PATH ~/.bashrc source ~/.bashrc解决方案 3使用python -m方式运行不依赖 PATH 的备选入口python -m cli_anything.unimol_tools.unimol_tools_cli --version2.2 权重文件找不到FileNotFoundError症状FileNotFoundError: [Errno 2] No such file or directory: /path/to/weights/mol_pre_all_h_220816.pt根因UNIMOL_WEIGHT_DIR环境变量未设置或指向了错误目录。从 utils/weights.py 的download_weights实现可以看到该 harness 通过unimol_tools.weights.weighthub的WEIGHT_DIR定位权重并将UNIMOL_WEIGHT_DIR映射为自定义权重目录list_downloaded_weights也直接基于weighthub.WEIGHT_DIR扫描.pt文件。因此该环境变量是 CLI 与权重仓库之间的唯一“地址簿”。解决方案 1设置环境变量# 进入 Uni-Mol 安装目录 cd /path/to/Uni-Mol/unimol_tools # 设置权重目录 export UNIMOL_WEIGHT_DIR$(pwd)/unimol_tools/weights # 验证 ls $UNIMOL_WEIGHT_DIR/*.pt解决方案 2写入 shell 配置使其永久生效echo export UNIMOL_WEIGHT_DIR/path/to/Uni-Mol/unimol_tools/unimol_tools/weights ~/.bashrc source ~/.bashrc # 验证 echo $UNIMOL_WEIGHT_DIR解决方案 3重新下载权重利用 weighthub 的自动下载能力cd /path/to/Uni-Mol/unimol_tools python -m unimol_tools.weights.weighthub # 检查下载结果应看到 mol_pre_all_h_220816.pt、mol_pre_no_h_220816.pt 等 ls unimol_tools/weights/从源码看download_weights内置了一张模型名到权重文件的映射表weights.pyunimolv1 → mol_pre_all_h_220816.pt、unimolv2-84m → unimol2_checkpoint_84m.pt、unimolv2-164m、unimolv2-310m、unimolv2-570m、unimolv2-1.1B等且会在下载前先检查目标文件是否已存在命中则返回status: exists这解释了“重复执行下载命令不会重复下载”的行为。若你使用 Uni-Mol v2 权重还需注意安装huggingface_hub其下载走weight_download_v2分支ImportError时 harness 会明确提示pip install unimol_tools huggingface_hub。2.3ModuleNotFoundError: No module named unimol_tools症状ModuleNotFoundError: No module named unimol_tools根因Uni-Mol Tools 基础包未安装。值得注意的是unimol_backend.py 在导入时用try/except将导入失败降级为UNIMOL_AVAILABLE False并在UniMolBackend.__init__中抛出带安装提示的RuntimeError因此“安装成功但训练时报错”也可能是这个原因。解决方案# 进入 Uni-Mol/unimol_tools 目录 cd /path/to/Uni-Mol/unimol_tools # 以可编辑模式安装 pip install -e . # 验证 python -c import unimol_tools; print(unimol_tools.__version__)三、CUDA 与 GPU 环境故障3.1 CUDA out of memory显存溢出症状RuntimeError: CUDA out of memory. Tried to allocate 2.00 GiB根因batch size 相对 GPU 显存过大。从 unimol_backend.py 可以看到MolTrain的batch_size直接透传自项目配置默认情况下 harness 通过use_cudaconfig.get(use_gpu, all) ! none决定是否使用 GPU因此调小 batch size 是最直接的降显存手段。解决方案 1减小 batch sizecli-anything-unimol-tools -p project.json train start --batch-size 8 # 若仍溢出继续调小 cli-anything-unimol-tools -p project.json train start --batch-size 4解决方案 2改用 CPU 训练更慢但可用export CUDA_VISIBLE_DEVICES cli-anything-unimol-tools -p project.json train start --batch-size 16解决方案 3清理其他进程占用的显存# 查看 GPU 占用 nvidia-smi # 找到占用进程 PID 后结束它示例kill -9 PID # 重新训练 cli-anything-unimol-tools -p project.json train start3.2 CUDA 版本不匹配症状RuntimeError: The NVIDIA driver on your system is too old CUDA driver version is insufficient for CUDA runtime version根因PyTorch 编译所依赖的 CUDA runtime 版本高于系统驱动支持的 CUDA 版本。解决方案 1核对两处版本# 系统 CUDA 版本 nvidia-smi | grep CUDA Version # PyTorch 自带 CUDA 版本 python -c import torch; print(fPyTorch CUDA: {torch.version.cuda})解决方案 2安装匹配的 PyTorch 版本# CUDA 11.8 环境 pip install torch2.0.0cu118 -f https://download.pytorch.org/whl/torch_stable.html # CUDA 12.1 环境 pip install torch2.1.0cu121 -f https://download.pytorch.org/whl/torch_stable.html解决方案 3安装纯 CPU 版 PyTorch无 GPU 环境pip install torch2.0.0cpu -f https://download.pytorch.org/whl/torch_stable.html export CUDA_VISIBLE_DEVICES四、训练阶段故障4.1 训练非常缓慢首轮 10 分钟以上、Conformer 生成卡住症状首个 epoch 耗时 10 分钟以上conformer 生成疑似卡死。根因Conformer分子三维构象需要从零生成、未使用 GPU、或 batch size 偏大。这一点与 unimol_backend.py 的conf_cache_levelconfig.get(conf_cache_level, 1)参数直接相关缓存级别默认开启首次运行生成 conformer 后写入缓存目录后续运行直接复用因此“第一次慢、第二次快”是预期行为。解决方案 1利用 conformer 缓存默认开启# 首次运行慢生成 conformer cli-anything-unimol-tools -p project.json train start --epochs 10 # 后续运行快复用 conformer cli-anything-unimol-tools -p project.json train start --epochs 20解决方案 2确认 GPU 可用python -c import torch; print(fCUDA available: {torch.cuda.is_available()}) nvidia-smi解决方案 3用小数据集做冒烟测试# 取前 50 行构造小数据集含表头故 head -n 51 head -n 51 train.csv train_small.csv # 在小数据集上快速验证训练链路 cli-anything-unimol-tools -p test.json project set-dataset train train_small.csv cli-anything-unimol-tools -p test.json train start --epochs 54.2 指标显示为空{}症状{ metrics: {} }根因metric.result文件缺失或保存失败。从 unimol_backend.py 的实现看训练完成后 harness 会去save_path/metric.result读取 Uni-Mol 落盘的 pickle 格式指标文件并转为 JSON若该文件不存在或读取失败会回退到fit()的返回值。因此metrics为空通常意味着落盘环节出了问题比如训练被中断、目录权限异常或 pickle 文件损坏。解决方案# 检查指标文件是否存在 ls models/run_001/metric.result # 缺失则重跑训练 cli-anything-unimol-tools -p project.json train start --epochs 10 # 再次确认 cat models/run_001/metric.result4.3 训练崩溃并报 pickle 错误症状pickle.UnpicklingError: invalid load key, \x00根因checkpoint 或metric.result文件损坏例如训练中途被 kill、磁盘写满。由于 harness 依赖 pickle 读取指标见 unimol_backend.py一旦文件被截断就会出现这类错误。解决方案 1删除损坏的 run 并重训rm -rf models/run_001/ cli-anything-unimol-tools -p project.json train start --epochs 10解决方案 2备份配置后整体清空重来cp project.json project.json.backup rm -rf models/* cli-anything-unimol-tools -p project.json train start --epochs 10五、预测推理阶段故障5.1 预测文件被保存到错误位置症状期望输出predictions.csv实际生成predictions/predictions/predict.csv。根因Uni-Mol 底层把输出路径当作目录处理会在其下追加默认文件名。解决方案该问题已被 CLI 自动处理——predict.py 会检测用户传入的-o路径并直接在项目predictions/目录下生成 CSV同时每次预测都会在项目的predictions记录中追加一条pred_id / run_id / data_path / output_path / timestamp / metrics记录predict.py便于追溯。# CLI 自动识别 .csv 扩展名并生成到指定位置 cli-anything-unimol-tools -p project.json predict run run_001 test.csv -o results.csv # 文件将位于: results.csv而非 results/predict.csv若仍复现# 查找真实输出位置 find . -name predict.csv # 手动移动到期望位置 mv path/to/predict.csv desired_location.csv5.2 预测报 No checkpoint found症状FileNotFoundError: No checkpoint found in models/run_001/根因目标 run 的 checkpoint 缺失或损坏。run_prediction在启动时会先校验run_id存在、再校验model_dir存在predict.py两层校验都通过后才调用后端MolPredict因此该错误本质上是模型产物目录不完整。解决方案 1确认 checkpoint 文件存在ls models/run_001/checkpoint.pth解决方案 2改用其他 run# 列出项目下所有 run cli-anything-unimol-tools -p project.json project info # 换一个 run 预测 cli-anything-unimol-tools -p project.json predict run run_002 test.csv解决方案 3重训模型cli-anything-unimol-tools -p project.json train start --epochs 10六、数据质量问题6.1 SMILES column not foundKeyError: SMILES症状KeyError: SMILES根因CSV 缺少 SMILES 列或列名大小写不符。CLI 与后端均要求列名严格为SMILES区分大小写这是 UNIMOL_TOOLS.md 中明确规定的数据格式要求。解决方案检查并修正 CSV 格式head train.csv # 应为 # SMILES,label # CC(C)Cc1ccc,1 # CCN(CC)C(O),0# 若列名是小写 smiles改为大写 sed -i 1s/smiles/SMILES/ train.csv # 或手动编辑 nano train.csv6.2 非法 SMILES 导致解析错误症状ValueError: Cannot parse SMILES: ... RDKit ERROR: Cant kekulize mol根因数据集中存在非法或格式错误的 SMILES 字符串。解决方案 1用 RDKit 批量校验并清洗from rdkit import Chem def validate_smiles(smiles_list): valid, invalid [], [] for smi in smiles_list: mol Chem.MolFromSmiles(smi) if mol is not None: valid.append(smi) else: invalid.append(smi) return valid, invalid # 读取 CSV import pandas as pd data pd.read_csv(train.csv) valid, invalid validate_smiles(data[SMILES]) print(fValid: {len(valid)}, Invalid: {len(invalid)}) print(fInvalid SMILES: {invalid}) # 保存清洗后的数据 data_clean data[data[SMILES].isin(valid)] data_clean.to_csv(train_clean.csv, indexFalse)注意原文示例中的import pandas as df存在笔误别名与后文pd.read_csv不一致实际应使用import pandas as pd。这与仓库数据层要求的 “SMILES 列 目标列” 结构保持一致参考 UNIMOL_TOOLS.md 的数据格式章节。解决方案 2使用清洗后的数据集训练cli-anything-unimol-tools -p project.json project set-dataset train train_clean.csv七、存储与清理故障7.1storage命令显示 0B 用量症状Total Usage: 0B根因尚未训练任何模型或project.json中的项目根目录与实际不符。从 storage.py 的analyze_project_storage实现看统计口径是项目根目录下的三类内容experiments/模型、conformers/构象缓存、predictions/预测结果三者皆为空时自然显示 0B。解决方案 1先训练一个模型cli-anything-unimol-tools -p project.json train start --epochs 10 cli-anything-unimol-tools -p project.json storage解决方案 2核对项目路径cat project.json | jq .project_root # 若路径不对说明用错了 project 文件7.2 清理误删所有模型症状所有模型被删除、没有任何 run 保留。根因清理策略过于激进。解决方案使用保守参数。suggest_deletable_modelsmodels_manager.py的决策逻辑为排名前keep_best_n的模型始终保留年龄 ≤max_age_days的新模型保留超出年龄且 AUC min_auc的删除其余「旧但性能尚可」的模型建议归档。因此合理设定三个阈值即可避免误删cli-anything-unimol-tools -p project.json cleanup --auto \ --keep-best5 \ --min-auc0.60 \ --max-age-days30预防先用交互模式预览。delete_model与batch_cleanupcleanup.py在删除前都会打印待删目录与体积并要求yes/no确认交互模式会在执行前展示清理计划务必先审阅再确认cli-anything-unimol-tools -p project.json cleanup7.3 归档恢复失败Archive not found症状FileNotFoundError: Archive not found: run_002根因归档不存在或 run_id 错误。归档由archive_model生成到~/.unimol-archive/cleanup.py文件命名格式为{project_name}_{run_id}_{YYYYMMDD}.tar.gzrestore_model会依据 run 记录中的archive_path解压回项目experiments/目录cleanup.py。解决方案 1列出可用归档cli-anything-unimol-tools archive list # 使用列表中的精确 run_id cli-anything-unimol-tools -p project.json archive restore run_002解决方案 2检查归档目录ls ~/.unimol-archive/ # 查找 project_name_run_id.tar.gz 文件八、项目管理故障8.1 Project already exists症状Error: Project file drug_activity.json already exists根因试图创建同名项目。解决方案 1换用不同名称cli-anything-unimol-tools project new -n drug_activity_v2 -t classification解决方案 2备份并删除旧项目cp drug_activity.json drug_activity.json.backup rm drug_activity.json cli-anything-unimol-tools project new -n drug_activity -t classification解决方案 3直接沿用现有项目cli-anything-unimol-tools -p drug_activity.json project info8.2 任务类型设置错误症状创建了回归项目但数据是分类数据需要修改任务类型。根因创建项目时指定了错误的task类型。任务类型在项目创建后不可直接修改因为后端MolTrain的task参数直接决定了模型头与损失函数unimol_backend.py。解决方案创建正确类型的新项目并迁移数据cli-anything-unimol-tools project new -n project_correct -t classification # 复制数据集设置 cli-anything-unimol-tools -p project_correct.json project set-dataset train train.csv九、性能与磁盘空间优化9.1 模型占用磁盘过大症状每个模型约 180MB磁盘快速占满。解决方案 1定期清理仅保留最优模型cli-anything-unimol-tools -p project.json cleanup --auto --keep-best2解决方案 2归档而非删除可显著节省空间。archive_model将模型目录压缩为.tar.gz后删除原目录cleanup.py并返回compression_ratio压缩率供评估cli-anything-unimol-tools -p project.json cleanup # 交互模式选择 Archive 选项解决方案 3删除 conformer 缓存# 若不再训练新模型可删除构象缓存 rm -rf conformers/ # 节省磁盘但再次训练时需要重新生成 conformer十、三大常见操作错误10.1 训练前未设置数据集错误做法cli-anything-unimol-tools project new -n myproject -t classification cli-anything-unimol-tools -p myproject.json train start # ERROR: No dataset这正是 train.py 中run_training的第一道校验project[datasets][train]为空时直接抛出ValueError(Training dataset not set. Use project set-dataset train path)。正确做法cli-anything-unimol-tools project new -n myproject -t classification cli-anything-unimol-tools -p myproject.json project set-dataset train train.csv cli-anything-unimol-tools -p myproject.json train start # OK10.2 忘记-p参数错误做法cli-anything-unimol-tools train start # ERROR: No project specified正确做法cli-anything-unimol-tools -p project.json train start或使用别名简化alias umolcli-anything-unimol-tools -p project.json umol train start10.3 使用错误的数据格式错误示例分类任务使用文本标签SMILES,activity CC(C)Cc1ccc,active # 应为 0 或 1而非文本 CCN(CC)C(O),inactive正确示例二分类标签必须为 0/1SMILES,label CC(C)Cc1ccc,1 CCN(CC)C(O),0不同任务类型对目标列格式有严格约定参考 UNIMOL_TOOLS.md二分类为 0/1 或 True/False回归为浮点数多分类为 0、1、2… 整数多标签分类为多个 0/1 列多标签回归为多个浮点列。十一、获取更多帮助的途径11.1 查看训练日志模型目录中会保存训练日志cat models/run_001/train.log11.2 开启调试模式设置环境变量以获得更详细的输出export UNIMOL_DEBUG1 cli-anything-unimol-tools -p project.json train start11.3 收集系统信息提交问题前先汇总环境快照# Python 版本 python --version # CUDA 版本 nvidia-smi # PyTorch 信息 python -c import torch; print(fPyTorch: {torch.__version__}); print(fCUDA: {torch.cuda.is_available()}) # 磁盘空间 df -h .11.4 反馈 bug 的标准流程先查本指南中的常见解决方案检查已有 issue是否已覆盖该问题收集信息# 版本号 cli-anything-unimol-tools --version # 系统信息 uname -a python --version # 完整错误回溯error traceback创建 issue并附上上述信息。十二、一键诊断脚本快速定位环境问题将以下脚本保存为diagnose.sh并执行可一次性核对 CLI 安装、权重目录、Python 环境、CUDA 与磁盘空间五项关键指标#!/bin/bash # diagnose.sh - Check Uni-Mol Tools CLI setup echo Uni-Mol Tools CLI Diagnostics echo # 1. CLI 安装 echo 1. CLI Installation: which cli-anything-unimol-tools cli-anything-unimol-tools --version echo # 2. 权重目录 echo 2. Weight Directory: echo UNIMOL_WEIGHT_DIR$UNIMOL_WEIGHT_DIR if [ -d $UNIMOL_WEIGHT_DIR ]; then ls -lh $UNIMOL_WEIGHT_DIR/*.pt 2/dev/null || echo No weight files found else echo Directory not found! fi echo # 3. Python 环境 echo 3. Python Environment: python --version python -c import torch; print(fPyTorch: {torch.__version__}) python -c import torch; print(fCUDA available: {torch.cuda.is_available()}) python -c import unimol_tools; print(fUni-Mol Tools: OK) 21 echo # 4. CUDA echo 4. CUDA: nvidia-smi --query-gpuname,memory.total,memory.free --formatcsv 2/dev/null || echo No CUDA GPU found (will use CPU) echo # 5. 磁盘空间 echo 5. Disk Space: df -h . | grep -v Filesystem echo echo End Diagnostics 执行方式bash diagnose.sh该脚本与 weights.py 提供的get_weight_info/list_downloaded_weights能力互为印证脚本负责 shell 层的环境检查而 harness 内置的权重管理接口可从 Python 侧返回weight_dir、hf_endpoint、custom_dir与exists等结构化信息。十三、高频问题速查表问题快速修复命令找不到pip install -e .权重缺失export UNIMOL_WEIGHT_DIR/path/to/weightsCUDA 显存溢出--batch-size 4或export CUDA_VISIBLE_DEVICES训练缓慢启用 conformer 缓存默认开启首轮慢属正常指标为空检查models/run_001/metric.result预测位置错误已被 CLI 自动处理SMILES 非法用 RDKit 校验并清洗数据磁盘占用过大cleanup --auto --keep-best2十四、总结与进一步阅读本指南覆盖了 Uni-Mol Tools CLI 从安装到推理的全链路故障场景。核心排查思路可概括为四步先确认 CLI 层命令、项目、参数→ 再确认依赖层unimol_tools、PyTorch、权重目录→ 接着核对数据层SMILES 列、标签格式、合法字符串→ 最后排查运行产物checkpoint、metric.result、conformer 缓存。配合diagnose.sh一键诊断与环境变量UNIMOL_WEIGHT_DIR、CUDA_VISIBLE_DEVICES、UNIMOL_DEBUG的合理使用绝大多数问题都能在五分钟内定位。如需继续深入仓库还提供了完整的配套文档可按序阅读安装指南环境准备、权重下载、CLI 安装与验证清单快速上手5 分钟跑通完整训练-预测流程基础用法project、train、predict、models、cleanup等命令的完整参考交互式特性交互模式与一键式模式的使用差异Uni-Mol Tools CLI SOP任务类型、数据格式要求与最佳实践总览。同时本文涉及的关键源码路径也便于你在排障时直接查阅核心训练编排、预测编排、存储分析、清理与归档、模型排名、后端适配层 与 权重管理以及覆盖清理、存储、全链路流程的 测试套件。【免费下载链接】CLI-AnythingCLI-Anything: Making ALL Software Agent-Native -- CLI-Hub: https://clianything.cc/项目地址: https://gitcode.com/GitHub_Trending/cl/CLI-Anything创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考