当前位置:首页 > 文章列表 > 科技周边 > 人工智能 > Safetensors 怎样只读取张量元数据而不加载全部权重

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

来源:17golang原创 2026-11-19 13:35:01 0浏览 收藏

查看大型模型文件时,真正需要的往往是张量名、形状和 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删除
PEFT LoraConfig 怎样只训练指定模块PEFT LoraConfig 怎样只训练指定模块
上一篇
PEFT LoraConfig 怎样只训练指定模块
下一篇
下一篇
暂无
查看更多
最新文章
查看更多
课程推荐
  • 前端进阶之JavaScript设计模式
    前端进阶之JavaScript设计模式
    设计模式是开发人员在软件开发过程中面临一般问题时的解决方案,代表了最佳的实践。本课程的主打内容包括JS常见设计模式以及具体应用场景,打造一站式知识长龙服务,适合有JS基础的同学学习。
    543次学习
  • GO语言核心编程课程
    GO语言核心编程课程
    本课程采用真实案例,全面具体可落地,从理论到实践,一步一步将GO核心编程技术、编程思想、底层实现融会贯通,使学习者贴近时代脉搏,做IT互联网时代的弄潮儿。
    516次学习
  • 简单聊聊mysql8与网络通信
    简单聊聊mysql8与网络通信
    如有问题加微信:Le-studyg;在课程中,我们将首先介绍MySQL8的新特性,包括性能优化、安全增强、新数据类型等,帮助学生快速熟悉MySQL8的最新功能。接着,我们将深入解析MySQL的网络通信机制,包括协议、连接管理、数据传输等,让
    500次学习
  • JavaScript正则表达式基础与实战
    JavaScript正则表达式基础与实战
    在任何一门编程语言中,正则表达式,都是一项重要的知识,它提供了高效的字符串匹配与捕获机制,可以极大的简化程序设计。
    487次学习
  • 从零制作响应式网站—Grid布局
    从零制作响应式网站—Grid布局
    本系列教程将展示从零制作一个假想的网络科技公司官网,分为导航,轮播,关于我们,成功案例,服务流程,团队介绍,数据部分,公司动态,底部信息等内容区块。网站整体采用CSSGrid布局,支持响应式,有流畅过渡和展现动画。
    485次学习
查看更多
AI推荐
  • PubMedQA数据集详解:生物医学问答基准、功能与应用指南
    PubMedQA
    深入了解PubMedQA生物医学问答数据集,涵盖其核心功能、使用方法及在临床决策、药物研发等场景的应用,助力提升NLP模型性能。
    1116次使用
  • H2O EvalGPT:开源LLM大模型评估与排行榜工具
    H2O EvalGPT
    H2O EvalGPT是H2O.ai推出的开源LLM评估平台,提供详细的大模型性能排行榜、行业特定基准测试及A/B测试功能,助您快速选择最适合项目的高性能大语言模型。
    1104次使用
  • LMArena是什么?伯克利AI模型评估平台使用指南与功能解析
    LMArena
    LMArena是加州大学伯克利分校推出的AI模型匿名评测平台。通过盲测投票机制,用户可对比不同大模型回答并生成实时排行榜,助力开发者优化模型及用户选择最佳AI工具。
    1277次使用
  • 斯坦福HELM:大语言模型Holistic Evaluation整体评估框架详解
    HELM
    深入了解斯坦福推出的HELM(Holistic Evaluation of Language Models)大模型评测体系。本文解析其核心功能、安装配置步骤及应用场景,涵盖准确性、公平性、鲁棒性等多维度指标,助力开发者全面优化语言模型性能。
    1219次使用
  • MMBench详解:多模态大模型基准测试、功能特点与使用指南
    MMBench
    MMBench是由上海人工智能实验室等机构联合推出的多模态基准测试平台,提供细粒度能力评估、大规模数据集及VLMEvalKit工具。本文详细介绍其核心功能、安装使用方法及应用场景,助力开发者全面评估多模态模型性能。
    1066次使用