Mooncake Transfer Engine MUSA Wheel 正式发布：从 PyPI 安装到 vLLM-MUSA 与 SGLang 接入

Mooncake 是面向大模型推理与训练的数据基础设施项目，其中 Transfer Engine 为 KV Cache、模型权重和中间张量提供统一的数据传输能力。近期，摩尔线程与 Mooncake 社区共同完善了 MUSA 构建与发布链路。从 v0.3.12 开始，摩尔线程 GPU 用户可以直接安装官方预编译 wheel，不再需要在推理镜像里从头编译整套 C++/MUSA 工程。

目前推荐使用修订版本 v0.3.12.post1。对应的 MUSA wheel 同时可以从 GitHub Release 和 PyPI 获取。本文先介绍发布流程和安装方法，再用 vLLM-MUSA 与 SGLang 演示最基础的 Prefill-Decode（PD）分离接入。

本文基于 2026-07-27 的公开版本。Mooncake、vLLM 和 SGLang 都在快速迭代，生产部署前请再次核对所用版本的文档与硬件兼容性。

为什么推理框架需要 Transfer Engine？

大模型在线推理通常包含两个特征不同的阶段：

• Prefill：处理完整输入，计算密集，并生成 KV Cache；
• Decode：逐 token 生成，更多受显存容量和显存带宽影响。

PD 分离把两个阶段部署到不同的 GPU 或节点上，使它们可以独立扩缩容和调优。与此同时，Prefill 产生的 KV Cache 必须快速、可靠地交给 Decode。Mooncake Transfer Engine 正是这条数据路径的核心组件：它负责内存注册、拓扑发现、传输任务管理，并可根据环境使用 TCP 或 RDMA 等传输方式。

正文图与首页封面均取自或裁切自 kvcache-ai/Mooncake，基于 Apache-2.0 许可。

MUSA 版本在编译时启用 USE_MUSA=ON，使 Transfer Engine 能通过 MUSA Runtime 识别 MUSA 设备内存，并执行设备拷贝与同步。在 GPUDirect RDMA 路径中，显存则由 RDMA verbs 配合 mthreads-peermem 注册。KV Cache 因而可以在摩尔线程 GPU 显存与远端节点之间传输，避免不必要的业务层改造。

需要强调的是：PD 分离不是一个打开后就必然提高总吞吐的开关。它的主要价值是将 TTFT（首 token 延迟）和 ITL（token 间延迟）的资源与调度相互隔离，便于分别扩容并控制尾延迟。是否值得采用，应结合真实流量、模型、网络和硬件拓扑评估。

MUSA Wheel 如何自动发布？

MUSA wheel 的发布入口由 Mooncake PR #2576 引入，现有稳定 tag 的补发能力由 PR #3092 完善。当前 release-musa.yaml 的流程如下：

稳定版 tag 会自动触发构建；对于已经存在的稳定 tag，也可以通过 workflow_dispatch 补发。补发流程会先校验实际构建提交与目标 tag 是否完全一致，避免用错误源码生成同名产物。发布阶段则把构建结果附加到 GitHub Release，并通过 PyPI Trusted Publishing/OIDC 上传到 PyPI。

v0.3.12.post1 当前公开的预编译产物范围如下：

项目	当前产物
PyPI 包名	mooncake-transfer-engine-musa
Python ABI	CPython 3.10（cp310）
系统与架构	Linux x86_64，manylinux_2_35
构建基线	Ubuntu 22.04、MUSA 5.2.0、PyTorch 2.9.1.post1、mp31
Python import	from mooncake.engine import TransferEngine

PyPI 元数据中的 Requires-Python 虽然是 >=3.9，但当前实际只发布了 cp310 wheel。因此，Python 3.9、3.11、3.12 或 AArch64 环境会遇到“找不到匹配分发包”，不能把元数据范围理解为这些 ABI 都已有预编译支持。

安装与快速校验

前置条件

在安装 wheel 之前，需要准备：

