# OSError：无法从缓存加载模型：'pytorch_model.bin' 文件哈希不匹配。期望 sha256：abc123... 但得到 xyz789...

- **ID:** `huggingface/transformers-cache-corruption`
- **领域:** huggingface
- **类别:** system_error
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

缓存的模型文件损坏（例如由于下载不完整、磁盘错误或并发写入），导致完整性验证期间 SHA-256 哈希不匹配。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| transformers>=4.20.0 | active | — | — |
| huggingface_hub>=0.12.0 | active | — | — |

## 解决方案

1. ```
   清除整个缓存目录：rm -rf ~/.cache/huggingface/hub/；然后使用 from_pretrained() 重新加载模型。这会强制重新下载。
   ```
2. ```
   使用 huggingface-cli 选择性清除缓存：huggingface-cli delete-cache；或设置 HF_HUB_ENABLE_HF_TRANSFER=1 以使用稳健的下载器。
   ```

## 无效尝试

- **Delete only the specific corrupted file and re-run the script** — The cache may still contain partial or corrupted metadata; the download might resume from a broken state. (60% 失败率)
- **Set `torch.hub.set_dir()` to a different directory and reload** — This changes the download location but does not fix the corruption in the original cache; the error persists if the same cache is used. (75% 失败率)
- **Ignore the hash check by setting `local_files_only=False`** — This forces a re-download but does not delete the corrupted file; the download may fail again or use the same broken file. (50% 失败率)