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

ACE-Step 1.5

ACE-Step 1.5 được giới thiệu trong ACE-Step 1.5: Đẩy mạnh giới hạn của tạo nhạc mã nguồn mở bởi ACE-Step Team (ACE Studio và StepFun). Đây là một mô hình nền tảng âm nhạc mã nguồn mở, có khả năng tạo ra nhạc stereo chất lượng thương mại kèm lời từ các prompt văn bản.

ACE-Step 1.5 tạo ra âm thanh stereo có độ dài thay đổi ở 48 kHz (từ 10 giây đến 10 phút) từ các prompt văn bản và lời bài hát tùy chọn. Hệ thống đầy đủ kết hợp một bộ lập kế hoạch Language Model với bộ tổng hợp Diffusion Transformer (DiT); pipeline này bao bọc phần DiT của stack đó và bao gồm ba thành phần: một VAE AutoencoderOobleck nén waveform thành các latents stereo 25 Hz, một text encoder dựa trên Qwen3 để điều kiện hóa prompt và lời bài hát, và một DiT AceStepTransformer1DModel hoạt động trong không gian latent của VAE bằng cách sử dụng flow matching.

Mô hình hỗ trợ hơn 50 ngôn ngữ cho lời bài hát — bao gồm tiếng Anh, tiếng Trung, tiếng Nhật, tiếng Hàn, tiếng Pháp, tiếng Đức, tiếng Tây Ban Nha, tiếng Ý, tiếng Bồ Đào Nha và tiếng Nga — và chạy trên GPU tiêu dùng (dưới 4 GB VRAM khi offload).

Pipeline này được đóng góp bởi ACE-Step Team. Mã nguồn gốc có thể được tìm thấy tại ace-step/ACE-Step-1.5.

Các biến thể

ACE-Step 1.5 cung cấp ba checkpoint DiT chia sẻ cùng kiến trúc transformer nhưng khác nhau về hành vi guidance; pipeline tự động phát hiện các checkpoint turbo từ cấu hình transformer đã tải và bỏ qua guidance CFG đối với các trọng số guidance-distilled đó.

Biến thể	CFG	Các bước mặc định	Mặc định guidance_scale	Mặc định shift	Kho HF
turbo (guidance-distilled)	off	8	bị bỏ qua	3.0	ACE-Step/acestep-v15-xl-turbo-diffusers
base	on	8	7.0	3.0	ACE-Step/acestep-v15-base
sft	on	8	7.0	3.0	ACE-Step/acestep-v15-sft

Base và SFT sử dụng null_condition_emb đã học cho classifier-free guidance (APG, không phải CFG thông thường). Người dùng thường ghi đè num_inference_steps thành 30–60 trên base/sft để đạt chất lượng cao hơn.

Mẹo

Khi xây dựng một prompt, hãy lưu ý:

• Đầu vào prompt mô tả chi tiết sẽ hoạt động tốt nhất; hãy sử dụng các tính từ để mô tả phong cách âm nhạc, nhạc cụ, tâm trạng và nhịp độ.
• Prompt nên mô tả các đặc điểm âm nhạc tổng thể (ví dụ: "bài hát pop sôi động với guitar điện và trống").
• Lời bài hát nên được cấu trúc với các thẻ như [verse], [chorus], [bridge], v.v.

Trong quá trình suy luận:

• num_inference_steps, guidance_scale và shift mặc định là các giá trị được hiển thị ở trên. Đối với các checkpoint turbo, guidance_scale > 1.0 sẽ bị bỏ qua kèm theo cảnh báo vì guidance đã được chưng cất vào trọng số.
• Tham số audio_duration kiểm soát độ dài của bản nhạc được tạo ra, tính bằng giây.
• Tham số vocal_language phải khớp với ngôn ngữ của lời bài hát.
• pipe.sample_rate và pipe.latents_per_second được lấy từ cấu hình VAE (48000 Hz và 25 fps đối với các checkpoint đã phát hành).
• Đối với các tác vụ audio-to-audio, hãy truyền src_audio và reference_audio dưới dạng các tensor stereo đã tiền xử lý ở pipe.sample_rate.
• flash và flash_hub sử dụng hỗ trợ cửa sổ trượt (sliding-window) bản địa của FlashAttention cho self-attention của ACE-Step và kỳ vọng các lô văn bản (text batches) không có padding. Nếu một lô prompt chứa padding, hãy dùng flash_varlen hoặc flash_varlen_hub thay thế. Suy luận với một prompt duy nhất dùng padding="longest" thường không có 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)

Nguồn

Tham số:

