模型加载失败怎么查
加载阶段起不来，按固定顺序查更省时间：路径与权限 → 文件完整性（分片与索引） → 配置匹配（架构、量化、精度） → 显存与内存 → 依赖与版本。每一层的报错关键词不同，逐层排除比反复重启有效，也能避免重启把日志覆盖掉。
基本信息
| 常见报错类别 | 找不到文件、权限拒绝、分片缺失、架构或量化配置不匹配、加载即显存不足、依赖缺失 |
|---|---|
| 最小验证 | 只读权重文件头并统计张量数，不占用 GPU |
| 日志位置 | 服务启动日志与容器标准输出 |
| 容器场景 | 确认挂载路径与宿主路径的对应关系 |
| 排查方式 | 逐层排除，每步只改一个条件 |
典型使用场景
- 服务启动即失败：先分清是找不到文件还是配置不匹配
- 换机器或换容器后起不来：多为路径映射与运行用户权限问题
- 下载中断导致不完整：分片文件缺失或大小异常，需要按索引核对
- 量化模型首次部署：缺量化配置或精度设置不符会直接报错
- 加载即显存不足：先看卡上是否有其他进程，再看模型是否真的装不下
核对文件与索引
核对文件与索引
ls -lh <模型目录>/*.safetensors | head # 各分片是否齐全、大小是否合理
cat <模型目录>/model.safetensors.index.json | head -20 # 索引里列了哪些分片
du -sh <模型目录> # 总量与预期是否相符
# 索引列出的文件必须全部存在且大小正常，否则加载到中途才报错最小验证：读权重头（不占 GPU）
最小验证：读权重头（不占 GPU）
# 只读取权重文件头并统计张量数，用来验证文件可读、格式正常
python -c "from safetensors import safe_open; f = safe_open('<权重文件>', framework='pt'); print(len(f.keys()))"
# 若这一步就失败，问题在文件或依赖，不在显存与推理框架报错关键词定位表
| 关键词 | 方向 | 首查项 |
|---|---|---|
| No such file / Permission denied | 路径与权限 | 运行用户对目录是否可读可进入 |
| index.json 相关报错 | 文件完整性 | 索引列出的分片是否全部存在 |
| unknown architecture / config | 配置匹配 | 架构名与量化配置是否与权重一致 |
| 加载阶段显存不足 | 硬件资源 | 卡上是否有其他进程占用 |
| undefined symbol / 缺模块 | 依赖版本 | 框架与算子的版本组合是否匹配 |
报错不要只看最后一行：加载失败的关键信息常在 traceback 的前半段，日志被滚动覆盖时就找不回来了。
分片下载中断是最常见的原因之一：用索引清单与文件大小双向核对，比只看目录是否存在可靠得多。