SGLang-MUSA 概览与环境准备（Docker镜像 v0.5.6.post3-ph1）

一、为什么单独把 SGLang-MUSA 拎出来讲？

截至本课更新（2026-06-06），摩尔线程对外提供的高性能推理引擎主要有两条主线：vllm-musa（前面 m5-l3、m8-l1~l2 已系统讲过）和 SGLang-MUSA（m5-l4 做过入门）。前者以"通用、上游对齐"见长，后者的差异化在于结构化生成 + RadixAttention 前缀复用 + 一套和 vLLM 形态不同的分布式语义（TP/PP/DP/EP + PD 分离）。

更关键的是，2026-06-05 摩尔线程在 docs.mthreads.com/sglang-musa 上线了第一版完整的 SGLang-MUSA 官方用户指南，明确给出了 Docker 镜像 tag、依赖版本、9 大模型族的部署命令。本课就以这份官方文档为基准，把"环境准备 → 镜像启动 → 虚拟环境切换 → 健康检查"这条链路一次性打通，避免线上踩坑。

二、架构一眼看：SGLang-MUSA 是怎么在 SGLang 上跑起来的？

在冲到镜像之前，先建立一个架构心智图，之后看参数就不会迷路。根据官方「简介」页面，SGLang-MUSA 采用三层剖分：

• 兑现层：SGLang Runtime + MultiPlatformOp — 上游 SGLang 主干原封不动，通过内置的多平台分发机制路由到 MUSA 实现，几乎所有 PR 已经回推到 sgl-project/sglang 主干。
• 兼容层：torch_musa + torchada — import torchada 一句话拦截 CUDA API，改写到 MUSA 后端；取代了早期侵入式的散点修补，跟上游版本成本近乎为零。
• 算子加速层：MATE（MUSA AI Tensor Engine）— 提供 FlashAttention-3 / SageAttention / FlashMLA / DeepGEMM 的兼容 API；分布式侧增强 MTLink 检测与 Custom AllReduce，并与 Mooncake 协作完成 PD 分离的跨节点 KV Transfer。

这三层决定了本课后续为什么要顺序检查「驱动 → peermem → mt-container-toolkit → torch_musa → SGLang」这条链，以及为什么要明确区分 --attention-backend fa3 与 nsa。

三、SGLang-MUSA 的官方版本栈（2026-06-05 镜像）

官方推荐用 Docker 镜像，对应 tag 是：

registry.mthreads.com/mcconline/inference/sglang:v0.5.6.post3-ph1-4.3.5-torch2.9.0-20260605

把 tag 拆开看，能一眼读出整条栈：

四、宿主机依赖（容器外必须装齐）

SGLang-MUSA 是 GPU 容器，要把 MTT S5000 透传进去，宿主机必须先装齐 4 个组件，版本要求严格对齐：

4 个组件全部装好后，跑一次冒烟检查：

mthreads-smi
# 期望看到 8 张 MTT S5000，每张 80GB HBM，温度< 50°C
# Driver 版本和 mtml 版本要分别 >= 3.3.5 / 2.2.0
docker run --rm --runtime=mthreads --env MTHREADS_VISIBLE_DEVICES=all \
  registry.mthreads.com/mcconline/inference/sglang:v0.5.6.post3-ph1-4.3.5-torch2.9.0-20260605 \
  mthreads-smi
# 期望容器内也能看到全部 8 张卡

五、Step-by-Step：拉起一个最小可用环境

Step 1：拉镜像（首次约 18 GB，建议挂内网 registry 镜像）

docker pull registry.mthreads.com/mcconline/inference/sglang:v0.5.6.post3-ph1-4.3.5-torch2.9.0-20260605

Step 2：启动容器（保留 SSH + 模型挂载点）

docker run -d --name sglang-musa \
  --runtime=mthreads --env MTHREADS_VISIBLE_DEVICES=all \
  --net=host --ipc=host --shm-size=64g \
  --ulimit memlock=-1 --ulimit stack=67108864 \
  -v /data/models:/models \
  -v /data/sglang-cache:/root/.cache \
  registry.mthreads.com/mcconline/inference/sglang:v0.5.6.post3-ph1-4.3.5-torch2.9.0-20260605 \
  bash -c 'apt-get update && apt-get install -y openssh-server && \
           service ssh start && tail -f /dev/null'

