diffusers/main/ru/api/pipelines/ace_step.md

ACE-Step 1.5

ACE-Step 1.5 был представлен в статье ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation командой ACE-Step (ACE Studio и StepFun). Это открытая фундаментальная модель для музыки, которая генерирует стерео-музыку коммерческого качества с текстом песни по текстовым запросам.

ACE-Step 1.5 генерирует стереозвук переменной длины (от 10 секунд до 10 минут) с частотой дискретизации 48 кГц по текстовым запросам и необязательным текстам песен. Полная система объединяет планировщик на основе языковой модели и синтезатор на основе диффузионного трансформера (DiT); данный конвейер инкапсулирует DiT-часть этого стека и состоит из трёх компонентов: VAE AutoencoderOobleck, сжимающего звуковые сигналы в стерео-латенты с частотой 25 Гц, текстового энкодера на базе Qwen3 для условного кодирования запросов и текстов песен, а также DiT AceStepTransformer1DModel, работающего в латентном пространстве VAE с использованием flow matching.

Модель поддерживает более 50 языков для текста песен — включая английский, китайский, японский, корейский, французский, немецкий, испанский, итальянский, португальский и русский — и работает на потребительских GPU (менее 4 ГБ VRAM при offload).

Этот конвейер был предоставлен командой ACE-Step Team. Исходная кодовая база доступна по адресу ace-step/ACE-Step-1.5.

Варианты

ACE-Step 1.5 включает три контрольные точки DiT, которые используют одну и ту же архитектуру трансформера, но различаются поведением при управлении (guidance); конвейер автоматически определяет турбо-контрольные точки по конфигурации загруженного трансформера и игнорирует управление CFG для этих весов, дистиллированных по управлению.

Вариант	CFG	Шаги по умолчанию	Значение guidance_scale по умолчанию	По умолчанию shift	Репозиторий HF
turbo (с дистиллированным guidance)	off	8	ignored	3.0	ACE-Step/acestep-v15-xl-turbo-diffusers
base	вкл	8	7.0	3.0	ACE-Step/acestep-v15-base
sft	вкл	8	7.0	3.0	ACE-Step/acestep-v15-sft

Base и SFT используют обученный null_condition_emb для classifier-free guidance (APG, а не обычный CFG). Пользователи часто переопределяют num_inference_steps в 30–60 для base/sft, чтобы повысить качество.

Советы

При составлении промпта помните:

• Описательные входные промпты работают лучше всего; используйте прилагательные для описания стиля музыки, инструментов, настроения и темпа.
• Промпт должен описывать общие музыкальные характеристики (например, «энергичная поп-песня с электрической гитарой и барабанами»).
• Текст песни должен быть структурирован с помощью тегов, таких как [verse], [chorus], [bridge] и т. д.

Во время инференса:

• num_inference_steps, guidance_scale и shift по умолчанию принимают значения, показанные выше. Для turbo-чекпоинтов guidance_scale > 1.0 игнорируется с предупреждением, поскольку guidance дистиллирован в веса.
• Параметр audio_duration управляет длительностью генерируемой музыки в секундах.
• Параметр vocal_language должен соответствовать языку текста песни.
• pipe.sample_rate и pipe.latents_per_second берутся из конфигурации VAE (48000 Гц и 25 к/с для выпущенных контрольных точек).
• Для задач аудио-в-аудио передавайте src_audio и reference_audio в виде предобработанных стереотензоров с частотой дискретизации pipe.sample_rate.
• flash и flash_hub используют нативную поддержку скользящего окна в FlashAttention для self-attention в ACE-Step и ожидают текстовые батчи без padding. Если батч промптов содержит padding, используйте вместо них flash_varlen или flash_varlen_hub. Инференс с одним промптом при padding="longest" обычно выполняется без padding.

import torch
import soundfile as sf
from diffusers import AceStepPipeline

pipe = AceStepPipeline.from_pretrained("ACE-Step/acestep-v15-xl-turbo-diffusers", dtype=torch.bfloat16)
pipe = pipe.to("cuda")  # or "mps", "xpu", "cpu"

