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

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

本地文件和远程模型要分开处理
本地文件适合用 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 请求适合训练吗?
它更适合元数据检查或小范围读取;训练需要稳定、连续的权重访问,应使用模型加载器和合适的缓存策略。
-
501 收藏
-
501 收藏
-
501 收藏
-
501 收藏
-
501 收藏
-
289 收藏
-
382 收藏
-
258 收藏
-
132 收藏
-
202 收藏
-
309 收藏
-
258 收藏
-
389 收藏
-
346 收藏
-
316 收藏
-
429 收藏
-
283 收藏
-
- 前端进阶之JavaScript设计模式
- 设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
- 立即学习 543次学习
-
- GO语言核心编程课程
- 本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
- 立即学习 516次学习
-
- 简单聊聊mysql8与网络通信
- 如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
- 立即学习 500次学习
-
- JavaScript正则表达式基础与实战
- 在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
- 立即学习 487次学习
-
- 从零制作响应式网站—Grid布局
- 本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
- 立即学习 485次学习