# ACE-Step 1.5

ACE-Step 1.5 由 ACE-Step 团队（ACE Studio 和 StepFun）在 [ACE-Step 1.5: Pushing the Boundaries of Open-Source Music Generation](https://arxiv.org/abs/2602.00744) 中发布。它是一个开源音乐基础模型，能够根据文本提示生成带有歌词的商业级立体声音乐。

ACE-Step 1.5 可根据文本提示和可选歌词生成 48 kHz 的可变长度立体声音频（时长从 10 秒到 10 分钟不等）。完整系统将语言模型规划器与扩散 Transformer（DiT）合成器相结合；该流水线封装了该架构中的 DiT 部分，由三个组件构成：一个将波形压缩为 25 Hz 立体声潜变量的 [AutoencoderOobleck](/docs/diffusers/v0.43.0/zh/api/models/autoencoder_oobleck#diffusers.AutoencoderOobleck) VAE、一个基于 Qwen3 的文本编码器用于提示和歌词条件化，以及一个在 VAE 潜空间中利用流匹配进行操作的 [AceStepTransformer1DModel](/docs/diffusers/v0.43.0/zh/api/models/ace_step_transformer#diffusers.AceStepTransformer1DModel) DiT。

该模型支持 50 多种语言的歌词——包括英语、中文、日语、韩语、法语、德语、西班牙语、意大利语、葡萄牙语和俄语——并可在消费级 GPU 上运行（卸载后显存占用低于 4 GB）。

此流水线由 [ACE-Step Team](https://github.com/ace-step) 贡献。原始代码库可在 [ace-step/ACE-Step-1.5](https://github.com/ace-step/ACE-Step-1.5) 中找到。

## 变体

ACE-Step 1.5 提供了三个 DiT 检查点，它们共享相同的 transformer 架构，但在 guidance 行为上有所不同；该 pipeline 会从加载的 transformer 配置中自动检测 turbo 检查点，并针对这些 guidance 蒸馏权重忽略 CFG guidance。

| 变体 | CFG | 默认步骤 | `guidance_scale` 的默认值 | 默认 `shift` | HF 仓库 |
|---------|:---:|:-------------:|:------------------------:|:---------------:|---------|
| `turbo`（guidance-distilled） | off | 8 | 已忽略 | 3.0 | [`ACE-Step/acestep-v15-xl-turbo-diffusers`](https://huggingface.co/ACE-Step/acestep-v15-xl-turbo-diffusers) |
| `base` | on | 8 | 7.0 | 3.0 | [`ACE-Step/acestep-v15-base`](https://huggingface.co/ACE-Step/acestep-v15-base) |
| `sft` | on | 8 | 7.0 | 3.0 | [`ACE-Step/acestep-v15-sft`](https://huggingface.co/ACE-Step/acestep-v15-sft) |

Base 和 SFT 使用学习到的 `null_condition_emb` 进行无分类器引导（APG，而非原生 CFG）。用户通常会将 base/sft 的 `num_inference_steps` 覆盖为 30–60，以获得更高的质量。

## 提示

在构建提示时，请记住：

* 描述性的提示词输入效果最佳；请使用形容词来描述音乐风格、乐器、情绪和节奏。
* 提示词应描述整体的音乐特征（例如，“带有电吉他和鼓的欢快流行歌曲”）。
* 歌词应使用诸如 `[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 Hz 和 25 fps）。
* 对于音频到音频任务，请将 `src_audio` 和 `reference_audio` 作为以 `pipe.sample_rate` 为采样率的预处理立体声张量传入。
* `flash` 和 `flash_hub` 利用 FlashAttention 原生的滑动窗口支持来处理 ACE-Step 的自注意力，并期望输入未填充的文本批次。如果批量提示中包含填充，请改用 `flash_varlen` 或 `flash_varlen_hub`。使用 `padding="longest"` 进行单提示推理时，通常不会包含填充。

```python
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]]

```python
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)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L134)

**参数：**

vae ([AutoencoderOobleck](/docs/diffusers/v0.43.0/zh/api/models/autoencoder_oobleck#diffusers.AutoencoderOobleck))：变分自编码器（VAE）模型，用于将音频波形编码为潜在表示，并从潜在表示解码回音频波形。

text_encoder ([AutoModel](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/auto#transformers.AutoModel))：文本编码器模型（例如 Qwen3-Embedding-0.6B），用于编码文本提示词和歌词。

tokenizer ([AutoTokenizer](https://huggingface.co/docs/transformers/v5.22.2/en/model_doc/auto#transformers.AutoTokenizer))：文本编码器的分词器。

transformer ([AceStepTransformer1DModel](/docs/diffusers/v0.43.0/zh/api/models/ace_step_transformer#diffusers.AceStepTransformer1DModel))：用于对音频潜在变量进行去噪的 Diffusion Transformer (DiT) 模型。

condition_encoder (`AceStepConditionEncoder`)：条件编码器，用于组合文本、歌词和音色嵌入以进行交叉注意力。

scheduler ([FlowMatchEulerDiscreteScheduler](/docs/diffusers/v0.43.0/zh/api/schedulers/flow_match_euler_discrete#diffusers.FlowMatchEulerDiscreteScheduler))：Flow-matching Euler 调度器。ACE-Step 将 DiT 的时间步输入为 `[0, 1]`，因此调度器配置为 `num_train_timesteps=1` 和 `shift=1.0` —— 流水线自行计算其 shifted / turbo sigma 调度，并通过 `set_timesteps(sigmas=...)` 传入。

使用 ACE-Step 1.5 进行文本到音乐生成的 Pipeline。

该模型继承自 [DiffusionPipeline](/docs/diffusers/v0.43.0/zh/api/pipelines/overview#diffusers.DiffusionPipeline)。有关为所有流水线实现的通用方法（下载、保存、在特定设备上运行等），请参阅父类文档。

该流水线使用带有自定义时间步调度的流匹配（flow matching）来执行扩散过程。turbo 模型变体默认使用 8 个推理步骤。

支持的任务类型：
- `"text2music"`：根据文本提示和歌词生成音乐。
- `"cover"`：根据源音频/语义代码生成音频，并从参考音频中迁移音色。
- `"repaint"`：重新生成现有音频的某一部分，同时保留其余部分。
- `"extract"`：从音频中提取特定音轨（例如人声、鼓声）。
- `"lego"`：根据音频上下文生成特定轨道。
- `"complete"`：通过添加额外的音轨来补全输入音频。

#### __调用__[[diffusers.AceStepPipeline.__call__]]

```python
__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)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L785)

**参数：**

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)：去噪步数。Turbo 模型专为 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)：文本提示编码的最大 token 长度。

