首页/AI/大模型部署与运维速查/模型加载失败:排查顺序
本包目录(267 条)
部署形态与选型43 条推理环境与 GPU50 条推理参数与优化50 条显存与并发估算40 条服务化与网关34 条
运维监控与排障50 条

模型加载失败:排查顺序

加载阶段起不来按固定顺序查:路径与权限 → 文件完整性(分片与索引) → 配置匹配(架构、量化、dtype) → 显存与内存 → 离线依赖,逐层排除比反复重启有效。

核对文件与索引

核对文件与索引
ls -lh <模型目录>/*.safetensors | head
cat <模型目录>/model.safetensors.index.json | head -20
du -sh <模型目录>

最小验证:读权重头(需装 safetensors,不占 GPU)

最小验证:读权重头(需装 safetensors,不占 GPU)
python -c "from safetensors import safe_open; f = safe_open('<权重文件>', framework='pt'); print(len(f.keys()))"
  • 权限:运行用户(如 www)对目录可读;容器内挂载路径别搞错
  • 分片缺失:index.json 列出的文件必须全部存在且大小正常
  • 配置匹配:架构名与权重一致;量化模型缺量化配置会报 unknown
  • 硬件:加载即 OOM 时先看卡上有没有别的进程

易错点

  • 报错只看最后一行:加载失败的关键信息常在被截掉的 traceback 前半段

数据来源与参考

  • Hugging Face 官方文档:safetensors 与模型文件结构
  • vLLM 官方文档:Troubleshooting(docs.vllm.ai)
​‌‌​​‌​​​‌‌​‌‌‌‌​‌‌​​​‌‌​‌‌‌​​‌‌​​‌​‌‌‌​​‌‌‌​​​‌​‌‌​‌​​‌​‌‌‌​​​‌​‌‌​‌​​‌​‌‌​​​‌‌​‌‌‌​‌​​​‌‌​‌‌‌‌​​‌​‌‌‌​​‌‌​​​‌‌​‌‌​‌‌‌‌​‌‌​‌‌​‌