• Linux x86_64 与 CPython 3.10；
• 已正确安装并可用的 MUSA Runtime；
• 若使用 GPUDirect RDMA，需配置 RDMA 网卡、驱动及 mthreads-peermem；
• 容器内需能访问 /usr/local/musa/lib，以及所需的 RDMA 设备。

wheel 不会把 libmusa.so、libmusart.so 或 GPU 驱动打包进去，这些仍由宿主机或基础镜像提供。官方构建要求可参考 Mooncake Hardware Backend Setup。

安装 MUSA 版本

建议固定版本安装：

python3.10 -m pip install \
  "mooncake-transfer-engine-musa==0.3.12.post1"

PyPI 上的标准发行包 mooncake-transfer-engine 默认面向 CUDA 环境；MUSA 环境应安装独立的 mooncake-transfer-engine-musa。两个发行包都会提供同名的 mooncake Python 模块，因此请在干净环境中二选一，不要同时安装。在已有的 CUDA 环境迁移到 MUSA 时，可以先执行：

python3.10 -m pip uninstall -y mooncake-transfer-engine
python3.10 -m pip install \
  "mooncake-transfer-engine-musa==0.3.12.post1"

校验版本和 import

python3.10 - <<'PY'
from importlib.metadata import version
from mooncake.engine import TransferEngine

print("Mooncake:", version("mooncake-transfer-engine-musa"))
print("TransferEngine:", TransferEngine)
PY

预期版本输出为：

Mooncake: 0.3.12.post1

上述 import 成功只能证明 Python 包与动态链接的基础条件满足；它不能代替真实的 GPU 显存传输、RDMA 和推理框架端到端验证。

在 vLLM-MUSA 中使用

vLLM-MUSA PR #122 已经把 mooncake-transfer-engine-musa==0.3.12.post1 接入默认的 v0.24.0-dev 分支。它的关键改动不是再维护一份 MUSA 专用 Connector，而是：

1. 在镜像中直接安装 PyPI 上的 MUSA wheel，删除 Mooncake 源码构建阶段；
2. 复用所固定上游 vLLM 的 MooncakeConnector；
3. 保留少量 MUSA 环境兼容处理和经过验证的 RDMA 容器启动方式。

因此，使用 PR #122 之后的 vLLM-MUSA 镜像时，通常不需要再次安装 Mooncake。已有环境则按上一节安装 MUSA wheel 即可。

最小单机双卡示例

vLLM-MUSA 已提供一个完整示例脚本，它会依次启动 Prefill、Decode 和请求代理。首先查看机器上的真实 HCA 名称：

ls /sys/class/infiniband

然后选择与目标 GPU 和业务网络匹配的 HCA。下面的 mlx5_0 只是占位示例，不应直接照抄：

cd /workspace/vllm-musa

export MC_TE_FILTERS=mlx5_0
export MC_FORCE_HCA=1

bash example/disaggregated_serving/disaggregated_serving.sh \
  /path/to/Qwen3-8B

• MC_TE_FILTERS 是 Mooncake 官方的 HCA 白名单，多个设备用逗号分隔；
• MC_FORCE_HCA=1 会在 RDMA 不可用时直接失败，适合验证和生产环境避免静默回退；
• 旧变量 MOONCAKE_RDMA_DEVICES 只保留为 vLLM-MUSA 兼容别名，新部署应使用 MC_TE_FILTERS。

这个脚本是一个自清理 smoke test：它会内置发送两次 completion 请求，打印结果后退出，并清理本次启动的 Prefill、Decode 和 proxy 进程。它适合快速验证环境，但不会留下常驻服务。

如需常驻服务，可以在仓库根目录下用三个终端分别启动以下进程。Prefill 和 Decode 必须使用相同模型和权重版本；两个推理终端也都要传入正确的 HCA 配置。

