Troubleshooting（常见问题与排查）

Troubleshooting（常见问题与排查）#

  • Status: active

  • Audience: Users / Developers / Infra

  • Last-Updated: 2026-06-10

1. 目的与范围#

本页用于快速定位 DP-EVA 在 Train/Infer/Feature/Collect/Analysis 过程中出现的问题，给出“先看哪里、再排什么”的最短路径。

2. 相关方#

  • 使用者：运行工作流、收集日志与复现问题

  • 开发者：维护错误提示、输入校验与日志锚点

  • 平台维护：处理 Slurm 队列与 DeepMD 环境问题

3. 总体排查顺序（强制建议）#

  1. 确认当前工作目录与配置文件路径（相对路径解析是否正确）

  2. 定位对应工作流的日志文件（Train/Infer/Feature/Collect）

  3. 判断是否出现完成标记（见 3.1）

  4. 若失败来自外部命令（dp/Slurm），先定位外部命令报错，再回到配置与输入数据

3.1 任务完成锚点#

DP-EVA 以统一完成标记作为应用层完成锚点：

DPEVA_TAG: WORKFLOW_FINISHED

没有该标记时，优先认为任务“未成功结束”，需要继续追踪日志中的异常堆栈或外部命令错误输出。

3.2 选择重跑方式#

先保存错误日志，确认旧进程或 Slurm 作业已结束，再决定是否重用输出目录。 --force 或移动目录都不会取消仍在运行的作业。Quickstart 的默认重新开始方式见 入门指南。

场景

当前支持的做法

想从头重做小型示例

备份整个示例工作目录，从第一阶段重新运行

Feature/Infer 中断，清单仍为未终结且非 submitted 状态

配置、输入、运行代码证据一致时，可指定原 --run-id ID --resume；这会创建新尝试，不保证跳过已成功的子任务

Feature/Infer 已记录 failed 或 finished

不能 resume；排除原因后，用原 --run-id ID --force --reason "原因" 显式创建新尝试，或使用新工作目录

Slurm 清单为 submitted

先查调度器状态与作业日志，不能把 CLI 返回当作计算完成；当前不支持 scheduler resume，重新提交前确认旧作业结束

Train 或 Collect 失败

没有统一的 --resume/--force 接口；先修复输入或环境，隔离旧输出后重新执行相应工作流。Train 不能据此声称从 checkpoint 续训

保留成功阶段时，只复用已确认成功且与当前配置、输入匹配的产物。沿 feature → train → infer → collect 的示例操作时，实际依赖还需分别核对： 更换候选池要重建对应描述符和推理结果；更换训练数据或训练模型后应重新训练、 推理，再采集。更换 Feature 基座模型则需要重建描述符。不要仅凭目录存在判断 上游已成功，也不要从未结束的 Slurm 作业输出中启动下游阶段。

4. 环境类问题#

4.1 dp: command not found#

症状：

  • 作业日志出现 dp: command not found

原因：

  • DeepMD-kit 环境未加载或未写入 PATH

处理：

  • Local：在当前 shell 环境中先 dp --version 验证

  • Slurm：将环境加载写入 submission.env_setup（不要依赖交互式 shell）

4.2 DeepMD 版本不匹配/行为差异#

症状：

  • dp 命令存在但输出/参数行为与预期不一致

处理：

  • 记录 dp --version 输出与运行环境信息（CUDA/驱动）

  • 若为集群，建议固定模块版本或 Conda 环境版本

5. 数据类问题（dpdata / Multi DataPool）#

5.1 dpdata 目录结构不符合预期#

症状：

  • Feature/Infer/Collect 报“找不到系统/空数据/系统数为 0”

