SGLang 启动报错 401 Unauthorized XET CAS 鉴权失败 完整排查与解决

一、报错根因

plaintext

RuntimeError: Task error: File reconstruction error: CAS Client Error: Request error: HTTP status client error (401 Unauthorized)

Hugging Face Hub 开启了 Xet 分布式文件存储加速下载，拉取模型分片时访问 cas-server.xethub.hf.co 接口鉴权失败（401 未授权），模型权重下载中断，子进程直接退出导致 SGLang 调度器崩溃。

核心诱因

1. 未配置 HuggingFace 登录令牌 HF_TOKEN；
2. 环境网络 / 代理导致 Xet 组件无法携带合法凭证；
3. huggingface_hub 新版默认启用 Xet 下载，内网 / 离线环境无权限访问该服务。

方案 1：临时关闭 Xet 下载（最快生效，推荐优先用）

启动服务前设置环境变量，强制禁用 Xet 分片下载逻辑：

bash

运行

# Linux / WSL
export HF_HUB_ENABLE_XET_FETCH=0
# 再启动sglang服务
python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

Windows PowerShell：

powershell

$env:HF_HUB_ENABLE_XET_FETCH="0"
python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

方案 2：登录 HuggingFace 授权，补齐访问凭证

步骤 1：安装并登录 hf cli

bash

运行

pip install huggingface-hub
huggingface-cli login

粘贴你在 HF 官网生成的 Read 权限 Token，回车确认。

步骤 2：直接在命令行注入环境变量启动

bash

运行

HF_TOKEN="你的hf读取token" python3 -m sglang.launch_server --model-path qwen/qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

方案 3：提前手动把模型下载到本地，完全绕过在线拉取

1. 使用 huggingface-cli 手动下载模型至本地目录

bash

运行

huggingface-cli download qwen/qwen2.5-0.5b-instruct --local-dir ./qwen2.5-0.5b-instruct

2. 启动时指定本地绝对路径，不会再触发在线下载与 Xet 鉴权：

bash

运行

python3 -m sglang.launch_server --model-path ./qwen2.5-0.5b-instruct --host 0.0.0.0 --port 30000

方案 4：国内镜像源下载（无外网 HF 环境适用）

使用 ModelScope / HF 镜像站点预下载模型，再挂载本地路径启动，彻底规避外网 401 问题。

补充排查点

1. 若配置了 HTTP/HTTPS 代理，建议临时清空代理环境变量再试：

bash

运行

unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

2. 升级 huggingface-hub 到最新版，部分旧版本 Xet 逻辑存在 bug：

bash

运行

pip install --upgrade huggingface-hub

3. 清理 HF 缓存目录损坏文件：

bash

运行

rm -rf ~/.cache/huggingface/hub

优先执行方案 1一行环境变量即可绕过该鉴权报错，是最简单稳定的修复方式。