# MusicGen Melody

## Обзор

Модель MusicGen Melody была предложена в работе [Simple and Controllable Music Generation](https://huggingface.co/papers/2306.05284) авторами Jade Copet, Felix Kreuk, Itai Gat, Tal Remez, David Kant, Gabriel Synnaeve, Yossi Adi и Alexandre Défossez.

MusicGen Melody — это одностадийная авто-регрессивная модель Transformer, способная генерировать музыкальные сэмплы высокого качества на основе текстовых описаний или аудиопромптов. Текстовые описания прогоняются через замороженную модель текстового энкодера для получения последовательности скрытых представлений. Затем MusicGen обучается предсказывать дискретные аудиотокены, или *аудиокоды*, в условиях этих скрытых представлений. Эти аудиотокены затем декодируются с помощью модели сжатия аудио, такой как EnCodec, для восстановления аудиоволны.

Благодаря эффективному способу чередования токенов, MusicGen не требует самообучаемого семантического представления текстовых или аудиопромптов, что исключает необходимость каскадного применения нескольких моделей для предсказания набора кодовых книг (например, иерархического или с апсемплингом). Вместо этого он способен генерировать все кодовые книги за один прямой проход.

Аннотация из статьи следующая:

*Мы рассматриваем задачу условной генерации музыки. Мы представляем MusicGen — единую языковую модель (LM), работающую с несколькими потоками сжатого дискретного представления музыки, то есть токенами. В отличие от предыдущих работ, MusicGen состоит из одностадийного трансформерного LM в сочетании с эффективными паттернами чередования токенов, что исключает необходимость каскадирования нескольких моделей, например, иерархического или с апсемплингом. Используя этот подход, мы показываем, как MusicGen может генерировать образцы высокого качества, управляясь текстовым описанием или мелодическими характеристиками, что позволяет лучше контролировать генерируемый результат. Мы провели обширную эмпирическую оценку, включая как автоматические, так и человеческие исследования, показав, что предложенный подход превосходит оценённые базовые модели на стандартном бенчмарке генерации музыки по тексту. С помощью исследований с абляцией мы раскрываем важность каждого из компонентов, составляющих MusicGen.*

Эта модель была предоставлена пользователем [ylacombe](https://huggingface.co/ylacombe). Исходный код можно найти [здесь](https://github.com/facebookresearch/audiocraft). Предобученные контрольные точки доступны на [Hugging Face Hub](https://huggingface.co/models?sort=downloads&search=facebook%2Fmusicgen).

## Отличие от [MusicGen](./musicgen)

Существуют два ключевых отличия от MusicGen:

1. Аудио-промпт используется здесь в качестве условного сигнала для генерируемого аудиосэмпла, тогда как в [MusicGen](./musicgen) он применяется для продолжения аудио.
2. Условные текстовые и аудиосигналы конкатенируются со скрытыми состояниями декодера, а не используются как сигнал кросс-внимания, как в MusicGen.

## Генерация

MusicGen Melody поддерживает два режима генерации: greedy и sampling. На практике режим sampling даёт значительно лучшие результаты, чем greedy, поэтому мы рекомендуем использовать sampling везде, где это возможно. Режим sampling включён по умолчанию, его можно явно указать, установив `do_sample=True` в вызове `MusicgenMelodyForConditionalGeneration.generate()`, либо переопределив конфигурацию генерации модели (см. ниже).

Transformers поддерживает как моно (1-канальные), так и стерео (2-канальные) варианты MusicGen Melody. Моно-версии генерируют один набор кодовых книг. Стерео-версии генерируют 2 набора кодовых книг, по одному для каждого канала (левый/правый), и каждый набор кодовых книг декодируется независимо через модель сжатия аудио. Аудиопотоки для каждого канала объединяются, чтобы получить итоговый стереовыход.

### Условная генерация аудио

Модель может генерировать аудиоприем, используя текстовый и аудиопромпт, при этом входные данные предварительно обрабатываются с помощью [MusicgenMelodyProcessor](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor).

В следующих примерах мы загружаем аудиофайл с помощью библиотеки 🤗 Datasets, которую можно установить через pip с помощью следующей команды:

```bash
pip install --upgrade pip
pip install datasets[audio]
```

Аудиофайл, который мы собираемся использовать, загружается следующим образом:

```python
from datasets import load_dataset

dataset = load_dataset("sanchit-gandhi/gtzan", split="train", streaming=True)
sample = next(iter(dataset))["audio"]
```

Аудиопромпт в идеале должен быть свободен от низкочастотных сигналов, которые обычно генерируются инструментами, такими как барабаны и бас-гитара. Модель [Demucs](https://github.com/adefossez/demucs/tree/main) можно использовать для выделения вокала и других сигналов из компонентов барабанов и баса.

Если вы хотите использовать Demucs, сначала выполните шаги по установке, описанные [здесь](https://github.com/adefossez/demucs/tree/main?tab=readme-ov-file#for-musicians), прежде чем использовать следующий фрагмент кода:

```python
import torch
from demucs import pretrained
from demucs.apply import apply_model
from demucs.audio import convert_audio

wav = torch.tensor(sample["array"]).to(torch.float32)

demucs = pretrained.get_model('htdemucs')

wav = convert_audio(wav[None], sample["sampling_rate"], demucs.samplerate, demucs.audio_channels)
wav = apply_model(demucs, wav[None])
```

Затем вы можете использовать следующий фрагмент кода для генерации музыки:

```python
from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    audio=wav,
    sampling_rate=demucs.samplerate,
    text=["80s blues track with groovy saxophone"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
```

Вы также можете передать аудиосигнал напрямую, не используя Demucs, хотя качество генерации, скорее всего, снизится:

```python
from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    audio=sample["array"],
    sampling_rate=sample["sampling_rate"],
    text=["80s blues track with groovy saxophone"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
```

Аудиовыход представляет собой трёхмерный тензор Torch с формой `(batch_size, num_channels, sequence_length)`. Чтобы прослушать сгенерированные аудиосемплы, вы можете воспроизвести их в ipynb-ноутбуке:

```python
from IPython.display import Audio

sampling_rate = model.config.audio_encoder.sampling_rate
Audio(audio_values[0].numpy(), rate=sampling_rate)
```

Или сохраните их в файл `.wav` с помощью сторонней библиотеки, например `soundfile`:

```python
import soundfile as sf

sampling_rate = model.config.audio_encoder.sampling_rate
sf.write("musicgen_out.wav", audio_values[0].T.numpy(), sampling_rate)
```

### Условная генерация только текста

Тот же [MusicgenMelodyProcessor](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) можно использовать для предварительной обработки текстового промпта.

```python
from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

inputs = processor(
    text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
```

Параметр `guidance_scale` используется в механизме classifier free guidance (CFG) для задания веса между условными логитами (предсказанными на основе текстовых промптов) и безусловными логитами (предсказанными на основе безусловного или «нулевого» промпта). Увеличение значения guidance scale побуждает модель генерировать образцы, более тесно связанные с входным промптом, обычно за счёт ухудшения качества аудио. CFG активируется при установке `guidance_scale > 1`. Для наилучших результатов используйте `guidance_scale=3` (значение по умолчанию).

Вы также можете выполнять генерацию пакетом:

```python

from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration

processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

# take the first quarter of the audio sample
sample_1 = sample["array"][: len(sample["array"]) // 4]

# take the first half of the audio sample
sample_2 = sample["array"][: len(sample["array"]) // 2]

inputs = processor(
    audio=[sample_1, sample_2],
    sampling_rate=sample["sampling_rate"],
    text=["80s blues track with groovy saxophone", "90s rock song with loud guitars and heavy drums"],
    padding=True,
    return_tensors="pt",
)
audio_values = model.generate(**inputs, do_sample=True, guidance_scale=3, max_new_tokens=256)
```

### Безусловная генерация

Входные данные для безусловной (или «нулевой») генерации можно получить с помощью метода [MusicgenMelodyProcessor.get_unconditional_inputs()](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor.get_unconditional_inputs):

```python
from transformers import MusicgenMelodyForConditionalGeneration, MusicgenMelodyProcessor

model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")
unconditional_inputs = MusicgenMelodyProcessor.from_pretrained("facebook/musicgen-melody").get_unconditional_inputs(num_samples=1)

audio_values = model.generate(**unconditional_inputs, do_sample=True, max_new_tokens=256)
```

### Конфигурация генерации

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

```python
from transformers import MusicgenMelodyForConditionalGeneration

model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto")

# inspect the default generation config
model.generation_config

# increase the guidance scale to 4.0
model.generation_config.guidance_scale = 4.0

# decrease the max length to 256 tokens
model.generation_config.max_length = 256
```

Обратите внимание, что любые аргументы, переданные в метод generate, **перекрывают** значения из конфигурации генерации, поэтому установка `do_sample=False` в вызове generate перекроет значение `model.generation_config.do_sample` в конфигурации генерации.

## Структура модели

Модель MusicGen можно разложить на три отдельных этапа:

1. Текстовый энкодер: преобразует текстовые входные данные в последовательность представлений скрытых состояний. Предобученные модели MusicGen используют замороженный текстовый энкодер из T5 или Flan-T5.
2. Декодер MusicGen Melody: языковая модель (LM), которая авто-регрессивно генерирует аудио-токены (или коды) с условием на представления скрытых состояний энкодера
3. Аудио-декодер: используется для восстановления аудиоволны из аудиотокенов, предсказанных декодером.

Таким образом, модель MusicGen может использоваться как автономная модель-декодер, соответствующая классу [MusicgenMelodyForCausalLM](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyForCausalLM), или как составная модель, включающая текстовый и аудиоконкодер, соответствующая классу [MusicgenMelodyForConditionalGeneration](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyForConditionalGeneration). Если необходимо загрузить только декодер из предварительно обученной контрольной точки, это можно сделать, сначала указав правильный конфиг, либо получить доступ к нему через атрибут `.decoder` составной модели:

```python
from transformers import AutoConfig, MusicgenMelodyForCausalLM, MusicgenMelodyForConditionalGeneration

# Option 1: get decoder config and pass to `.from_pretrained`
decoder_config = AutoConfig.from_pretrained("facebook/musicgen-melody").decoder
decoder = MusicgenMelodyForCausalLM.from_pretrained("facebook/musicgen-melody", **decoder_config.to_dict(), device_map="auto")

# Option 2: load the entire composite model, but only return the decoder
decoder = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody", device_map="auto").decoder
```

Поскольку модели текстового и аудиокодировщика заморожены во время обучения, декодер MusicGen [MusicgenMelodyForCausalLM](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyForCausalLM) можно обучать автономно на датасете скрытых состояний кодировщиков и аудиокодов. Для инференса обученный декодер можно объединить с замороженными текстовым и аудиокодировщиками, чтобы восстановить составную модель [MusicgenMelodyForConditionalGeneration](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyForConditionalGeneration).

## Конвертация контрольных точек

- После загрузки исходных контрольных точек с [этой страницы](https://github.com/facebookresearch/audiocraft/blob/main/docs/MUSICGEN.md#importing--exporting-models) вы можете выполнить их конвертацию с помощью **скрипта конвертации**, доступного по пути `src/transformers/models/musicgen_melody/convert_musicgen_melody_transformers.py`, следующей командой:

```bash
python src/transformers/models/musicgen_melody/convert_musicgen_melody_transformers.py \
    --checkpoint="facebook/musicgen-melody" --pytorch_dump_folder /output/path 
```

Советы:

* MusicGen обучен на контрольной точке Encodec с частотой 32 кГц. Убедитесь, что вы используете совместимую версию модели Encodec.
* Режим сэмплирования, как правило, даёт лучшие результаты, чем жадный алгоритм. Переключить сэмплирование можно с помощью переменной `do_sample` в вызове `MusicgenMelodyForConditionalGeneration.generate()`.

## MusicgenMelodyDecoderConfig[[transformers.MusicgenMelodyDecoderConfig]]

#### transformers.MusicgenMelodyDecoderConfig[[transformers.MusicgenMelodyDecoderConfig]]

```python
transformers.MusicgenMelodyDecoderConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 2048, max_position_embeddings: int = 2048, num_hidden_layers: int = 24, ffn_dim: int = 4096, num_attention_heads: int = 16, layerdrop: float | int = 0.0, use_cache: bool = True, activation_function: str = 'gelu', hidden_size: int = 1024, dropout: float | int = 0.1, attention_dropout: float | int = 0.0, activation_dropout: float | int = 0.0, initializer_factor: float = 0.02, scale_embedding: bool = False, num_codebooks: int = 4, audio_channels: int = 1, pad_token_id: int | None = 2048, bos_token_id: int | None = 2048, eos_token_id: int | list[int] | None = None, tie_word_embeddings: bool = False, is_decoder: bool = False, add_cross_attention: bool = False)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/configuration_musicgen_melody.py#L28)

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

vocab_size (`int`, *необязательный*, по умолчанию `2048`) : Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены в `input_ids`.

max_position_embeddings (`int`, *необязательный*, по умолчанию `2048`) : Максимальная длина последовательности, с которой может использоваться данная модель.

num_hidden_layers (`int`, *необязательный*, по умолчанию `24`) : Количество скрытых слоев в декодере Transformer.

ffn_dim (`int`, *необязательный*, по умолчанию `4096`) : Размерность представлений MLP.

num_attention_heads (`int`, *необязательный*, по умолчанию `16`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

layerdrop (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Вероятность LayerDrop. Подробнее см. в [статье о LayerDrop](see https://huggingface.co/papers/1909.11556).

use_cache (`bool`, *необязательный*, по умолчанию `True`) : Следует ли модели возвращать последние значения внимания key/values (не используется во всех моделях). Актуально только при `config.is_decoder=True` или если модель является генеративной моделью только с декодером.

activation_function (`str`, *необязательный*, по умолчанию `gelu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

hidden_size (`int`, *необязательный*, по умолчанию `1024`) : Размерность скрытых представлений.

dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.1`) : Доля для всех слоёв dropout.

attention_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент dropout для вероятностей внимания.

activation_dropout (`Union[float, int]`, *необязательный*, по умолчанию `0.0`) : Коэффициент dropout для активаций внутри полносвязного слоя.

initializer_factor (`float`, *optional*, по умолчанию `0.02`) : Коэффициент для инициализации всех матриц весов (должен оставаться равным 1, используется внутренне для тестирования инициализации).

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

num_codebooks (`int`, *optional*, по умолчанию `4`) : Количество параллельных кодовых книг, используемых моделью.

audio_channels (`int`, *optional*, по умолчанию 1) : Количество аудиоканалов, используемых моделью (моно или стерео). Стерео-модели генерируют отдельный аудиопоток для левого/правого выходных каналов. Моно-модели генерируют один аудиопоток на выходе.

pad_token_id (`int`, *необязательный*, по умолчанию `2048`) : Идентификатор токена, используемый для выравнивания в словаре.

bos_token_id (`int`, *необязательный*, по умолчанию `2048`) : Идентификатор токена, используемый для начала потока в словаре.

eos_token_id (`Union[int, list[int]]`, *необязательный*) : Идентификатор токена, используемый для обозначения конца потока в словаре.

tie_word_embeddings (`bool`, *необязательный*, по умолчанию `False`) : Связывать ли веса эмбеддингов согласно отображению `tied_weights_keys` модели.

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

add_cross_attention (`bool`, *необязательный*, по умолчанию `False`) : Следует ли добавлять слои кросс-внимания в модель.

Это класс конфигурации для хранения настроек модели MusicgenMelodyModel. Он используется для создания модели Musicgen Melody в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [facebook/musicgen-melody](https://huggingface.co/facebook/musicgen-melody)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

## MusicgenMelodyProcessor[[transformers.MusicgenMelodyProcessor]]

#### transformers.MusicgenMelodyProcessor[[transformers.MusicgenMelodyProcessor]]

```python
transformers.MusicgenMelodyProcessor(feature_extractor, tokenizer)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L29)

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

feature_extractor (`MusicgenMelodyFeatureExtractor`) : Извлекатель признаков является обязательным входом.

tokenizer (`T5Tokenizer`) : Токенизатор является обязательным входным параметром.

Создаёт MusicgenMelodyProcessor, который объединяет feature extractor и tokenizer в единый processor.

[MusicgenMelodyProcessor](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) предоставляет все возможности [MusicgenMelodyFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) и [T5Tokenizer](/docs/transformers/v5.23.0/ru/model_doc/t5#transformers.T5Tokenizer). Подробнее см. в [~MusicgenMelodyFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) и [~T5Tokenizer](/docs/transformers/v5.23.0/ru/model_doc/t5#transformers.T5Tokenizer).

#### __call__[[transformers.MusicgenMelodyProcessor.__call__]]

```python
__call__(*args, **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L37)

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

return_tensors (`str` или [TensorType](/docs/transformers/v5.23.0/ru/internal/file_utils#transformers.TensorType), *optional*) : Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:  - `'pt'`: возвращает объекты `torch.Tensor` PyTorch. - `'np'`: возвращает объекты `np.ndarray` NumPy.

#### get_unconditional_inputs[[transformers.MusicgenMelodyProcessor.get_unconditional_inputs]]

```python
get_unconditional_inputs(num_samples = 1, return_tensors = 'pt')
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/processing_musicgen_melody.py#L90)

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

num_samples (int, *необязательный*) : Количество аудиовыборок, которые будут сгенерированы без условий.

Вспомогательная функция для получения нулевых входных данных для безусловной генерации, что позволяет использовать модель без извлечателя признаков или токенизатора.

Пример:
```python
>>> from transformers import MusicgenMelodyForConditionalGeneration, MusicgenMelodyProcessor

>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody")

>>> # get the unconditional (or 'null') inputs for the model
>>> processor = MusicgenMelodyProcessor.from_pretrained("facebook/musicgen-melody")
>>> unconditional_inputs = processor.get_unconditional_inputs(num_samples=1)

>>> audio_samples = model.generate(**unconditional_inputs, max_new_tokens=256)
```

## MusicgenMelodyFeatureExtractor[[transformers.MusicgenMelodyFeatureExtractor]]

#### transformers.MusicgenMelodyFeatureExtractor[[transformers.MusicgenMelodyFeatureExtractor]]

```python
transformers.MusicgenMelodyFeatureExtractor(feature_size = 12, sampling_rate = 32000, hop_length = 4096, chunk_length = 30, n_fft = 16384, num_chroma = 12, padding_value = 0.0, return_attention_mask = False, stem_indices = [3, 2], **kwargs)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/feature_extraction_musicgen_melody.py#L40)

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

feature_size (`int`, *optional*, по умолчанию 12) : Размерность признаков извлекаемых признаков.

sampling_rate (`int`, *optional*, по умолчанию 32000) : Частота дискретизации, с которой аудиофайлы должны быть оцифрованы, выраженная в герцах (Гц).

hop_length (`int`, *optional*, по умолчанию 4096) : Длина перекрывающихся окон для БПФ, используемой для получения коэффициентов Мел-частот.

chunk_length (`int`, *optional*, по умолчанию 30) : Максимальное количество фрагментов по `sampling_rate` выборок, используемых для обрезки и дополнения более длинных или коротких аудиопоследовательностей.

n_fft (`int`, *необязательный*, по умолчанию 16384) : Размер преобразования Фурье.

num_chroma (`int`, *optional*, по умолчанию 12) : Количество используемых хромовых бинов.

padding_value (`float`, *необязательный*, по умолчанию 0.0) : Значение, используемое для дополнения аудио.

return_attention_mask (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли возвращать маску внимания. Может быть переопределено при вызове экстрактора признаков.  [Что такое маски внимания?](../glossary#attention-mask)    Для моделей Whisper `attention_mask` следует всегда передавать при пакетном выводе, чтобы избежать тонких ошибок.

stem_indices (`list[int]`, *необязательный*, по умолчанию `[3, 2]`) : Каналы стебля, которые нужно извлекать, если на вход передаются результаты demucs.

Создаёт экстрактор признаков MusicgenMelody.

Этот экстрактор признаков наследуется от [SequenceFeatureExtractor](/docs/transformers/v5.23.0/ru/main_classes/feature_extractor#transformers.SequenceFeatureExtractor), который содержит большинство основных методов. За дополнительной информацией о них следует обращаться к этому суперклассу.

Этот класс извлекает хроматические признаки из аудио, обработанного с помощью [Demucs](https://github.com/adefossez/demucs/tree/main), или непосредственно из исходной звуковой волны.

## MusicgenMelodyConfig[[transformers.MusicgenMelodyConfig]]

#### transformers.MusicgenMelodyConfig[[transformers.MusicgenMelodyConfig]]

```python
transformers.MusicgenMelodyConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, text_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, audio_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, decoder: dict | transformers.configuration_utils.PreTrainedConfig | None = None, num_chroma: int = 12, chroma_length: int = 235, initializer_factor: float = 0.02)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/configuration_musicgen_melody.py#L86)

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

text_encoder (`Union[dict, `PretrainedConfig`]`) : экземпляр объекта конфигурации, определяющий конфигурацию текстового энкодера.

audio_encoder (`Union[dict, `PretrainedConfig`]`) : экземпляр объекта конфигурации, определяющий конфигурацию аудио-энкодера.

decoder (`Union[dict, `PretrainedConfig`]`) : экземпляр объекта конфигурации, определяющий конфигурацию декодера.

num_chroma (`int`, *optional*, по умолчанию 12) : Количество используемых хромовых бинов.

chroma_length (`int`, *optional*, по умолчанию 235) : Максимальная длительность хрома, если для обусловливания модели используется аудио. Соответствует максимальной длительности, использовавшейся при обучении.

initializer_factor (`float`, *optional*, по умолчанию `0.02`) : Коэффициент для инициализации всех матриц весов (должен оставаться равным 1, используется внутренне для тестирования инициализации).

Это класс конфигурации для хранения настроек модели MusicgenMelodyModel. Он используется для создания модели Musicgen Melody в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [facebook/musicgen-melody](https://huggingface.co/facebook/musicgen-melody)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

Пример:

```python
>>> from transformers import (
...     MusicgenMelodyConfig,
...     MusicgenMelodyDecoderConfig,
...     T5Config,
...     EncodecConfig,
...     MusicgenMelodyForConditionalGeneration,
... )

>>> # Initializing text encoder, audio encoder, and decoder model configurations
>>> text_encoder_config = T5Config()
>>> audio_encoder_config = EncodecConfig()
>>> decoder_config = MusicgenMelodyDecoderConfig()

>>> configuration = MusicgenMelodyConfig(
...     text_encoder=text_encoder_config, audio_encoder=audio_encoder_config, decoder=decoder_config
... )

>>> # Initializing a MusicgenMelodyForConditionalGeneration (with random weights) from the facebook/musicgen-melody style configuration
>>> model = MusicgenMelodyForConditionalGeneration(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
>>> config_text_encoder = model.config.text_encoder
>>> config_audio_encoder = model.config.audio_encoder
>>> config_decoder = model.config.decoder

>>> # Saving the model, including its configuration
>>> model.save_pretrained("musicgen_melody-model")

>>> # loading model and config from pretrained folder
>>> musicgen_melody_config = MusicgenMelodyConfig.from_pretrained("musicgen_melody-model")
>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("musicgen_melody-model", config=musicgen_melody_config)
```

## MusicgenMelodyModel[[transformers.MusicgenMelodyModel]]

#### transformers.MusicgenMelodyModel[[transformers.MusicgenMelodyModel]]

```python
transformers.MusicgenMelodyModel(config: MusicgenMelodyDecoderConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L539)

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

config ([MusicgenMelodyDecoderConfig](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyDecoderConfig)) : класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Musicgen Melody без дополнительных слоёв, выводящая необработанные скрытые состояния.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.MusicgenMelodyModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L552)

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

input_ids (`torch.LongTensor` формы `(batch_size * num_codebooks, sequence_length)`) : Индексы токенов входной последовательности в словаре, соответствующие последовательности аудиокодов. Индексы можно получить, закодировав аудиопромпт с помощью модели аудиоконкодера для предсказания аудиокодов, например, с использованием [EncodecModel](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel). Подробности см. в [EncodecModel.encode()](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel.encode). [Что такое входные идентификаторы?](../glossary#input-ids) `input_ids` будут автоматически преобразованы из формы `(batch_size * num_codebooks, target_sequence_length)` в `(batch_size, num_codebooks, target_sequence_length)` при прямом проходе. Если вы получаете аудиокоды из модели аудиоконкодера, такой как [EncodecModel](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel), убедитесь, что количество кадров равно 1, и что вы изменяете размер аудиокодов с `(frames, batch_size, num_codebooks, target_sequence_length)` до `(batch_size * num_codebooks, target_sequence_length)` перед их передачей в качестве `input_ids`.

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

encoder_hidden_states (`torch.Tensor` формы `(batch_size, encoder_sequence_length, hidden_size)`, *необязательный*) : Последовательность скрытых состояний, представляющая конкатенацию вывода текстового кодировщика и обработанного вывода аудио-кодировщика. Используется как условный сигнал и, следовательно, будет конкатенирована с проецированными `decoder_input_ids`.

encoder_attention_mask (`torch.LongTensor` формы `(batch_size, encoder_sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к условным скрытым состояниям. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

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

**Возвращает:** [BaseModelOutputWithPast](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) или `tuple(torch.Tensor)`

[BaseModelOutputWithPast](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации (`None`) и входных данных.

Метод forward модели [MusicgenMelodyModel](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyModel) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя модели.

  Если используется `past_key_values`, выводится только последнее скрытое состояние последовательностей формы `(batch_size, 1, hidden_size)`.
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и, при необходимости, если `config.is_encoder_decoder=True`, в блоках кросс-внимания), которые можно использовать (см. входной параметр `past_key_values`) для ускорения последовательного декодирования.
- **hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

## MusicgenMelodyForCausalLM[[transformers.MusicgenMelodyForCausalLM]]

#### transformers.MusicgenMelodyForCausalLM[[transformers.MusicgenMelodyForCausalLM]]

```python
transformers.MusicgenMelodyForCausalLM(config: MusicgenMelodyDecoderConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L623)

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

config ([MusicgenMelodyDecoderConfig](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyDecoderConfig)) : класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель декодера Musicgen Melody с головной частью для моделирования языка.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.MusicgenMelodyForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, encoder_attention_mask: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, labels: typing.Optional[torch.LongTensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L651)

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

input_ids (`torch.LongTensor` формы `(batch_size * num_codebooks, sequence_length)`) : Индексы токенов входной последовательности в словаре, соответствующие последовательности аудиокодов. Индексы можно получить, закодировав аудиопромпт с помощью модели аудиоконкодера для предсказания аудиокодов, например, с использованием [EncodecModel](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel). Подробности см. в [EncodecModel.encode()](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel.encode). [Что такое входные идентификаторы?](../glossary#input-ids) `input_ids` будут автоматически преобразованы из формы `(batch_size * num_codebooks, target_sequence_length)` в `(batch_size, num_codebooks, target_sequence_length)` при прямом проходе. Если вы получаете аудиокоды из модели аудиоконкодера, такой как [EncodecModel](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel), убедитесь, что количество кадров равно 1, и что вы изменяете размер аудиокодов с `(frames, batch_size, num_codebooks, target_sequence_length)` до `(batch_size * num_codebooks, target_sequence_length)` перед их передачей в качестве `input_ids`.

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

encoder_hidden_states (`torch.Tensor` формы `(batch_size, encoder_sequence_length, hidden_size)`, *необязательный*) : Последовательность скрытых состояний, представляющая конкатенацию вывода текстового кодировщика и обработанного вывода аудио-кодировщика. Используется как условный сигнал и, следовательно, будет конкатенирована с проецированными `decoder_input_ids`.

encoder_attention_mask (`torch.LongTensor` формы `(batch_size, encoder_sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к условным скрытым состояниям. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

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

labels (`torch.LongTensor` формы `(batch_size, sequence_length, num_codebooks)`, *необязательный*) : Метки для моделирования языка. Обратите внимание, что метки **сдвинуты** внутри модели, то есть можно установить `labels = input_ids` Индексы выбираются из `[-100, 0, ..., config.vocab_size]` Все метки, установленные в `-100`, игнорируются (маскируются), потеря вычисляется только для меток в `[0, ..., config.vocab_size]`

**Возвращает:** `MusicgenMelodyOutputWithPast` или `tuple(torch.Tensor)`

Объект `MusicgenMelodyOutputWithPast` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([MusicgenMelodyConfig](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyConfig)) и входных данных.

Метод forward класса [MusicgenMelodyForCausalLM](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyForCausalLM) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **hidden_states** (`tuple[torch.Tensor]`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **encoder_hidden_states** (`torch.Tensor` формы `(batch_size, encoder_sequence_length, hidden_size)`, *необязательный*) -- Последовательность условных скрытых состояний, представляющая собой конкатенацию проекции вывода текстового энкодера и проекции вывода аудиоэнкодера. Используется как условный сигнал.

Пример:

```python
```

## MusicgenMelodyForConditionalGeneration[[transformers.MusicgenMelodyForConditionalGeneration]]

#### transformers.MusicgenMelodyForConditionalGeneration[[transformers.MusicgenMelodyForConditionalGeneration]]

```python
transformers.MusicgenMelodyForConditionalGeneration(config: MusicgenMelodyConfig = None, text_encoder: transformers.modeling_utils.PreTrainedModel | None = None, audio_encoder: transformers.modeling_utils.PreTrainedModel | None = None, decoder: transformers.models.musicgen_melody.modeling_musicgen_melody.MusicgenMelodyForCausalLM | None = None)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L1091)

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

config ([MusicgenMelodyConfig](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyConfig), *optional*) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

text_encoder (`PreTrainedModel`, *необязательный*) : Модель текстового кодировщика, которая кодирует текст в скрытые состояния для условного формирования.

audio_encoder (`PreTrainedModel`, *необязательный*) : Модель аудио-энкодера, которая кодирует аудио в скрытые состояния для условного формирования.

decoder (`MusicgenMelodyForCausalLM`, *необязательный*) : Модель декодера, которая генерирует аудиотокены на основе сигналов обусловливания.

Модель Musicgen Melody для генерации токенов с условием на другие модальности (например, генерация текста из изображения и текста).

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.MusicgenMelodyForConditionalGeneration.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.BoolTensor] = None, input_features: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, encoder_hidden_states: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, decoder_inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/musicgen_melody/modeling_musicgen_melody.py#L1388)

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

attention_mask (`torch.BoolTensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

input_features (`torch.Tensor` формы `(batch_size, sequence_length, feature_dim)`, *необязательно*) : Тензоры, соответствующие входным аудиособытиям. Аудиособытия можно получить с помощью [MusicgenMelodyFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor). Подробности см. в `MusicgenMelodyFeatureExtractor.__call__()` ([MusicgenMelodyProcessor](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyProcessor) использует [MusicgenMelodyFeatureExtractor](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyFeatureExtractor) для обработки аудио).

decoder_input_ids (`torch.LongTensor` формы `(batch_size * num_codebooks, target_sequence_length)`, *необязательный*) : Индексы токенов входной последовательности декодера в словаре, соответствующие последовательности аудиокодов. Индексы можно получить, закодировав аудиопромпт с помощью модели аудиоконкодера для предсказания аудиокодов, например, с использованием [EncodecModel](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel). Подробности см. в [EncodecModel.encode()](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel.encode). [Что такое входные идентификаторы декодера?](../glossary#decoder-input-ids) `decoder_input_ids` будут автоматически преобразованы из формы `(batch_size * num_codebooks, target_sequence_length)` в `(batch_size, num_codebooks, target_sequence_length)` при прямом проходе. Если вы получаете аудиокоды из модели аудиоконкодера, такой как [EncodecModel](/docs/transformers/v5.23.0/ru/model_doc/encodec#transformers.EncodecModel), убедитесь, что количество кадров равно 1, и что вы изменяете размер аудиокодов с `(frames, batch_size, num_codebooks, target_sequence_length)` до `(batch_size * num_codebooks, target_sequence_length)` перед их передачей в качестве `decoder_input_ids`.

decoder_attention_mask (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Поведение по умолчанию: генерировать тензор, игнорирующий токены заполнения в `decoder_input_ids`. Маска причинности также будет использоваться по умолчанию.

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

encoder_hidden_states (`torch.Tensor` формы `(batch_size, encoder_sequence_length, hidden_size)`, *необязательный*) : Последовательность условных скрытых состояний, представляющая конкатенацию проекции вывода текстового энкодера и проекции вывода аудиоэнкодера. Используется как условный сигнал и, следовательно, будет конкатенирована с проекцией `decoder_input_ids`.

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

decoder_inputs_embeds (`torch.Tensor` формы `(batch_size, target_sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `decoder_input_ids` можно напрямую передать встроенное представление. Если используется `past_key_values`, по желанию на вход нужно передавать только последние `decoder_inputs_embeds` (см. `past_key_values`). Это полезно, если требуется больший контроль над тем, как индексы `decoder_input_ids` преобразуются в соответствующие векторы, чем это делает внутренняя матрица поиска встраиваний модели. Если `decoder_input_ids` и `decoder_inputs_embeds` не заданы, `decoder_inputs_embeds` принимает значение `inputs_embeds`.

labels (`torch.LongTensor` формы `(batch_size, sequence_length, num_codebooks)`, *необязательный*) : Метки для моделирования языка. Обратите внимание, что метки **сдвинуты** внутри модели, то есть можно установить `labels = input_ids` Индексы выбираются из `[-100, 0, ..., config.vocab_size]` Все метки, установленные в `-100`, игнорируются (маскируются), потеря вычисляется только для меток в `[0, ..., config.vocab_size]`

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

**Возвращает:** `MusicgenMelodyOutputWithPast` или `tuple(torch.Tensor)`

Объект `MusicgenMelodyOutputWithPast` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([MusicgenMelodyConfig](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyConfig)) и входных данных.

Метод forward класса [MusicgenMelodyForConditionalGeneration](/docs/transformers/v5.23.0/ru/model_doc/musicgen_melody#transformers.MusicgenMelodyForConditionalGeneration) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache). Подробнее см. в нашем [руководстве по кэшированию kv](https://huggingface.co/docs/transformers/en/kv_cache).

  Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания), которые можно использовать (см. вход `past_key_values`) для ускорения последовательного декодирования.
- **hidden_states** (`tuple[torch.Tensor]`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния модели на выходе каждого слоя, а также необязательные выходные значения начального слоя встраивания.
- **attentions** (`tuple[torch.Tensor]`, *необязательный*, возвращается при передаче `output_attentions=True` или когда `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания после softmax в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **encoder_hidden_states** (`torch.Tensor` формы `(batch_size, encoder_sequence_length, hidden_size)`, *необязательный*) -- Последовательность условных скрытых состояний, представляющая собой конкатенацию проекции вывода текстового энкодера и проекции вывода аудиоэнкодера. Используется как условный сигнал.

Примеры:
```python
>>> from transformers import AutoProcessor, MusicgenMelodyForConditionalGeneration
>>> import torch

>>> processor = AutoProcessor.from_pretrained("facebook/musicgen-melody")
>>> model = MusicgenMelodyForConditionalGeneration.from_pretrained("facebook/musicgen-melody")

>>> inputs = processor(
...     text=["80s pop track with bassy drums and synth", "90s rock song with loud guitars and heavy drums"],
...     padding=True,
...     return_tensors="pt",
... )

>>> pad_token_id = model.generation_config.pad_token_id
>>> decoder_input_ids = (
...     torch.ones((inputs.input_ids.shape[0] * model.decoder.num_codebooks, 1), dtype=torch.long)
...     * pad_token_id
... )

>>> logits = model(**inputs, decoder_input_ids=decoder_input_ids).logits
>>> logits.shape  # (bsz * num_codebooks, encoder_len + tgt_len, vocab_size)
torch.Size([8, 249, 2048])
```