vae (AutoencoderOobleck) : Mô hình Variational Auto-Encoder (VAE) để mã hóa và giải mã các dạng sóng âm thanh sang và từ các biểu diễn ẩn.

text_encoder (AutoModel) : Mô hình mã hóa văn bản (ví dụ: Qwen3-Embedding-0.6B) để mã hóa các prompt và lời bài hát.

tokenizer (AutoTokenizer) : Tokenizer cho text encoder.

transformer (AceStepTransformer1DModel) : Mô hình Diffusion Transformer (DiT) để khử nhiễu các ẩn âm thanh.

condition_encoder (AceStepConditionEncoder) : Bộ mã hóa điều kiện kết hợp các vector nhúng văn bản, lời bài hát và âm sắc cho cross-attention.

scheduler (FlowMatchEulerDiscreteScheduler) : Trình lập lịch Euler cho flow-matching. ACE-Step cung cấp các bước thời gian của DiT trong [0, 1], do đó trình lập lịch được cấu hình với num_train_timesteps=1 và shift=1.0 — pipeline tự tính toán lịch sigma đã dịch chuyển / turbo của nó và truyền qua set_timesteps(sigmas=...).

Pipeline để tạo nhạc từ văn bản sử dụng ACE-Step 1.5.

Mô hình này kế thừa từ DiffusionPipeline. Xem tài liệu của lớp cha để biết các phương thức chung được triển khai cho tất cả các pipeline (tải xuống, lưu, chạy trên một thiết bị cụ thể, v.v.).

Pipeline sử dụng flow matching với lịch trình timestep tùy chỉnh cho quá trình khuếch tán. Biến thể mô hình turbo sử dụng 8 bước suy luận theo mặc định.

Các loại tác vụ được hỗ trợ:

• "text2music": Tạo nhạc từ các câu lệnh văn bản và lời bài hát.
• "cover": Tạo âm thanh từ âm thanh nguồn / mã ngữ nghĩa với chuyển đổi âm sắc từ âm thanh tham chiếu.
• "repaint": Tạo lại một phần của âm thanh hiện có trong khi giữ nguyên phần còn lại.
• "extract": Trích xuất một track cụ thể (ví dụ: giọng hát, trống) từ âm thanh.
• "lego": Tạo một track cụ thể dựa trên ngữ cảnh âm thanh.
• "complete": Hoàn thiện một âm thanh đầu vào bằng các bản nhạc bổ sung.

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)

Nguồn

Tham số:

prompt (str hoặc List[str], tùy chọn) : Prompt hoặc các prompt để định hướng việc tạo nhạc. Mô tả phong cách, thể loại, nhạc cụ, v.v.

lyrics (str hoặc List[str], tùy chọn, mặc định là "") : Văn bản lời bài hát. Hỗ trợ lời bài hát có cấu trúc với các thẻ như [verse], [chorus], v.v.

audio_duration (float, tuỳ chọn, mặc định là 60.0) : Thời lượng của âm thanh được tạo ra, tính bằng giây.

vocal_language (str hoặc List[str], tùy chọn, mặc định là "en") : Mã ngôn ngữ cho lời bài hát (ví dụ: "en", "zh", "ja").

num_inference_steps (int, optional, mặc định là 8) : Số bước khử nhiễu. Mô hình turbo được thiết kế cho 8 bước.

guidance_scale (float, optional, mặc định là 7.0) : Thang độ dẫn hướng cho classifier-free guidance. Giá trị 1.0 sẽ tắt CFG.

shift (float, optional, mặc định là 3.0) : Tham số dịch chuyển cho lịch trình bước thời gian (1.0, 2.0, hoặc 3.0).

generator (torch.Generator hoặc List[torch.Generator], tùy chọn) : Bộ tạo để làm cho quá trình sinh ra kết quả xác định.

latents (torch.Tensor, tùy chọn) : Các latents nhiễu được tạo trước có hình dạng (batch_size, latent_length, acoustic_dim).

output_type (str, tùy chọn, mặc định là "pt") : Định dạng đầu ra. "pt" cho tensor PyTorch, "np" cho mảng NumPy, "latent" cho latent thô.

return_dict (bool, tùy chọn, mặc định là True) : Xác định việc trả về một AudioPipelineOutput hay một tuple đơn thuần.

callback (Callable, tùy chọn) : Một hàm được gọi mỗi callback_steps bước với (step, timestep, latents).

callback_steps (int, tuỳ chọn, mặc định là 1) : Tần suất của hàm callback.

