safetensors 模块缺失还是权重文件无法读取？先分阶段排查

文件后缀不能替代 Python 库

Safetensors 官方文档区分 Python 包和文件读取接口。导入失败发生在解析具体权重文件之前。后续出现 SafetensorError 也不能仅凭异常类名断定下载损坏：上游源码还区分头部格式、大小限制、偏移量和缓冲区不完整等错误。Safetensors 文档 读取器错误定义

python -c "import sys; print(sys.executable); import safetensors; print(safetensors.__version__)"

两条排查路线

请用启动 ComfyUI 的同一个 Python 解释器执行上面的命令；包装在另一个环境里不等于当前进程能导入。若导入成功，保留完整异常及失败路径。进入文件读取阶段后，先记录发布仓库、revision、路径、实际大小和发布者提供的校验依据，再判断是下载不完整、格式不支持还是选错了文件。不要只记录模型家族名称，也不要靠更改后缀来修复头部或缓冲区错误。

如果怀疑下载不完整，建议把新下载保存成独立文件，先比较，再决定替换；不要在唯一一份仍可能有效的文件上覆盖试错。存在相同文件名的多个版本时，保存来源关系，比比较文件名更有用。

我们建议的验收记录

分别记录库导入、独立文件读取和工作流加载结果。官方 safetensors.torch.load_file 接口可以读取指定文件中的张量；读取成功不证明张量键或架构适合当前 ComfyUI 加载器。Torch API 模型加载也不代表所有输出都已验证。

安全边界

本页不运行未知权重、不修改权重头部，也不提供强行忽略格式校验的方案。没有来源校验值时，明确写“缺少比对依据”，不生成一个哈希后就称为官方验证。

相关排查

• Spandrel 已安装仍打不开模型：先查支持的架构
• Transformers 缺包、找不到类、模型下载失败：不要混着修

2026-09-26 复核来源并审阅中文。未安装包、读取本地文件、执行 ComfyUI 或 GPU 复现。步骤是编辑建议，不表示已诊断你的文件。