Diffusers documentation
MiniMax Music 3
MiniMax Music 3
MiniMax Music 3 é um modelo de geração de música que produz canções completas de até cinco minutos a partir de letras e uma descrição musical, com vocais expressivos e estrutura de longo alcance.
O modelo é um híbrido de um estágio autoregressivo e um estágio de difusão: um modelo de linguagem global baseado em Qwen3 de 8B prevê um token de áudio semântico por quadro, enquanto um decodificador de profundidade pequeno preenche sete codebooks residuais RVQ, e os estados ocultos fundidos deles condicionam um transformer de flow-matching de 2.4B que produz latentes Flow-VAE em blocos sobrepostos. Um decodificador estilo DAC converte os latentes em áudio estéreo de 44,1 kHz.
Uso
MiniMax Music 3 está disponível como um pipeline modular.
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)Reduzir o uso de memória
Consulte o guia Reduzir o uso de memória para mais detalhes sobre as diversas técnicas de economia de memória.
O pipeline completo requer ~23 GB de VRAM em bfloat16. Com o offloading automático para CPU, uma geração é executada em ~22 GB de VRAM livre, e, adicionalmente, o group-offloading do modelo de linguagem cabe em 8 GB.
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
)Dicas
- Tags de estrutura, como
[intro],[verse],[pre-chorus],[chorus],[bridge],[instrumental],[solo]e[outro], devem estar cada uma em sua própria linha emlyrics. O texto na mesma linha que uma tag inicial é descartado pelo contrato de entrada do modelo. - A descrição da música controla os vocais: descreva explicitamente o gênero e o timbre vocal (por exemplo, “vocal feminino quente”) ou o modelo pode se desviar para uma faixa instrumental. Para um controle mais detalhado, estruture a descrição em metadados globais (gênero, BPM, tonalidade, progressão emocional), detalhes vocais e arranjo.
audio_durationé um limite superior — o modelo de linguagem pode encerrar a música antes com um token de parada. O estágio autoregressivo gera 25 quadros por segundo de áudio e domina o tempo de execução.- A escala de orientação sem classificador da etapa de correspondência de fluxo é uma configuração de guia (o valor de referência de inferência é 1.7): substitua-a por
pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...)). - O pipeline retorna a saída estéreo nativa de 44,1 kHz do vocoder. O servidor de referência também faz a reamostragem para 32 kHz; aplique sua própria reamostragem se precisar dessa taxa exata.
MiniMaxMusic3ModularPipeline
classe diffusers.MiniMaxMusic3ModularPipeline
< source >( blocks: diffusers.modular_pipelines.modular_pipeline.ModularPipelineBlocks | None = Nonepretrained_model_name_or_path: str | os.PathLike | None = Nonecomponents_manager: diffusers.modular_pipelines.components_manager.ComponentsManager | None = Nonecollection: str | None = Noneworkflow: str | None = Nonemodular_config_dict: dict[str, typing.Any] | None = Noneconfig_dict: dict[str, typing.Any] | None = None**kwargs )
Uma ModularPipeline para geração de música condicionada por letras e legendas com MiniMax Music 3.
MiniMaxMusic3Blocks
Pipeline modular para geração de música condicionada por letras e descrições usando MiniMax Music 3. Um modelo de linguagem autoregressivo Qwen3 gera códigos semânticos por quadro e estados ocultos a partir das letras e da descrição da música; um transformer de flow-matching converte os estados ocultos em latentes Flow-VAE em blocos; e um vocoder estilo DAC os decodifica em uma forma de onda estéreo a 44,1 kHz.
Componentes:
tokenizer (Qwen2Tokenizer) language_model (Qwen3ForCausalLM) rvq_depth_decoder
(MiniMaxMusic3RVQDepthDecoder) condition_encoder (MiniMaxMusic3ConditionEncoder) transformer
(MiniMaxMusic3Transformer1DModel) scheduler (FlowMatchEulerDiscreteScheduler) guider
(ClassifierFreeGuidance) vocoder (MiniMaxMusic3Vocoder)
Entradas:
prompt (str):
A descrição da música (gênero, clima, vocais, instrumentação, arranjo).
lyrics (str):
A letra a ser cantada. Tags de estrutura, como [verse] ou [chorus], devem estar cada uma em sua própria linha; o texto
na mesma linha de uma tag inicial é descartado pelo contrato de entrada do checkpoint.
audio_duration (float, opcional, padrão 60.0):
Limite superior para a duração do áudio gerado, em segundos. O modelo de linguagem pode parar antes. Limitado a 9000
frames (seis minutos).
generator (Generator, opcional):
Gerador do Torch para geração determinística.
num_inference_steps (int, opcional, padrão 30):
Número de passos de Euler de flow-matching por chunk.
output_type (str, opcional, padrão np):
Formato de saída: ‘np’ ou ‘pt’.
Saídas:
audios (Tensor | ndarray):
A forma de onda estéreo gerada, com formato (batch, channels, samples) em [-1, 1].
MiniMaxMusic3ConditionEncoder
classe diffusers.MiniMaxMusic3ConditionEncoder
< source >( condition_hidden_dim: int = 4096num_condition_layers: int = 8out_dim: int = 2048input_sampling_rate: int = 24000input_hop_length: int = 960output_sampling_rate: int = 44100output_hop_length: int = 512 )
Projeta os estados ocultos por quadro da etapa autoregressiva para a linha do tempo latente do Flow-VAE.
Cada quadro gerado carrega num_condition_layers estados ocultos de tamanho condition_hidden_dim (um do modelo de linguagem e um para cada etapa do codebook residual). Eles são misturados com pesos softmax aprendidos, projetados e reamostrados da taxa de quadros do modelo de linguagem para a taxa de quadros latente com interpolação de vizinho mais próximo.
forward
< source >( hidden_states: Tensor ) → torch.Tensor of shape (batch, latent_length, out_dim)
Parâmetros
- hidden_states (
torch.Tensorde forma(batch, frames, num_condition_layers * condition_hidden_dim)) — Estados ocultos concatenados por quadro da etapa autoregressiva.
Retorna
torch.Tensor de forma (batch, latent_length, out_dim)
a sequência de condicionamento alinhada ao espaço latente.
MiniMaxMusic3RVQDepthDecoder
classe diffusers.MiniMaxMusic3RVQDepthDecoder
< source >( hidden_size: int = 4096num_layers: int = 4num_attention_heads: int = 16intermediate_size: int = 6144audio_vocab_size: int = 1024num_codebooks: int = 8max_position_embeddings: int = 16 )
O modelo de linguagem local do MiniMax Music 3. Dentro de cada quadro de áudio, ele prevê autoregressivamente os sete codebooks residuais RVQ (c1..c7) a partir do estado oculto do modelo de linguagem global e do código semântico do quadro, e expõe os estados ocultos por etapa que condicionam o transformer de flow-matching.
Ele também possui a tabela de incorporação para os livros de códigos residuais, que o pipeline usa para incorporar quadros completos para o loop de feedback do modelo de linguagem global.
forward
< source >( inputs_embeds: Tensor ) → torch.Tensor of shape (batch, steps, hidden_size)
Parâmetros
- inputs_embeds (
torch.Tensorde forma(batch, steps, hidden_size)) — Incorporações de sequência de profundidade projetadas: o estado oculto global seguido pelos códigos incorporados amostrados até o momento, cada um passado porprojection.
Retorna
torch.Tensor de forma (batch, steps, hidden_size)
estados ocultos normalizados; a última etapa alimenta a próxima cabeça do codebook.
MiniMaxMusic3Vocoder
classe diffusers.MiniMaxMusic3Vocoder
< source >( latent_channels: int = 128decoder_input_dim: int = 1024decoder_hidden_dim: int = 1536upsampling_ratios: tuple = (8, 8, 4, 2)sampling_rate: int = 44100 )
O decodificador de forma de onda Flow-VAE do MiniMax Music 3 (um decodificador no estilo DAC). Ele decodifica latentes de fluxo compatível de forma (batch, latent_channels, length) em formas de onda estéreo em sampling_rate; os dois canais de áudio são decodificados como
dois fluxos dobrados de latent_channels // 2.
forward
< source >( latents: Tensor ) → torch.Tensor of shape (batch, 2, samples)