callback_on_step_end (Callable, tùy chọn) : Một hàm được gọi vào cuối mỗi bước khử nhiễu trong quá trình suy luận. Hàm này được gọi với các đối số sau: callback_on_step_end(self: DiffusionPipeline, step: int, timestep: int, callback_kwargs: Dict). callback_kwargs sẽ bao gồm một danh sách tất cả các tensor như được chỉ định bởi callback_on_step_end_tensor_inputs.

callback_on_step_end_tensor_inputs (List, tùy chọn) : Danh sách các đầu vào tensor cho hàm callback_on_step_end. Các tensor được chỉ định trong danh sách sẽ được truyền dưới dạng tham số callback_kwargs. Bạn chỉ có thể bao gồm các biến được liệt kê trong thuộc tính ._callback_tensor_inputs của lớp pipeline của bạn.

instruction (str, tùy chọn) : Văn bản hướng dẫn tùy chỉnh cho tác vụ tạo. Nếu không được cung cấp, nó sẽ được tự động tạo dựa trên task_type.

max_text_length (int, tuỳ chọn, mặc định là 256) : Độ dài token tối đa cho việc mã hóa prompt văn bản.

max_lyric_length (int, tuỳ chọn, mặc định là 2048) : Độ dài token tối đa cho việc mã hóa lời bài hát.

bpm (int, optional) : BPM (số nhịp mỗi phút) cho metadata âm nhạc. Nếu là None, mô hình sẽ ước lượng giá trị này.

keyscale (str, tùy chọn) : Khó nhạc (ví dụ: "C major", "A minor"). Nếu là None, mô hình sẽ ước lượng.

timesignature (str, tùy chọn) : Khung nhịp (ví dụ, "4" cho 4/4, "3" cho 3/4). Nếu là None, mô hình sẽ ước lượng.

task_type (str, tùy chọn, mặc định là "text2music") : Kiểu tác vụ tạo. Một trong số "text2music", "cover", "repaint", "extract", "lego", "complete".

track_name (str, tùy chọn) : Tên track cho các tác vụ "extract" hoặc "lego" (ví dụ: "vocals", "drums").

complete_track_classes (List[str], tùy chọn) : Các lớp theo dõi cho tác vụ "complete".

src_audio (torch.Tensor, tùy chọn) : Tensor âm thanh nguồn có hình dạng [channels, samples] ở 48kHz cho các tác vụ audio-to-audio (repaint, lego, cover, extract, complete). Âm thanh được mã hóa thông qua VAE để tạo ra các latents nguồn.

reference_audio (torch.Tensor, tùy chọn) : Tensor âm thanh tham chiếu có hình dạng [channels, samples] ở 48kHz để điều kiện hóa âm sắc. Được sử dụng để trích xuất các đặc trưng âm sắc cho việc chuyển đổi phong cách.

audio_codes (str hoặc List[str], tùy chọn) : Chuỗi mã ngữ nghĩa âm thanh (ví dụ "<|audio_code_123|><|audio_code_456|>..."). Khi được cung cấp, tác vụ sẽ tự động chuyển sang chế độ "cover" và các module tokenizer / detokenizer âm thanh ACE-Step đã đăng ký sẽ giải mã các mã 5 Hz thành điều kiện âm học 25 Hz.

repainting_start (float, optional) : Thời gian bắt đầu tính bằng giây cho vùng tô lại (dành cho các tác vụ "repaint" và "lego").

repainting_end (float, optional) : Thời gian kết thúc tính bằng giây cho vùng tô lại. Sử dụng -1 hoặc None cho đến khi kết thúc.

audio_cover_strength (float, optional, mặc định là 1.0) : Độ mạnh của việc trộn phủ âm thanh (0.0 đến 1.0). Khi < 1.0, trộn các đầu ra được điều kiện bởi phủ và chỉ điều kiện bởi văn bản. Các giá trị thấp hơn tạo ra hiệu ứng chuyển đổi phong cách nhiều hơn.

cfg_interval_start (float, tuỳ chọn, mặc định là 0.0) : Tỷ lệ bắt đầu (0.0-1.0) của khoảng bước thời gian mà CFG được áp dụng.

cfg_interval_end (float, tuỳ chọn, mặc định là 1.0) : Tỉ lệ kết thúc (0.0-1.0) của khoảng bước thời gian mà CFG được áp dụng.

timesteps (List[float], tùy chọn) : Lịch trình bước thời gian tùy chỉnh. Nếu được cung cấp, sẽ ghi đè num_inference_steps và shift.

attention_kwargs (dict, tùy chọn) : Một từ điển kwargs được truyền đến AttentionProcessor. Được dùng để truyền thang đo LoRA thông qua {"scale": float}.

