Xet Server Vibe 项目

2. Xet Server（Xet Server）

项目简介

Xet Server 是一个用 Go 语言从零实现的、与 Hugging Face 真实 Xet 存储协议线兼容的服务端。Xet 是 Hugging Face Hub 用来替代 Git LFS 的新一代内容寻址分块存储层，依靠内容定义分块与优先去重，把大模型文件切成可复用的块再组合存储。这个项目不满足于做一个「差不多的演示」：它照着真实协议逐字节复刻了 xorb 与 shard 二进制格式、BLAKE3 键控 Merkle 哈希、LZ4 解码与 ByteGrouping4 编解码，最终让官方 hf 命令行（huggingface_hub 加 hf_xet）可以直接对着它上传下载，字节级往返一致。项目采用 MIT 协议，2026 年 9 月 11 日创建，至今仍在高频提交。

核心功能

1. 线兼容 CAS HTTP API：提供 xorb 上传与拉取、shard 上传、带 Range 分页的文件重建，接口形状对齐 xet-core 自己的 openapi 定义。
2. Hub API 垫片：实现仓库创建、预上传、读写令牌签发、提交、解析与 HEAD 等接口，让真实 hf upload 与 hf download 命令行直接可用，并支持每个仓库独立的分支与版本。
3. 缓存拉取代理 xet-proxyd：作为 huggingface.co 前置的拉取透传代理，一旦某个仓库或文件被成功代理过一次，即使官方站点不可达仍可下载；其缓存目录还可以直接交给普通 xetd 当作永久离线副本。
4. 从零实现的协议细节：BLAKE3 键控 Merkle 哈希对齐 xet-core 的 DataHash，xorb 与 shard 格式用真实客户端抓包校验；LZ4 解码器与 ByteGrouping4 编解码器依公开规范自行编写，不依赖第三方库。
5. 可插拔流式存储：Store 接口下提供文件系统与 S3 兼容两种后端，均基于 io.Reader 流式处理，多 GB 文件上传下载的内存占用恒定；S3 后端自研 AWS SigV4 签名，不引入 AWS SDK。
6. 认证与仓库级令牌：可用令牌参数或环境变量开启鉴权，读写权限分离；签发给客户端的短期令牌用 HMAC 绑定到具体仓库，跨仓库访问直接拒绝。
7. Git LFS 服务端模式：设置 lfs.url 指向该服务后，标准 git-lfs 与 git-xet 即可把 LFS 对象以分块去重方式推入 Xet CAS。
8. 索引与持久化：提供全局分块去重索引与 V2 多区间重建接口，元数据周期性写入原子 JSON 快照，服务重启不丢。

技术实现

整个服务端被拆成三个命令：xetd 跑 CAS 服务，带上 hub 地址参数后再起一个 Hub API 垫子，正好对应真实环境中 Hub 与 CAS 分离的部署形状；xet-proxyd 复用同样的双端口结构跑缓存代理；xet 则是只面向 Xet Data API 的轻量命令行。协议侧最费工的是把 xet-core 的行为逐条对齐：Merkle 哈希实现用官方发布的参考向量做字节级校验，二进制格式则靠抓取真实 hf_xet 上传流量来还原，包括真实客户端实际上传时不写 footer 这一细节。存储层刻意建立在 io.Reader 与 io.ReadCloser 之上，任何后端都不会把整个对象读进内存，实测用真实 GGUF 模型文件跑到 27.6 GB。构建 demo 路径零外部依赖，走协议路径只增加一个纯 Go 的 blake3 模块并锁进 go.sum。测试方面，多个包带有直接从真实会话抓取的测试固件，可在单元测试里回放，用来防止线兼容性被悄悄改坏。

快速上手

1. 准备 Go 1.27 及以上版本、GNU Make 与 Bash，执行 make build 产出 xetd、xet-proxyd 与 xet 三个二进制；
2. 启动服务：./bin/xetd -addr :8420 -hub-addr :8421 -data ./xet-data；
3. 把官方客户端指过来：设置 HF_ENDPOINT 为本机 8421 端口，然后 hf upload myuser/my-model ./model.safetensors；
4. 回读校验：用 hf download 取回文件后以 cmp 比对，确认字节完全一致；
5. 需要轻量接口时，用 xet push 上传、xet pull 还原、xet stats 查看去重后的存储量。

适用人群

需要在断网或受限环境里离线托管大模型权重的研究团队与实验室、想自建 Hugging Face 镜像站点的运维工程师、关注模型文件存储成本与去重收益的团队，以及正在研究大模型分发协议、内容寻址存储与分块去重技术的开发者。