audio = pipe(
    prompt="A beautiful piano piece with soft melodies and gentle rhythm",
    lyrics="[verse]\nSoft notes in the morning light\nDancing through the air so bright\n[chorus]\nMusic fills the air tonight\nEvery note feels just right",
    audio_duration=30.0,
).audios

sf.write("output.wav", audio[0].T.cpu().float().numpy(), pipe.sample_rate)

AceStepPipeline[[diffusers.AceStepPipeline]]

diffusers.AceStepPipeline[[diffusers.AceStepPipeline]]

diffusers.AceStepPipeline(vae: AutoencoderOobleck, text_encoder: PreTrainedModel, tokenizer: TokenizersBackend, transformer: AceStepTransformer1DModel, condition_encoder: AceStepConditionEncoder, scheduler: FlowMatchEulerDiscreteScheduler, audio_tokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenizer] = None, audio_token_detokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenDetokenizer] = None)

Источник

Параметры:

vae (AutoencoderOobleck) : вариационная автокодирующая модель (VAE) для кодирования и декодирования аудиосигналов в латентные представления и обратно.

text_encoder (AutoModel): модель текстового кодировщика (например, Qwen3-Embedding-0.6B) для кодирования текстовых подсказок и текстов песен.

tokenizer (AutoTokenizer) : токенизатор для текстового энкодера.

transformer (AceStepTransformer1DModel) : Модель Diffusion Transformer (DiT) для удаления шума из латентных представлений аудио.

condition_encoder (AceStepConditionEncoder) : Кодировщик условий, объединяющий эмбеддинги текста, текста песни и тембра для кросс-внимания.

scheduler (FlowMatchEulerDiscreteScheduler) : планировщик Euler для flow-matching. ACE-Step передаёт шаги DiT в диапазоне [0, 1], поэтому планировщик настраивается с параметрами num_train_timesteps=1 и shift=1.0 — пайплайн самостоятельно вычисляет свой сдвинутый / turbo-расписание сигм и передаёт его через set_timesteps(sigmas=...).

Пайплайн для генерации музыки из текста с использованием ACE-Step 1.5.

Эта модель наследуется от DiffusionPipeline. Общую документацию по методам, реализованным для всех пайплайнов (загрузка, сохранение, запуск на конкретном устройстве и т. д.), см. в документации родительского класса.

Пайплайн использует flow matching с пользовательским расписанием шагов времени для процесса диффузии. Вариант модели turbo по умолчанию использует 8 шагов инференса.

Поддерживаемые типы задач:

• "text2music": Генерация музыки по текстовым запросам и текстам песен.
• "cover": Генерация аудио из исходного аудио / семантических кодов с переносом тембра из референсного аудио.
• "repaint": Пересоздаёт часть существующего аудио, сохраняя остальное.
• "extract": Извлечь конкретный трек (например, вокал или ударные) из аудио.
• "lego": Генерация конкретного трека на основе аудиоконтекста.
• "complete": Дополнить входной аудиодорожкой дополнительными треками.

call[[diffusers.AceStepPipeline.call]]

__call__(prompt: typing.Union[str, typing.List[str]] = None, lyrics: typing.Union[str, typing.List[str]] = '', audio_duration: float = 60.0, vocal_language: typing.Union[str, typing.List[str]] = 'en', num_inference_steps: int = 8, guidance_scale: float = 7.0, shift: float = 3.0, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None, output_type: typing.Optional[str] = 'pt', return_dict: bool = True, callback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = None, callback_steps: typing.Optional[int] = 1, callback_on_step_end: typing.Optional[typing.Callable[..., dict]] = None, callback_on_step_end_tensor_inputs: typing.List[str] = ('latents',), instruction: typing.Optional[str] = None, max_text_length: int = 256, max_lyric_length: int = 2048, bpm: typing.Optional[int] = None, keyscale: typing.Optional[str] = None, timesignature: typing.Optional[str] = None, task_type: str = 'text2music', track_name: typing.Optional[str] = None, complete_track_classes: typing.Optional[typing.List[str]] = None, src_audio: typing.Optional[torch.Tensor] = None, reference_audio: typing.Optional[torch.Tensor] = None, audio_codes: typing.Union[str, typing.List[str], NoneType] = None, repainting_start: typing.Optional[float] = None, repainting_end: typing.Optional[float] = None, audio_cover_strength: float = 1.0, cfg_interval_start: float = 0.0, cfg_interval_end: float = 1.0, timesteps: typing.Optional[typing.List[float]] = None, attention_kwargs: typing.Optional[dict] = None)

