如何在单GPU上5分钟跑通Xor:Docker快速部署与完整避坑教程
如何在单GPU上5分钟跑通Xor:Docker快速部署与完整避坑教程
Xor 1.2(xor-1.2)是一个专为"带类型决策任务"(typed decision)后训练的开源大模型,基于 Qwen3.6-35B-A3B(350 亿参数 MoE 架构,BF16 精度),通过 Docker 化服务包在单张 GPU 上即可启动,API 端点为 /v1/systemone。本文是一份 Xor 单 GPU 部署指南,带你走完"下载—校验—启动—验证"全流程,并汇总部署 Xor 时最常见的报错与避坑方案。
一、Xor 是什么?为什么值得部署
一句话概括:Xor 是一个能给出"结构化答案 + 概率分布"的决策模型。与普通聊天模型不同,它的服务接口支持三种带类型的问答:
| 类型 | 返回内容 | 典型用途 |
|---|---|---|
noul |
二元概率(是/否) | 风控判定、合规检查 |
choice |
类别决策 + 完整概率分布 | 多分类决策 |
score |
期望序数分 + 完整概率分布 | 打分、评级 |
请求还可附带最多 8 张图片或 1 段视频(data URL),让模型对"文本 + 媒体"做联合判断。服务层内置了确定性候选读出、正反向选项顺序评估和概率校准,保证结果可复现——这也是它要求使用官方服务包、而非自己裸跑模型的原因。
📌 版本提示:
release/xor-1.2分支对应 Xor 1.2,v1.1、xor-v1为不可变旧版。可复现部署请锁定 revision(详见 README.md 的 Revisions 一节)。
二、部署前环境清单:5分钟自检
Xor 的官方运行环境是 Linux x86-64 + Docker,部署前用 5 分钟逐项打勾,能避开后面 80% 的坑:
- [ ] 操作系统:Linux x86-64(官方验证环境)
- [ ] GPU:单卡(TP1 验证于 1 × NVIDIA H200 NVL,143 GB 显存;模型权重约 66 GB,BF16 下对显存要求较高,低显存显卡需自行验证)
- [ ] 磁盘:约 120 GB 空闲空间(模型文件 + 运行目录)
- [ ] Hugging Face CLI:已安装并可登录(用于
hf download) - [ ] Docker Engine + 新版 Docker Compose v2:服务包使用了 service 级
gpus字段,旧版 Compose 会直接拒绝启动 - [ ] NVIDIA Container Toolkit:让容器内能看到 GPU
自检命令(3 条):
nvidia-smi # 确认 GPU 可见
docker compose version # 确认 Compose v2
docker run --rm --gpus all nvidia/cuda:12.4.1-base-ubuntu22.04 nvidia-smi
第三条是关键:如果容器内 nvidia-smi 报错,说明 NVIDIA Container Toolkit 没装好,这是单 GPU 部署第一常见报错来源。
三、5分钟快速部署:下载 → 校验 → 启动
1. 下载发布包并锁定版本
hf download juspay/xor --revision release/xor-1.2 --local-dir xor-1.2
2. 校验服务包完整性
发布的服务包(serving/ 目录下的 tar 包)自带 SHA256 清单,先验签再解压:
(cd xor-1.2/serving && sha256sum -c xor-1.2-serving.tar.gz.sha256)
mkdir -p xor-1.2-runtime
tar -xzf xor-1.2/serving/xor-1.2-serving.tar.gz -C xor-1.2-runtime --strip-components=1
服务包本体见 serving/xor-1.2-serving.tar.gz,指纹文件为 serving/xor-1.2-serving.tar.gz.sha256。
3. 配置并启动
cd xor-1.2-runtime
cp .env.example .env
sed -i "s|^MODEL_DIR=.*|MODEL_DIR=$(cd ../xor-1.2 && pwd)|" .env
./run.sh
run.sh 启动前会用 checksums.sha256 逐个核对全部模型分片,任何文件损坏都会在这里被拦下,而不是在服务中途才暴露。
冒烟测试通过后,API 地址为:
http://127.0.0.1:30002/v1/systemone
发一条测试请求验证:
curl -sS -X POST http://127.0.0.1:30002/v1/systemone \
-H 'Content-Type: application/json' \
--data @examples/request.json
⏱️ 顺利的话:下载时间取决于带宽,"解压 + 启动 + 首请求"在已验证环境下约 5 分钟量级。
四、完整避坑指南:按报错逐条排查
坑 1:Compose 报 gpus 相关错误 / 服务直接拒绝启动
原因:旧版 Docker Compose 不认识 service 级 gpus 字段。
解法:升级到新版 Compose v2 插件(docker compose version 确认)。这是最容易踩、也最好修的坑。
坑 2:容器内看不到 GPU
原因:缺 NVIDIA Container Toolkit,或驱动与容器运行时不匹配。
解法:安装 NVIDIA Container Toolkit 后,用第二节第三条命令在容器里跑 nvidia-smi 验证;再启动 Xor。
坑 3:磁盘空间不足导致下载/启动中断
原因:模型 16 个分片约 66 GB,加上解压后的运行目录,官方建议预留 约 120 GB。
解法:df -h 确认目标分区余量;不要把模型放在系统盘剩余空间紧张的分区上。
坑 4:请求返回 HTTP 422
原因:请求体超过 8 MB 上限(base64 编码后媒体大约只剩 6 MB 空间)。 解法:压缩图片/视频后再转 data URL;图片最多 8 张、视频最多 1 个。
坑 5:同时传了图片和视频,结果"分不清"
原因:API 层面允许两者同传,但模型无法可靠区分。 解法:每个请求只发一种媒体,这是官方明确的操作规范。
坑 6:评分请求和普通生成请求混跑,调度器崩溃
原因:上游 SGLang 在 candidate-logprob 处理上的一个缺陷。
解法:无需手动修复——官方服务镜像 prakhar1611/xor-sglang 已内置该补丁(补丁源文件为 Dockerfile.sglang-logprob-fix)。避坑要点:不要用未打补丁的裸 SGLang 镜像自建服务。
坑 7:远程部署被外网裸访问
原因:服务绑定 localhost 时不需要 API Key,但直接暴露到公网没有任何认证。 解法:远程部署时,务必在入口层(ingress)加认证、TLS、限流和请求大小限制,四层缺一不可。
坑 8:两次部署结果不一致
原因:没有锁定版本。
解法:按 README.md 的说明 pin revision;release/xor-1.2 是分支,追求字节级可复现时请进一步 pin commit hash。完整产物哈希、基座 revision 与运行镜像 digest 都记录在 RELEASE_PROVENANCE.json 中,可逐项比对。
五、参考数据:Xor 1.2 的公开成绩
在公开 JEVBench 分层上(1 × H200 NVL,TP1,无缓存)的自测结果:
| 层级 | 题数 | 准确率 | p50 延迟 | p95 延迟 |
|---|---|---|---|---|
| Easy | 48 | 1.0000 | 0.0679 s | 0.0709 s |
| Original | 72 | 0.9583 | 0.0670 s | 0.0701 s |
| Hard public | 111 | 0.8198 | 0.0832 s | 0.1845 s |
| 全部公开层 | 231 | 0.9004 | 0.0691 s | 0.1616 s |
总体 macro accuracy 0.9070、ECE 0.0733,schema 校验通过率 100%(自测口径,非官方榜单排名,延迟与硬件强相关)。
六、仓库文件资料索引
| 文件 | 说明 |
|---|---|
| README.md | 快速开始、接口说明、验证环境 |
| serving/ | Docker 服务包(tar.gz + SHA256 指纹) |
| checksums.sha256 | 全部模型文件 SHA256 校验清单 |
| RELEASE_PROVENANCE.json | 基座/适配器/合并/镜像的完整溯源记录 |
| config.json | 模型架构配置(MoE、256 专家、BF16) |
| generation_config.json | 生成参数(temperature 1.0、top_p 0.95) |
| tokenizer.json / vocab.json / merges.txt | 分词器文件 |
| THIRD_PARTY_NOTICES.md / LICENSE | 第三方声明与 Apache 2.0 许可 |
七、常见问题 FAQ
Q:没有 143 GB 大显存,单卡能跑吗? 官方仅验证了 1 × H200 NVL(TP1)配置;不同硬件和并行设置需自行验证后再引用性能数据。显存不足时可关注量化/多卡方案,但不在官方发布验证范围内。
Q:一定要用官方服务包吗? 是的。服务层(候选读出、概率校准、schema 转换)是发布推理配置的一部分,自己裸跑模型拿不到可复现结果。
Q:启动后如何确认服务健康?
向 http://127.0.0.1:30002/v1/systemone 发送示例请求,收到结构化 JSON(决策 + 概率分布)即代表全链路正常。
按以上步骤操作,你就能在单张 GPU 上把 Xor 从下载到稳定服务一次跑通。遇到报错时,优先对照"避坑指南"逐条排查:Compose 版本 → GPU 可见性 → 磁盘空间 → 请求大小,绝大多数部署问题都藏在这四步里。