Diffusers documentation
ACE-Step 1.5
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_scalevàshiftmặc định là các giá trị được hiển thị ở trên. Đối với các checkpoint turbo,guidance_scale > 1.0sẽ 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_durationkiểm soát độ dài của bản nhạc được tạo ra, tính bằng giây. - Tham số
vocal_languagephải khớp với ngôn ngữ của lời bài hát. pipe.sample_ratevà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_audiovàreference_audiodưới dạng các tensor stereo đã tiền xử lý ởpipe.sample_rate. flashvàflash_hubsử 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ùngflash_varlenhoặcflash_varlen_hubthay thế. Suy luận với một prompt duy nhất dùngpadding="longest"thường là 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
lớp 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 )
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 dạng văn bản.
- 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 embedding 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ớinum_train_timesteps=1vàshift=1.0— pipeline tự tính toán lịch sigma đã dịch chuyển / turbo của nó và truyền quaset_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 mặc định sử dụng 8 bước suy luận.
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__
< 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
Tham số
- prompt (
strhoặcList[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 (
strhoặcList[str], tùy chọn, mặc định là"") — Văn bản lời bài hát cho bản nhạc. 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, tùy 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 (
strhoặcList[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, tùy chọn, 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, tùy chọn, 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, tùy chọn, mặc định là 3.0) — Tham số shift cho lịch trình bước thời gian (1.0, 2.0 hoặc 3.0). - generator (
torch.GeneratorhoặcList[torch.Generator], tùy chọn) — Một generator để đảm bảo quá trình sinh ra là tất đị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 latents thô. - return_dict (
bool, tùy chọn, mặc định làTrue) — Có nên trả về mộtAudioPipelineOutputhay một tuple đơn thuần hay không. - callback (
Callable, tùy chọn) — Một hàm được gọi mỗicallback_stepsbước với(step, timestep, latents). - callback_steps (
int, tùy 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_kwargssẽ bao gồm danh sách tất cả các tensor như được chỉ định bởicallback_on_step_end_tensor_inputs. - callback_on_step_end_tensor_inputs (
List, optional) — Danh sách các tensor đầu vào cho hàmcallback_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_inputscủa lớp pipeline của bạn. - instruction (
str, tùy chọn) — Văn bản chỉ 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êntask_type. - max_text_length (
int, tùy 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, tùy 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, tùy chọn) — 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) — Giọng nhạc (ví dụ:"C major","A minor"). Nếu làNone, mô hình sẽ tự ước lượng. - timesignature (
str, tùy chọn) — Khóa nhịp (ví dụ:"4"cho 4/4,"3"cho 3/4). Nếu làNone, mô hình sẽ ước lượng khóa nhịp. - task_type (
str, tùy chọn, mặc định là"text2music") — Loại tác vụ sinh. 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 track cho tác vụ"complete". - src_audio (
torch.Tensor, optional) — Tensor âm thanh nguồn có shape[channels, samples]ở 48kHz cho các tác vụ audio-to-audio (repaint, lego, cover, extract, complete). Âm thanh được mã hóa qua VAE để tạo ra source latents. - 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 (
strhoặcList[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, tùy chọn) — Thời điểm bắt đầu tính bằng giây cho vùng tô lại (dùng cho các tác vụ"repaint"và"lego"). - repainting_end (
float, tùy chọn) — Thời điểm kết thúc (tính bằng giây) của vùng repaint. Dùng-1hoặcNoneđể kéo dài đến hết. - audio_cover_strength (
float, tùy chọn, mặc định là 1.0) — Độ mạnh của việc trộn audio cover (0.0 đến 1.0). Khi < 1.0, sẽ trộn các đầu ra được điều kiện bởi cover và chỉ điều kiện bởi văn bản. 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, tùy 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, tùy 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 timestep tùy chỉnh. Nếu được cung cấp, sẽ ghi đè lênnum_inference_stepsvàshift. - attention_kwargs (
dict, tùy chọn) — Một từ điển kwargs được truyền đếnAttentionProcessor. Đượ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,
... ).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] )
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
< 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 )
Tham số
- prompt (
strhoặcList[str]) — Chú thích văn bản mô tả bản nhạc. - lyrics (
strhoặcList[str]) — Văn bản lời bài hát. - device (
torch.device) — Thiết bị cho các tensor. - vocal_language (
strhoặcList[str], tùy chọn, mặc định là"en") — Mã ngôn ngữ cho lời bài hát. - audio_duration (
float, tùy 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 chỉ thị 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) — Giọng nhạc (ví dụ:"C major"). - timesignature (
str, tùy chọn) — Khóa nhịp (ví dụ:"4"cho 4/4). - max_text_length (
int, tùy chọn, mặc định là 256) — Độ dài token tối đa cho các prompt văn bản. - max_lyric_length (
int, tùy chọn, mặc định là 2048) — Độ dài token tối đa cho lời bài hát.
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
< source >( batch_size: intaudio_duration: floatdtype: dtypedevice: devicegenerator: typing.Union[torch.Generator, typing.List[torch.Generator], NoneType] = Nonelatents: typing.Optional[torch.Tensor] = None )
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 tiềm ẩn. - device (
torch.device) — Thiết bị cho các biến tiềm ẩn (latents). - generator (
torch.GeneratorhoặcList[torch.Generator], tùy chọn) — Bộ tạo số ngẫu nhiên. - latents (
torch.Tensor, tùy chọn) — Latents đã được tạo trước.
Chuẩn bị các latent nhiễu ban đầu cho quy trình khớp dòng (flow matching).
prepare_reference_audio_latents
< source >( reference_audio: Tensorbatch_size: intdevice: devicedtype: dtype )
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
< 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' )
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 (
strhoặcList[str], tùy chọn) — Chuỗi mã ngữ nghĩa âm thanh. - latent_length (
int, tùy chọn) — Độ dài latent mục tiêu 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) — Kiểu dữ liệu đích. - batch_size (
int) — Kích thước lô. - task_type (
str) — Loại tác vụ hiện tại.
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.