Источник

Параметры:

prompt (str или List[str], необязательный) : Промпт или промпты для управления генерацией музыки. Описывает стиль, жанр, инструменты и т. д.

lyrics (str или List[str], необязательный, по умолчанию "") : Текст песни. Поддерживает структурированные тексты с тегами, такими как [verse], [chorus] и т. д.

audio_duration (float, необязательный, по умолчанию 60.0) : Длительность сгенерированного аудио в секундах.

vocal_language (str или List[str], необязательный, по умолчанию "en") : Код языка для текста песни (например, "en", "zh", "ja").

num_inference_steps (int, optional, по умолчанию 8) : Количество шагов денойзинга. Турбо-модель рассчитана на 8 шагов.

guidance_scale (float, optional, по умолчанию 7.0) : Масштаб направляющего коэффициента для classifier-free guidance. Значение 1.0 отключает CFG.

shift (float, optional, по умолчанию 3.0) : Параметр сдвига для расписания шагов времени (1.0, 2.0 или 3.0).

generator (torch.Generator или List[torch.Generator], необязательный) : Генератор для обеспечения детерминированности генерации.

latents (torch.Tensor, необязательный) : Предварительно сгенерированные шумовые латенты формы (batch_size, latent_length, acoustic_dim).

output_type (str, необязательный, по умолчанию "pt") : Формат вывода. "pt" для тензора PyTorch, "np" для массива NumPy, "latent" для необработанных латентов.

return_dict (bool, необязательный, по умолчанию True) : Возвращать ли AudioPipelineOutput или обычный кортеж.

callback (Callable, необязательный) : функция, вызываемая каждые callback_steps шагов с аргументами (step, timestep, latents).

callback_steps (int, необязательный, по умолчанию 1) : Частота вызова функции обратного вызова.

callback_on_step_end (Callable, необязательный) : функция, вызываемая в конце каждого шага денойзинга во время инференса. Функция вызывается со следующими аргументами: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs будет содержать список всех тензоров, как указано в callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (List, необязательный) : Список тензорных входных данных для функции callback_on_step_end. Тензоры, указанные в списке, будут переданы в качестве аргумента callback_kwargs. Вы сможете включать только переменные, перечисленные в атрибуте ._callback_tensor_inputs вашего класса конвейера.

instruction (str, необязательный) : Пользовательский текст инструкции для задачи генерации. Если не указан, генерируется автоматически на основе task_type.

max_text_length (int, необязательный, по умолчанию 256) : Максимальная длина токенов для кодирования текстового промпта.

max_lyric_length (int, optional, по умолчанию 2048) : Максимальная длина токенов для кодирования текста песни.

bpm (int, optional) : BPM (ударов в минуту) для метаданных музыки. Если None, модель оценивает его самостоятельно.

keyscale (str, необязательный) : Тональность (например, "C major", "A minor"). Если None, модель оценивает её автоматически.

timesignature (str, необязательный) : Размерность такта (например, "4" для 4/4, "3" для 3/4). Если None, модель оценивает её автоматически.

task_type (str, необязательный, по умолчанию "text2music") : Тип задачи генерации. Один из "text2music", "cover", "repaint", "extract", "lego", "complete".

track_name (str, необязательный) : Название дорожки для задач "extract" или "lego" (например, "vocals", "drums").

complete_track_classes (List[str], необязательный) : Классы для отслеживания для задачи "complete".

src_audio (torch.Tensor, необязательный) : исходный аудиотензор формы [channels, samples] с частотой дискретизации 48 кГц для задач аудио-в-аудио (repaint, lego, cover, extract, complete). Аудио кодируется через VAE для получения исходных латентов.

reference_audio (torch.Tensor, необязательный) : Тензор опорного аудио с формой [channels, samples] при частоте дискретизации 48 кГц для настройки тембра. Используется для извлечения тембровых признаков при передаче стиля.

