登录
推荐 文章 Go 技术 课程 下载 专题 AI
首页 >  科技周边 >  人工智能

Safetensors 怎样只读取张量元数据而不加载全部权重

来源:17golang原创

时间:2026-11-19 13:35:01 240浏览 收藏

查看大型模型文件时,真正需要的往往是张量名、形状和 dtype,而不是马上把所有权重变成 PyTorch 张量。Safetensors 的实用做法是先用 safe_open 读取文件头,再决定是否调用 get_tensor 或 get_slice。这样可以把“查看结构”和“加载权重”拆开,避免一次性占用与模型大小接近的内存。

官方地址:https://huggingface.co/docs/safetensors/

要点速览
  • keys() 和 metadata() 只用于查看索引与文件级说明,不会返回完整权重。
  • get_slice() 适合先看形状、dtype,或只取一个张量的局部范围。
  • 远程 Hub 文件要查看头部时,可用 HTTP Range 请求;分片模型还要结合 index 文件。

先读取文件头,不要直接调用 load_file

Safetensors 文件开头包含固定长度信息和 JSON 头部,头部记录张量名、dtype、shape、data_offsets,以及可选的 __metadata__。因此,检查模型结构时优先打开文件并遍历 keys。load_file 的语义是把文件中的张量加载成字典,不适合作为第一步的“目录查看器”。

from safetensors import safe_open

file_path = "model.safetensors"

# 只查看张量索引和文件级 metadata,不创建完整权重字典
with safe_open(file_path, framework="pt", device="cpu") as handle:
    tensor_names = list(handle.keys())
    file_metadata = handle.metadata() or {}

print("张量数量:", len(tensor_names))
print("前几个名称:", tensor_names[:5])
print("文件 metadata:", file_metadata)

这里的 metadata 是保存时写入的字符串键值信息,不能把它当成每个张量的数值统计。若只需要知道有哪些权重、文件采用什么格式,这一步就已经足够。

Safetensors 文件头连接张量名称、dtype、shape 与 metadata 的结构说明图
图1:Safetensors 文件头的原创结构说明图,展示索引信息与权重数据的边界,不是运行截图。

用 get_slice 查看形状并按需取局部数据

如果还要知道某个张量的形状和 dtype,可以从 get_slice 返回的对象读取元信息。只有在真正索引切片时,才把所需范围交给框架。不要为了打印 shape 先调用 get_tensor,后者会得到整个张量。

from safetensors import safe_open

with safe_open("model.safetensors", framework="pt", device="cpu") as handle:
    # get_slice 先保留按需访问能力,不把整个 embedding 读入变量
    view = handle.get_slice("embedding")
    print("shape:", view.get_shape())
    print("dtype:", view.get_dtype())

    # 只取前 32 行和前 128 列;索引范围应按实际张量形状调整
    preview = view[:32, :128]
    print("局部形状:", tuple(preview.shape))

get_slice 不是把全部权重“变小后永久缓存”,而是把读取范围交给底层实现;局部数据一旦取出,仍然会占用与该局部结果相应的内存。要做完整推理或训练,最终仍需加载模型需要的权重。

Safetensors 通过 get_slice 从单个张量索引到局部数据的关系说明图
图2:按需访问关系说明图,突出 get_slice、shape/dtype 和局部张量之间的边界,不是运行证据。

本地文件和远程模型要分开处理

本地文件适合用 safe_open 做索引查看和局部读取。若文件在 Hugging Face Hub,且目标只是查看头部元数据,可以用两个 Range 请求:先取 0 到 7 字节得到头部长度,再取 JSON 头部。头部里的 data_offsets 是相对于数据区的偏移,不能直接当作远程文件的绝对 URL。

目标推荐入口是否读取完整权重
查看张量名和文件说明safe_open、keys、metadata否
查看形状并取局部范围get_slice只取需要的范围
完整推理或训练get_tensor、模型加载器按模型需求加载
Hub 远程头部检查HTTP Range 或 get_safetensors_metadata通常不下载全部权重

分片模型还要先根据 model.safetensors.index.json 的 weight_map 判断某个张量落在哪个文件,再对对应文件读取头部。只看单个分片的 keys,不能推断整个模型的完整张量集合。

相关问题

读取 metadata 会把权重载入内存吗?

不会。它读取的是文件头中的字符串键值;真正的张量数据需要通过取值或切片入口访问。

为什么不直接用 load_file?

load_file 面向完整张量字典。只做结构检查时,safe_open 更容易控制读取范围。

get_slice 能保证永远不占用大内存吗?

不能。切片结果仍会占用对应范围的内存,过大的切片或后续复制同样可能产生压力。

远程文件的 Range 请求适合训练吗?

它更适合元数据检查或小范围读取;训练需要稳定、连续的权重访问,应使用模型加载器和合适的缓存策略。

声明:本文转载于:17golang原创 如有侵犯,请联系study_golang@163.com删除
相关阅读
更多>
最新阅读
更多>
课程推荐
更多>