Transformers documentation
MusicGen
Эта модель была опубликована в HF papers 08.06.2023 и добавлена в Hugging Face Transformers 29.06.2023.
MusicGen
Обзор
Модель MusicGen была предложена в статье Simple and Controllable Music Generation авторами Jade Copet, Felix Kreuk, Itai Gat, Tal Remez, David Kant, Gabriel Synnaeve, Yossi Adi и Alexandre Défossez.
MusicGen — это одностадийная авто-регрессивная модель Transformer, способная генерировать музыкальные сэмплы высокого качества на основе текстовых описаний или аудиопромптов. Текстовые описания прогоняются через замороженную модель текстового кодировщика, чтобы получить последовательность скрытых представлений. Затем MusicGen обучается предсказывать дискретные аудиотокены, или аудиокоды, в условиях этих скрытых представлений. Эти аудиотокены затем декодируются с помощью модели сжатия аудио, такой как EnCodec, для восстановления аудиоволны.
Благодаря эффективному способу чередования токенов MusicGen не требует самообучаемого семантического представления текстовых/аудио-промптов, что исключает необходимость каскадного применения нескольких моделей для предсказания набора кодовых книг (например, иерархического или с апсемплингом). Вместо этого он способен генерировать все кодовые книги за один прямой проход.
Аннотация из статьи следующая:
Мы рассматриваем задачу условной генерации музыки. Мы представляем MusicGen — единую языковую модель (LM), работающую с несколькими потоками сжатого дискретного представления музыки, то есть токенами. В отличие от предыдущих работ, MusicGen состоит из одностадийного трансформерного LM в сочетании с эффективными паттернами чередования токенов, что исключает необходимость каскадирования нескольких моделей, например, иерархического или с апсемплингом. Используя этот подход, мы показываем, как MusicGen может генерировать образцы высокого качества, управляясь текстовым описанием или мелодическими признаками, что позволяет лучше контролировать генерируемый вывод. Мы проводим обширную эмпирическую оценку, включая как автоматические, так и человеческие исследования, демонстрируя, что предложенный подход превосходит оцененные базовые модели на стандартном бенчмарке генерации музыки по тексту. С помощью абляционных исследований мы раскрываем важность каждого из компонентов, составляющих MusicGen.
Эта модель была предоставлена sanchit-gandhi. Исходный код можно найти здесь. Предобученные контрольные точки доступны на Hugging Face Hub.
Советы по использованию
- После загрузки исходных контрольных точек с этой страницы вы можете конвертировать их с помощью скрипта конвертации, доступного по адресу
src/transformers/models/musicgen/convert_musicgen_transformers.py, следующей командой:
python src/transformers/models/musicgen/convert_musicgen_transformers.py \
--checkpoint small --pytorch_dump_folder /output/pathГенерация
MusicGen поддерживает два режима генерации: жадный (greedy) и сэмплирование (sampling). На практике сэмплирование даёт значительно лучшие результаты, чем жадный режим, поэтому мы рекомендуем использовать сэмплирование, где это возможно. Сэмплирование включено по умолчанию, его можно явно указать, установив do_sample=True в вызове MusicgenForConditionalGeneration.generate(), либо переопределив конфигурацию генерации модели (см. ниже).
Генерация ограничена синусоидальными позиционными эмбеддингами до 30-секундных входных данных. Это означает, что MusicGen не может генерировать более 30 секунд аудио (1503 токена), а входное аудио, передаваемое через Audio-Prompted Generation, учитывается в этом лимите: например, при входе в 20 секунд аудио MusicGen не сможет сгенерировать более 10 секунд дополнительного аудио.
Transformers поддерживает как моно (1-канальные), так и стерео (2-канальные) варианты MusicGen. Моно-версии генерируют один набор кодовых книг. Стерео-версии генерируют 2 набора кодовых книг, по одному для каждого канала (левый/правый), и каждый набор кодовых книг декодируется независимо через модель сжатия аудио. Аудиопотоки для каждого канала объединяются для получения итогового стереовыхода.
Безусловная генерация
Входные данные для безусловной (или «нулевой») генерации можно получить с помощью метода MusicgenForConditionalGeneration.get_unconditional_inputs():
from transformers import MusicgenForConditionalGeneration
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", device_map="auto")
unconditional_inputs = model.get_unconditional_inputs(num_samples=1)
audio_values = model.generate(**unconditional_inputs, do_sample=True, max_new_tokens=256)Аудиовыход представляет собой трёхмерный тензор Torch с формой (batch_size, num_channels, sequence_length). Чтобы прослушать сгенерированные аудиоприборы, вы можете воспроизвести их в ipynb-ноутбуке:
from IPython.display import Audio
sampling_rate = model.config.audio_encoder.sampling_rate
Audio(audio_values[0].numpy(), rate=sampling_rate)Или сохраните их в файл .wav с помощью сторонней библиотеки, например scipy:
import scipy
sampling_rate = model.config.audio_encoder.sampling_rate
scipy.io.wavfile.write("musicgen_out.wav", rate=sampling_rate, data=audio_values[0, 0].numpy())Генерация с текстовым условием
Модель может генерировать аудиоприложение, обусловленное текстовым запросом, с использованием MusicgenProcessor для предварительной обработки входных данных:
from transformers import AutoProcessor, MusicgenForConditionalGeneration
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", 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 (значение по умолчанию).
Генерация по аудио-промпту
Тот же MusicgenProcessor можно использовать для предобработки аудио-промпта, применяемого для продолжения аудио. В следующем примере мы загружаем аудиофайл с помощью библиотеки 🤗 Datasets, которую можно установить через pip с помощью команды ниже:
pip install --upgrade pip pip install datasets[audio]
from datasets import load_dataset
from transformers import AutoProcessor, MusicgenForConditionalGeneration
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", device_map="auto")
dataset = load_dataset("sanchit-gandhi/gtzan", split="train", streaming=True)
sample = next(iter(dataset))["audio"]
# take the first half of the audio sample
sample["array"] = sample["array"][: len(sample["array"]) // 2]
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)Для пакетной генерации по аудио-промпту сгенерированные audio_values можно постобработать, чтобы удалить заполнители, используя класс MusicgenProcessor:
from datasets import load_dataset
from transformers import AutoProcessor, MusicgenForConditionalGeneration
processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", device_map="auto")
dataset = load_dataset("sanchit-gandhi/gtzan", split="train", streaming=True)
sample = next(iter(dataset))["audio"]
# 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)
# post-process to remove padding from the batched audio
audio_values = processor.batch_decode(audio_values, padding_mask=inputs.padding_mask)Конфигурация генерации
Параметры по умолчанию, управляющие процессом генерации, такие как выборка, масштаб направляющего сигнала и количество генерируемых токенов, можно найти в конфигурации генерации модели и изменить по необходимости:
from transformers import MusicgenForConditionalGeneration
model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", 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 можно разложить на три отдельных этапа:
- Текстовый энкодер: преобразует текстовые входные данные в последовательность представлений скрытых состояний. Предобученные модели MusicGen используют замороженный текстовый энкодер из T5 или Flan-T5
- Декодер MusicGen: языковая модель (LM), которая авто-регрессивно генерирует аудио-токены (или коды) с условием на представления скрытых состояний энкодера
- Аудио-энкодер/декодер: используется для кодирования аудиопромпта в токены промпта и восстановления аудиоволны из аудиотокенов, предсказанных декодером
Таким образом, модель MusicGen может использоваться как автономная модель-декодер, соответствующая классу MusicgenForCausalLM,
или как составная модель, включающая текстовый энкодер и аудиоэнкодер/декодер, соответствующая классу MusicgenForConditionalGeneration. Если необходимо загрузить только декодер из предварительно обученной контрольной точки, это можно сделать, сначала
указав правильный конфиг, либо получить доступ к нему через атрибут .decoder составной модели:
from transformers import AutoConfig, MusicgenForCausalLM, MusicgenForConditionalGeneration
# Option 1: get decoder config and pass to `.from_pretrained`
decoder_config = AutoConfig.from_pretrained("facebook/musicgen-small").decoder
decoder = MusicgenForCausalLM.from_pretrained("facebook/musicgen-small", **decoder_config, device_map="auto")
# Option 2: load the entire composite model, but only return the decoder
decoder = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small", device_map="auto").decoderПоскольку модели текстового кодировщика и аудио-кодировщика/декодировщика заморожены во время обучения, декодер MusicGen MusicgenForCausalLM может обучаться автономно на датасете скрытых состояний кодировщика и аудио-кодов. Для инференса обученный декодер можно объединить с замороженными текстовым кодировщиком и аудио-кодировщиком/декодировщиком, чтобы восстановить составную модель MusicgenForConditionalGeneration.
Советы:
- MusicGen обучен на контрольной точке Encodec с частотой 32 кГц. Убедитесь, что вы используете совместимую версию модели Encodec.
- Режим сэмплирования, как правило, даёт лучшие результаты, чем жадный. Переключить сэмплирование можно с помощью переменной
do_sampleв вызовеMusicgenForConditionalGeneration.generate().
MusicgenDecoderConfig
класс transformers.MusicgenDecoderConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonevocab_size: int = 2048max_position_embeddings: int = 2048num_hidden_layers: int = 24ffn_dim: int = 4096num_attention_heads: int = 16layerdrop: float | int = 0.0use_cache: bool = Trueactivation_function: str = 'gelu'hidden_size: int = 1024dropout: float | int = 0.1attention_dropout: float | int = 0.0activation_dropout: float | int = 0.0initializer_factor: float = 0.02scale_embedding: bool = Falsenum_codebooks: int = 4audio_channels: int = 1pad_token_id: int | None = 2048bos_token_id: int | None = 2048eos_token_id: int | list[int] | None = Nonetie_word_embeddings: bool = Falseis_decoder: bool = Falseadd_cross_attention: bool = Falsecross_attention_hidden_size: int | None = None )
Параметры
- 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](см. https://huggingface.co/papers/1909.11556) для подробностей. - use_cache (
bool, необязательный, по умолчаниюTrue) — Указывает, должен ли модель возвращать последние ключи/значения внимания (не используется во всех моделях). Актуально только если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, необязательный, по умолчанию0.02) — Коэффициент для инициализации всех матриц весов (должен быть равен 1, используется внутренне для тестирования инициализации). - scale_embedding (
bool, необязательный, по умолчаниюFalse) — Указывает, следует ли масштабировать эмбеддинги, деля их на sqrt(d_model). - num_codebooks (
int, необязательный, по умолчанию4) — Количество параллельных кодовых книг, используемых моделью. - audio_channels (
int, необязательный, по умолчанию1) — Количество входных каналов. - pad_token_id (
int, необязательный, по умолчанию2048) — Идентификатор токена, используемого для выравнивания (padding) в словаре. - 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) — Указывает, следует ли добавлять слои кросс-внимания в модель. - cross_attention_hidden_size (
int, необязательный) — Размер скрытого слоя выходов энкодера, проецируемый в пространство ключей/значений кросс-внимания декодера. Используется, когда у энкодера и декодера разные размеры скрытого слоя.
Это класс конфигурации для хранения настроек модели MusicgenModel. Он используется для создания модели Musicgen в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/musicgen-small
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
MusicgenConfig
класс transformers.MusicgenConfig
< source >( transformers_version: str | None = Nonearchitectures: list[str] | None = Noneoutput_hidden_states: bool | None = Falsereturn_dict: bool | None = Truedtype: str | torch.dtype | None = Nonechunk_size_feed_forward: int = 0is_encoder_decoder: bool = Falseid2label: dict[int, str] | dict[str, str] | None = Nonelabel2id: dict[str, int] | dict[str, str] | None = Noneproblem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = Nonetext_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneaudio_encoder: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonedecoder: dict | transformers.configuration_utils.PreTrainedConfig | None = Noneinitializer_factor: float = 0.02 )
Параметры
- text_encoder (
Union[dict,PretrainedConfig]) — Экземпляр объекта конфигурации, определяющий конфигурацию текстового кодировщика. - audio_encoder (
Union[dict,PretrainedConfig]) — Объект конфигурации, определяющий конфигурацию аудио-энкодера. - decoder (
Union[dict,PretrainedConfig]) — Объект конфигурации, определяющий конфигурацию декодера. - initializer_factor (
float, необязательный, по умолчанию0.02) — Коэффициент для инициализации всех матриц весов (должен быть равен 1, используется внутренне для тестирования инициализации).
Это класс конфигурации для хранения настроек модели MusicgenModel. Он используется для создания модели Musicgen в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации facebook/musicgen-small
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Пример:
>>> from transformers import (
... MusicgenConfig,
... MusicgenDecoderConfig,
... T5Config,
... EncodecConfig,
... MusicgenForConditionalGeneration,
... )
>>> # Initializing text encoder, audio encoder, and decoder model configurations
>>> text_encoder_config = T5Config()
>>> audio_encoder_config = EncodecConfig()
>>> decoder_config = MusicgenDecoderConfig()
>>> configuration = MusicgenConfig(
... text_encoder=text_encoder_config,
... audio_encoder=audio_encoder_config,
... decoder=decoder_config,
... )
>>> # Initializing a MusicgenForConditionalGeneration (with random weights) from the facebook/musicgen-small style configuration
>>> model = MusicgenForConditionalGeneration(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-model")
>>> # loading model and config from pretrained folder
>>> musicgen_config = MusicgenConfig.from_pretrained("musicgen-model")
>>> model = MusicgenForConditionalGeneration.from_pretrained("musicgen-model", config=musicgen_config)MusicgenProcessor
класс transformers.MusicgenProcessor
< source >( feature_extractortokenizer )
Создаёт MusicgenProcessor, который объединяет feature extractor и tokenizer в единый processor.
MusicgenProcessor предоставляет все возможности EncodecFeatureExtractor и T5Tokenizer. Подробнее см. в ~EncodecFeatureExtractor и ~T5Tokenizer.
__call__
< source >( *args**kwargs )
Параметры
- return_tensors (
strили TensorType, необязательный) — Если задано, возвращает тензоры конкретного фреймворка. Допустимые значения:'pt': возвращает объектыtorch.TensorPyTorch.'np': возвращает объекты NumPynp.ndarray.
MusicgenModel
класс transformers.MusicgenModel
< source >( config: MusicgenDecoderConfig )
Параметры
- config (MusicgenDecoderConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.
Модель Musicgen без дополнительных слоёв, выводящая необработанные скрытые состояния.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneencoder_hidden_states: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → BaseModelOutputWithPastAndCrossAttentions or tuple(torch.Tensor)
Параметры
- input_ids (
torch.LongTensorформы(batch_size * num_codebooks, sequence_length)) — Индексы токенов входной последовательности в словаре, соответствующие последовательности аудиокодов. Индексы можно получить, закодировав аудиопромпт с помощью модели аудиоконкодера для предсказания аудиокодов, например, с помощью EncodecModel. Подробности см. в EncodecModel.encode(). Что такое входные идентификаторы? В ходе прямого прохода input_ids автоматически преобразуются из формы (batch_size * num_codebooks, target_sequence_length) в (batch_size, num_codebooks, target_sequence_length). Если вы получаете аудиокоды из модели аудиоконкодера, такой как EncodecModel, убедитесь, что количество кадров равно 1, и что вы изменяете размерность аудиокодов с (frames, batch_size, num_codebooks, target_sequence_length) до (batch_size * num_codebooks, target_sequence_length) перед передачей их в качестве input_ids.Индексы можно получить, закодировав аудиопромпт с помощью аудио-кодерной модели для предсказания аудиокодов, например, с использованием EncodecModel. Подробности см. в EncodecModel.encode().
Что такое входные идентификаторы?
input_idsавтоматически преобразуются из формы(batch_size * num_codebooks, target_sequence_length)в(batch_size, num_codebooks, target_sequence_length)при прямом проходе. Если вы получаете аудиокоды от модели кодирования аудио, например 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 для токенов, которые замаскированы.
- encoder_hidden_states (
torch.Tensorформы(batch_size, encoder_sequence_length, hidden_size), необязательный) — Последовательность скрытых состояний на выходе последнего слоя энкодера. Используется в кросс-внимании декодера. - encoder_attention_mask (
torch.LongTensorформы(batch_size, encoder_sequence_length), , необязательный) — Маска для предотвращения выполнения cross-attention на индексах токенов padding во входных encoder input_ids. Значения маски выбираются из[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- past_key_values (
~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно этоpast_key_values, возвращённые моделью на предыдущем этапе декодирования, когдаuse_cache=Trueилиconfig.use_cache=True.В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован 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).
Возвращает
BaseModelOutputWithPastAndCrossAttentions или tuple(torch.Tensor)
Объект BaseModelOutputWithPastAndCrossAttentions или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (MusicgenConfig) и входных данных.
Метод forward модели MusicgenModel переопределяет специальный метод __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. Подробнее см. в нашем руководстве по кэшу kv.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и, при необходимости, если
config.is_encoder_decoder=True, в блоках кросс-внимания), которые можно использовать (см. входной параметрpast_key_values) для ускорения последовательного декодирования.hidden_states (
tuple(torch.Tensor), optional, возвращается, если передано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 в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
cross_attentions (
tuple(torch.Tensor), необязательный, возвращается, если переданоoutput_attentions=Trueиconfig.add_cross_attention=Trueили еслиconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания кросс-внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах кросс-внимания.
MusicgenForCausalLM
класс transformers.MusicgenForCausalLM
< source >( config: MusicgenDecoderConfig )
Параметры
- config (MusicgenDecoderConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Используйте метод from_pretrained() для загрузки весов модели.
Модель декодера MusicGen с головкой для моделирования языка.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.Tensor] = Noneencoder_hidden_states: typing.Optional[torch.Tensor] = Noneencoder_attention_mask: typing.Optional[torch.LongTensor] = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → CausalLMOutputWithCrossAttentions or tuple(torch.Tensor)
Параметры
- input_ids (
torch.LongTensorформы(batch_size * num_codebooks, sequence_length)) — Индексы токенов входной последовательности в словаре, соответствующие последовательности аудиокодов. Индексы можно получить, закодировав аудиопромпт с помощью модели аудиоконкодера для предсказания аудиокодов, например, с помощью EncodecModel. Подробности см. в EncodecModel.encode(). Что такое входные идентификаторы? В ходе прямого прохода input_ids автоматически преобразуются из формы (batch_size * num_codebooks, target_sequence_length) в (batch_size, num_codebooks, target_sequence_length). Если вы получаете аудиокоды из модели аудиоконкодера, такой как EncodecModel, убедитесь, что количество кадров равно 1, и что вы изменяете размерность аудиокодов с (frames, batch_size, num_codebooks, target_sequence_length) до (batch_size * num_codebooks, target_sequence_length) перед передачей их в качестве input_ids.Индексы можно получить, закодировав аудиопромпт с помощью аудио-кодерной модели для предсказания аудиокодов, например, с использованием EncodecModel. Подробности см. в EncodecModel.encode().
Что такое входные идентификаторы?
input_idsавтоматически преобразуются из формы(batch_size * num_codebooks, target_sequence_length)в(batch_size, num_codebooks, target_sequence_length)при прямом проходе. Если вы получаете аудиокоды от модели кодирования аудио, например 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 для токенов, которые замаскированы.
- encoder_hidden_states (
torch.Tensorформы(batch_size, encoder_sequence_length, hidden_size), необязательный) — Последовательность скрытых состояний на выходе последнего слоя энкодера. Используется в кросс-внимании декодера. - encoder_attention_mask (
torch.LongTensorформы(batch_size, encoder_sequence_length), , необязательный) — Маска для предотвращения выполнения cross-attention на индексах токенов padding во входных encoder input_ids. Значения маски выбираются из[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- past_key_values (
~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно этоpast_key_values, возвращённые моделью на предыдущем этапе декодирования, когдаuse_cache=Trueилиconfig.use_cache=True.В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован 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преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели. - 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).
Возвращает
CausalLMOutputWithCrossAttentions или tuple(torch.Tensor)
Объект CausalLMOutputWithCrossAttentions или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (MusicgenConfig) и входных данных.
Метод forward класса MusicgenForCausalLM переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
loss (
torch.Tensorформы(1,), необязательный, возвращается, если заданlabels) — Потери языковой модели (для предсказания следующего токена).logits (
torch.Tensorформы(batch_size, sequence_length, config.vocab_size)) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).hidden_states (
tuple(torch.Tensor), optional, возвращается, если передано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 в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
cross_attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили приconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса кросс-внимания после softmax внимания, используемые для вычисления взвешенного среднего в головах кросс-внимания.
past_key_values (
Cache, необязательный, возвращается при передачеuse_cache=Trueили когдаconfig.use_cache=True) — это экземпляр Cache. Подробнее см. в нашем руководстве по кэшу kv.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках внимания), которые можно использовать (см. вход
past_key_values) для ускорения последовательного декодирования.
MusicgenForConditionalGeneration
класс transformers.MusicgenForConditionalGeneration
< source >( config: transformers.models.musicgen.configuration_musicgen.MusicgenConfig | None = Nonetext_encoder: transformers.modeling_utils.PreTrainedModel | None = Noneaudio_encoder: transformers.modeling_utils.PreTrainedModel | None = Nonedecoder: transformers.models.musicgen.modeling_musicgen.MusicgenForCausalLM | None = None )
Параметры
- config (MusicgenConfig, необязательный) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
- text_encoder (
PreTrainedModel, необязательный) — Модель текстового кодировщика, которая кодирует текст в скрытые состояния для условного формирования. - audio_encoder (
PreTrainedModel, необязательный) — Модель аудио-энкодера, которая кодирует аудио в скрытые состояния для условного формирования. - decoder (
MusicgenForCausalLM, необязательный) — Модель декодера, которая генерирует аудио-токены на основе сигналов обусловливания.
Композитная модель MusicGen с текстовым энкодером, аудиоэнкодером и декодером Musicgen,
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneattention_mask: typing.Optional[torch.BoolTensor] = Noneinput_values: typing.Optional[torch.Tensor] = Nonepadding_mask: typing.Optional[torch.BoolTensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_attention_mask: typing.Optional[torch.BoolTensor] = Noneencoder_outputs: tuple[torch.Tensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonedecoder_inputs_embeds: typing.Optional[torch.Tensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Seq2SeqLMOutput or tuple(torch.Tensor)
Параметры
- input_ids (
torch.LongTensorформы(batch_size, sequence_length), , необязательный) — Индексы токенов входной последовательности в словаре. По умолчанию токены отсечки (padding) игнорируются.Индексы можно получить с помощью AutoTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
- attention_mask (
torch.BoolTensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- input_values (
torch.Tensorформы(batch_size, sequence_length), необязательный) — Значения типа float для входной необработанной звуковой волны. Значения можно получить, загрузив аудиофайл.flacили.wavв массив типаlist[float],numpy.ndarrayилиtorch.Tensor, например, с помощью библиотеки torchcodec (pip install torchcodec) или библиотеки soundfile (pip install soundfile). Для подготовки массива вinput_valuesследует использовать AutoProcessor для выравнивания (padding) и преобразования в тензор типаtorch.Tensor. Подробности см. в MusicgenProcessor.call(). - padding_mask (
torch.BoolTensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из вычислений внимания. Значения маски из диапазона[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- decoder_input_ids (
torch.LongTensorформы(batch_size * num_codebooks, target_sequence_length), необязательный) — Индексы токенов входной последовательности декодера в словаре, соответствующие последовательности аудиокодов. Индексы можно получить, закодировав аудиопромпт с помощью модели аудиоконкодера для предсказания аудиокодов, например, с помощью EncodecModel. Подробности см. в EncodecModel.encode(). Что такое decoder input IDs? decoder_input_ids автоматически преобразуются из формы (batch_size * num_codebooks, target_sequence_length) в (batch_size, num_codebooks, target_sequence_length) при прямом проходе. Если вы получаете аудиокоды из модели аудиоконкодера, такой как EncodecModel, убедитесь, что количество кадров равно 1, и что вы изменяете размерность аудиокодов с (frames, batch_size, num_codebooks, target_sequence_length) до (batch_size * num_codebooks, target_sequence_length) перед передачей их в качестве decoder_input_ids.Индексы можно получить, закодировав аудиопромпт с помощью аудио-кодерной модели для предсказания аудиокодов, например, с использованием EncodecModel. Подробности см. в EncodecModel.encode().
Что такое входные идентификаторы декодера?
decoder_input_idsавтоматически преобразуются из формы(batch_size * num_codebooks, target_sequence_length)в(batch_size, num_codebooks, target_sequence_length)при прямом проходе. Если вы получаете аудиокоды от модели кодирования аудио, например 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. По умолчанию также будет использоваться каузальная маска. - encoder_outputs (
tuple[torch.Tensor], необязательный) — Кортеж состоит из (last_hidden_state, необязательный:hidden_states, необязательный:attentions)last_hidden_stateформы(batch_size, sequence_length, hidden_size), необязательный) представляет собой последовательность скрытых состояний на выходе последнего слоя энкодера. Используется в кросс-внимании декодера. - past_key_values (
~cache_utils.Cache, необязательный) — Предвычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно этоpast_key_values, возвращённые моделью на предыдущем этапе декодирования, когдаuse_cache=Trueилиconfig.use_cache=True.В качестве входного параметра допускается только экземпляр Cache, см. наше руководство по кэшу KV. Если
past_key_valuesне переданы, по умолчанию будет инициализирован 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преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели. - 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).
Возвращает
Seq2SeqLMOutput или tuple(torch.Tensor)
Объект Seq2SeqLMOutput или кортеж
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (MusicgenConfig) и входных данных.
Метод forward класса MusicgenForConditionalGeneration переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
loss (
torch.Tensorформы(1,), необязательный, возвращается, если заданlabels) — Потери языковой модели.logits (
torch.Tensorформы(batch_size, sequence_length, config.vocab_size)) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).past_key_values (
EncoderDecoderCache, необязательный, возвращается при передачеuse_cache=Trueили когдаconfig.use_cache=True) — это экземпляр EncoderDecoderCache. Подробнее см. в нашем руководстве по кэшу kv.Содержит предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать (см. вход
past_key_values) для ускорения последовательного декодирования.decoder_hidden_states (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_hidden_states=Trueили приconfig.output_hidden_states=True) — Кортеж изtorch.Tensor(один для вывода эмбеддингов, если у модели есть слой эмбеддингов, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния декодера на выходе каждого слоя, а также выходные значения начального слоя встраивания.
decoder_attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили когдаconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
cross_attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили приconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания кросс-внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах кросс-внимания.
encoder_last_hidden_state (
torch.Tensorформы(batch_size, sequence_length, hidden_size), необязательный) — Последовательность скрытых состояний на выходе последнего слоя энкодера модели.encoder_hidden_states (
tuple(torch.Tensor), необязательный, возвращается, если переданоoutput_hidden_states=Trueили еслиconfig.output_hidden_states=True) — Кортежtorch.Tensor(один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния кодировщика на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
encoder_attentions (
tuple(torch.Tensor), необязательный, возвращается при передачеoutput_attentions=Trueили приconfig.output_attentions=True) — Кортежtorch.Tensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
Примеры:
>>> from transformers import AutoProcessor, MusicgenForConditionalGeneration
>>> import torch
>>> processor = AutoProcessor.from_pretrained("facebook/musicgen-small")
>>> model = MusicgenForConditionalGeneration.from_pretrained("facebook/musicgen-small")
>>> 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, tgt_len, vocab_size)
torch.Size([8, 1, 2048])