audio_codes (str или List[str], необязательный) : строки семантических кодов аудио (например, "<|audio_code_123|><|audio_code_456|>..."). Если значение указано, задача автоматически переключается в режим "cover", а зарегистрированные модули токенизатора/детокенизатора аудио ACE-Step декодируют коды с частотой 5 Гц в акустическое условие с частотой 25 Гц.

repainting_start (float, optional) : Время начала в секундах для области перерисовки (для задач "repaint" и "lego").

repainting_end (float, optional) : Конец времени в секундах для области перерисовки. Используйте -1 или None для до конца.

audio_cover_strength (float, optional, по умолчанию 1.0) : Сила смешивания аудио-покрытия (от 0.0 до 1.0). При значении < 1.0 смешиваются выходы, обусловленные покрытием, и выходы, обусловленные только текстом. Более низкие значения создают более выраженный эффект переноса стиля.

cfg_interval_start (float, optional, по умолчанию 0.0) : Начальная доля (0.0–1.0) диапазона временных шагов, в которой применяется CFG.

cfg_interval_end (float, optional, по умолчанию 1.0) : Конечное отношение (0.0-1.0) диапазона временных шагов, в котором применяется CFG.

timesteps (List[float], необязательный) : Пользовательское расписание временных шагов. Если указано, переопределяет num_inference_steps и shift.

attention_kwargs (dict, необязательный) : Словарь kwargs, передаваемый в AttentionProcessor. Используется для передачи масштаба LoRA через {"scale": float}.

Возвращает: AudioPipelineOutput или tuple

Если return_dict равно True, возвращается AudioPipelineOutput, иначе — кортеж с сгенерированным аудио.

Функция вызова pipeline для генерации музыки.

Примеры:

>>> import torch
>>> import soundfile as sf
>>> from diffusers import AceStepPipeline

>>> pipe = AceStepPipeline.from_pretrained(
...     "ACE-Step/acestep-v15-xl-turbo-diffusers", torch_dtype=torch.bfloat16
... )
>>> pipe = pipe.to("cuda")

>>> # Text-to-music generation with metadata
>>> audio = pipe(
...     prompt="A beautiful piano piece with soft melodies",
...     lyrics="[verse]\nSoft notes in the morning light\n[chorus]\nMusic fills the air tonight",
...     audio_duration=30.0,
...     num_inference_steps=8,
...     bpm=120,
...     keyscale="C major",
...     timesignature="4",
... ).audios

>>> # Save the generated audio
>>> sf.write("output.wav", audio[0, 0].cpu().numpy(), 48000)

>>> # Repaint task: regenerate a section of existing stereo 48kHz audio
>>> src_audio, sr = sf.read("input.wav")
>>> src_audio = torch.from_numpy(src_audio).float().T
>>> audio = pipe(
...     prompt="Epic rock guitar solo",
...     lyrics="",
...     task_type="repaint",
...     src_audio=src_audio,
...     repainting_start=10.0,
...     repainting_end=20.0,
... ).audios

>>> # Cover task with reference audio for timbre transfer
>>> ref_audio, sr = sf.read("reference.wav")
>>> ref_audio = torch.from_numpy(ref_audio).float().T
>>> audio = pipe(
...     prompt="Pop song with bright vocals",
...     lyrics="[verse]\nHello world",
...     task_type="cover",
...     reference_audio=ref_audio,
...     audio_cover_strength=0.8,
... ).audios

check_inputs[[diffusers.AceStepPipeline.check_inputs]]

check_inputs(prompt: typing.Union[str, typing.List[str]], lyrics: typing.Union[str, typing.List[str]], task_type: str, num_inference_steps: int, guidance_scale: float, shift: float, audio_cover_strength: float, cfg_interval_start: float, cfg_interval_end: float, repainting_start: typing.Optional[float], repainting_end: typing.Optional[float])

Источник

Проверяйте аргументы, предназначенные для пользователя, до начала выделения тензоров шума.

encode_prompt[[diffusers.AceStepPipeline.encode_prompt]]

