汤圆工具箱

GGUF模型元数据查看器

在线解析 GGUF(llama.cpp生态模型文件格式)文件头和元数据区,展示 version、tensor_count、模型架构名称、量化版本等信息,文件仅在浏览器本地解析,不上传。

免费在线工具
Loading…

使用说明

点击虚线框选择本地 .gguf 模型文件,或直接拖拽文件到框内;也可以点击“加载示例数据”体验一个工具内合成构造的最小合法GGUF文件(不依赖真实模型文件)。

解析完成后会展示:文件头信息(文件大小、version、tensor_count 张量数量、metadata_kv_count 元数据条目数)、常见字段(自动从元数据里提取 general.architecture、general.name、general.quantization_version 等常见字符串/数值字段并高亮展示)、以及全部元数据表格(列出解析到的每一个key、值类型、值内容;ARRAY类型的字段只展示元素类型和长度摘要,不逐项展开)。

如果文件不是合法GGUF(magic number不匹配)或数据被截断,会显示明确的错误提示。为避免大文件(数十GB模型权重)撑爆内存,超过64MB的文件只读取前4MB(通常足以覆盖文件头和metadata区),不加载完整张量数据。

功能介绍

GGUF 是 llama.cpp 生态广泛使用的模型文件格式,用于存储量化后的大语言模型权重和相关元信息。文件开头是一个结构化的头部区(magic number + version + tensor_count + metadata_kv_count),紧接着是若干个 key-value 元数据对(如模型架构名称、量化版本、上下文长度等),再之后才是体积巨大的张量权重数据。

很多时候用户只想快速确认一个GGUF文件的基本信息(是哪个架构、什么量化版本、大概有多少张量),而不需要真正加载整个模型。本工具按 GGUF 官方规范(ggml-org/ggml 仓库文档)在浏览器本地按字节解析文件头和metadata区:先校验4字节magic number是否为“GGUF”,再按小端序依次读取version(uint32)、tensor_count(uint64)、metadata_kv_count(uint64),然后逐条解析metadata的key-value对,支持全部13种官方定义的value_type(UINT8/INT8/UINT16/INT16/UINT32/INT32/FLOAT32/BOOL/STRING/ARRAY/UINT64/INT64/FLOAT64),ARRAY类型会正确跳过其全部字节但只展示摘要,避免超大数组撑爆页面渲染。

本工具不解析文件后续的tensor info区和实际权重数据,只读取头部和元数据,所以处理超大模型文件也很快;所有解析都在浏览器本地用 FileReader + DataView 完成,文件内容不会上传到任何服务器。

使用场景

下载模型前快速确认文件基本信息
从网上下载到一个.gguf模型文件后,先用本工具查看其架构、量化版本、张量数量等信息,确认是否是自己需要的模型,无需先加载进推理框架。
排查模型加载失败问题
当 llama.cpp 或其他推理框架加载某个GGUF文件报错时,先用本工具确认文件本身的magic number和头部结构是否合法,排除文件损坏或格式不对的可能性。
对比不同量化版本模型的元数据差异
对同一个模型的不同量化版本(如Q4_K_M、Q8_0等)文件分别查看元数据,对比general.quantization_version等字段的差异。
学习GGUF文件格式结构
通过“加载示例数据”生成的最小合法GGUF文件,直观看到文件头字段和metadata key-value对是如何组织的,帮助理解GGUF格式规范。

常见问题

上传的模型文件会被发送到服务器吗?
不会。文件通过浏览器原生的 FileReader API 读取到本地内存中解析,全部解析逻辑运行在你的浏览器里,文件内容不会上传、也不会发送到任何网络地址。
为什么大文件只读取前4MB,会不会漏掉信息?
GGUF文件的头部和metadata区通常位于文件最前部,只有几KB到几MB,后面绝大部分体积是张量权重数据(可能有几十GB)。本工具只需要解析头部和metadata区就能展示你需要的信息,因此对超过64MB的文件只读取前4MB以避免大文件占用过多浏览器内存,这个范围通常足以覆盖完整的metadata区;如果metadata区异常庞大导致被截断,工具会明确提示“数据不完整”而不是显示错误结果。
上传的文件不是GGUF格式会怎样?
工具会先校验文件开头4个字节是否是GGUF格式规定的magic number(对应ASCII"GGUF"),不匹配时会直接返回明确的错误提示“不是合法的GGUF文件”,不会尝试强行解析或展示乱码数据。
ARRAY类型的元数据字段为什么不展示具体内容?
GGUF里的ARRAY类型字段(比如某些模型会用数组存储分词器词表等)可能包含成千上万个元素,直接全部渲染到页面会导致卡顿。本工具会正确解析并跳过ARRAY字段的全部字节(保证后续字段能继续正常解析),但只展示这个数组的元素类型和长度摘要,不逐项展开渲染。