llama.cpp llama-gguf-hashGGUF 张量级哈希生成与清单校验工具完整指南【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp本文围绕 llama.cpp 中的llama-gguf-hash命令行工具展开它跳过 GGUF 文件的元数据KV store直接对张量 payload 逐层计算哈希从而在文件级哈希已经失效的场景下定位具体哪一层张量发生了变化。读完本文你将掌握该工具的完整命令行参数、manifest哈希清单的生成与校验流程、不同哈希算法xxh64 / sha1 / sha256 / UUIDv5的适用场景并能结合源码理解其读取 GGUF、逐张量流式哈希与清单比对的全部实现细节。为什么文件级哈希不够用大多数 POSIX 系统自带sha256sum这类哈希校验程序但它们校验的是整个文件的字节流。对于 GGUF 模型文件来说这并非理想的校验粒度GGUF 文件由KV store元数据 张量数据两部分组成即使元数据内容被更新例如补充了推理参数描述、chat template 等只要张量数据没有变化模型的实际推理行为就是一致的反之如果某个张量被篡改或损坏文件级哈希只能告诉你文件变了却无法定位是哪一层张量出了问题。llama-gguf-hash正是为解决这个问题而设计的它对 GGUF 张量 payload 做**逐张量层per tensor layer哈希同时提供一个整模型张量entire tensor model**哈希。其设计意图是先检查整模型级别的哈希如果发现不一致再用逐张量层的哈希进一步缩小范围定位到具体的故障张量层。该工具面向三类使用者各自解决的问题不同角色场景对应机制维护者Maintainers开发与自动化测试中检测张量不一致xxh64速度快 逐张量层哈希便于缩小故障范围sha1更慢但通用性更好模型创建者Model Creators基于模型张量内容生成一致的可复现 IDUUIDv5适合作为数据库主键。llama.cpp 的 UUIDv5 命名空间为ef001206-dadc-5f6d-a15f-3359e577d4e5由 URLen.wikipedia.org/wiki/Llama.cpp的 UUIDv5 URL 命名空间推导而来模型使用者Model Users即使元数据被更新也能确认张量层完整性sha256文档认为其截至 2024 年仍被视为非常安全命令行参数一览工具的用法格式为llama-gguf-hash [options] GGUF_IN。完整参数如下与 README 及源码中hash_print_usage()的实现一致参数说明-h,--help显示帮助信息并退出--xxh64使用 xxh6464 位 xxHash哈希默认模式--sha1使用 SHA-1 哈希--sha256使用 SHA-256 哈希--all同时使用以上全部哈希类型sha256 sha1 xxh64--no-layer排除逐张量层哈希只输出整模型哈希--uuid基于张量内容生成 UUIDv5 ID-c,--check manifest对照一个 manifest 文件进行校验从源码结构看参数解析函数 hash_params_parse_ex() 还接受下划线形式的参数如--no_layer会被自动替换为--no-layer未知参数会抛出异常并打印用法后以失败退出。需要注意一处文档与实现的不一致README 的 Design Note 一节提到默认使用 xxhash 的 xxh32 模式但同一文档的参数列表以及源码 main() 中明确的行为是当未指定任何哈希开关时默认启用xxh64选择 64 位 xxHash 的理由是截至 2024 年大多数计算机为 64 位计算 64 位哈希的亲和性更好。实际运行行为以源码为准即默认 xxh64。编译与运行示例按照 README 给出的编译流程先配置 CMake 工程再单独构建llama-gguf-hash目标cmake -B build -DCMAKE_BUILD_TYPEDebug -DLLAMA_FATAL_WARNINGSON make -C build clean make -C build llama-gguf-hash VERBOSE1 ./build/bin/llama-gguf-hash test.gguf ./build/bin/llama-gguf-hash --xxh64 test.gguf ./build/bin/llama-gguf-hash --sha1 test.gguf ./build/bin/llama-gguf-hash --uuid test.gguf ./build/bin/llama-gguf-hash --sha256 test.gguf从构建配置看该目标在 examples/gguf-hash/CMakeLists.txt 中定义链接了三个库vendor::hash哈希算法静态库、ggmlGGUF 文件读取与张量访问以及线程库编译标准为 C17。Manifest多类型哈希清单的生成生成 manifest 的典型命令如下--all会同时输出 sha256、sha1、xxh64 三种哈希逐张量层与整模型各一份UUID 属于 ID 而非哈希不包含在内./llama-gguf-hash --all test.gguf test.gguf.manifest生成的 manifest 每行一条记录格式为hash_type hash tensor_name。其中逐张量层的条目使用文件名:张量名的命名形式示例中为test.gguf:tensor_0整模型条目的名称则是文件本身。README 中给出的完整示例如下xxh64 f66e9cd66a4396a0 test.gguf:tensor_0 sha1 59f79ecefd8125a996fdf419239051a7e99e5f20 test.gguf:tensor_0 sha256 c0510d38fa060c46265e0160a85c7243096b01dd31c2f355bdbb5516b20de1bd test.gguf:tensor_0 xxh64 7d3a1f9ac04d0537 test.gguf:tensor_1 sha1 4765f592eacf096df4628ba59476af94d767080a test.gguf:tensor_1 sha256 8514cbcc73692a2c56bd7a33a022edd5ff819614bd23b19915d7224387f397a7 test.gguf:tensor_1 xxh64 a0af5d700049693b test.gguf:tensor_2 sha1 25cbfbad4513cc348e2c95ebdee69d6ff2fd8753 test.gguf:tensor_2 sha256 947e6b36e20f2cc95e1d2ce1c1669d813d574657ac6b5ac5196158d454d35180 test.gguf:tensor_2 xxh64 e83fddf559d7b6a6 test.gguf:tensor_3 sha1 a9cba73e2d90f2ee3dae2548caa42bef3fe6a96c test.gguf:tensor_3 sha256 423b044e016d8ac73c39f23f60bf01bedef5ecb03c0230accd824c91fe86f1a1 test.gguf:tensor_3 xxh64 1257733306b7992d test.gguf:tensor_4 sha1 d7bc61db93bb685ce9d598da89717c66729b7543 test.gguf:tensor_4 sha256 79737cb3912d4201384cf7f16a1a37ff7823f23ea796cb205b6ca361ab9e3ebf test.gguf:tensor_4 xxh64 d238d16ba4711e58 test.gguf:tensor_5 sha1 0706566c198fe1072f37e0a5135b4b5f23654c52 test.gguf:tensor_5 sha256 60949be8298eced0ecdde64487643d018407bd261691e061d9e9c3dbc9fd358b test.gguf:tensor_5 xxh64 3fbc3b65ab8c7f39 test.gguf:tensor_6 sha1 73922a0727226a409049f6fc3172a52219ca6f00 test.gguf:tensor_6 sha256 574f4c46ff384a3b9a225eb955d2a871847a2e8b3fa59387a8252832e92ef7b0 test.gguf:tensor_6 xxh64 c22021c29854f093 test.gguf:tensor_7 sha1 efc39cece6a951188fc41e354c73bbfe6813d447 test.gguf:tensor_7 sha256 4c0410cd3c500f078ae5b21e8dc9eb79e29112713b2ab58a882f82a3868d4d75 test.gguf:tensor_7 xxh64 936df61f5d64261f test.gguf:tensor_8 sha1 c2490296d789a4f34398a337fed8377d943d9f06 test.gguf:tensor_8 sha256 c4401313feeba0261275c3b25bd2d8fe40ce04e0f440c2980ed0e9674c30ff01 test.gguf:tensor_8 xxh64 93fd20c64421c081 test.gguf:tensor_9 sha1 7047ce1e78437a6884337a3751c7ee0421918a65 test.gguf:tensor_9 sha256 23d57cf0d7a6e90b0b3616b41300e0cd354781e812add854a5f95aa55f2bc514 test.gguf:tensor_9 xxh64 5a54d3aad816f302 test.gguf sha1 d15be52c4ff213e823cb6dd13af7ee2f978e7042 test.gguf sha256 7dd641b32f59b60dbd4b5420c4b0f6321ccf48f58f6ae201a3dbc4a58a27c6e4 test.gguf从实现上看manifest 的每一行会被解析为三个字段哈希类型、哈希值、张量名例如xxh64 f66e9cd66a4396a0 test.gguf:tensor_0见 gguf-hash.cpp 中的注释这也保证了 manifest 可以直接用diff、grep等文本工具处理。对照 Manifest 校验三种典型用法1. 自动选择最强哈希默认行为提供 manifest 后如果用户没有显式指定哈希类型工具会自动选择安全强度最高的哈希进行校验优先级 sha256 sha1 xxh64 uuid见 main() 中的自动选择逻辑$ ./llama-gguf-hash --check test.gguf.manifest test.gguf manifest test.gguf.manifest sha256 sha1 xxh64 sha256 c0510d38fa060c46265e0160a85c7243096b01dd31c2f355bdbb5516b20de1bd test.gguf:tensor_0 - Ok sha256 8514cbcc73692a2c56bd7a33a022edd5ff819614bd23b19915d7224387f397a7 test.gguf:tensor_1 - Ok sha256 947e6b36e20f2cc95e1d2ce1c1669d813d574657ac6b5ac5196158d454d35180 test.gguf:tensor_2 - Ok sha256 423b044e016d8ac73c39f23f60bf01bedef5ecb03c0230accd824c91fe86f1a1 test.gguf:tensor_3 - Ok sha256 79737cb3912d4201384cf7f16a1a37ff7823f23ea796cb205b6ca361ab9e3ebf test.gguf:tensor_4 - Ok sha256 60949be8298eced0ecdde64487643d018407bd261691e061d9e9c3dbc9fd358b test.gguf:tensor_5 - Ok sha256 574f4c46ff384a3b9a225eb955d2a871847a2e8b3fa59387a8252832e92ef7b0 test.gguf:tensor_6 - Ok sha256 4c0410cd3c500f078ae5b21e8dc9eb79e29112713b2ab58a882f82a3868d4d75 test.gguf:tensor_7 - Ok sha256 c4401313feeba0261275c3b25bd2d8fe40ce04e0f440c2980ed0e9674c30ff01 test.gguf:tensor_8 - Ok sha256 23d57cf0d7a6e90b0b3616b41300e0cd354781e812add854a5f95aa55f2bc514 test.gguf:tensor_9 - Ok sha256 7dd641b32f59b60dbd4b5420c4b0f6321ccf48f58f6ae201a3dbc4a58a27c6e4 test.gguf - Ok Verification results for test.gguf.manifest - Success输出中每行末尾会标注比对结果Ok/Mismatch/Not Found最后一行汇总验证结论。2. 显式指定更快的哈希xxh64当只需要快速一致性检查例如 CI 中反复运行时可显式指定--xxh64$ ./llama-gguf-hash --check test.gguf.manifest --xxh64 test.gguf manifest test.gguf.manifest sha256 sha1 xxh64 xxh64 f66e9cd66a4396a0 test.gguf:tensor_0 - Ok xxh64 7d3a1f9ac04d0537 test.gguf:tensor_1 - Ok xxh64 a0af5d700049693b test.gguf:tensor_2 - Ok xxh64 e83fddf559d7b6a6 test.gguf:tensor_3 - Ok xxh64 1257733306b7992d test.gguf:tensor_4 - Ok xxh64 d238d16ba4711e58 test.gguf:tensor_5 - Ok xxh64 3fbc3b65ab8c7f39 test.gguf:tensor_6 - Ok xxh64 c22021c29854f093 test.gguf:tensor_7 - Ok xxh64 936df61f5d64261f test.gguf:tensor_8 - Ok xxh64 93fd20c64421c081 test.gguf:tensor_9 - Ok xxh64 5a54d3aad816f302 test.gguf - Ok Verification results for test.gguf.manifest - Success3. 校验全部哈希类型如果希望 manifest 中所有类型的哈希全部参与比对使用--all$ ./llama-gguf-hash --check test.gguf.manifest --all test.gguf manifest test.gguf.manifest sha256 sha1 xxh64 xxh64 f66e9cd66a4396a0 test.gguf:tensor_0 - Ok sha1 59f79ecefd8125a996fdf419239051a7e99e5f20 test.gguf:tensor_0 - Ok sha256 c0510d38fa060c46265e0160a85c7243096b01dd31c2f355bdbb5516b20de1bd test.gguf:tensor_0 - Ok xxh64 7d3a1f9ac04d0537 test.gguf:tensor_1 - Ok sha1 4765f592eacf096df4628ba59476af94d767080a test.gguf:tensor_1 - Ok sha256 8514cbcc73692a2c56bd7a33a022edd5ff819614bd23b19915d7224387f397a7 test.gguf:tensor_1 - Ok xxh64 a0af5d700049693b test.gguf:tensor_2 - Ok sha1 25cbfbad4513cc348e2c95ebdee69d6ff2fd8753 test.gguf:tensor_2 - Ok sha256 947e6b36e20f2cc95e1d2ce1c1669d813d574657ac6b5ac5196158d454d35180 test.gguf:tensor_2 - Ok xxh64 e83fddf559d7b6a6 test.gguf:tensor_3 - Ok sha1 a9cba73e2d90f2ee3dae2548caa42bef3fe6a96c test.gguf:tensor_3 - Ok sha256 423b044e016d8ac73c39f23f60bf01bedef5ecb03c0230accd824c91fe86f1a1 test.gguf:tensor_3 - Ok xxh64 1257733306b7992d test.gguf:tensor_4 - Ok sha1 d7bc61db93bb685ce9d598da89717c66729b7543 test.gguf:tensor_4 - Ok sha256 79737cb3912d4201384cf7f16a1a37ff7823f23ea796cb205b6ca361ab9e3ebf test.gguf:tensor_4 - Ok xxh64 d238d16ba4711e58 test.gguf:tensor_5 - Ok sha1 0706566c198fe1072f37e0a5135b4b5f23654c52 test.gguf:tensor_5 - Ok sha256 60949be8298eced0ecdde64487643d018407bd261691e061d9e9c3dbc9fd358b test.gguf:tensor_5 - Ok xxh64 3fbc3b65ab8c7f39 test.gguf:tensor_6 - Ok sha1 73922a0727226a409049f6fc3172a52219ca6f00 test.gguf:tensor_6 - Ok sha256 574f4c46ff384a3b9a225eb955d2a871847a2e8b3fa59387a8252832e92ef7b0 test.gguf:tensor_6 - Ok xxh64 c22021c29854f093 test.gguf:tensor_7 - Ok sha1 efc39cece6a951188fc41e354c73bbfe6813d447 test.gguf:tensor_7 - Ok sha256 4c0410cd3c500f078ae5b21e8dc9eb79e29112713b2ab58a882f82a3868d4d75 test.gguf:tensor_7 - Ok xxh64 936df61f5d64261f test.gguf:tensor_8 - Ok sha1 c2490296d789a4f34398a337fed8377d943d9f06 test.gguf:tensor_8 - Ok sha256 c4401313feeba0261275c3b25bd2d8fe40ce04e0f440c2980ed0e9674c30ff01 test.gguf:tensor_8 - Ok xxh64 93fd20c64421c081 test.gguf:tensor_9 - Ok sha1 7047ce1e78437a6884337a3751c7ee0421918a65 test.gguf:tensor_9 - Ok sha256 23d57cf0d7a6e90b0b3616b41300e0cd354781e812add854a5f95aa55f2bc514 test.gguf:tensor_9 - Ok xxh64 5a54d3aad816f302 test.gguf - Ok sha1 d15be52c4ff213e823cb6dd13af7ee2f978e7042 test.gguf - Ok sha256 7dd641b32f59b60dbd4b5420c4b0f6321ccf48f58f6ae201a3dbc4a58a27c6e4 test.gguf - Ok Verification results for test.gguf.manifest - Success退出码语义校验模式下的进程退出码定义了清晰的失败类别hash_exit_code_t便于在 CI 脚本中做分支判断退出码常量含义0HASH_EXIT_SUCCESS所有哈希生成或验证通过1HASH_EXIT_FAILURE通用失败校验过程中出现不一致2HASH_EXIT_MISMATCH验证时哈希不匹配3HASH_EXIT_MANIFEST_MISSING_ENTRYmanifest 中找不到对应的模型/张量条目可能读错了 manifest4HASH_EXIT_MANIFEST_UNKNOWN_HASHmanifest 存在但不包含任何已知的哈希格式5HASH_EXIT_MANIFEST_FILE_ERRORmanifest 文件缺失或无法打开值得注意的一个容错设计见 校验结果判定逻辑如果 manifest 中缺少整模型条目工具不会直接判失败而是退回去检查逐张量层条目——只要所有张量层条目都在且通过校验仍返回成功只有在张量层也缺失时才报MANIFEST_MISSING_ENTRY。这使得同一 manifest 在只有逐层哈希或整模型哈希缺失的场景下依然可用。哈希算法与 UUIDv5 的实现细节三类哈希 UUID 的分工工具内置四种输出xxh64非加密哈希速度最快面向维护者在自动化测试中做快速一致性检测sha1较慢但更广泛支持是通用兼容的兜底选择sha256安全性最强面向终端用户做张量完整性确认UUIDv5不是哈希而是确定性 ID——基于固定命名空间对张量内容做 SHA-1再按 RFC 规定的位规则改写版本/变体位。适合作为数据库主键只要张量内容相同生成的 UUID 就相同因此可以为模型注册系统提供可复现的模型标识。UUIDv5 的生成实现在 generate_uuidv5()先取 SHA-1 摘要的前 16 字节然后将第 7 字节高 4 位写入版本5uuid[6] ~(0xF 4); uuid[6] | (5 4);第 9 字节写入变体位0b10uuid[8] ~(0xc 4); uuid[8] | (0x8 4);代码注释指明参照 RFC 9562 第 5.5 节。命名空间常量定义在 gguf-hash.cpp 头部// uuid.uuid5(uuid.NAMESPACE_URL, en.wikipedia.org/wiki/Llama.cpp) #define UUID_NAMESPACE_LLAMA_CPP ef001206-dadc-5f6d-a15f-3359e577d4e5即等价于 Python 中uuid.uuid5(uuid.NAMESPACE_URL, en.wikipedia.org/wiki/Llama.cpp)的结果。哈希计算主流程核心函数gguf_hash()的实现流程gguf-hash.cpp用 GGUF C API 打开文件gguf_init_from_file()加载元数据ggml_get_tensor(ctx_data, name)取得每个张量的原始数据指针cur-data与字节数ggml_nbytes(cur)按gguf_get_n_tensors()遍历全部张量对每个张量的 payload 字节计算逐层哈希XXH64()/SHA1()/sha256_hash()同时把该张量字节喂入各自的整模型流式上下文XXH64_update()/SHA1Update()/sha256_update()遍历结束后输出各算法的整模型终值XXH64_digest()/SHA1Final()/sha256_final()。从源码结构看整模型哈希是按 GGUF 中张量顺序将所有张量 payload 串联后计算的并不包含文件头与 KV store 字节——这正呼应了文档的设计目标元数据变化不会改变整模型哈希张量变化则一定被捕获。依赖的哈希库及其管理方式README 末尾说明这三个微型的 C 哈希库最初是通过 clibs C 包管理器引入的xxHashCyan4973、sha1clibs、sha256.cjb55。在当前仓库中这些依赖已被**vendored内嵌**到 vendor/hash/ 目录包含xxhash/、sha1/、sha256/三个子目录及sha256的依赖头文件rotate-bits/。vendor/hash/CMakeLists.txt 将三者连同封装文件hash.cpp编译为静态库并导出vendor::hash别名供本工具链接。同步这些依赖的机制在 scripts/sync_vendor.py 中脚本把每个上游仓库固定到具体 commit例如XXHASH_COMMIT 9f465f1e...注释说明原因是这些仓库没有 release tag只能 pin commit并在下载后打上本地补丁xxhash修复旧版 Windows SDK 缺少stdalign.h时的 C11 检测问题sha1上游导出了裸的SHA1符号会与 boringssl 发生链接冲突因此脚本把sha1.c/sha1.h包进namespace vendor_hash并以 C 方式编译这与 gguf-hash.cpp 中的注释 sha1 is compiled as C and lives in a namespace, see scripts/sync_vendor.py 以及using namespace vendor_hash;相呼应sha256将uint32_t W[16]初始化为 {0}以消除 maybe-uninitialized 警告。与 Python 版 gguf_hash.py 的关系仓库中另有一个 Python 实现的哈希脚本 gguf-py/gguf/scripts/gguf_hash.py它输出 sha1 / sha256 / uuid 三类结果同样使用ef001206-dadc-5f6d-a15f-3359e577d4e5这个 UUIDv5 命名空间因此两侧生成的模型级 UUID 语义一致。两者差异可以概括为Python 版额外提供了权重进度条并且会跳过.attention.masked_bias、.attention.bias、.rotary_emb.inv_freq这类不需要校验的张量而 C 版llama-gguf-hash对gguf_get_n_tensors()返回的全部张量逐一体积参与哈希并且多了 xxh64 快速通道与 manifest 校验--check能力。日常在 C/C 工具链和 CI 中做完整性校验时优先使用编译出的llama-gguf-hash二进制。典型工作流小结结合前文的参数与命令一个完整的开发期快速检测 发布期强校验工作流是开发/CI 快速检测维护者视角./llama-gguf-hash --xxh64 my-model.gguf与基线逐层哈希对比若整模型哈希变化再看逐层输出定位到具体张量生成权威 manifest模型创建者视角./llama-gguf-hash --all my-model.gguf my-model.gguf.manifest同时用./llama-gguf-hash --uuid my-model.gguf生成可复现的模型 UUID 作为数据库键发布后完整性验证用户视角./llama-gguf-hash --check my-model.gguf.manifest my-model.gguf默认走 sha256 强校验退出码非 0 即表示张量层存在不一致且输出中可以直接看到是哪个my-model.gguf:tensor_N不匹配。这套整模型哈希粗筛 逐张量哈希细查 多算法分档的组合正是llama-gguf-hash相对sha256sum等文件级工具的核心价值让 GGUF 模型的完整性校验精确到张量层并且对元数据的合法更新保持免疫。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
llama.cpp llama-gguf-hash：GGUF 张量级哈希生成与清单校验工具完整指南
llama.cpp llama-gguf-hashGGUF 张量级哈希生成与清单校验工具完整指南【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp本文围绕 llama.cpp 中的llama-gguf-hash命令行工具展开它跳过 GGUF 文件的元数据KV store直接对张量 payload 逐层计算哈希从而在文件级哈希已经失效的场景下定位具体哪一层张量发生了变化。读完本文你将掌握该工具的完整命令行参数、manifest哈希清单的生成与校验流程、不同哈希算法xxh64 / sha1 / sha256 / UUIDv5的适用场景并能结合源码理解其读取 GGUF、逐张量流式哈希与清单比对的全部实现细节。为什么文件级哈希不够用大多数 POSIX 系统自带sha256sum这类哈希校验程序但它们校验的是整个文件的字节流。对于 GGUF 模型文件来说这并非理想的校验粒度GGUF 文件由KV store元数据 张量数据两部分组成即使元数据内容被更新例如补充了推理参数描述、chat template 等只要张量数据没有变化模型的实际推理行为就是一致的反之如果某个张量被篡改或损坏文件级哈希只能告诉你文件变了却无法定位是哪一层张量出了问题。llama-gguf-hash正是为解决这个问题而设计的它对 GGUF 张量 payload 做**逐张量层per tensor layer哈希同时提供一个整模型张量entire tensor model**哈希。其设计意图是先检查整模型级别的哈希如果发现不一致再用逐张量层的哈希进一步缩小范围定位到具体的故障张量层。该工具面向三类使用者各自解决的问题不同角色场景对应机制维护者Maintainers开发与自动化测试中检测张量不一致xxh64速度快 逐张量层哈希便于缩小故障范围sha1更慢但通用性更好模型创建者Model Creators基于模型张量内容生成一致的可复现 IDUUIDv5适合作为数据库主键。llama.cpp 的 UUIDv5 命名空间为ef001206-dadc-5f6d-a15f-3359e577d4e5由 URLen.wikipedia.org/wiki/Llama.cpp的 UUIDv5 URL 命名空间推导而来模型使用者Model Users即使元数据被更新也能确认张量层完整性sha256文档认为其截至 2024 年仍被视为非常安全命令行参数一览工具的用法格式为llama-gguf-hash [options] GGUF_IN。完整参数如下与 README 及源码中hash_print_usage()的实现一致参数说明-h,--help显示帮助信息并退出--xxh64使用 xxh6464 位 xxHash哈希默认模式--sha1使用 SHA-1 哈希--sha256使用 SHA-256 哈希--all同时使用以上全部哈希类型sha256 sha1 xxh64--no-layer排除逐张量层哈希只输出整模型哈希--uuid基于张量内容生成 UUIDv5 ID-c,--check manifest对照一个 manifest 文件进行校验从源码结构看参数解析函数 hash_params_parse_ex() 还接受下划线形式的参数如--no_layer会被自动替换为--no-layer未知参数会抛出异常并打印用法后以失败退出。需要注意一处文档与实现的不一致README 的 Design Note 一节提到默认使用 xxhash 的 xxh32 模式但同一文档的参数列表以及源码 main() 中明确的行为是当未指定任何哈希开关时默认启用xxh64选择 64 位 xxHash 的理由是截至 2024 年大多数计算机为 64 位计算 64 位哈希的亲和性更好。实际运行行为以源码为准即默认 xxh64。编译与运行示例按照 README 给出的编译流程先配置 CMake 工程再单独构建llama-gguf-hash目标cmake -B build -DCMAKE_BUILD_TYPEDebug -DLLAMA_FATAL_WARNINGSON make -C build clean make -C build llama-gguf-hash VERBOSE1 ./build/bin/llama-gguf-hash test.gguf ./build/bin/llama-gguf-hash --xxh64 test.gguf ./build/bin/llama-gguf-hash --sha1 test.gguf ./build/bin/llama-gguf-hash --uuid test.gguf ./build/bin/llama-gguf-hash --sha256 test.gguf从构建配置看该目标在 examples/gguf-hash/CMakeLists.txt 中定义链接了三个库vendor::hash哈希算法静态库、ggmlGGUF 文件读取与张量访问以及线程库编译标准为 C17。Manifest多类型哈希清单的生成生成 manifest 的典型命令如下--all会同时输出 sha256、sha1、xxh64 三种哈希逐张量层与整模型各一份UUID 属于 ID 而非哈希不包含在内./llama-gguf-hash --all test.gguf test.gguf.manifest生成的 manifest 每行一条记录格式为hash_type hash tensor_name。其中逐张量层的条目使用文件名:张量名的命名形式示例中为test.gguf:tensor_0整模型条目的名称则是文件本身。README 中给出的完整示例如下xxh64 f66e9cd66a4396a0 test.gguf:tensor_0 sha1 59f79ecefd8125a996fdf419239051a7e99e5f20 test.gguf:tensor_0 sha256 c0510d38fa060c46265e0160a85c7243096b01dd31c2f355bdbb5516b20de1bd test.gguf:tensor_0 xxh64 7d3a1f9ac04d0537 test.gguf:tensor_1 sha1 4765f592eacf096df4628ba59476af94d767080a test.gguf:tensor_1 sha256 8514cbcc73692a2c56bd7a33a022edd5ff819614bd23b19915d7224387f397a7 test.gguf:tensor_1 xxh64 a0af5d700049693b test.gguf:tensor_2 sha1 25cbfbad4513cc348e2c95ebdee69d6ff2fd8753 test.gguf:tensor_2 sha256 947e6b36e20f2cc95e1d2ce1c1669d813d574657ac6b5ac5196158d454d35180 test.gguf:tensor_2 xxh64 e83fddf559d7b6a6 test.gguf:tensor_3 sha1 a9cba73e2d90f2ee3dae2548caa42bef3fe6a96c test.gguf:tensor_3 sha256 423b044e016d8ac73c39f23f60bf01bedef5ecb03c0230accd824c91fe86f1a1 test.gguf:tensor_3 xxh64 1257733306b7992d test.gguf:tensor_4 sha1 d7bc61db93bb685ce9d598da89717c66729b7543 test.gguf:tensor_4 sha256 79737cb3912d4201384cf7f16a1a37ff7823f23ea796cb205b6ca361ab9e3ebf test.gguf:tensor_4 xxh64 d238d16ba4711e58 test.gguf:tensor_5 sha1 0706566c198fe1072f37e0a5135b4b5f23654c52 test.gguf:tensor_5 sha256 60949be8298eced0ecdde64487643d018407bd261691e061d9e9c3dbc9fd358b test.gguf:tensor_5 xxh64 3fbc3b65ab8c7f39 test.gguf:tensor_6 sha1 73922a0727226a409049f6fc3172a52219ca6f00 test.gguf:tensor_6 sha256 574f4c46ff384a3b9a225eb955d2a871847a2e8b3fa59387a8252832e92ef7b0 test.gguf:tensor_6 xxh64 c22021c29854f093 test.gguf:tensor_7 sha1 efc39cece6a951188fc41e354c73bbfe6813d447 test.gguf:tensor_7 sha256 4c0410cd3c500f078ae5b21e8dc9eb79e29112713b2ab58a882f82a3868d4d75 test.gguf:tensor_7 xxh64 936df61f5d64261f test.gguf:tensor_8 sha1 c2490296d789a4f34398a337fed8377d943d9f06 test.gguf:tensor_8 sha256 c4401313feeba0261275c3b25bd2d8fe40ce04e0f440c2980ed0e9674c30ff01 test.gguf:tensor_8 xxh64 93fd20c64421c081 test.gguf:tensor_9 sha1 7047ce1e78437a6884337a3751c7ee0421918a65 test.gguf:tensor_9 sha256 23d57cf0d7a6e90b0b3616b41300e0cd354781e812add854a5f95aa55f2bc514 test.gguf:tensor_9 xxh64 5a54d3aad816f302 test.gguf sha1 d15be52c4ff213e823cb6dd13af7ee2f978e7042 test.gguf sha256 7dd641b32f59b60dbd4b5420c4b0f6321ccf48f58f6ae201a3dbc4a58a27c6e4 test.gguf从实现上看manifest 的每一行会被解析为三个字段哈希类型、哈希值、张量名例如xxh64 f66e9cd66a4396a0 test.gguf:tensor_0见 gguf-hash.cpp 中的注释这也保证了 manifest 可以直接用diff、grep等文本工具处理。对照 Manifest 校验三种典型用法1. 自动选择最强哈希默认行为提供 manifest 后如果用户没有显式指定哈希类型工具会自动选择安全强度最高的哈希进行校验优先级 sha256 sha1 xxh64 uuid见 main() 中的自动选择逻辑$ ./llama-gguf-hash --check test.gguf.manifest test.gguf manifest test.gguf.manifest sha256 sha1 xxh64 sha256 c0510d38fa060c46265e0160a85c7243096b01dd31c2f355bdbb5516b20de1bd test.gguf:tensor_0 - Ok sha256 8514cbcc73692a2c56bd7a33a022edd5ff819614bd23b19915d7224387f397a7 test.gguf:tensor_1 - Ok sha256 947e6b36e20f2cc95e1d2ce1c1669d813d574657ac6b5ac5196158d454d35180 test.gguf:tensor_2 - Ok sha256 423b044e016d8ac73c39f23f60bf01bedef5ecb03c0230accd824c91fe86f1a1 test.gguf:tensor_3 - Ok sha256 79737cb3912d4201384cf7f16a1a37ff7823f23ea796cb205b6ca361ab9e3ebf test.gguf:tensor_4 - Ok sha256 60949be8298eced0ecdde64487643d018407bd261691e061d9e9c3dbc9fd358b test.gguf:tensor_5 - Ok sha256 574f4c46ff384a3b9a225eb955d2a871847a2e8b3fa59387a8252832e92ef7b0 test.gguf:tensor_6 - Ok sha256 4c0410cd3c500f078ae5b21e8dc9eb79e29112713b2ab58a882f82a3868d4d75 test.gguf:tensor_7 - Ok sha256 c4401313feeba0261275c3b25bd2d8fe40ce04e0f440c2980ed0e9674c30ff01 test.gguf:tensor_8 - Ok sha256 23d57cf0d7a6e90b0b3616b41300e0cd354781e812add854a5f95aa55f2bc514 test.gguf:tensor_9 - Ok sha256 7dd641b32f59b60dbd4b5420c4b0f6321ccf48f58f6ae201a3dbc4a58a27c6e4 test.gguf - Ok Verification results for test.gguf.manifest - Success输出中每行末尾会标注比对结果Ok/Mismatch/Not Found最后一行汇总验证结论。2. 显式指定更快的哈希xxh64当只需要快速一致性检查例如 CI 中反复运行时可显式指定--xxh64$ ./llama-gguf-hash --check test.gguf.manifest --xxh64 test.gguf manifest test.gguf.manifest sha256 sha1 xxh64 xxh64 f66e9cd66a4396a0 test.gguf:tensor_0 - Ok xxh64 7d3a1f9ac04d0537 test.gguf:tensor_1 - Ok xxh64 a0af5d700049693b test.gguf:tensor_2 - Ok xxh64 e83fddf559d7b6a6 test.gguf:tensor_3 - Ok xxh64 1257733306b7992d test.gguf:tensor_4 - Ok xxh64 d238d16ba4711e58 test.gguf:tensor_5 - Ok xxh64 3fbc3b65ab8c7f39 test.gguf:tensor_6 - Ok xxh64 c22021c29854f093 test.gguf:tensor_7 - Ok xxh64 936df61f5d64261f test.gguf:tensor_8 - Ok xxh64 93fd20c64421c081 test.gguf:tensor_9 - Ok xxh64 5a54d3aad816f302 test.gguf - Ok Verification results for test.gguf.manifest - Success3. 校验全部哈希类型如果希望 manifest 中所有类型的哈希全部参与比对使用--all$ ./llama-gguf-hash --check test.gguf.manifest --all test.gguf manifest test.gguf.manifest sha256 sha1 xxh64 xxh64 f66e9cd66a4396a0 test.gguf:tensor_0 - Ok sha1 59f79ecefd8125a996fdf419239051a7e99e5f20 test.gguf:tensor_0 - Ok sha256 c0510d38fa060c46265e0160a85c7243096b01dd31c2f355bdbb5516b20de1bd test.gguf:tensor_0 - Ok xxh64 7d3a1f9ac04d0537 test.gguf:tensor_1 - Ok sha1 4765f592eacf096df4628ba59476af94d767080a test.gguf:tensor_1 - Ok sha256 8514cbcc73692a2c56bd7a33a022edd5ff819614bd23b19915d7224387f397a7 test.gguf:tensor_1 - Ok xxh64 a0af5d700049693b test.gguf:tensor_2 - Ok sha1 25cbfbad4513cc348e2c95ebdee69d6ff2fd8753 test.gguf:tensor_2 - Ok sha256 947e6b36e20f2cc95e1d2ce1c1669d813d574657ac6b5ac5196158d454d35180 test.gguf:tensor_2 - Ok xxh64 e83fddf559d7b6a6 test.gguf:tensor_3 - Ok sha1 a9cba73e2d90f2ee3dae2548caa42bef3fe6a96c test.gguf:tensor_3 - Ok sha256 423b044e016d8ac73c39f23f60bf01bedef5ecb03c0230accd824c91fe86f1a1 test.gguf:tensor_3 - Ok xxh64 1257733306b7992d test.gguf:tensor_4 - Ok sha1 d7bc61db93bb685ce9d598da89717c66729b7543 test.gguf:tensor_4 - Ok sha256 79737cb3912d4201384cf7f16a1a37ff7823f23ea796cb205b6ca361ab9e3ebf test.gguf:tensor_4 - Ok xxh64 d238d16ba4711e58 test.gguf:tensor_5 - Ok sha1 0706566c198fe1072f37e0a5135b4b5f23654c52 test.gguf:tensor_5 - Ok sha256 60949be8298eced0ecdde64487643d018407bd261691e061d9e9c3dbc9fd358b test.gguf:tensor_5 - Ok xxh64 3fbc3b65ab8c7f39 test.gguf:tensor_6 - Ok sha1 73922a0727226a409049f6fc3172a52219ca6f00 test.gguf:tensor_6 - Ok sha256 574f4c46ff384a3b9a225eb955d2a871847a2e8b3fa59387a8252832e92ef7b0 test.gguf:tensor_6 - Ok xxh64 c22021c29854f093 test.gguf:tensor_7 - Ok sha1 efc39cece6a951188fc41e354c73bbfe6813d447 test.gguf:tensor_7 - Ok sha256 4c0410cd3c500f078ae5b21e8dc9eb79e29112713b2ab58a882f82a3868d4d75 test.gguf:tensor_7 - Ok xxh64 936df61f5d64261f test.gguf:tensor_8 - Ok sha1 c2490296d789a4f34398a337fed8377d943d9f06 test.gguf:tensor_8 - Ok sha256 c4401313feeba0261275c3b25bd2d8fe40ce04e0f440c2980ed0e9674c30ff01 test.gguf:tensor_8 - Ok xxh64 93fd20c64421c081 test.gguf:tensor_9 - Ok sha1 7047ce1e78437a6884337a3751c7ee0421918a65 test.gguf:tensor_9 - Ok sha256 23d57cf0d7a6e90b0b3616b41300e0cd354781e812add854a5f95aa55f2bc514 test.gguf:tensor_9 - Ok xxh64 5a54d3aad816f302 test.gguf - Ok sha1 d15be52c4ff213e823cb6dd13af7ee2f978e7042 test.gguf - Ok sha256 7dd641b32f59b60dbd4b5420c4b0f6321ccf48f58f6ae201a3dbc4a58a27c6e4 test.gguf - Ok Verification results for test.gguf.manifest - Success退出码语义校验模式下的进程退出码定义了清晰的失败类别hash_exit_code_t便于在 CI 脚本中做分支判断退出码常量含义0HASH_EXIT_SUCCESS所有哈希生成或验证通过1HASH_EXIT_FAILURE通用失败校验过程中出现不一致2HASH_EXIT_MISMATCH验证时哈希不匹配3HASH_EXIT_MANIFEST_MISSING_ENTRYmanifest 中找不到对应的模型/张量条目可能读错了 manifest4HASH_EXIT_MANIFEST_UNKNOWN_HASHmanifest 存在但不包含任何已知的哈希格式5HASH_EXIT_MANIFEST_FILE_ERRORmanifest 文件缺失或无法打开值得注意的一个容错设计见 校验结果判定逻辑如果 manifest 中缺少整模型条目工具不会直接判失败而是退回去检查逐张量层条目——只要所有张量层条目都在且通过校验仍返回成功只有在张量层也缺失时才报MANIFEST_MISSING_ENTRY。这使得同一 manifest 在只有逐层哈希或整模型哈希缺失的场景下依然可用。哈希算法与 UUIDv5 的实现细节三类哈希 UUID 的分工工具内置四种输出xxh64非加密哈希速度最快面向维护者在自动化测试中做快速一致性检测sha1较慢但更广泛支持是通用兼容的兜底选择sha256安全性最强面向终端用户做张量完整性确认UUIDv5不是哈希而是确定性 ID——基于固定命名空间对张量内容做 SHA-1再按 RFC 规定的位规则改写版本/变体位。适合作为数据库主键只要张量内容相同生成的 UUID 就相同因此可以为模型注册系统提供可复现的模型标识。UUIDv5 的生成实现在 generate_uuidv5()先取 SHA-1 摘要的前 16 字节然后将第 7 字节高 4 位写入版本5uuid[6] ~(0xF 4); uuid[6] | (5 4);第 9 字节写入变体位0b10uuid[8] ~(0xc 4); uuid[8] | (0x8 4);代码注释指明参照 RFC 9562 第 5.5 节。命名空间常量定义在 gguf-hash.cpp 头部// uuid.uuid5(uuid.NAMESPACE_URL, en.wikipedia.org/wiki/Llama.cpp) #define UUID_NAMESPACE_LLAMA_CPP ef001206-dadc-5f6d-a15f-3359e577d4e5即等价于 Python 中uuid.uuid5(uuid.NAMESPACE_URL, en.wikipedia.org/wiki/Llama.cpp)的结果。哈希计算主流程核心函数gguf_hash()的实现流程gguf-hash.cpp用 GGUF C API 打开文件gguf_init_from_file()加载元数据ggml_get_tensor(ctx_data, name)取得每个张量的原始数据指针cur-data与字节数ggml_nbytes(cur)按gguf_get_n_tensors()遍历全部张量对每个张量的 payload 字节计算逐层哈希XXH64()/SHA1()/sha256_hash()同时把该张量字节喂入各自的整模型流式上下文XXH64_update()/SHA1Update()/sha256_update()遍历结束后输出各算法的整模型终值XXH64_digest()/SHA1Final()/sha256_final()。从源码结构看整模型哈希是按 GGUF 中张量顺序将所有张量 payload 串联后计算的并不包含文件头与 KV store 字节——这正呼应了文档的设计目标元数据变化不会改变整模型哈希张量变化则一定被捕获。依赖的哈希库及其管理方式README 末尾说明这三个微型的 C 哈希库最初是通过 clibs C 包管理器引入的xxHashCyan4973、sha1clibs、sha256.cjb55。在当前仓库中这些依赖已被**vendored内嵌**到 vendor/hash/ 目录包含xxhash/、sha1/、sha256/三个子目录及sha256的依赖头文件rotate-bits/。vendor/hash/CMakeLists.txt 将三者连同封装文件hash.cpp编译为静态库并导出vendor::hash别名供本工具链接。同步这些依赖的机制在 scripts/sync_vendor.py 中脚本把每个上游仓库固定到具体 commit例如XXHASH_COMMIT 9f465f1e...注释说明原因是这些仓库没有 release tag只能 pin commit并在下载后打上本地补丁xxhash修复旧版 Windows SDK 缺少stdalign.h时的 C11 检测问题sha1上游导出了裸的SHA1符号会与 boringssl 发生链接冲突因此脚本把sha1.c/sha1.h包进namespace vendor_hash并以 C 方式编译这与 gguf-hash.cpp 中的注释 sha1 is compiled as C and lives in a namespace, see scripts/sync_vendor.py 以及using namespace vendor_hash;相呼应sha256将uint32_t W[16]初始化为 {0}以消除 maybe-uninitialized 警告。与 Python 版 gguf_hash.py 的关系仓库中另有一个 Python 实现的哈希脚本 gguf-py/gguf/scripts/gguf_hash.py它输出 sha1 / sha256 / uuid 三类结果同样使用ef001206-dadc-5f6d-a15f-3359e577d4e5这个 UUIDv5 命名空间因此两侧生成的模型级 UUID 语义一致。两者差异可以概括为Python 版额外提供了权重进度条并且会跳过.attention.masked_bias、.attention.bias、.rotary_emb.inv_freq这类不需要校验的张量而 C 版llama-gguf-hash对gguf_get_n_tensors()返回的全部张量逐一体积参与哈希并且多了 xxh64 快速通道与 manifest 校验--check能力。日常在 C/C 工具链和 CI 中做完整性校验时优先使用编译出的llama-gguf-hash二进制。典型工作流小结结合前文的参数与命令一个完整的开发期快速检测 发布期强校验工作流是开发/CI 快速检测维护者视角./llama-gguf-hash --xxh64 my-model.gguf与基线逐层哈希对比若整模型哈希变化再看逐层输出定位到具体张量生成权威 manifest模型创建者视角./llama-gguf-hash --all my-model.gguf my-model.gguf.manifest同时用./llama-gguf-hash --uuid my-model.gguf生成可复现的模型 UUID 作为数据库键发布后完整性验证用户视角./llama-gguf-hash --check my-model.gguf.manifest my-model.gguf默认走 sha256 强校验退出码非 0 即表示张量层存在不一致且输出中可以直接看到是哪个my-model.gguf:tensor_N不匹配。这套整模型哈希粗筛 逐张量哈希细查 多算法分档的组合正是llama-gguf-hash相对sha256sum等文件级工具的核心价值让 GGUF 模型的完整性校验精确到张量层并且对元数据的合法更新保持免疫。【免费下载链接】llama.cppLLM inference in C/C项目地址: https://gitcode.com/GitHub_Trending/ll/llama.cpp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
 详解：关闭浏览器上下文与隔离环境的 API 及源码实现)
