Xet 协议规范
备注
本规范定义了内容寻址数据的端到端 Xet 协议：分块和哈希规则、去重策略、xorb 和 shard 对象格式、文件重建语义、身份验证，以及用于上传和下载的 CAS API。 其目标是互操作性和确定性：独立实现必须产生相同的哈希、对象和 API 行为，以便一个客户端写入的数据可以被另一个客户端以完整性和性能读取。 实现者可以创建自己的客户端、SDK 和工具，使用 Xet 协议并与 CAS 服务交互，只要它们必须遵守此处定义的要求。
构建 Xet 存储的客户端库
- 上传协议：上传流程的端到端顶层描述。
- 下载协议：下载过程的说明。
- CAS API：用于重建、全局块去重、xorb 上传和 shard 上传的 HTTP 端点，包括错误语义。
- 身份验证和授权：如何从 Hugging Face Hub 获取 Xet 令牌、令牌作用域和安全注意事项。
- 将 Hugging Face Hub 文件转换为 Xet 文件 ID：如何从 Hugging Face Hub 获取模型或数据集仓库中特定文件的 Xet 文件 ID。
Xet 整体架构
- 内容定义分块：基于 Gearhash 的 CDC，包含参数、边界规则和性能优化。
- 哈希方法：用于块、xorbs 和 term 验证条目的不同哈希函数的描述和定义。
- 文件重建：使用 xorb 哈希 + 块范围定义基于"term"的文件表示。
- Xorb 格式：解释将块分组为 xorbs、64 MiB 限制、二进制布局和压缩方案。
- Shard 格式：二进制 shard 结构（标头、文件信息、CAS 信息、页脚）、偏移量、HMAC 密钥使用和书挡。
- 去重：块级去重的说明，包括全局系统级块级去重。
参考实现
xet-core: hf-xet + git-xet
用 Rust 🦀 编写的主要参考实现位于 xet-core 仓库的多个 crate 中：
- cas_types - 用于与 CAS API 交互的通用可重用类型
- cas_client - 调用 CAS API 的客户端接口，包括下载协议的全面实现。
- mdb_shard - 用于与 shard 和 shard 二进制格式交互的库。
- deduplication - 公开用于本地和全局去重块的接口
- deduplication/src/chunking.rs - 分块算法的参考实现。
- merklehash - 导出一个广泛用于表示哈希的
MerkleHash类型。导出用于计算跟踪块、xorbs 和文件的不同哈希的函数。 - data - 公开用于上传和下载内容的接口的综合包
- hf_xet - 用于使用 Xet 协议与 Hugging Face Hub 进行上传和下载的 Python 绑定。
- git-xet - git lfs 自定义传输代理，使用 xet 协议将文件上传到 Hugging Face Hub。
huggingface.js
在 Huggingface.js 中还有第二个参考实现，可以在使用 @huggingface/hub 库下载或上传文件时使用。
- 下载使用可以在 XetBlob.ts 中找到的
XetBlob。 - 上传实现更加全面，但其根源始于 uploadShards。
- 上传过程使用从 Rust 编译到 WebAssembly 的 xet-core 构造，特别是从 hf_xet_thin_wasm crate 导出的所有函数。