WorldSonus 装完却起不来，先不要急着怀疑代码本身。大多数这类启动失败，都能从第一条异常里归到三类之一：Python 依赖被其他包顶掉、模型权重没落在程序实际读取的目录、显存或内存资源不足。判断顺序建议是：先看真正抛错的栈帧和错误类型，再核对依赖版本，然后确认权重路径，最后才看资源。下面按这四个方向给出可执行的确认动作和最小修复步骤。
WorldSonus 启动失败时，先用第一条异常把问题归到依赖、路径或资源三类，不要从日志最后一行倒推。依赖类看 ModuleNotFoundError、ImportError、版本冲突提示；路径类看 FileNotFoundError、找不到权重文件、配置项里的模型目录不存在；资源类看 CUDA out of memory 或进程被系统杀掉。每次只改一项并保留验证日志，改多处会导致无法归因。
先读第一条报错，不要从最后一行猜
Python 的异常栈要从下往上看：最下面一行是最终抛出的异常类型和消息，紧挨着它往上的几行是真正出错的文件和行号，再往上是各级调用。日志最后一行往往只是“进程退出码 1”或框架统一包装的提示，直接拿它去搜，容易把问题带到错误方向。
找到最早出现异常的栈帧后，按错误字样分类：
- 依赖缺失或版本不符：出现
ModuleNotFoundError: No module named 'xxx'、ImportError: cannot import name 'xxx'、AttributeError: module 'xxx' has no attribute 'yyy'，或者报错提到某个库的版本不满足要求。这类错误通常发生在 import 阶段，程序还没开始加载模型。 - 路径不存在：出现
FileNotFoundError: [Errno 2] No such file or directory、IsADirectoryError，或者框架自己抛出的“找不到 config.json / 找不到权重文件 / 找不到 tokenizer 相关文件”。这类错误通常发生在程序已经 import 完成、开始构造模型的时候。 - 资源不足：出现
CUDA out of memory、torch.cuda.OutOfMemoryError，或者进程没有任何 Python 异常、直接被系统终止。这类错误通常发生在模型加载到设备或首次前向计算时。
建议把完整启动日志重定向到文件再读，例如 python 启动入口.py 2>&1 | tee run.log，这样能翻到第一处异常，不用在终端里来回滚。
用环境导出结果核对依赖是否被顶掉
确认依赖是否被顶掉，最直接的办法是把当前环境的包清单导出来，和仓库声明的依赖文件逐项比对。导出命令的骨架通常是：
python -m pip freeze > env-now.txt
python -m pip list `--format`=columns > env-list.txt
python -V然后打开仓库里的依赖声明文件（可能是 requirements.txt、pyproject.toml、environment.yml 或 setup.py，字段名以仓库实际声明为准），把以下字段逐项对齐：
- Python 解释器版本：与声明的最低版本或版本区间对照。
- 核心框架版本：例如 torch、torchvision、torchaudio、numpy、transformers 一类，这类包互相之间有版本咬合关系，单独升级一个容易连带出错。
- CUDA 相关包版本：与当前驱动支持的运行版本对照，不要只看包名。
- 声明了版本上限的包：被其他依赖顶到更高版本时，往往表现为 import 成功但调用时缺属性。
发现不一致时，最小修复动作是：先创建一个干净虚拟环境，再按声明的依赖文件安装，避免在原环境里逐个降级。能否直接升级或降级，需要结合仓库声明的版本区间确认，不要凭感觉替换。
确认权重文件落在程序实际读取的目录
路径类问题的关键是区分“你以为的目录”和“程序实际读取的目录”。找默认读取路径有两个入口：一是配置文件里声明模型目录的字段，二是启动日志中打印的加载路径。启动日志通常在加载模型前会输出类似“loading model from …”的行，这一行就是程序实际读取的位置。
拿到路径后做两件事：第一，用 ls -l 路径 确认该目录存在且里面有配置文件和权重文件；第二，核对目录层级是否多套了一层。常见的写法差异包括：
- 配置里写相对路径，但启动时工作目录不是仓库根目录，实际解析到了别的位置。
- 权重解压后多出一层同名目录，例如期望是
models/xxx/config.json，实际是models/xxx/xxx/config.json。 - 文件名大小写不一致，或者权重文件和配置文件不在同一目录。
- 用符号链接或挂载路径时，容器内外路径不一致。
最小修复动作是改配置项指向真实目录，或者在启动命令里显式切换工作目录，而不是把文件复制到多个位置试。改完后用启动日志里的加载路径行确认程序读的就是你改的那条路径。
区分配置报错与显存不足
资源配置错误和代码错误的处理方式完全不同，界面上看都是“跑不起来”，但日志特征明显不同。显存不足时的典型字样是 CUDA out of memory、torch.cuda.OutOfMemoryError，有时会附带“tried to allocate …”这类描述；如果是被系统层面终止，Python 不会留下异常，只有进程退出或被 kill 的记录。
观察方式是在另一个终端同时监控显存占用，例如 nvidia-smi -l 2 循环刷新，或在启动脚本前后各记录一次显存使用情况。看到显存占用在模型加载阶段快速上涨并触发报错，基本可以归为资源类；如果显存占用很低就报错，更可能是配置或路径问题。这里只描述现象，具体能加载多大的模型需要结合显卡型号和框架配置自行确认。
资源类问题的处理顺序建议是多卡或减少负载参数、检查是否有其他进程占着显存、确认是否误开了不该开的优化项，而不是去改代码逻辑。
改完一项只验一项
启动失败时最忌讳一次改依赖、改路径、改参数，改完之后虽然能跑，但已经不知道是哪一项起了作用。建议按下面的顺序单变量验证：
- 只修依赖：重建干净环境并按声明安装，重新启动，观察第一条异常是否变化。
- 只修路径：保存依赖环境不动，只改配置项或工作目录，重新启动，观察是否越过加载阶段。
- 只调资源相关参数：前两项确认无误后，再处理显存或并发相关配置。
每次验证后保留的日志行包括：启动命令本身、Python 版本输出、第一条异常的完整栈、模型加载路径那一行、进程退出码。把这几次日志分开保存，前后对比第一条异常是否从 import 类变成路径类，就能确认修改是否真的推进了问题，而不是被新报错掩盖。