Diffusers documentation
ACE-Step 1.5
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
< source >( vae: AutoencoderOoblecktext_encoder: PreTrainedModeltokenizer: TokenizersBackendtransformer: AceStepTransformer1DModelcondition_encoder: AceStepConditionEncoderscheduler: FlowMatchEulerDiscreteScheduleraudio_tokenizer: typing.Optional[diffusers.pipelines.ace_step.modeling_ace_step.AceStepAudioTokenizer] = Noneaudio_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__
< source >( prompt: typing.Union[str, typing.List[str]] = Nonelyrics: typing.Union[str, typing.List[str]] = ''audio_duration: float = 60.0vocal_language: typing.Union[str, typing.List[str]] = 'en'num_inference_steps: int = 8guidance_scale: float = 7.0shift: float = 3.0generator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = Noneoutput_type: typing.Optional[str] = 'pt'return_dict: bool = Truecallback: typing.Optional[typing.Callable[[int, int, torch.Tensor], NoneType]] = Nonecallback_steps: typing.Optional[int] = 1callback_on_step_end: typing.Optional[typing.Callable[..., dict]] = Nonecallback_on_step_end_tensor_inputs: typing.List[str] = ('latents',)instruction: typing.Optional[str] = Nonemax_text_length: int = 256max_lyric_length: int = 2048bpm: typing.Optional[int] = Nonekeyscale: typing.Optional[str] = Nonetimesignature: typing.Optional[str] = Nonetask_type: str = 'text2music'track_name: typing.Optional[str] = Nonecomplete_track_classes: typing.Optional[typing.List[str]] = Nonesrc_audio: typing.Optional[torch.Tensor] = Nonereference_audio: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Union[str, typing.List[str], NoneType] = Nonerepainting_start: typing.Optional[float] = Nonerepainting_end: typing.Optional[float] = Noneaudio_cover_strength: float = 1.0cfg_interval_start: float = 0.0cfg_interval_end: float = 1.0timesteps: typing.Optional[typing.List[float]] = Noneattention_kwargs: typing.Optional[dict] = None ) → AudioPipelineOutput or tuple
Параметры
- 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, необязательный, по умолчанию 8) — Количество шагов денойзинга. Турбо-модель рассчитана на 8 шагов. - guidance_scale (
float, необязательный, по умолчанию 7.0) — Масштаб руководства для classifier-free guidance. Значение 1.0 отключает CFG. - shift (
float, необязательный, по умолчанию 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, необязательный, по умолчанию 2048) — Максимальная длина токенов для кодирования текста песни. - bpm (
int, необязательный) — 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, необязательный) — Начальное время в секундах для области перерисовки (для задач"repaint"и"lego"). - repainting_end (
float, необязательный) — Время окончания в секундах для области перерисовки. Используйте-1илиNoneдля указания до конца. - audio_cover_strength (
float, необязательный, по умолчанию 1.0) — Сила смешивания аудио-покрытия (от 0.0 до 1.0). При значении < 1.0 выполняется смешивание выходов, обусловленных покрытием, и выходов, обусловленных только текстом. Более низкие значения создают более выраженный эффект переноса стиля. - cfg_interval_start (
float, необязательный, по умолчанию 0.0) — Начальная доля (0.0–1.0) диапазона временных шагов, в которой применяется CFG. - cfg_interval_end (
float, необязательный, по умолчанию 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,
... ).audioscheck_inputs
< source >( prompt: typing.Union[str, typing.List[str]]lyrics: typing.Union[str, typing.List[str]]task_type: strnum_inference_steps: intguidance_scale: floatshift: floataudio_cover_strength: floatcfg_interval_start: floatcfg_interval_end: floatrepainting_start: typing.Optional[float]repainting_end: typing.Optional[float] )
Проверяйте аргументы, предназначенные для пользователя, до начала выделения тензоров шума.
encode_prompt
< source >( prompt: typing.Union[str, typing.List[str]]lyrics: typing.Union[str, typing.List[str]]device: devicevocal_language: typing.Union[str, typing.List[str]] = 'en'audio_duration: float = 60.0instruction: typing.Optional[str] = Nonebpm: typing.Optional[int] = Nonekeyscale: typing.Optional[str] = Nonetimesignature: typing.Optional[str] = Nonemax_text_length: int = 256max_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) — Максимальная длина токенов для текста песни.
Кодируйте текстовые подсказки и тексты песен в эмбеддинги.
Текстовые промпты кодируются с помощью полной модели текстового энкодера для получения контекстных скрытых состояний. Текст песни проходит только через слой эмбеддингов текстового энкодера (поиск токенов), поскольку контекстное кодирование обрабатывается энкодером текста песни в условном энкодере.
prepare_latents
< source >( batch_size: intaudio_duration: floatdtype: dtypedevice: devicegenerator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: 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, необязательный) — Предварительно сгенерированные латенты.
Подготовьте начальные шумовые латенты для процесса flow matching.
prepare_reference_audio_latents
< source >( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )
Обработайте эталонный аудиосигнал в акустические латенты для энкодера тембра.
Справочный аудиосигнал повторяется/обрезается до 30 секунд (3 сегмента по 10 секунд каждый из начала, середины и конца), кодируется через VAE, а затем транспонируется для энкодера тембра.
prepare_src_latents
< source >( device: devicedtype: dtypebatch_size: int = 1src_audio: typing.Optional[torch.Tensor] = Noneaudio_codes: typing.Union[str, typing.List[str], NoneType] = Nonelatent_length: typing.Optional[int] = Nonetask_type: str = 'text2music' )
Параметры
- src_audio (
torch.Tensor, необязательный) — исходный аудиотензор формы[channels, samples]с частотой дискретизацииself.sample_rate. - audio_codes (
strилиList[str], необязательный) — Строки семантических кодов аудио. - latent_length (
int, необязательный) — Целевая длина латентного представления, если не заданы исходный аудиосигнал или аудиокоды. - device (
torch.device) — Целевое устройство. - dtype (
torch.dtype) — Целевой dtype. - batch_size (
int) — Размер батча. - task_type (
str) — Текущий тип задачи.
Подготовьте исходные латенты для задач генерации музыки по тексту и преобразования аудио в аудио.