处理：

  • 检查数据目录是否包含 type.raw/type_map.raw 与 set.000/*.npy

  • Multi DataPool 场景确认目录层级为：Pool/System/set.000

5.2 type_map 不一致导致元素映射错误#

症状：

  • 推理结果异常（能量/力量级明显不对）

  • 部分 system 加载失败

处理：

  • 确认训练集与候选池在 type_map.raw 的元素顺序一致

  • Analysis 的 type_map 必须与训练/数据一致

5.3 deepmd/lmdb 输入无法加载或被拒绝#

症状：

  • load_systems 报 DatasetLoadError，提示 "Reading 'deepmd/lmdb' requires dpdata>=1.1"

  • Feature 的 eval-desc/embed 在提交前报 "cannot consume a DeepMD LMDB dataset"

  • dpeva infer 在解析旧 LMDB 明细时可能报缺少 frame_nlocs/frame_system_ids

  • Clean 在 LMDB 缺少 frame_system_ids/system_info 时会拒绝猜测原始 system 划分

处理：

  • 先跑 dpeva doctor --json：dpdata.lmdb 检查为 ok 表示当前环境可读 LMDB； 为 unavailable 时升级到 dpdata>=1.1（预置环境需重建或补装）

  • 数据路径按 deepmd-kit 的判定规则识别：目录名以 .lmdb 结尾，或目录内含 data.mdb

  • LMDB 不保存目录级体系身份，读回结果按组成分组；需要逐 system 统计或 target_systems= 筛选时，改用同一数据集的 deepmd/npy/npy/mixed 副本

  • dp eval-desc/dp embed 上游不支持 LMDB；Feature 工作流请指向 npy/mixed 副本， 或使用进程内 DescriptorGenerator 路径。上游跟踪 issue： deepmodeling/deepmd-kit#6034。 2026-10-22 复核 master commit a78bdfe8，issue 仍 open，尚无实现 PR。

  • 训练（dp train）支持 LMDB，但 training_data.systems 必须是单个 LMDB 路径； 不要把多个 LMDB 放在一个容器目录里让 DP-EVA 展开。SAI 200-step execution A/B（JobID 1893783）已证明两条训练路径均可完成并写出 checkpoint；短程 lcurve 受随机采样影响，不能据此声称训练曲线逐位等价。

  • dp test 自报的聚合指标在 LMDB 上有效；带 frame_nlocs/frame_system_ids 的 LMDB 可由 dpeva infer/analysis 解析逐帧明细。缺失元数据时 parser 会 fail-loud，不会猜测归属

  • test + deepmd/lmdb 已由 DeepMD 3.2.0 CPU contract 与 SAI npy↔lmdb A/B 证据晋级 supported。DeepMD-kit 3.2.0 的 mixed-nloc -d 输出可能只有首个 [nloc=...] header；parser 仅在总行数与帧索引完全一致时按组序归属，否则 报错。clean 在 LMDB 带 frame_system_ids 元数据时可用；缺失时请补齐元数据或使用 npy/mixed 副本。同一 source system 内 atom count 不同的混合帧仍会被 clean 拒绝合并；同 atom count、不同组成的 mixed 帧会保留 real_atom_types。

6. 作业与调度类问题（Slurm）#

6.1 sbatch 提交失败#

症状：

  • sbatch: error: ...

处理：

  • 检查 partition/qos/account 是否符合策略

  • GPU/CPU 资源字段是否与分区匹配

  • 检查提交目录权限与配额

6.2 长时间 pending#

处理：

  • 使用 squeue -j <jobid> 查看原因（资源不足/策略限制）

  • 适当降低资源申请（缩短 walltime、减少 GPU/CPU）

6.3 日志不落盘/找不到日志文件#

处理：

  • 以提交目录为准确认 .out 位置（建议固定 work_dir 并在其中提交）

  • 对照 docs/source/guides/slurm.md 的常见日志命名约定

7. 数值类问题（NaN/Inf/聚类不收敛）#

7.1 UQ 分布异常或全 NaN/Inf#

处理：

  • 优先检查推理输出是否完整（results.*.out 是否存在）

  • 检查是否存在失败模型（某个模型推理输出缺失会影响方差/UQ）

  • 若输入数据包含异常结构（box/coord 形状不一致），先修复数据

7.2 聚类不收敛或采样结果为空#

处理：

  • 检查 sampler_type 与参数组是否匹配（direct vs 2-direct）

  • 降低 direct_n_clusters 或调整阈值相关参数

  • 若候选池数量过少或被联合采样去重，采样数少于目标是预期行为

8. 变更记录#

  • 2026-02-18：补齐 Troubleshooting 的结构化排查路径与四类常见问题处理建议。

目录