照着零散教程装 EchoWM 依赖、跑起来却报缺权重或版本冲突，多数时候不是环境太刁钻，而是把仓库里必需的文件和可选的文件当成一堆一起装了。建议先读仓库：认全目录职责，分清依赖清单里的硬性项和可选加速项，再用几条命令核对运行时下限，最后才动手装。下面四步按这个顺序展开，每一步都给出可执行的确认动作，路径和文件名请以你拉下来的实际仓库为准。
处理 EchoWM 这类仓库，建议先把目录职责认全，再按依赖清单区分跑不起来的硬性依赖和可以后补的加速项，安装前用命令核对 Python、驱动与加速库是否达到下限。首次运行报错按缺失文件、版本冲突、显存不足的顺序排查，每步都用同一条启动命令复测。具体目录名和权重位置以实际仓库和默认配置为准，不同分支可能不一样。
按目录确认代码、配置、权重、示例数据各自在哪
先别急着 pip install。在仓库根目录用 ls 或 git ls-files | head -50 看一遍顶层结构，把每个目录归到四类里：代码、配置、权重、示例数据。归类的目的很直接——知道哪一类需要你自己下载、哪一类缺了不影响首次跑通。
| 目录（常见命名） | 通常放什么 | 是否必需 | 怎么确认 |
|---|---|---|---|
| 入口脚本（demo / inference / train 之类） | 启动推理或训练的入口 | 必需 | 看仓库说明里的启动命令指向哪个文件 |
| configs/ 或 conf/ | 模型与运行的参数文件 | 通常必需 | 打开默认配置，看它引用的权重路径 |
| 模型代码目录（models/、src/ 等） | 网络结构与前后处理 | 必需 | 与配置里的类名、文件名对得上 |
| checkpoints/ 或 weights/ | 权重文件 | 多数仓库不含，需自行下载 | ls 看是否为空或只有占位文件 |
| data/ 或 examples/ | 示例输入 | 首次跑通可能需要 | 用于验证流程，不用于正式结果 |
| scripts/ | 下载权重、转换格式等辅助脚本 | 条件必需 | 看仓库说明是否要求先执行 |
上面这些目录名只是常见写法，EchoWM 实际叫什么以仓库为准，别按名字硬套；判断依据是目录里文件的实际内容和默认配置的引用路径。权重文件通常体积大、不进 git，所以在 git ls-files 里看不到，需要单独下载。确认权重该放哪最直接的办法是打开默认配置，找到里面的路径字段，再按这个路径去放文件或改配置指向真实位置。
读依赖清单，区分硬性依赖与可选加速项
依赖声明常见几种形式，阅读顺序建议是：Dockerfile 或 environment.yml（信息最全，含系统级与 Python 版本）→ pyproject.toml / setup.py（带 extras 分组）→ requirements.txt（最常见，但常只覆盖一部分）→ 仓库说明里的安装段（往往写了作者实际用的顺序）。几份清单不一致时，以能跑通的那份为准，不要混装。
逐条过的时候按下面顺序：
- 先找硬性依赖：模型框架本体、核心 import 的包。少一个就直接导入失败。
- 再看可选依赖：常见标注是 extras 分组、
# optional注释，或者说明里写着“如需 XX 再装”。这类可以先不装，等报错再补。 - 标出必须按机器改动的行：与 CUDA 版本绑定的框架安装源、需要本地编译工具链的编译型包、带平台条件标记的行。这些在别人机器上能装，在你这里可能需要替换。
- 最后看被注释掉的包和版本上限标记：注释掉的往往是历史遗留或已知冲突项，别顺手解开。
操作上建议先建独立虚拟环境再装，装完用 pip check 看依赖关系是否自洽。至于各种加速项，装不上时先确认代码是否强制要求——不少仓库有开关或回退路径，可以先跑通基础流程，再回头补这些。
用检查命令确认运行时环境是否满足下限
安装前先用几条命令把版本问题暴露出来。下面只是骨架，具体下限以仓库说明或依赖清单里写的要求为准，这里不预设任何版本号。
# 1. 解释器与包管理器
python -V
which python
pip -V
# 2. 显卡驱动及其自带的 CUDA 能力
nvidia-smi
# 3. 本地编译工具链（仅当依赖里有需要编译的包）
nvcc -V
# 4. 框架与加速库实际装到的版本
python -c "import torch;print(torch.__version__, torch.version.cuda, torch.cuda.is_available())"
# 5. 依赖关系自检
pip check比对方式很简单：把上面的输出与仓库要求的最低版本逐项对照，只判断有没有达到下限，不追求完全一致。几个容易忽略的点：nvidia-smi 显示的是驱动支持的 CUDA 上限，不等于本地装了 CUDA 工具链；torch.version.cuda 为 None 或 cuda.is_available() 为 False，说明装到的是 CPU 版本或驱动不匹配；容器、虚拟机、WSL 里的驱动情况与宿主机不同，需要单独确认。如果不满足，先解决环境，再去装仓库其余依赖，否则后面每个报错都要重新判断是不是环境造成的。
首次运行的报错按缺失文件、版本冲突、显存不足三步定位
第一次运行报错，建议按“缺失文件 → 版本冲突 → 显存不足”的顺序处理，一次只改一处，改完用同一条启动命令复测。顺序的原因：前两类是代码根本起不来，第三类是起来了但跑不动，混着改会分不清是哪一步起了作用。
第一步：缺失文件
典型日志是 FileNotFoundError、No such file or directory、加载权重时提示路径不存在，或者配置里引用的文件名对不上。验证动作：把日志里的完整路径抄出来，在终端 ls -l 这个路径，确认是文件真的缺失、路径层级写错，还是权重下载到了别的位置。确实没有权重时，回到仓库说明里找下载方式的描述，不要用手边的其他权重顶替，除非形状和命名都对得上。改完重新执行启动命令，看能不能越过这一行报错。
第二步：版本冲突
典型日志是 ImportError、ModuleNotFoundError、undefined symbol、某个模块没有预期属性，以及 pip 报依赖解析失败。验证动作：先 pip check，再单独 python -c "import 模块名" 把范围缩到某一个包，然后 pip show 包名 看实际装的版本，与仓库要求对照。重建虚拟环境重装通常比在原地反复升降级更干净。复测还是同一条命令，确认报错行有没有变化。
第三步：显存不足
典型日志是 CUDA out of memory 或 torch.cuda.OutOfMemoryError，并提示尝试分配多少、当前已占用多少。验证动作：另开一个终端跑 watch -n 1 nvidia-smi，观察运行时的占用情况，确认是显存本来就不够，还是同一张卡上有别的进程占着。处理方向是降低批大小或输入分辨率、减少并行进程，先让流程跑通再逐步调回。这类调整只影响单次运行的内存占用，不构成性能优化。
三类都过一遍后，把最终能跑通的启动命令、配置路径和权重位置记在仓库说明旁边。下次换机器或换分支时按同样顺序复查，比重新翻一遍零散教程省事。