safetensors 报 HeaderTooLarge，下载到的可能只是 LFS 指针

加载 .safetensors 权重时，程序刚打开文件就报 HeaderTooLarge。它检查的是文件头声明的长度，不是模型参数量或显存是否足够。一个扩展名正确的文件，也可能只是 Git LFS 指针、错误页面或损坏的下载内容。

以下按 safetensors 0.5.3 的格式解析说明。不同版本的异常文字可能写成 header too large，排查时仍应确认实际打开的文件。

只读一点文件，先判断它是什么

safetensors 的前 8 字节是小端无符号整数，表示后面 JSON header 的字节数。0.5.3 会拒绝超过 100,000,000 字节的 header。文本文件的开头如果被当成这个整数读取，可能得到极大的值，因而在读取张量之前失败。

下面是只读诊断示例，把路径换成异常指向的那一份权重分片；不要对多 GB 文件直接全文打印：

from pathlib import Path

path = Path("/srv/models/model-00001-of-00002.safetensors")
print("bytes:", path.stat().st_size)
with path.open("rb") as handle:
    prefix = handle.read(256)
print("prefix:", repr(prefix))
if len(prefix) >= 8:
    print("declared header bytes:", int.from_bytes(prefix[:8], "little"))

若前缀类似以下三行，它是指向大文件的文本记录，不是权重本身。这里的哈希和大小仅用于展示格式：

version https://git-lfs.github.com/spec/v1
oid sha256:REPLACE_WITH_OBJECT_HASH
size 1234567890

指针里 size 描述真正对象的字节数，当前文本文件可能只有一百多字节。前缀是 HTML 或 JSON 错误响应时，则应回查下载地址、身份与响应状态。小文件是线索，不应仅按大小认定所有合法 safetensors 文件都损坏。

确认是 LFS 指针，再补齐对应对象

在可信模型仓库的工作副本中，确认当前 revision 正确、工作区改动已保存、网络与仓库读取权限可用。Git LFS 已安装后，可以执行下面的修复片段：

git lfs install --local
git lfs pull

install --local 配置当前仓库的 LFS 支持，pull 下载当前 ref 的 LFS 对象并在需要时更新工作副本。它可能下载大量文件并占用磁盘，先核对剩余空间及 include/exclude 设置。保留原文件与仓库 revision，不在混有未保存模型修改的工作区直接覆盖。

只执行 git lfs fetch 会下载对象，但不等于工作副本中的指针已经替换；不要手动在 .git/lfs 里随意找一个 blob 改名成权重。需要限定文件范围时，也必须包括权重索引实际引用的所有分片，而不是只补第一片。

若文件本来通过 HTTP 下载，重新获取真正的文件地址并核对成功响应，不必为了修一次下载把整个目录改造成 Git 仓库。受限模型下载失败时，核对该仓库的访问批准与实际运行环境提供的 token。文件解析尚未通过时，调整 GPU 配置不会补齐错误的文件。

没有指针特征时，不修改解析上限

LFS 只是其中一种原因。还应比较模型发布方提供的文件大小与哈希，确认文件格式匹配、传输未截断、磁盘没有写满。分片模型按索引核对每个实际文件，避免修了另一个同名副本。

将 .pt 或 .ckpt 重命名为 .safetensors 不会转换格式。也不要为了让文本或损坏文件通过，修改 header 上限或绕过解析检查。

恢复后确认前缀已不是指针或错误页、大小与可信发布记录匹配，并让原加载器完成解析。在有足够资源的验证环境中再检查模型输出；“header 不再报错”还不能证明模型、tokenizer 与配置版本一致。保留错误文件的诊断副本，确认新文件通过前不删除原缓存。