自托管部署 MiniMax Music 3

MiniMax Music 3 根据歌词和音乐描述生成包含人声与伴奏的完整歌曲。本页介绍如何使用 SGLang-Omni 在 NVIDIA CUDA GPU 上部署 HTTP 服务；这是面向服务器的自托管部署，不是消费级设备本地运行指南。

模型卡声明模型原生支持最长约 5 分钟的歌曲。SGLang-Omni 最多接受 9,000 个声学帧，按每秒 25 帧换算为 6 分钟请求上限。框架上限不代表模型额外验证了 1 分钟能力。需要保持在模型已公开的 5 分钟范围内时，请将 max_new_tokens 设为不超过 7,500。

部署状态

项目	基线
部署状态	官方未公开稳定性等级；MiniMax 发布完整硬件与性能基线前，请将本页作为参考部署方案
已验证 API 路径	通过 `POST /v1/audio/speech` 输入歌词和音乐描述，获得非流式 WAV 响应
模型	`MiniMaxAI/MiniMax-Music3`
模型 revision	`fbdf52fbaaca799592917417eb05f1899f1255ec`
推理框架	`sglang-omni==0.1.3`（tag `v0.1.3`）
Python	3.10–3.12；本文使用 3.12
文档核验日期	2026 年 8 月 26 日

固定模型 revision 和推理框架版本可以避免命令随 main 分支变化，但不代表 MiniMax 已验证所有兼容的 GPU、驱动和操作系统组合。

硬件基线

SGLang-Omni 只公开了一套参考音频配置和两种阶段放置方式，尚未公开 Music 3 的峰值显存、最低 GPU 显存、主机内存、最低驱动版本、生成耗时或实时系数。

配置	GPU 放置	参考负载	峰值显存	主机内存	性能	状态
1 × NVIDIA H200	自回归和声学阶段位于同一张 GPU	使用默认设置生成 5 个不超过 30 秒的参考片段	未公开	未公开	未公开	上游参考配置
2 × NVIDIA CUDA GPU	自回归阶段位于 GPU 0；DiT 和音频解码器位于 GPU 1	未公开	未公开	未公开	未公开	支持阶段放置，未验证容量

单 GPU 命令不代表任意 CUDA GPU 都具备足够显存。接收生产流量前，请先在实际硬件上验证短音频请求。模型仓库当前显示文件总量约 57.4 GB；还需为 Python 环境、下载元数据和临时文件预留额外磁盘空间。

快速开始

安装固定版本的运行环境

请使用配有 NVIDIA CUDA GPU 的干净 Linux 环境。SGLang-Omni 0.1.3 固定使用 CUDA 13 运行时组件、PyTorch 2.11.0 和 SGLang 0.5.16。上游尚未为 Music 3 配置公开准确的 NVIDIA 最低驱动版本；安装前请确认主机驱动支持所安装的 CUDA 运行时。

uv venv .venv --python 3.12
source .venv/bin/activate
uv pip install --prerelease=allow "sglang-omni==0.1.3"

python -c "import sglang_omni, torch; print(sglang_omni.__version__, torch.__version__, torch.cuda.is_available())"

继续操作前，最后一个值必须为 True。UCX 与 CUDA 编译依赖请参阅 SGLang-Omni 安装指南。

下载固定版本的权重

export MUSIC3_MODEL_DIR=/data/models/MiniMax-Music3-fbdf52f

hf download MiniMaxAI/MiniMax-Music3 \
  --revision fbdf52fbaaca799592917417eb05f1899f1255ec \
  --local-dir "$MUSIC3_MODEL_DIR"

启动服务

快速开始默认只监听本机回环地址。保持当前终端运行：

CUDA_VISIBLE_DEVICES=0 sgl-omni serve \
  --model-path "$MUSIC3_MODEL_DIR" \
  --model-name MiniMaxAI/MiniMax-Music3 \
  --host 127.0.0.1 \
  --port 8000

检查服务健康状态

在另一个终端执行：

curl -fsS http://127.0.0.1:8000/health
curl -fsS http://127.0.0.1:8000/v1/models

/health 应返回 HTTP 200，状态为 healthy 且 running。/v1/models 应包含 MiniMaxAI/MiniMax-Music3。

生成并验证歌曲

curl --fail-with-body -X POST http://127.0.0.1:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MiniMaxAI/MiniMax-Music3",
    "input": "[Verse]\n晨光穿过安静的窗\n街道在微风中醒来\n[Chorus]\n向着今天出发\n让歌声越过云海",
    "instructions": "温暖的原声流行歌曲，96 BPM，女声主唱，指弹吉他与柔和钢琴，副歌逐渐加入鼓组并扩展立体声场。",
    "seed": 7,
    "max_new_tokens": 750,
    "response_format": "wav",
    "stream": false
  }' \
  --output minimax_music3.wav

