# ValueError: safetensors 元数据不匹配：期望 1024 个张量，实际得到 1023 个

- **ID:** `huggingface/safetensors-metadata-mismatch`
- **领域:** huggingface
- **类别:** data_error
- **验证级别:** ai_generated
- **修复率:** 85%

## 根因

safetensors 文件头部元数据声明的张量数量与实际文件中存储的张量数量不一致，通常是由于下载不完整或检查点损坏导致。

## 版本兼容性

| 版本 | 状态 | 引入 | 弃用 |
|------|------|------|------|
| safetensors>=0.3.0 | active | — | — |
| transformers>=4.30.0 | active | — | — |
| huggingface-hub>=0.16.0 | active | — | — |

## 解决方案

1. ```
   Clear the Hugging Face cache and re-download the model: `rm -rf ~/.cache/huggingface/hub/models--org--model-name/` then `from transformers import AutoModel; AutoModel.from_pretrained('org/model-name')`
   ```
2. ```
   Use the huggingface_hub CLI to force re-download: `huggingface-cli download org/model-name --cache-dir /tmp/new-cache --local-dir ./model --force-download`
   ```
3. ```
   If the file is partially downloaded, use `wget -c` to resume: `wget -c https://huggingface.co/org/model-name/resolve/main/model.safetensors`
   ```

## 无效尝试

- **Re-download the same file without clearing cache** — If the cached file is corrupted, re-downloading to the same cache path without clearing will reuse the broken file. (70% 失败率)
- **Manually editing the safetensors metadata with a hex editor** — Safetensors files are integrity-checked; any manual tampering causes a checksum error and breaks loading entirely. (95% 失败率)
- **Upgrading transformers to the latest version** — The error originates from the safetensors library, not transformers; upgrading transformers alone does not fix the corrupted file. (60% 失败率)