mi renoir token.bin 无法加载模型权重如何解决？

Question

问题：在使用 `mi_renoir` 模型时，加载 `token.bin` 权重文件报错“Unable to load state dict”，导致模型初始化失败。常见原因包括权重文件路径错误、文件损坏或格式不兼容。此外，PyTorch 版本与保存权重时的版本不一致也可能引发加载异常。部分情况下，`token.bin` 并非完整模型权重，而仅为 tokenizer 编码表，误将其作为模型参数加载会导致解析失败。需确认权重文件实际内容、匹配模型结构，并检查是否需通过 `.safe_tensor` 或 `.pt` 正确加载。

Answer 1

1. 问题现象与初步排查

在使用 mi_renoir 模型加载权重时，出现“Unable to load state dict”的报错，提示模型无法从 token.bin 文件中恢复状态字典。该问题通常发生在调用 torch.load() 或 model.load_state_dict() 时。

• 检查文件路径是否正确，确认 token.bin 是否存在于指定目录。
• 验证文件权限，确保运行进程有读取权限。
• 通过 os.path.exists() 和 os.path.getsize() 判断文件是否存在且非空。

2. 权重文件内容分析

并非所有以 .bin 结尾的文件都是 PyTorch 模型权重。部分情况下，token.bin 实际是 tokenizer 的词汇表或编码映射表（如 SentencePiece 模型），而非 state_dict。

import pickle
try:
    data = torch.load("token.bin")
    print("Loaded as PyTorch tensor/state_dict.")
except Exception as e:
    print(f"PyTorch load failed: {e}")
    
try:
    with open("token.bin", "rb") as f:
        raw_data = f.read(64)
    print(f"Binary header preview: {raw_data}")
except IOError:
    print("File not accessible.")
    

3. 格式兼容性与序列化方式

现代模型常采用 .safetensors 格式替代传统 .pt 或 .bin，因其更安全、高效。若原始权重为 safetensors 格式但被重命名为 .bin，将导致解析失败。

文件扩展名	典型用途	加载方式
.pt / .pth	PyTorch state_dict	torch.load()
.bin	通用二进制文件（可能非模型）	需判断内容类型
.safetensors	安全张量存储	from safetensors.torch import load_file
.model	Tokenizer 模型文件	SentencePieceProcessor.Load()

4. PyTorch 版本与序列化协议差异

不同版本的 PyTorch 使用不同的内部序列化协议。例如，旧版保存的 legacy_pickle 格式可能无法被新版正确反序列化，尤其涉及自定义类或未注册的命名空间。

# 查看当前 PyTorch 版本
print(torch.__version__)

# 尝试兼容性加载
try:
    state_dict = torch.load("token.bin", map_location="cpu", weights_only=True)
except RuntimeError as e:
    if "expected version <= X" in str(e):
        print("Version mismatch detected. Consider using older PyTorch or converting weights.")
    

5. 模型结构与 state_dict 键名匹配

即使成功加载字典，若模型类定义的层名与 state_dict.keys() 不匹配，仍会触发错误。常见于模型实现变更、前缀缺失（如缺少 module.）等情况。

• 打印现有 state_dict 键名：print(state_dict.keys())
• 对比模型实际参数名：print(dict(model.named_parameters()).keys())
• 必要时进行键名映射或前缀裁剪。

6. 完整诊断流程图

graph TD
            A[开始加载 token.bin] --> B{文件存在且可读?}
            B -- 否 --> C[检查路径/权限]
            B -- 是 --> D[尝试 torch.load]
            D -- 失败 --> E[是否为 safetensors?]
            E -- 是 --> F[使用 safetensors.load_file]
            E -- 否 --> G[检查是否为 tokenizer 文件]
            G -- 是 --> H[改用 Tokenizer API 加载]
            G -- 否 --> I[检查 PyTorch 版本兼容性]
            D -- 成功 --> J{键名匹配模型结构?}
            J -- 否 --> K[调整键名或模型定义]
            J -- 是 --> L[成功加载]

7. 解决方案建议清单

1. 确认 token.bin 是否为模型权重文件，而非 tokenizer 资产。
2. 使用 file token.bin 命令查看其真实格式（Linux/macOS）。
3. 若为 SafeTensor 格式，安装 safetensors 包并使用专用加载器。
4. 检查项目文档或 Hugging Face 页面，确认权重发布格式。
5. 尝试在虚拟环境中降级 PyTorch 至训练时版本。
6. 使用 weights_only=True 提高安全性并避免潜在攻击向量。
7. 若确为 tokenizer 文件，应通过 AutoTokenizer.from_pretrained() 调用。
8. 构建调试脚本批量检测多个候选文件。
9. 联系模型维护者获取元信息或校验和。
10. 记录日志包括 SHA256 校验值，便于复现问题。

8. 高级调试技巧

对于复杂情况，可通过 monkey patching 或自定义 unpickler 捕获反序列化过程中的异常对象。此外，使用 torch.jit.load() 可识别是否为 TorchScript 模型。

# 示例：自定义 Unpickler 用于调试类缺失问题
class DebugUnpickler(pickle.Unpickler):
    def find_class(self, module, name):
        try:
            return super().find_class(module, name)
        except AttributeError:
            print(f"Class lookup failed: {module}.{name}")
            return None

with open("token.bin", "rb") as f:
    data = DebugUnpickler(f).load()