python -c 'import wave; f=wave.open("minimax_music3.wav"); print({"channels": f.getnchannels(), "sample_rate": f.getframerate(), "sample_width_bytes": f.getsampwidth(), "duration_seconds": round(f.getnframes()/f.getframerate(), 2)})'

文件必须是非空 WAV，并显示 channels=2、sample_rate=32000 和 sample_width_bytes=2。750 帧最多允许 30 秒音频；模型输出音频结束标记时，实际时长可以更短。

能力边界

能力	模型原生能力	当前部署路径已验证能力
歌词与音乐描述生成完整歌曲	支持	支持
输出格式	32 kHz、16-bit 立体声 WAV	支持
歌曲时长	最长约 5 分钟	上游参考音频只验证了不超过 30 秒的片段；MiniMax 尚未公开长音频性能基线
流式生成	不支持	`stream` 必须为 `false`
音色选择或克隆	当前请求协议不支持	`voice` 和参考音频字段会被拒绝
精确 BPM、调性、乐器、歌词或结构	属于生成控制，不是严格保证	不保证

SGLang-Omni 声明，在相同环境中保持歌词、instructions、seed 和长度完全一致，可以得到字节级一致的音频。不要假设不同模型 revision、推理框架版本或硬件栈之间仍可保持字节级一致。

请求协议

字段	要求
`input`	必填且不能为空，用于提供歌词。`[Verse]`、`[Chorus]`、`[Bridge]`、`[Outro]` 等结构标签必须单独占一行。
`instructions`	必填且不能为空，用于描述曲风、乐器、速度、情绪、人声、编曲和制作风格。
`seed`	非负 64-bit 整数。默认值 `0` 也是固定 seed，并非随机值。
`max_new_tokens`	声学帧数上限，每秒 25 帧。服务端最大值为 `9,000`；要保持在模型公开的 5 分钟范围内，请不超过 `7,500`。
`response_format`	必须为 `wav`。
`stream`	必须为 `false`；模型生成完成后才返回响应。

文本提示分词后最多为 5,000 token。如果其他字段均有效但请求因这一限制被拒绝，请缩短歌词或 instructions。

结构标签必须单独占一行。例如，应写成 [Verse]\nWalking down the street。如果把歌词写在标签同一行，规范化阶段可能在不报错的情况下删除该行歌词。

不要传入 temperature、top_p、top_k、repetition_penalty、voice、参考音频字段、language 或 task_type。速度和人声特征应写入 instructions。 HTTP 客户端还有一种名为 streaming response 的机制，表示客户端把已经产生的 HTTP 响应体分块写入磁盘。它不会让 Music 3 的模型生成变成流式。本指南统一使用普通的 curl --output，避免混淆这两个概念。

权重、缓存与离线部署

官方权重：MiniMaxAI/MiniMax-Music3
本文固定的权重：revision fbdf52f
Hugging Face 默认缓存目录为 ~/.cache/huggingface/hub；可通过 HF_HOME 或 HF_HUB_CACHE 调整。
本文使用 --local-dir，服务启动时直接加载固定本地路径，不解析远程 main。
截至文档核验日期，Music 3 模型卡没有链接 MiniMax 官方 ModelScope 镜像。

离线部署时，先在联网机器下载固定 revision，再把完整目录复制到目标主机，并使用本地路径启动。可通过以下环境变量阻止意外访问网络：

export HF_HUB_OFFLINE=1
export MUSIC3_MODEL_DIR=/data/models/MiniMax-Music3-fbdf52f

CUDA_VISIBLE_DEVICES=0 sgl-omni serve \
  --model-path "$MUSIC3_MODEL_DIR" \
  --model-name MiniMaxAI/MiniMax-Music3 \
  --host 127.0.0.1 \
  --port 8000

下载中断或文件损坏时，请使用相同 revision 重新执行 hf download。只有需要替换本地文件，而不是续传或复用已有文件时，才添加 --force-download。

生产部署与安全

使用两张 GPU

SGLang-Omni 会把自回归阶段放在第一张可见 GPU，把 DiT 和音频解码阶段放在第二张：

CUDA_VISIBLE_DEVICES=0,1 sgl-omni serve \
  --model-path "$MUSIC3_MODEL_DIR" \
  --model-name MiniMaxAI/MiniMax-Music3 \
  --host 127.0.0.1 \
  --port 8000

