Hugging Face's logo

Diffusers documentation

MiniMax Music 3

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v0.43.0).
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→