# MiniMax Music 3

[MiniMax Music 3](https://huggingface.co/MiniMaxAI/MiniMax-Music3) 是一款音乐生成模型，能够根据歌词和音乐描述生成时长最长为五分钟的完整歌曲，并具备富有表现力的人声和长程结构。

该模型是自回归阶段与扩散阶段的混合体：一个基于 8B Qwen3 的全局语言模型每帧预测一个语义音频 token，同时一个小型深度解码器填充七个残差 RVQ 码本，它们融合后的隐藏状态作为条件输入一个 2.4B 的 flow-matching transformer，以重叠块的方式生成 Flow-VAE 潜变量。一个 DAC 风格的解码器将这些潜变量转换为 44.1 kHz 立体声音频。

## 用法

MiniMax Music 3 以模块化流水线形式提供。

```py
import soundfile as sf
import torch
from diffusers import ModularPipeline

pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-Music3")
pipe.load_components(dtype=torch.bfloat16)
pipe.to("cuda")  # or "mps", "xpu", "cpu"

lyrics = """[verse]
Morning light filtering through the pine
Every quiet street is yours and mine
[chorus]
Softly the world begins to breathe"""

prompt = (
    "Genre: acoustic pop. BPM: 96. Key: C major. Warm and intimate, building gently into the chorus. "
    "Vocals: soft female lead, close and breathy, light stacked harmonies in the chorus. "
    "Arrangement: fingerpicked guitar and soft piano; brushed drums and upright bass enter in the chorus."
)

audio = pipe(
    prompt=prompt,
    lyrics=lyrics,
    audio_duration=60.0,
    generator=torch.Generator("cuda").manual_seed(7),
    output="audios",
)[0]

sf.write("minimax_music3.wav", audio.T, pipe.sampling_rate)
```

## 减少内存使用

有关各种内存节省技术的详细信息，请参阅 [减少内存使用](../../optimization/memory) 指南。

完整流水线在 bfloat16 下需要约 23 GB 的 VRAM。使用自动 CPU 卸载后，生成过程仅需约 22 GB 的可用 VRAM；若同时对语言模型进行组卸载，则 8 GB 即可满足需求。

```py
import torch
from diffusers import ComponentsManager, ModularPipeline
from diffusers.hooks.group_offloading import apply_group_offloading

manager = ComponentsManager()
manager.enable_auto_cpu_offload(device="cuda")  # or "mps", "xpu", "cpu"
pipe = ModularPipeline.from_pretrained("MiniMaxAI/MiniMax-Music3", components_manager=manager)
pipe.load_components(dtype=torch.bfloat16)

# Only needed below ~22 GB of free VRAM — slower, but fits in 8 GB.
apply_group_offloading(
    pipe.language_model, onload_device=torch.device("cuda"), offload_type="leaf_level", use_stream=True
)
```

## 提示

- 诸如 `[intro]`、`[verse]`、`[pre-chorus]`、`[chorus]`、`[bridge]`、`[instrumental]`、`[solo]` 和 `[outro]` 等结构标签，在 `lyrics` 中必须各自独占一行。与行首标签位于同一行的文本会被模型的输入约定丢弃。
- 音乐描述用于控制人声：请明确描述人声的性别和音色（例如“温暖的女声”），否则模型可能会偏向纯器乐。若要实现精细控制，请将描述结构化为全局元数据（流派、BPM、调性、情感走向）、人声细节以及编曲。
- `audio_duration` 是一个上限——语言模型可能会通过停止标记提前结束歌曲。自回归阶段每秒生成 25 帧音频，并且是运行时间的主要部分。
- 流匹配阶段的无分类器引导尺度是一个 guider 设置（参考推理值为 1.7）：使用 `pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...))` 进行替换。
- 该 pipeline 返回声码器原生的 44.1 kHz 立体声输出。参考服务器会额外将其重采样为 32 kHz；如果您需要该特定采样率，请自行应用重采样。

## MiniMaxMusic3ModularPipeline[[diffusers.MiniMaxMusic3ModularPipeline]]

#### diffusers.MiniMaxMusic3ModularPipeline[[diffusers.MiniMaxMusic3ModularPipeline]]

```python
diffusers.MiniMaxMusic3ModularPipeline(blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = None, pretrained_model_name_or_path: str | os.PathLike | None = None, components_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = None, collection: str | None = None, workflow: str | None = None, modular_config_dict: dict[str, typing.Any] | None = None, config_dict: dict[str, typing.Any] | None = None, **kwargs)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_music3/modular_pipeline.py#L22)

一个用于基于歌词和描述条件生成音乐的 ModularPipeline，基于 MiniMax Music 3。

## MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

#### diffusers.MiniMaxMusic3Blocks[[diffusers.MiniMaxMusic3Blocks]]

```python
diffusers.MiniMaxMusic3Blocks()
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/modular_pipelines/minimax_music3/modular_blocks_minimax_music3.py#L130)

基于 MiniMax Music 3 的模块化流水线，用于根据歌词和描述生成音乐。自回归 Qwen3 语言模型根据歌词和音乐描述生成逐帧的语义编码和隐藏状态；流匹配 Transformer 将隐藏状态逐块转换为 Flow-VAE 潜在表示；DAC 风格的声码器将其解码为 44.1 kHz 的立体声波形。

组件：分词器（`Qwen2Tokenizer`）语言模型（`Qwen3ForCausalLM`）rvq_depth_decoder（`MiniMaxMusic3RVQDepthDecoder`）condition_encoder（`MiniMaxMusic3ConditionEncoder`）transformer（`MiniMaxMusic3Transformer1DModel`）调度器（`FlowMatchEulerDiscreteScheduler`）guider（`ClassifierFreeGuidance`）声码器（`MiniMaxMusic3Vocoder`）

输入：prompt (`str`)：音乐描述（流派、情绪、人声、配器、编曲）。lyrics (`str`)：要演唱的歌词。诸如 `[verse]` 或 `[chorus]` 之类的结构标签必须各自独占一行；与行首标签位于同一行的文本会被检查点的输入约定丢弃。audio_duration (`float`，*可选*，默认值为 60.0)：生成音频时长的上限（以秒为单位）。语言模型可能会提前停止。上限为 9000 帧（六分钟）。generator (`Generator`，*可选*)：用于确定性生成的 Torch 生成器。num_inference_steps (`int`，*可选*，默认值为 30)：每个块中 flow-matching Euler 步数。output_type (`str`，*可选*，默认值为 np)：输出格式：'np' 或 'pt'。

输出：audios（`Tensor | ndarray`）：形状为 `(batch, channels, samples)` 的生成立体声波形，取值范围为 `[-1, 1]`。

## MiniMaxMusic3ConditionEncoder[[diffusers.MiniMaxMusic3ConditionEncoder]]

#### diffusers.MiniMaxMusic3ConditionEncoder[[diffusers.MiniMaxMusic3ConditionEncoder]]

```python
diffusers.MiniMaxMusic3ConditionEncoder(condition_hidden_dim: int = 4096, num_condition_layers: int = 8, out_dim: int = 2048, input_sampling_rate: int = 24000, input_hop_length: int = 960, output_sampling_rate: int = 44100, output_hop_length: int = 512)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_minimax_music3.py#L23)

将自回归阶段的逐帧隐藏状态投影到 Flow-VAE 潜在时间轴上。

每个生成的帧都携带 `num_condition_layers` 个大小为 `condition_hidden_dim` 的隐藏状态（一个来自语言模型，每个残差码本步骤各一个）。这些隐藏状态通过学习得到的 softmax 权重进行混合，经过投影后，使用最近邻插值从语言模型的帧率重采样到潜在帧率。

#### forward[[diffusers.MiniMaxMusic3ConditionEncoder.forward]]

```python
forward(hidden_states: Tensor)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/condition_embedders/condition_embedder_minimax_music3.py#L48)

**参数：**

hidden_states (`torch.Tensor`，形状为 `(batch, frames, num_condition_layers * condition_hidden_dim)`)：自回归阶段中逐帧拼接的隐藏状态。

**返回值：** 形状为 `(batch, latent_length, out_dim)` 的 `torch.Tensor`

潜在对齐的条件序列。

## MiniMaxMusic3RVQDepthDecoder[[diffusers.MiniMaxMusic3RVQDepthDecoder]]

#### diffusers.MiniMaxMusic3RVQDepthDecoder[[diffusers.MiniMaxMusic3RVQDepthDecoder]]

```python
diffusers.MiniMaxMusic3RVQDepthDecoder(hidden_size: int = 4096, num_layers: int = 4, num_attention_heads: int = 16, intermediate_size: int = 6144, audio_vocab_size: int = 1024, num_codebooks: int = 8, max_position_embeddings: int = 16)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/minimax_music3_rvq_depth_decoder.py#L91)

MiniMax Music 3 的本地语言模型。在每个音频帧中，它基于全局语言模型的隐藏状态以及该帧的语义码，自回归地预测七个残差 RVQ 码本（c1..c7），并暴露出用于条件化 flow-matching transformer 的逐步隐藏状态。

它还负责管理残差码本的嵌入表，该流水线使用此表对完整帧进行嵌入，以支持全局语言模型的反馈循环。

#### forward[[diffusers.MiniMaxMusic3RVQDepthDecoder.forward]]

```python
forward(inputs_embeds: Tensor)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/transformers/minimax_music3_rvq_depth_decoder.py#L127)

**参数：**

inputs_embeds (`torch.Tensor`，形状为 `(batch, steps, hidden_size)`)：投影后的深度序列嵌入：全局隐藏状态，后接迄今为止采样的嵌入代码，每个均通过 `projection` 处理。

**返回：** 形状为 `(batch, steps, hidden_size)` 的 `torch.Tensor`

归一化后的隐藏状态；最后一步将结果传递给下一个码本头。

## MiniMaxMusic3Vocoder[[diffusers.MiniMaxMusic3Vocoder]]

#### diffusers.MiniMaxMusic3Vocoder[[diffusers.MiniMaxMusic3Vocoder]]

```python
diffusers.MiniMaxMusic3Vocoder(latent_channels: int = 128, decoder_input_dim: int = 1024, decoder_hidden_dim: int = 1536, upsampling_ratios: tuple = (8, 8, 4, 2), sampling_rate: int = 44100)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/minimax_music3_vocoder.py#L71)

MiniMax Music 3 的 Flow-VAE 波形解码器（一种 DAC 风格的解码器）。它将形状为 `(batch, latent_channels, length)` 的流匹配潜在变量解码为采样率为 `sampling_rate` 的立体声音频波形；两个音频通道被解码为两条折叠的 `latent_channels // 2` 流。

#### forward[[diffusers.MiniMaxMusic3Vocoder.forward]]

```python
forward(latents: Tensor)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/models/autoencoders/minimax_music3_vocoder.py#L100)

**参数：**

latents (`torch.Tensor`，形状为 `(batch, latent_channels, length)`)：Flow-matched Flow-VAE 潜变量。

**返回：** 形状为 `(batch, 2, samples)` 的 `torch.Tensor`

`[-1, 1]` 中的立体声波形。