# OSError：无法从 Hugging Face 检查点加载权重。错误：文件已损坏或截断

- **ID:** `llm/huggingface-model-load-cache-corruption`
- **领域:** llm
- **类别:** resource_error
- **验证级别:** ai_generated
- **修复率:** 90%

## 根因

Hugging Face 模型缓存文件的部分下载或磁盘损坏，通常是由于下载中断或对缓存目录的并发写入访问导致。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| transformers==4.41.0 | active | — | — |
| huggingface_hub==0.23.0 | active | — | — |
| torch==2.3.0 | active | — | — |

## 解决方案

1. ```
   Clear the specific model cache and re-download: `rm -rf ~/.cache/huggingface/hub/models--bert-base-uncased` then reload the model.
   ```
2. ```
   Use `snapshot_download` with `resume_download=False` to force a fresh download: `from huggingface_hub import snapshot_download; snapshot_download('bert-base-uncased', resume_download=False)`
   ```
3. ```
   Set `HF_HUB_ENABLE_HF_TRANSFER=1` to use the faster download library which includes integrity checks by default.
   ```

## 无效尝试

- **** — The corrupted file remains in the cache; the loader will attempt to read the same broken file and fail again. (100% 失败率)
- **** — The error is about file integrity, not capacity; more space won't fix a truncated file. (80% 失败率)
- **** — This changes the model entirely and doesn't address the cache corruption for the original model. (90% 失败率)