# LongCat-AudioDiT

LongCat-AudioDiT là mô hình khuếch tán từ văn bản sang âm thanh của Meituan LongCat. Tích hợp diffusers cung cấp giao diện [DiffusionPipeline](/docs/diffusers/v0.43.0/vi/api/pipelines/overview#diffusers.DiffusionPipeline) tiêu chuẩn cho việc tạo âm thanh có điều kiện từ văn bản.

Pipeline này được điều chỉnh từ bản triển khai tham chiếu LongCat-AudioDiT: https://github.com/meituan-longcat/LongCat-AudioDiT

Pipeline này hỗ trợ nạp từ một thư mục cục bộ hoặc kho lưu trữ Hugging Face Hub ở định dạng diffusers (chứa các thư mục con `text_encoder/`, `transformer/`, `vae/`, `tokenizer/` và `scheduler/`).

## Cách sử dụng

```py
import soundfile as sf
import torch
from diffusers import LongCatAudioDiTPipeline

pipeline = LongCatAudioDiTPipeline.from_pretrained(
    "ruixiangma/LongCat-AudioDiT-1B-Diffusers",
    dtype=torch.float16,
)
pipeline = pipeline.to("cuda")  # or "mps", "xpu", "cpu"

prompt = "A calm ocean wave ambience with soft wind in the background."
audio = pipeline(
    prompt,
    audio_duration_s=5.0,
    num_inference_steps=16,
    guidance_scale=4.0,
    generator=torch.Generator("cuda").manual_seed(42),
).audios[0, 0]

sf.write("longcat.wav", audio, pipeline.sample_rate)
```

## Mẹo

- `audio_duration_s` là cách trực tiếp nhất để kiểm soát thời lượng đầu ra.
- Sử dụng `generator=torch.Generator("cuda").manual_seed(42)` để đảm bảo quá trình tạo ra có thể tái lập được.
- Hình dạng đầu ra là `(batch, channels, samples)` - sử dụng `.audios[0, 0]` để lấy một mẫu âm thanh đơn lẻ.
- Pipeline xuất ra âm thanh mono (1 kênh). Nếu bạn cần âm thanh stereo, bạn có thể nhân đôi kênh: `audio.unsqueeze(0).repeat(1, 2, 1)`.

## LongCatAudioDiTPipeline[[diffusers.LongCatAudioDiTPipeline]]

#### diffusers.LongCatAudioDiTPipeline[[diffusers.LongCatAudioDiTPipeline]]

```python
diffusers.LongCatAudioDiTPipeline(vae: LongCatAudioDiTVae, text_encoder: UMT5EncoderModel, tokenizer: PreTrainedTokenizerBase, transformer: LongCatAudioDiTTransformer, scheduler: diffusers.schedulers.scheduling_flow_match_euler_discrete.FlowMatchEulerDiscreteScheduler | None = None)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/longcat_audio_dit/pipeline_longcat_audio_dit.py#L99)

#### __call__[[diffusers.LongCatAudioDiTPipeline.__call__]]

```python
__call__(prompt: str | list[str], negative_prompt: str | list[str] | None = None, audio_duration_s: float | None = None, latents: typing.Optional[torch.Tensor] = None, num_inference_steps: int = 16, guidance_scale: float = 4.0, generator: typing.Union[torch.Generator, list[torch.Generator], NoneType] = None, output_type: str = 'np', return_dict: bool = True, callback_on_step_end: typing.Optional[typing.Callable[[int, int], NoneType]] = None, callback_on_step_end_tensor_inputs: list[str] = ['latents'])
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/longcat_audio_dit/pipeline_longcat_audio_dit.py#L219)

**Tham số:**

prompt (`str` hoặc `list[str]`) : Prompt hoặc các prompt hướng dẫn việc tạo âm thanh.

negative_prompt (`str` hoặc `list[str]`, *tùy chọn*) : Prompt âm cho classifier-free guidance.

audio_duration_s (`float`, *optional*) : Độ dài âm thanh đích tính bằng giây. Bỏ qua khi `latents` được cung cấp.

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

num_inference_steps (`int`, mặc định là 16) : Số bước khử nhiễu.

guidance_scale (`float`, mặc định là 4.0) : Thang độ dẫn hướng cho classifier-free guidance.

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

output_type (`str`, mặc định là `"np"`) : Định dạng đầu ra: `"np"`, `"pt"`, hoặc `"latent"`.

return_dict (`bool`, mặc định là `True`) : Có nên trả về `AudioPipelineOutput` hay không.

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, nhận vào pipeline, chỉ số bước, timestep và các tensor đầu vào được chỉ định bởi `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, mặc định là `["latents"]`) : Các đầu vào Tensor được truyền vào `callback_on_step_end`.

**Trả về:** [AudioPipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) hoặc `tuple`

[AudioPipelineOutput](/docs/diffusers/v0.43.0/vi/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) nếu `return_dict` là True, ngược lại là một `tuple`. Khi trả về tuple, phần tử đầu tiên là dạng sóng âm thanh đã tạo.

Hàm được gọi khi gọi pipeline cho việc sinh.

Ví dụ:
```py
>>> import soundfile as sf
>>> import torch
>>> from diffusers import LongCatAudioDiTPipeline

>>> pipe = LongCatAudioDiTPipeline.from_pretrained("ruixiangma/LongCat-AudioDiT-1B-Diffusers")
>>> pipe.to("cuda")

>>> prompt = "A calm ocean wave ambience with soft wind in the background."
>>> audio = pipe(
...     prompt,
...     audio_duration_s=5.0,
...     num_inference_steps=20,
...     guidance_scale=4.0,
...     generator=torch.Generator("cuda").manual_seed(42),
... ).audios[0, 0]
>>> sf.write("output.wav", audio, pipe.sample_rate)
```

#### from_pretrained[[diffusers.LongCatAudioDiTPipeline.from_pretrained]]

```python
from_pretrained(pretrained_model_name_or_path: str | os.PathLike, **kwargs)
```

[Nguồn](https://github.com/huggingface/diffusers/blob/v0.43.0/src/diffusers/pipelines/pipeline_utils.py#L638)

**Tham số:**

pretrained_model_name_or_path (`str` hoặc `os.PathLike`, *tùy chọn*) : Có thể là:  - Một chuỗi, *repo id* (ví dụ `CompVis/ldm-text2im-large-256`) của một pipeline được huấn luyện trước có trên Hub. - Một đường dẫn đến *thư mục* (ví dụ `./my_pipeline_directory/`) chứa các trọng số pipeline đã được lưu bằng [save_pretrained()](/docs/diffusers/v0.43.0/vi/api/pipelines/overview#diffusers.DiffusionPipeline.save_pretrained).

dtype (`torch.dtype` hoặc `dict[str, Union[str, torch.dtype]]`, *tùy chọn*) : Ghi đè `torch.dtype` mặc định và tải mô hình với một dtype khác. Để tải các mô hình con với các dtype khác nhau, hãy truyền một `dict` (ví dụ `{'transformer': torch.bfloat16, 'vae': torch.float16}`). Đặt dtype mặc định cho các thành phần không được chỉ định bằng `default` (ví dụ `{'transformer': torch.bfloat16, 'default': torch.float16}`). Nếu một thành phần không được chỉ định và không có default được đặt, `torch.float32` sẽ được sử dụng.

custom_pipeline (`str`, *optional*) : > [!WARNING] > 🧪 Đây là tính năng thử nghiệm và có thể thay đổi trong tương lai.  Có thể là:  - Một chuỗi, *repo id* (ví dụ `hf-internal-testing/diffusers-dummy-pipeline`) của một pipeline tùy chỉnh được lưu trữ trên Hub. Kho phải chứa một tệp có tên pipeline.py định nghĩa pipeline tùy chỉnh. - Một chuỗi, *tên tệp* của một pipeline cộng đồng được lưu trữ trên GitHub dưới [Community](https://github.com/huggingface/diffusers/tree/main/examples/community). Tên tệp hợp lệ phải khớp với tên tệp chứ không phải script pipeline (`clip_guided_stable_diffusion` thay vì `clip_guided_stable_diffusion.py`). Các pipeline cộng đồng luôn được tải từ nhánh main hiện tại của GitHub. - Đường dẫn đến một thư mục (`./my_pipeline_directory/`) chứa pipeline tùy chỉnh. Thư mục phải chứa một tệp có tên `pipeline.py` định nghĩa pipeline tùy chỉnh.  Để biết thêm thông tin về cách tải và tạo các pipeline tùy chỉnh, hãy xem [Tải và Thêm Pipeline Tùy Chỉnh](https://huggingface.co/docs/diffusers/using-diffusers/custom_pipeline_overview)

force_download (`bool`, *tùy chọn*, mặc định là `False`) : Xác định có nên ép buộc tải lại (re-download) trọng số mô hình và các tệp cấu hình hay không, ghi đè lên các phiên bản đã được lưu trong bộ nhớ đệm nếu chúng tồn tại.

cache_dir (`Union[str, os.PathLike]`, *tùy chọn*) : Đường dẫn đến thư mục nơi cấu hình mô hình được huấn luyện trước đã tải xuống được lưu đệm nếu không sử dụng bộ lưu đệm tiêu chuẩn.

proxies (`Dict[str, str]`, *tùy chọn*) : Một từ điển các máy chủ proxy để sử dụng theo giao thức hoặc điểm cuối, ví dụ, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Các proxy được sử dụng cho mỗi yêu cầu.

output_loading_info(`bool`, *tuỳ chọn*, mặc định là `False`) : Có trả về một từ điển chứa các khóa bị thiếu, các khóa không mong đợi và thông báo lỗi hay không.

local_files_only (`bool`, *tùy chọn*, mặc định là `False`) : Xác định xem có chỉ tải trọng số và tệp cấu hình của mô hình cục bộ hay không. Nếu đặt thành `True`, mô hình sẽ không được tải xuống từ Hub.

token (`str` hoặc *bool*, *tùy chọn*) : Token được sử dụng làm HTTP bearer authorization cho các tệp từ xa. Nếu là `True`, token được tạo từ `diffusers-cli login` (được lưu trong `~/.huggingface`) sẽ được sử dụng.

revision (`str`, *tùy chọn*, mặc định là `"main"`) : Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên thẻ, id commit, hoặc bất kỳ định danh nào được Git cho phép.

custom_revision (`str`, *tuỳ chọn*) : Phiên bản mô hình cụ thể cần sử dụng. Nó có thể là tên nhánh, tên thẻ, hoặc id commit tương tự như `revision` khi tải một pipeline tùy chỉnh từ Hub. Mặc định là phiên bản 🤗 Diffusers ổn định mới nhất.

mirror (`str`, *tùy chọn*) : Nguồn mirror để giải quyết các vấn đề về khả năng truy cập nếu bạn đang tải xuống một model ở Trung Quốc. Chúng tôi không đảm bảo tính kịp thời hay an toàn của nguồn, và bạn nên tham khảo trang mirror để biết thêm thông tin.

device_map (`str`, *tùy chọn*) : Chiến lược quy định cách các thành phần khác nhau của pipeline nên được đặt trên các thiết bị khả dụng. Hiện tại, chỉ hỗ trợ `device_map` "balanced". Xem [đây](https://huggingface.co/docs/diffusers/main/en/tutorials/inference_with_big_models#device-placement) để biết thêm.

max_memory (`Dict`, *tùy chọn*) : Một từ điển định danh thiết bị cho bộ nhớ tối đa. Nếu không được đặt, giá trị mặc định sẽ là bộ nhớ tối đa khả dụng cho mỗi GPU và RAM CPU khả dụng.

offload_folder (`str` hoặc `os.PathLike`, *tùy chọn*) : Đường dẫn để offload trọng số nếu device_map chứa giá trị `"disk"`.

offload_state_dict (`bool`, *tùy chọn*) : Nếu `True`, sẽ tạm thời offload state dict trên CPU xuống ổ cứng để tránh hết RAM CPU nếu trọng số của state dict trên CPU + shard lớn nhất của checkpoint không vừa. Mặc định là `True` khi có offload xuống đĩa.

low_cpu_mem_usage (`bool`, *tuỳ chọn*, mặc định là `True` nếu phiên bản torch >= 1.9.0, ngược lại là `False`) : Tăng tốc quá trình tải mô hình bằng cách chỉ tải các trọng số được huấn luyện trước và không khởi tạo các trọng số. Đồng thời, tham số này cũng cố gắng không sử dụng quá 1 lần kích thước mô hình trong bộ nhớ CPU (bao gồm cả bộ nhớ đỉnh) trong khi tải mô hình. Chỉ hỗ trợ cho PyTorch >= 1.9.0. Nếu bạn đang sử dụng phiên bản PyTorch cũ hơn, việc đặt tham số này thành `True` sẽ gây ra lỗi.

use_safetensors (`bool`, *tuỳ chọn*, mặc định là `None`) : Nếu được đặt thành `None`, các trọng số safetensors sẽ được tải xuống nếu chúng có sẵn **và** nếu thư viện safetensors đã được cài đặt. Nếu được đặt thành `True`, mô hình sẽ được tải bắt buộc từ các trọng số safetensors. Nếu được đặt thành `False`, các trọng số safetensors sẽ không được tải.

use_onnx (`bool`, *tùy chọn*, mặc định là `None`) : Nếu đặt thành `True`, trọng số ONNX sẽ luôn được tải xuống nếu có. Nếu đặt thành `False`, trọng số ONNX sẽ không bao giờ được tải xuống. Mặc định, `use_onnx` có giá trị mặc định là thuộc tính lớp `_is_onnx`, vốn là `False` đối với các pipeline không phải ONNX và `True` đối với các pipeline ONNX. Trọng số ONNX bao gồm cả các tệp kết thúc bằng `.onnx` và `.pb`.

kwargs (đictionary còn lại của các đối số từ khóa, *tùy chọn*) : Có thể được sử dụng để ghi đè lên các biến load và saveable (các thành phần pipeline của lớp pipeline cụ thể). Các thành phần bị ghi đè sẽ được truyền trực tiếp vào phương thức `__init__` của pipeline. Xem ví dụ bên dưới để biết thêm thông tin.

variant (`str`, *tùy chọn*) : Nạp trọng số từ tên tệp biến thể được chỉ định, chẳng hạn như `"fp16"` hoặc `"ema"`.

disable_mmap ('bool', *optional*, mặc định là 'False') : Có vô hiệu hóa mmap khi tải một mô hình Safetensors hay không. Tùy chọn này có thể cho hiệu suất tốt hơn khi mô hình nằm trên ổ đĩa mạng hoặc ổ cứng, những nơi có thể không xử lý tốt tính chất truy cập ngẫu nhiên (seeky) của mmap.

Tạo một pipeline khuếch tán PyTorch từ trọng số pipeline được huấn luyện trước.

Pipeline được đặt ở chế độ đánh giá (`model.eval()`) theo mặc định.

Nếu bạn nhận được thông báo lỗi bên dưới, bạn cần tinh chỉnh trọng số cho tác vụ hạ nguồn của mình:

```
Some weights of UNet2DConditionModel were not initialized from the model checkpoint at stable-diffusion-v1-5/stable-diffusion-v1-5 and are newly initialized because the shapes did not match:
- conv_in.weight: found shape torch.Size([320, 4, 3, 3]) in the checkpoint and torch.Size([320, 9, 3, 3]) in the model instantiated
You should probably TRAIN this model on a down-stream task to be able to use it for predictions and inference.
```

> [!TIP] > Để sử dụng các mô hình riêng tư hoặc [gated](https://huggingface.co/docs/hub/models-gated#gated-models), hãy đăng nhập
với `hf > auth login`.

Ví dụ:

```py
>>> from diffusers import DiffusionPipeline

>>> # Download pipeline from huggingface.co and cache.
>>> pipeline = DiffusionPipeline.from_pretrained("CompVis/ldm-text2im-large-256")

>>> # Download pipeline that requires an authorization token
>>> # For more information on access tokens, please refer to this section
>>> # of the documentation](https://huggingface.co/docs/hub/security-tokens)
>>> pipeline = DiffusionPipeline.from_pretrained("stable-diffusion-v1-5/stable-diffusion-v1-5")

>>> # Use a different scheduler
>>> from diffusers import LMSDiscreteScheduler

>>> scheduler = LMSDiscreteScheduler.from_config(pipeline.scheduler.config)
>>> pipeline.scheduler = scheduler
```