# LongCat-AudioDiT

LongCat-AudioDiT — это диффузионная модель для генерации аудио по тексту от Meituan LongCat. Интеграция с diffusers предоставляет стандартный интерфейс [DiffusionPipeline](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline) для генерации аудио по текстовому условию.

Этот конвейер адаптирован из эталонной реализации LongCat-AudioDiT: https://github.com/meituan-longcat/LongCat-AudioDiT

Этот конвейер поддерживает загрузку из локального каталога или репозитория Hugging Face Hub в формате diffusers (содержащего подкаталоги `text_encoder/`, `transformer/`, `vae/`, `tokenizer/` и `scheduler/`).

## Использование

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

## Советы

- `audio_duration_s` — самый прямой способ управлять длительностью вывода.
- Используйте `generator=torch.Generator("cuda").manual_seed(42)`, чтобы сделать генерацию воспроизводимой.
- Форма выходных данных — `(batch, channels, samples)` — используйте `.audios[0, 0]`, чтобы получить один аудиосэмпл.
- Пайплайн выводит моноаудио (1 канал). Если вам нужен стерео, вы можете дублировать канал: `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)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/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'])
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/longcat_audio_dit/pipeline_longcat_audio_dit.py#L219)

**Параметры:**

prompt (`str` или `list[str]`) : Промпт или промпты, направляющие генерацию аудио.

negative_prompt (`str` или `list[str]`, *необязательный*) : Отрицательный промпт(ы) для classifier-free guidance.

audio_duration_s (`float`, *необязательный*) : Целевая длительность аудио в секундах. Игнорируется, если предоставлено `latents`.

latents (`torch.Tensor`, *необязательный*) : Предварительно сгенерированные зашумленные латенты формы `(batch_size, duration, latent_dim)`.

num_inference_steps (`int`, по умолчанию 16) : Количество шагов денойзинга.

guidance_scale (`float`, по умолчанию 4.0) : Масштаб направляющего коэффициента для классификаторно-свободного наведения (classifier-free guidance).

generator (`torch.Generator` или `list[torch.Generator]`, *необязательно*) : Генератор(ы) случайных чисел.

output_type (`str`, по умолчанию `"np"`) : Формат вывода: `"np"`, `"pt"` или `"latent"`.

return_dict (`bool`, по умолчанию `True`) : Возвращать ли `AudioPipelineOutput`.

callback_on_step_end (`Callable`, *необязательный*) : функция, вызываемая в конце каждого шага денойзинга с параметрами: пайплайн, индекс шага, timestep и тензорные входные данные, указанные в `callback_on_step_end_tensor_inputs`.

callback_on_step_end_tensor_inputs (`list`, по умолчанию `["latents"]`) : тензорные входные данные, передаваемые в `callback_on_step_end`.

**Возвращает:** [AudioPipelineOutput](/docs/diffusers/main/ru/api/pipelines/audioldm2#diffusers.AudioPipelineOutput) или `tuple`

[AudioPipelineOutput](/docs/diffusers/main/ru/api/pipelines/audioldm2#diffusers.AudioPipelineOutput), если `return_dict` равно True, иначе `tuple`. При возврате кортежа первым элементом является сгенерированная аудиоволна.

Функция, вызываемая при обращении к конвейеру для генерации.

Примеры:
```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)
```

[Источник](https://github.com/huggingface/diffusers/blob/main/src/diffusers/pipelines/pipeline_utils.py#L638)

**Параметры:**

pretrained_model_name_or_path (`str` или `os.PathLike`, *необязательный*) : Может быть одним из:  - строка, *repo id* (например, `CompVis/ldm-text2im-large-256`) предобученного пайплайна, размещенного на Hub. - путь к *каталогу* (например, `./my_pipeline_directory/`), содержащему веса пайплайна, сохраненные с помощью [save_pretrained()](/docs/diffusers/main/ru/api/pipelines/overview#diffusers.DiffusionPipeline.save_pretrained).

dtype (`torch.dtype` или `dict[str, Union[str, torch.dtype]]`, *необязательный*) : Переопределяет стандартный `torch.dtype` и загружает модель с другим dtype. Чтобы загрузить подмодели с разными dtype, передайте `dict` (например, `{'transformer': torch.bfloat16, 'vae': torch.float16}`). Установите стандартный dtype для не указанных компонентов с помощью `default` (например, `{'transformer': torch.bfloat16, 'default': torch.float16}`). Если компонент не указан и стандартный dtype не задан, используется `torch.float32`.

custom_pipeline (`str`, *optional*) : > [!WARNING] > 🧪 Это экспериментальная функция, которая может измениться в будущем.  Может принимать одно из значений:  - Строка, *repo id* (например, `hf-internal-testing/diffusers-dummy-pipeline`) пользовательского пайплайна, размещённого на Hub. Репозиторий должен содержать файл pipeline.py, в котором определяется пользовательский пайплайн. - Строка, *file name* пайплайна сообщества, размещённого на GitHub в разделе [Community](https://github.com/huggingface/diffusers/tree/main/examples/community). Допустимые имена файлов должны соответствовать имени файла, а не имени скрипта пайплайна (`clip_guided_stable_diffusion`, а не `clip_guided_stable_diffusion.py`). Пайплайны сообщества всегда загружаются из текущей ветки main на GitHub. - Путь к каталогу (`./my_pipeline_directory/`), содержащему пользовательский пайплайн. В каталоге должен находиться файл `pipeline.py`, определяющий пользовательский пайплайн.  Подробнее о загрузке и создании пользовательских пайплайнов см. в разделе [Loading and Adding Custom Pipelines](https://huggingface.co/docs/diffusers/using-diffusers/custom_pipeline_overview)

force_download (`bool`, *необязательный*, по умолчанию `False`) : Указывает, следует ли принудительно (пере)скачивать веса модели и файлы конфигурации, заменяя кэшированные версии, если они существуют.

cache_dir (`Union[str, os.PathLike]`, *необязательный*) : Путь к каталогу, в котором кэшируется конфигурация загруженной предобученной модели, если стандартный кэш не используется.

proxies (`Dict[str, str]`, *необязательный*) : Словарь прокси-серверов, используемых по протоколу или конечной точке, например, `{'http': 'foo.bar:3128', 'http://hostname': 'foo.bar:4012'}`. Прокси используются при каждом запросе.

output_loading_info(`bool`, *необязательный*, по умолчанию `False`) : Нужно ли также возвращать словарь, содержащий отсутствующие ключи, неожиданные ключи и сообщения об ошибках.

local_files_only (`bool`, *необязательный*, по умолчанию `False`) : Загружать только локальные веса модели и файлы конфигурации или нет. Если установлено в `True`, модель не будет скачана с Hub.

token (`str` или *bool*, *необязательный*) : Токен, используемый в качестве HTTP bearer-авторизации для удалённых файлов. Если `True`, используется токен, сгенерированный командой `diffusers-cli login` (сохранённый в `~/.huggingface`).

revision (`str`, *необязательный*, по умолчанию `"main"`) : Конкретная версия модели, которую следует использовать. Может быть именем ветки, именем тега, идентификатором коммита или любым другим идентификатором, поддерживаемым Git.

custom_revision (`str`, *optional*) : Конкретная версия модели для использования. Может быть именем ветки, именем тега или идентификатором коммита, аналогично `revision` при загрузке пользовательского пайплайна с Hub. По умолчанию используется последняя стабильная версия 🤗 Diffusers.

mirror (`str`, *необязательный*) : Зеркальный источник для решения проблем с доступностью при загрузке модели в Китае. Мы не гарантируем актуальность или безопасность источника, поэтому за дополнительной информацией обращайтесь на сайт зеркала.

device_map (`str`, *необязательный*) : Стратегия, определяющая, как различные компоненты конвейера должны распределяться по доступным устройствам. В настоящее время поддерживается только «сбалансированная» `device_map`. Подробнее см. [здесь](https://huggingface.co/docs/diffusers/main/en/tutorials/inference_with_big_models#device-placement).

max_memory (`Dict`, *необязательный*) : Словарь идентификаторов устройств для максимальной памяти. Если не задано, по умолчанию используется максимальная доступная память для каждого GPU и доступная оперативная память CPU.

offload_folder (`str` или `os.PathLike`, *необязательный*) : Путь для выгрузки весов, если device_map содержит значение `"disk"`.

offload_state_dict (`bool`, *необязательный*) : Если `True`, состояние CPU state dict временно выгружается на диск, чтобы избежать нехватки оперативной памяти CPU, если вес CPU state dict и крупнейший фрагмент контрольной точки не помещаются в неё. По умолчанию `True`, если используется выгрузка на диск.

low_cpu_mem_usage (`bool`, *необязательный*, по умолчанию `True`, если версия torch >= 1.9.0, иначе `False`) : Ускоряет загрузку модели, загружая только предобученные веса и не инициализируя их. Также это позволяет не использовать больше 1x размера модели в оперативной памяти (включая пиковое потребление) при загрузке модели. Поддерживается только для PyTorch >= 1.9.0. Если вы используете более старую версию PyTorch, установка этого аргумента в `True` вызовет ошибку.

use_safetensors (`bool`, *необязательный*, по умолчанию `None`) : Если установлено в `None`, веса safetensors загружаются, если они доступны **и** если библиотека safetensors установлена. Если установлено в `True`, модель принудительно загружается из весов safetensors. Если установлено в `False`, веса safetensors не загружаются.

use_onnx (`bool`, *необязательный*, по умолчанию `None`) : Если установлено в `True`, веса ONNX всегда будут загружаться, если они присутствуют. Если установлено в `False`, веса ONNX никогда не будут загружаться. По умолчанию `use_onnx` принимает значение атрибута класса `_is_onnx`, которое равно `False` для не-ONNX конвейеров и `True` для ONNX конвейеров. К весам ONNX относятся как файлы, заканчивающиеся на `.onnx`, так и на `.pb`.

kwargs (остаточный словарь аргументов с ключами, *необязательный*) : может использоваться для переопределения переменных загрузки и сохранения (компонентов конвейера конкретного класса конвейера). Переопределённые компоненты передаются непосредственно в метод `__init__` конвейера. См. пример ниже для получения дополнительной информации.

variant (`str`, *необязательный*) : Загружает веса из файла с указанным вариантом имени, например `"fp16"` или `"ema"`.

disable_mmap ('bool', *optional*, по умолчанию 'False') : Отключает ли использование mmap при загрузке модели Safetensors. Этот параметр может обеспечить лучшую производительность, если модель находится на сетевом диске или жёстком диске, которые могут плохо справляться с частыми операциями перемотки, характерными для mmap.

Создайте пайплайн диффузии PyTorch из предобученных весов пайплайна.

По умолчанию пайплайн устанавливается в режим оценки (`model.eval()`).

Если вы получаете сообщение об ошибке, приведённое ниже, вам необходимо дообучить веса для вашей целевой задачи:

```
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] > Для использования частных или [gated](https://huggingface.co/docs/hub/models-gated#gated-models) моделей выполните вход
с помощью `hf > auth login`.

Примеры:

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