Trả về: AudioPipelineOutput hoặc tuple

Nếu return_dict là True, một AudioPipelineOutput sẽ được trả về, ngược lại một tuple chứa âm thanh được tạo sẽ được trả về.

Hàm gọi call của pipeline để tạo nhạc.

Ví dụ:

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

Nguồn

Xác thực các đối số hướng tới người dùng trước khi bắt đầu phân bổ các tensor nhiễu.

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)

Nguồn

Tham số:

prompt (str hoặc List[str]) : Câu mô tả (caption) văn bản mô tả bản nhạc.

lyrics (str hoặc List[str]) : Văn bản lời bài hát.

device (torch.device) : Thiết bị cho các tensor.

vocal_language (str hoặc List[str], tùy chọn, mặc định là "en") : Mã ngôn ngữ cho lời bài hát.

audio_duration (float, tuỳ chọn, mặc định là 60.0) : Thời lượng của âm thanh tính bằng giây.

instruction (str, tùy chọn) : Văn bản hướng dẫn cho quá trình tạo.

bpm (int, tùy chọn) : BPM (số nhịp mỗi phút) cho metadata.

keyscale (str, tùy chọn) : Khóe nhạc (ví dụ: "C major").

timesignature (str, tùy chọn) : Khung nhịp (ví dụ: "4" cho 4/4).

max_text_length (int, tuỳ chọn, mặc định là 256) : Độ dài tối đa của token cho các prompt văn bản.

max_lyric_length (int, tuỳ chọn, mặc định là 2048) : Độ dài tối đa của token cho lời bài hát.

Trả về:

Bộ ba (text_hidden_states, text_attention_mask, lyric_hidden_states, lyric_attention_mask).

Mã hóa các prompt văn bản và lời bài hát thành các embedding.

Các prompt văn bản được mã hóa thông qua mô hình text encoder đầy đủ để tạo ra các hidden states mang ngữ cảnh. Lời bài hát chỉ được đưa qua lớp embedding của text encoder (token lookup), vì lyric encoder trong condition encoder sẽ xử lý việc mã hóa ngữ cảnh.

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)

Nguồn

Tham số:

batch_size (int) : Số lượng mẫu cần tạo.

audio_duration (float) : Thời lượng của âm thanh tính bằng giây.

dtype (torch.dtype) : Kiểu dữ liệu cho các biến ẩn (latents).

device (torch.device) : Thiết bị cho các biến ẩn.

generator (torch.Generator hoặc List[torch.Generator], tùy chọn) : Bộ tạo số ngẫu nhiên.

latents (torch.Tensor, tùy chọn) : Các latents đã được tạo trước.

Trả về:

Noise latents có hình dạng (batch_size, latent_length, acoustic_dim).

Chuẩn bị các latent nhiễu ban đầu cho quy trình khớp dòng (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)

Nguồn

Tham số:

reference_audio (torch.Tensor) : Tensor âm thanh tham chiếu có hình dạng [channels, samples] ở self.sample_rate.

batch_size (int) : Kích thước lô.

device (torch.device) : Thiết bị đích.

dtype (torch.dtype) : dtype đích.

Trả về:

Bộ ba (refer_audio_acoustic, refer_audio_order_mask).

Xử lý âm thanh tham chiếu thành các ẩn âm học cho bộ mã hóa âm sắc.

Âm thanh tham chiếu được lặp lại/cắt xén thành 30 giây (3 đoạn, mỗi đoạn 10 giây, lấy từ phần đầu, giữa và cuối), được mã hóa qua VAE, sau đó được chuyển vị cho bộ mã hóa âm sắc.

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

Nguồn

Tham số:

src_audio (torch.Tensor, tùy chọn) : Tensor âm thanh nguồn có hình dạng [channels, samples] ở self.sample_rate.

audio_codes (str hoặc List[str], tùy chọn) : Chuỗi mã ngữ nghĩa âm thanh.

latent_length (int, tuỳ chọn) : Độ dài tiềm năng đích khi không có âm thanh nguồn hoặc mã âm thanh nào được cung cấp.

device (torch.device) : Thiết bị đích.

dtype (torch.dtype) : dtype đích.

batch_size (int) : Kích thước lô.

task_type (str) : Kiểu tác vụ hiện tại.

Trả về:

Bộ ba (src_latents, latent_length) trong đó src_latents có hình dạng [batch, T, D].

Chuẩn bị các nguồn latents cho các tác vụ từ văn bản sang âm nhạc và từ âm thanh sang âm thanh.