max_lyric_length (`int`，*可选*，默认值为 2048)：歌词编码的最大 token 长度。

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`, *可选*) : 用于音频到音频任务（repaint、lego、cover、extract、complete）的源音频张量，形状为 `[channels, samples]`，采样率为 48kHz。该音频将通过 VAE 编码以生成源潜在表示。

reference_audio (`torch.Tensor`, *可选*) : 用于音色条件控制的参考音频张量，形状为 `[channels, samples]`，采样率为 48kHz。用于提取音色特征以进行风格迁移。

audio_codes (`str` 或 `List[str]`，*可选*)：音频语义编码字符串（例如 `"<|audio_code_123|><|audio_code_456|>..."`）。提供该参数时，任务会自动切换为 `"cover"` 模式，已注册的 ACE-Step 音频分词器/反分词器模块会将 5 Hz 编码解码为 25 Hz 声学条件。

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)：应用 CFG 的时间步范围起始比例（0.0-1.0）。

cfg_interval_end (`float`, *可选*，默认为 1.0)：应用 CFG 的时间步范围（0.0-1.0）的结束比例。

timesteps (`List[float]`, *可选*) : 自定义时间步调度。如果提供，将覆盖 `num_inference_steps` 和 `shift`。

attention_kwargs (`dict`, *可选*) : 传递给 `AttentionProcessor` 的 kwargs 字典。用于通过 `{"scale": float}` 传递 LoRA 缩放值。

**返回：** [AudioPipelineOutput](/docs/diffusers/v0.43.0/zh/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) 或 `tuple`

如果 `return_dict` 为 `True`，则返回 `AudioPipelineOutput`，否则返回包含生成音频的元组。

用于音乐生成的 pipeline 的调用函数。

示例：
```py
>>> 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]]

```python
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])
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L233)

在开始分配噪声张量之前，验证面向用户的参数。

#### encode_prompt[[diffusers.AceStepPipeline.encode_prompt]]

```python
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)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L402)

**参数：**

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)：文本提示词的最大 token 长度。

max_lyric_length (`int`，*可选*，默认值为 2048)：歌词的最大 token 长度。

**返回值：**

`(text_hidden_states, text_attention_mask, lyric_hidden_states, lyric_attention_mask)` 的元组。

将文本提示和歌词编码为嵌入。

文本提示词通过完整的文本编码器模型进行编码，以生成上下文隐藏状态。歌词仅通过文本编码器的嵌入层（即 token 查找）进行处理，因为条件编码器中的歌词编码器负责处理上下文编码。

#### prepare_latents[[diffusers.AceStepPipeline.prepare_latents]]

```python
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)
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L507)

**参数：**

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)` 的噪声潜变量。

为流匹配过程准备初始噪声潜变量。

#### prepare_reference_audio_latents[[diffusers.AceStepPipeline.prepare_reference_audio_latents]]

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

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L581)

**参数：**

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 秒（从开头、中间和结尾各取 10 秒，共 3 段），然后通过 VAE 进行编码，最后转置以输入音色编码器。

#### prepare_src_latents[[diffusers.AceStepPipeline.prepare_src_latents]]

```python
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')
```

[源代码](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/ace_step/pipeline_ace_step.py#L634)

**参数：**

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`)：当前任务类型。

**返回值：**

`(src_latents, latent_length)` 元组，其中 `src_latents` 的形状为 `[batch, T, D]`。

为文本生成音乐和音频到音频任务准备源潜在变量。