Hugging Face's logo

Diffusers documentation

MiniMax Music 3

Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

MiniMax Music 3

MiniMax Music 3 — это модель генерации музыки, которая создает полноценные треки длительностью до пяти минут на основе текста песни и описания музыкального стиля, с выразительным вокалом и продуманной структурой.

Модель представляет собой гибрид авто-регрессивного и диффузионного этапов: глобальная языковая модель на базе Qwen3 объёмом 8B предсказывает один семантический аудиотокен на кадр, в то время как небольшой декодер глубины заполняет семь остаточных RVQ-кодовых книг, а их объединённые скрытые состояния задают условия для трансформера flow-matching объёмом 2.4B, который генерирует латенты Flow-VAE в перекрывающихся фрагментах. Декодер в стиле DAC преобразует латенты в стереоаудио с частотой 44.1 кГц.

Использование

MiniMax Music 3 доступен в виде модульного конвейера.

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)

Сокращение использования памяти

См. руководство Сокращение использования памяти для получения подробной информации о различных техниках экономии памяти.

Полный конвейер требует ~23 ГБ VRAM в bfloat16. При автоматическом выгрузке на CPU генерация выполняется в ~22 ГБ свободной VRAM, а при дополнительном group-offloading языковой модели объём уменьшается до 8 ГБ.

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 кадров в секунду аудио и определяет общее время выполнения.
  • Масштаб направляющего сигнала без классификатора (classifier-free guidance) для этапа flow-matching является параметром guider (ссылочное значение при выводе — 1.7): замените его с помощью pipe.update_components(guider=ClassifierFreeGuidance(guidance_scale=...)).
  • Пайплайн возвращает стерео-выход вокодера с частотой дискретизации 44,1 кГц. Справочный сервер дополнительно выполняет ресемплинг до 32 кГц; при необходимости получить именно эту частоту примените собственный ресемплинг.

MiniMaxMusic3ModularPipeline

класс diffusers.MiniMaxMusic3ModularPipeline

< >

( 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 )

ModularPipeline для генерации музыки по условиям в виде текста песни и описания с использованием MiniMax Music 3.

MiniMaxMusic3Blocks

класс diffusers.MiniMaxMusic3Blocks

< >

( )

Модульный конвейер для генерации музыки по текстам песен и описаниям с использованием MiniMax Music 3. Авто-регрессионная языковая модель Qwen3 генерирует семантические коды и скрытые состояния для каждого кадра на основе текста песни и описания музыки; трансформер с потоковым соответствием (flow-matching) преобразует скрытые состояния в латенты Flow-VAE по частям; а вокодер в стиле DAC декодирует их в стерео-волну с частотой 44,1 кГц.

Компоненты: tokenizer (Qwen2Tokenizer) language_model (Qwen3ForCausalLM) rvq_depth_decoder (MiniMaxMusic3RVQDepthDecoder) condition_encoder (MiniMaxMusic3ConditionEncoder) transformer (MiniMaxMusic3Transformer1DModel) scheduler (FlowMatchEulerDiscreteScheduler) guider (ClassifierFreeGuidance) vocoder (MiniMaxMusic3Vocoder)

Входные данные: prompt (str): Описание музыки (жанр, настроение, вокал, инструменты, аранжировка). lyrics (str): Текст песни. Структурные теги, такие как [verse] или [chorus], должны находиться на отдельных строках; текст, расположенный на той же строке, что и ведущий тег, отбрасывается в соответствии с контрактом входных данных чекпоинта. audio_duration (float, необязательный, по умолчанию 60.0): Верхний предел длительности генерируемого аудио в секундах. Языковая модель может остановиться раньше. Ограничено 9000 кадрами (шесть минут). generator (Generator, необязательный): Генератор Torch для детерминированной генерации. num_inference_steps (int, необязательный, по умолчанию 30): Количество шагов Эйлера для flow-matching на каждый чанк. output_type (str, необязательный, по умолчанию np): Формат вывода: ‘np’ или ‘pt’.

Выводы: audios (Tensor | ndarray): Сгенерированная стерео-волновая форма с формой (batch, channels, samples) в диапазоне [-1, 1].

MiniMaxMusic3ConditionEncoder

класс diffusers.MiniMaxMusic3ConditionEncoder

< >

( 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 )

Проекция скрытых состояний каждого кадра авто-регрессивного этапа на латентную временную шкалу Flow-VAE.

Каждый сгенерированный кадр содержит num_condition_layers скрытых состояний размера condition_hidden_dim (одно от языковой модели и одно на каждый шаг остаточного кодового бука). Они смешиваются с обученными весами softmax, проецируются и пересэмплируются с частоты кадров языковой модели до частоты кадров латентного пространства с использованием интерполяции ближайшего соседа.

forward

< >

( hidden_states: Tensor ) → torch.Tensor of shape (batch, latent_length, out_dim)

Параметры

  • hidden_states (torch.Tensor формы (batch, frames, num_condition_layers * condition_hidden_dim)) — Сконкатенированные скрытые состояния по кадрам из авто-регрессивного этапа.

Возвращает

torch.Tensor с формой (batch, latent_length, out_dim)

условную последовательность, согласованную с латентным пространством.

MiniMaxMusic3RVQDepthDecoder

класс diffusers.MiniMaxMusic3RVQDepthDecoder

< >

( 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 )

Локальная языковая модель MiniMax Music 3. В каждом аудиокадре она авто регрессивно предсказывает семь остаточных RVQ-кодовых книг (c1..c7) на основе скрытого состояния глобальной языковой модели и семантического кода кадра, а также предоставляет скрытые состояния на каждом шаге, которые задают условия для трансформера flow-matching.

Он также содержит таблицу эмбеддингов для остаточных кодовых книг, которую конвейер использует для встраивания полных кадров в контуре обратной связи глобальной языковой модели.

forward

< >

( inputs_embeds: Tensor ) → torch.Tensor of shape (batch, steps, hidden_size)

Параметры

  • inputs_embeds (torch.Tensor формы (batch, steps, hidden_size)) — Проецированные эмбеддинги последовательности глубины: глобальное скрытое состояние, за которым следуют эмбеддинги кодов, сэмплированных на данный момент, каждый из которых пропущен через projection.

Возвращает

torch.Tensor формы (batch, steps, hidden_size)

нормализованные скрытые состояния; последний шаг передает данные следующей голове кодовой книги.

MiniMaxMusic3Vocoder

класс diffusers.MiniMaxMusic3Vocoder

< >

( latent_channels: int = 128decoder_input_dim: int = 1024decoder_hidden_dim: int = 1536upsampling_ratios: tuple = (8, 8, 4, 2)sampling_rate: int = 44100 )

Декодер волновых форм Flow-VAE в MiniMax Music 3 (декодер в стиле DAC). Он декодирует латенты, полученные с помощью flow-matching, формы (batch, latent_channels, length) в стереоволновые формы с частотой дискретизации sampling_rate; два аудиоканала декодируются как два свёрнутых потока latent_channels // 2.

forward

< >

( latents: Tensor ) → torch.Tensor of shape (batch, 2, samples)

Параметры

  • latents (torch.Tensor формы (batch, latent_channels, length)) — Латенты Flow-VAE с flow-matching.

Возвращает

torch.Tensor формы (batch, 2, samples)

стереосигнал в диапазоне [-1, 1].

Update on GitHub

←LTXVideo MiniMax-H3→