关键参数解释：

• --shm-size=64g：必须开大，TP=8 通信走共享内存，小了会 OOM
• --ipc=host：保证多进程 NCCL/MCCL 看得见
• --ulimit memlock=-1：HBM pinning，跑大模型必开
• --net=host：PD 分离时跨节点 KV Transfer 要直连

Step 3：进入容器，切到 sglang 虚拟环境

docker exec -it sglang-musa bash
# 容器内
source ~/.virtualenvs/sglang-0.5.6/bin/activate
python3 -c "import sglang; print(sglang.__version__)"
# 期望输出：0.5.6.post3
python3 -c "import torch, torch_musa; print(torch.__version__, torch_musa.__version__, torch.musa.is_available())"
# 期望输出：2.9.0 2.9.0 True

Step 4：清理 triton 缓存（首次启动后强烈推荐）

workon triton-3.2.0   # 切换 triton 虚拟环境
rm -rf ~/.triton/cache/ && rm -rf /tmp/torch_inductor_*
workon sglang-0.5.6   # 切回 sglang

原因：MUSA 后端的 triton 编译产物会按 GPU 架构指纹缓存，跨镜像复用同一个 /data/sglang-cache 时偶发"算子版本错配"。每次升镜像后清一次 cache 最稳。

Step 5：用最小模型做一次端到端冒烟

# 容器内，单卡 0.8B 起一个最小 server
python3 -m sglang.launch_server \
  --model-path /models/Qwen3.5-0.8B \
  --served-model-name qwen3.5-0.8b \
  --trust-remote-code \
  --tp-size 1 --pp-size 1 \
  --mem-fraction-static 0.8 \
  --attention-backend fa3 \
  --sampling-backend flashinfer \
  --port 30000 &
# 另起一个终端
curl http://127.0.0.1:30000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen3.5-0.8b","messages":[{"role":"user","content":"用一句话介绍 SGLang-MUSA"}]}'

如果能看到正常 JSON 回复（一般 1.5s 以内），说明驱动、容器、SDK、torch_musa、SGLang、FA3、flashinfer sampler 这一整条链路都通了，后续 m8-l10 的大模型部署就可以直接基于本环境复制扩容。

六、SGLang-MUSA 当前支持的模型清单（来自官方「支持模型及平台」）

了解环境之后，立刻明确：这套镜像究竟能跑哪些模型？官方支持模型及平台页面给出的当前矩阵如下（截至 2026-06-05）：

这张矩阵就是后续课程 m8-l10 一上来要分模板讲解的依据，本课先建立一个直观印象：SGLang-MUSA 当前覆盖了从 0.8B 小模型到 671B FP8 超大 MoE 的全谱系，且包含 VL 和扩散两类多模态，已经足够撑起一个生产级推理底座。

七、上线前检查清单

八、为什么是现在把 SGLang-MUSA 拉进雷达？

过去几周的周报里，SGLang 只作为「推理生态」下面的一个备选被提及。这周官方文档上线后，与之前零散的 GitHub PR 信息拼在一起，能得出三个明确判断：第一，SGLang-MUSA 已经从「社区实验」走到「官方维护 + 主干回推」阶段、与 vllm-musa 并列。第二，它是 DeepSeek V3.2 / R1 在 MUSA 上唯一被官方背书的 NSA 部署路径，这在 671B FP8 场景里算是关键名单。第三，零侵入的 torchada 架构让它能同步上游 SGLang 每一个周周发版本，高 PR 回推率让它在成本优势上不输主流 NVIDIA 后端。本周起，本站点的雷达也官方加入了 sglang-musa 文档站作为独立追踪源，未来任何「发布信息」「支持模型」「部署参数」上的变动都会被周报捕获、并在下一轮迭代同步到本课和 m8-l10。

九、参考链接（全部来自摩尔线程官方）

• SGLang-MUSA 用户指南 · 简介
• 版本发布信息
• 支持模型及平台
• 环境准备
• 快速开始
• FAQ