# 终端 1：Prefill，生成 KV Cache
MC_TE_FILTERS=mlx5_0 MC_FORCE_HCA=1 \
VLLM_MOONCAKE_BOOTSTRAP_PORT=8998 \
MUSA_VISIBLE_DEVICES=0 \
vllm serve /path/to/Qwen3-8B \
  --port 8100 \
  --max-model-len 512 \
  --max-num-seqs 16 \
  --gpu-memory-utilization 0.8 \
  --trust-remote-code \
  --kv-transfer-config \
  '{"kv_connector":"MooncakeConnector","kv_role":"kv_producer"}'

# 终端 2：Decode，接收 KV Cache 并继续生成
MC_TE_FILTERS=mlx5_0 MC_FORCE_HCA=1 \
MUSA_VISIBLE_DEVICES=1 \
vllm serve /path/to/Qwen3-8B \
  --port 8200 \
  --max-model-len 512 \
  --max-num-seqs 16 \
  --gpu-memory-utilization 0.8 \
  --trust-remote-code \
  --kv-transfer-config \
  '{"kv_connector":"MooncakeConnector","kv_role":"kv_consumer"}'

# 终端 3：启动所固定上游 vLLM 提供的 Mooncake proxy
python3.10 third_party/vllm/examples/disaggregated/mooncake_connector/mooncake_connector_proxy.py \
  --prefill http://127.0.0.1:8100 8998 \
  --decode http://127.0.0.1:8200 \
  --port 8000

客户端应访问 proxy 的 8000 端口，而不是绕过它直接访问 Prefill 或 Decode：

curl http://127.0.0.1:8000/v1/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "/path/to/Qwen3-8B",
    "prompt": "摩尔线程 GPU 是",
    "max_tokens": 32,
    "temperature": 0
  }'

完整参数和日志目录说明可查看 vLLM-MUSA Disaggregated Serving 示例。

容器中的 RDMA 注意事项

只设置 --network host 还不够。容器通常还需要：

• /dev/infiniband；
• /sys/class/infiniband 与 /sys/class/net 的只读挂载；
• 对应 verbs 和 rdma_cm 字符设备的 cgroup 权限；
• IPC_LOCK capability 与 unlimited memlock。

设备号与 HCA 名称都和宿主机有关，建议直接使用 vLLM-MUSA 文档中的 完整非特权容器 recipe，不要复制其他节点的设备号。

PR #122 的公开回归覆盖了 S5000/RoCE、Qwen3-0.6B，以及 eager 和 compiled 两条 vLLM 路径。这证明了该组合的可用性，但不代表所有模型、MUSA 版本和网络拓扑都已经验证。

在 SGLang 中使用

SGLang 当前主分支已经同时提供 MUSA 平台支持和 Mooncake PD backend。MUSA 安装 extra 本身不包含 Mooncake，因此需要额外安装本节所述的 MUSA wheel。SGLang 通过 mooncake.engine.TransferEngine 使用同一套 Python API；从接口上看可以直接换用 MUSA wheel，无需先修改 Connector，但以下仍是需要在目标环境验证的接入模板。

安装 SGLang MUSA 环境

下面沿用 SGLang Moore Threads GPU 文档 的源码安装方式，并额外加入 Mooncake MUSA wheel：

git clone https://github.com/sgl-project/sglang.git
cd sglang
git checkout abb8f4b5e3feac3f9d50d5e8987b9c4ca7f6e5aa

python3.10 -m pip install --upgrade pip
(cd sgl-kernel && python3.10 setup_musa.py install)

rm -f python/pyproject.toml
mv python/pyproject_other.toml python/pyproject.toml
python3.10 -m pip install -e "python[all_musa]"

# Router 是单独发布的包
python3.10 -m pip install "sglang-router==0.3.2"

python3.10 -m pip install \
  "mooncake-transfer-engine-musa==0.3.12.post1"

如果环境中已经安装通用版 mooncake-transfer-engine，请先卸载，避免两个发行包覆盖同一个 mooncake 模块。

启动 Prefill、Decode 与 Router

以下命令参考 SGLang 的 PD Disaggregation 文档。三个进程分别在三个终端运行，模型路径和 HCA 名称需要替换为本机实际值。