encode_prompt(prompt: typing.Union[str, typing.List[str]], lyrics: typing.Union[str, typing.List[str]], device: device, vocal_language: typing.Union[str, typing.List[str]] = 'en', audio_duration: float = 60.0, instruction: typing.Optional[str] = None, bpm: typing.Optional[int] = None, keyscale: typing.Optional[str] = None, timesignature: typing.Optional[str] = None, max_text_length: int = 256, max_lyric_length: int = 2048)

Источник

Параметры:

prompt (str или List[str]) : Текстовые описания музыки.

lyrics (str или List[str]) : Текст(ы) песни.

device (torch.device) : Устройство для тензоров.

vocal_language (str или List[str], необязательный, по умолчанию "en") : Код(ы) языка для текста песни.

audio_duration (float, необязательный, по умолчанию 60.0) : Длительность аудио в секундах.

instruction (str, необязательный) : Текст инструкции для генерации.

bpm (int, необязательный) : BPM (ударов в минуту) для метаданных.

keyscale (str, необязательный) : Музыкальный лад (например, "C major").

timesignature (str, необязательный) : Размер (например, "4" для 4/4).

max_text_length (int, необязательный, по умолчанию 256) : Максимальная длина токенов для текстовых промптов.

max_lyric_length (int, необязательный, по умолчанию 2048) : Максимальная длина токенов для текста песни.

Возвращает:

Кортеж (text_hidden_states, text_attention_mask, lyric_hidden_states, lyric_attention_mask).

Кодируйте текстовые подсказки и тексты песен в эмбеддинги.

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

prepare_latents[[diffusers.AceStepPipeline.prepare_latents]]

prepare_latents(batch_size: int, audio_duration: float, dtype: dtype, device: device, generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = None, latents: typing.Optional[torch.Tensor] = None)

Источник

Параметры:

batch_size (int) : Количество генерируемых образцов.

audio_duration (float) : Длительность аудио в секундах.

dtype (torch.dtype) : Тип данных для латентов.

device (torch.device) : Устройство для латентов.

generator (torch.Generator или List[torch.Generator], необязательный) : Генератор(ы) случайных чисел.

latents (torch.Tensor, необязательный) : Предварительно сгенерированные латенты.

Возвращает:

Шумовые латенты формы (batch_size, latent_length, acoustic_dim).

Подготовьте начальные шумовые латенты для процесса flow matching.

prepare_reference_audio_latents[[diffusers.AceStepPipeline.prepare_reference_audio_latents]]

prepare_reference_audio_latents(reference_audio: Tensor, batch_size: int, device: device, dtype: dtype)

Источник

Параметры:

reference_audio (torch.Tensor) : Ссылочный аудиотензор формы [channels, samples] с частотой дискретизации self.sample_rate.

batch_size (int) : Размер батча.

device (torch.device) : Целевое устройство.

dtype (torch.dtype) : Целевой dtype.

Возвращает:

Кортеж (refer_audio_acoustic, refer_audio_order_mask).

Обработайте эталонный аудиосигнал в акустические латенты для энкодера тембра.

Справочный аудиосигнал повторяется/обрезается до 30 секунд (3 сегмента по 10 секунд каждый из начала, середины и конца), кодируется через VAE, а затем транспонируется для энкодера тембра.

prepare_src_latents[[diffusers.AceStepPipeline.prepare_src_latents]]

prepare_src_latents(device: device, dtype: dtype, batch_size: int = 1, src_audio: typing.Optional[torch.Tensor] = None, audio_codes: typing.Union[str, typing.List[str], NoneType] = None, latent_length: typing.Optional[int] = None, task_type: str = 'text2music')

Источник

Параметры:

src_audio (torch.Tensor, необязательный) : Исходный аудиотензор формы [channels, samples] с частотой дискретизации self.sample_rate.

audio_codes (str или List[str], необязательный) : Строки семантических кодов аудио.

latent_length (int, optional) : Целевая длина латентного представления, если не заданы исходный аудиосигнал или аудиокоды.

device (torch.device) : Целевое устройство.

dtype (torch.dtype) : Целевой dtype.

batch_size (int) : Размер батча.

task_type (str) : Текущий тип задачи.

Возвращает:

Кортеж (src_latents, latent_length), где src_latents имеет форму [batch, T, D].

Подготовьте исходные латенты для задач генерации музыки по тексту и преобразования аудио в аудио.