这只是阶段放置选项，不代表任何特定双 GPU 组合具备最低显存或性能保证。

规划并发

Music 3 在两个生成阶段都使用 classifier-free guidance。每个请求会在自回归引擎中占用两行 KV Cache。提高请求上限时，需要按准入请求数的两倍规划容量：

CUDA_VISIBLE_DEVICES=0,1 sgl-omni serve \
  --model-path "$MUSIC3_MODEL_DIR" \
  --model-name MiniMaxAI/MiniMax-Music3 \
  --host 127.0.0.1 \
  --port 8000 \
  --max-running-requests 32

在实际硬件上测量峰值显存和延迟之前，不要提高此值。先用 10 秒、250 帧的片段验证歌词和音乐描述，再生成完整歌曲，可以降低迭代成本。

安全地开放服务

尽可能让模型服务监听 127.0.0.1。需要远程访问时，应在前面部署带身份验证的 API 网关或反向代理，并配置 TLS、请求大小限制、速率限制、超时和网络白名单。不要把未经鉴权的 0.0.0.0:8000 直接暴露到互联网。配置访问日志和可观测性时，应将歌词和音乐描述视为潜在敏感数据。

故障排查

现象	常见原因	处理方式
`torch.cuda.is_available()` 输出 `False`，或 CUDA 动态库加载失败	驱动、CUDA 运行时、PyTorch 与 SGLang-Omni 依赖不兼容	使用全新的 Python 3.10–3.12 环境，严格重装 `sglang-omni==0.1.3`，并在启动前确认主机驱动支持其 CUDA 运行时。
进程被终止或出现 CUDA OOM	单 GPU 无法容纳共置阶段，或并发/KV Cache 过大	将 `--max-running-requests` 设为 `1`，先测试 250 帧，停止其他 GPU 任务，或改用双 GPU 放置。不要假设降低 `mem_fraction_static` 可以解决声学阶段显存问题。
权重下载停滞、失败或加载报错	磁盘不足、网络中断或本地文件损坏	检查剩余磁盘，按固定 revision 重新下载；只有需要替换损坏文件时才使用 `--force-download`。
`/health` 返回 `503` 或无法连接	模型 Worker 仍在加载，或某个阶段启动失败	等待所有阶段就绪，再从服务日志中查找第一条 CUDA、依赖、权重或阶段间传输错误。
请求返回 HTTP `4xx`	必填字段为空，或传入了不支持的 Speech API 字段	从上面的最小请求开始，保持 `stream=false` 和 WAV 输出，并删除 TTS 采样、音色和参考音频字段。
歌词缺失或音频短于请求长度	结构标签和歌词写在同一行，或模型输出了结束标记	让标签单独占一行；`max_new_tokens` 是上限，不是目标时长。

遇到多 GPU NCCL 或 UCX 错误时，先确认单 GPU 命令可以启动，再检查 GPU 可见性、GPU 间连接，以及 SGLang-Omni 文档中的 UCX 前置依赖。

License 与相关资源

资源	链接
模型仓库	`MiniMaxAI/MiniMax-Music3`
推理代码与提示词工具	MiniMax-AI/MiniMax-Music3
模型 License	MiniMax-Music3 Community License
推理参考	SGLang-Omni `v0.1.3` Music 3 Cookbook

模型 License 包含产品署名、商业收入门槛、安全措施、知识产权和 Acceptable Use Policy 等要求。向第三方提供 Music 3 服务前，请阅读权威 License 原文并落实全部适用条款。SGLang-Omni 另行采用 Apache-2.0 License。

开始使用

使用指南

常见问题

条款与政策

部署状态

硬件基线

快速开始

安装固定版本的运行环境

下载固定版本的权重

启动服务

检查服务健康状态

生成并验证歌曲

能力边界

请求协议

权重、缓存与离线部署

生产部署与安全

使用两张 GPU

规划并发

安全地开放服务

故障排查

License 与相关资源

​部署状态

​硬件基线

​快速开始

​安装固定版本的运行环境

​下载固定版本的权重

​启动服务

​检查服务健康状态

​生成并验证歌曲

​能力边界

​请求协议

​权重、缓存与离线部署

​生产部署与安全

​使用两张 GPU

​规划并发

​安全地开放服务

​故障排查

​License 与相关资源

部署状态

硬件基线

快速开始

安装固定版本的运行环境

下载固定版本的权重

启动服务

检查服务健康状态

生成并验证歌曲

能力边界

请求协议

权重、缓存与离线部署

生产部署与安全

使用两张 GPU

规划并发

安全地开放服务

故障排查

License 与相关资源