# 终端 1：Prefill，使用 GPU 0
python3.10 -m sglang.launch_server \
  --model-path /path/to/Qwen3-8B \
  --device musa \
  --disaggregation-mode prefill \
  --disaggregation-transfer-backend mooncake \
  --disaggregation-bootstrap-port 8998 \
  --disaggregation-ib-device mlx5_0 \
  --port 30000

# 终端 2：Decode，使用 GPU 1
python3.10 -m sglang.launch_server \
  --model-path /path/to/Qwen3-8B \
  --device musa \
  --base-gpu-id 1 \
  --disaggregation-mode decode \
  --disaggregation-transfer-backend mooncake \
  --disaggregation-ib-device mlx5_0 \
  --port 30001

# 终端 3：对外服务入口
python3.10 -m sglang_router.launch_router \
  --pd-disaggregation \
  --prefill http://127.0.0.1:30000 \
  --decode http://127.0.0.1:30001 \
  --host 0.0.0.0 \
  --port 8000

同样，客户端只访问 Router：

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "/path/to/Qwen3-8B",
    "messages": [{"role": "user", "content": "介绍一下 Mooncake"}],
    "max_tokens": 64
  }'

SGLang 迭代很快，实际参数应以所用 commit 的文档为准。目前公开 CI 中没有看到 MUSA + Mooncake PD 的完整端到端覆盖，因此这里应理解为接口级基础接入模板；上线前仍需在目标 SGLang 版本、模型、MUSA Runtime 与 RDMA 网络上完成回归。

常见问题

1. 为什么 pip 提示没有匹配的版本？

先检查 python --version、uname -m 和系统 glibc。当前 wheel 只面向 CPython 3.10、Linux x86_64 和兼容 manylinux_2_35 的环境。

2. 为什么 import 成功，但启动框架时报 MUSA 动态库错误？

wheel 不携带 MUSA Runtime。确认 libmusa.so、libmusart.so 在动态链接器搜索路径中，并检查基础镜像、驱动和 Runtime 是否匹配。

3. 为什么日志里使用了 TCP，而不是 RDMA？

检查容器设备、memlock、HCA 名称、路由以及 mthreads-peermem。验证 RDMA 时建议设置 MC_FORCE_HCA=1，让配置错误直接暴露，而不是静默回退。

4. HCA 名称应该怎么填？

使用 ls /sys/class/infiniband 或 ibdev2netdev 查看当前机器。不要照抄本文的 mlx5_0，多 HCA 可以通过 MC_TE_FILTERS=mlx5_0,mlx5_1 配置；SGLang 则通过 --disaggregation-ib-device 传入。

5. GitHub Release 和 PyPI 应该选哪个？

日常安装推荐 PyPI，便于版本固定和依赖管理；离线环境可以从 GitHub Release 下载 wheel 后安装。两个入口都提供 MUSA 产物，但不要假设同一版本在两个入口的文件一定具有相同校验和，制作离线镜像时应记录实际下载来源和 SHA256。

总结

Mooncake 从 v0.3.12 起把 MUSA Transfer Engine 纳入官方 release pipeline，v0.3.12.post1 已可通过 mooncake-transfer-engine-musa 直接安装。这使推理框架的集成从“在镜像里 clone 并编译 Mooncake”简化为“固定一个经过发布的 wheel 版本”。

对于 vLLM-MUSA，PR #122 已完成 wheel 固定、上游 Connector 复用和 S5000/RoCE 回归；对于 SGLang，接口层可以额外安装 MUSA wheel 并沿用 Mooncake PD backend，但还需要匹配的独立 Router 包和目标环境回归。真正上线时，仍应围绕目标模型、Python ABI、MUSA Runtime、容器设备权限和 RDMA 拓扑做完整验证。

参考资料

• Mooncake GitHub 仓库
• Mooncake v0.3.12 Release
• Mooncake v0.3.12.post1 Release
• mooncake-transfer-engine-musa on PyPI
• MUSA release workflow
• vLLM-MUSA PR #122
• vLLM MooncakeConnector 使用文档
• SGLang PD Disaggregation 文档