Transformers documentation
Модели кодировщика-декодировщика для речевых данных
Эта модель была опубликована в HF papers 14.04.2021 и добавлена в Hugging Face Transformers 01.09.2021.
Модели кодировщика-декодировщика для речевых данных
Модель SpeechEncoderDecoderModel можно использовать для инициализации модели преобразования речи в текст с любым предварительно обученным моделью автокодирования речи в качестве энкодера (например Wav2Vec2, Hubert) и любым предварительно обученным авто-регрессивным моделью в качестве декодера.
Эффективность инициализации моделей «последовательность речи — последовательность текста» с помощью предобученных контрольных точек для распознавания речи и перевода речи, например, была продемонстрирована в работе Large-Scale Self- and Semi-Supervised Learning for Speech Translation авторов Changhan Wang, Anne Wu, Juan Pino, Alexei Baevski, Michael Auli, Alexis Conneau.
Пример использования SpeechEncoderDecoderModel для инференса можно найти в декодере Speech2Text2.
Случайная инициализация SpeechEncoderDecoderModel из конфигураций модели
Модель SpeechEncoderDecoderModel может быть инициализирована случайным образом на основе конфигураций энкодера и декодера. В примере ниже показано, как это сделать, используя конфигурацию Wav2Vec2Model по умолчанию для энкодера
и конфигурацию BertForCausalLM по умолчанию для декодера.
from transformers import BertConfig, SpeechEncoderDecoderConfig, SpeechEncoderDecoderModel, Wav2Vec2Config
config_encoder = Wav2Vec2Config()
config_decoder = BertConfig()
config = SpeechEncoderDecoderConfig.from_encoder_decoder_configs(config_encoder, config_decoder)
model = SpeechEncoderDecoderModel(config=config)Инициализация SpeechEncoderDecoderModel из предобученного энкодера и предобученного декодера
SpeechEncoderDecoderModel может быть инициализирован из предобученной контрольной точки энкодера и предобученной контрольной точки декодера. Обратите внимание, что в качестве энкодера может использоваться любая предобученная речевая модель на основе Transformer, например Wav2Vec2, Hubert, а в качестве декодера — как предобученные автоэнкодерные модели, например BERT, предобученные каузальные языковые модели, например GPT2, так и предобученная часть декодера последовательностно-последовательностных моделей, например декодер BART.
В зависимости от выбранной архитектуры декодера слои кросс-внимания могут быть инициализированы случайными значениями.
Инициализация SpeechEncoderDecoderModel из предобученных контрольных точек энкодера и декодера требует дообучения модели на целевой задаче, как показано в статье в блоге Warm-starting-encoder-decoder.
Для этого класс SpeechEncoderDecoderModel предоставляет метод SpeechEncoderDecoderModel.from_encoder_decoder_pretrained().
from transformers import SpeechEncoderDecoderModel
model = SpeechEncoderDecoderModel.from_encoder_decoder_pretrained(
"facebook/hubert-large-ll60k", "google-bert/bert-base-uncased"
)Загрузка существующей контрольной точки SpeechEncoderDecoderModel и выполнение инференса
Для загрузки дообученных контрольных точек класса SpeechEncoderDecoderModel SpeechEncoderDecoderModel предоставляет метод from_pretrained(...), как и любая другая архитектура модели в Transformers.
Для выполнения инференса используется метод generate, который позволяет генерировать текст авто-регрессивно. Этот метод поддерживает различные способы декодирования, такие как жадный поиск, beam search и мультиномиальное сэмплирование.
from transformers import Wav2Vec2Processor, SpeechEncoderDecoderModel
from datasets import load_dataset
import torch
# load a fine-tuned speech translation model and corresponding processor
model = SpeechEncoderDecoderModel.from_pretrained("facebook/wav2vec2-xls-r-300m-en-to-15", device_map="auto")
processor = Wav2Vec2Processor.from_pretrained("facebook/wav2vec2-xls-r-300m-en-to-15")
# let's perform inference on a piece of English speech (which we'll translate to German)
ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
input_values = processor(ds[0]["audio"]["array"], return_tensors="pt").to(model.device).input_values
# autoregressively generate transcription (uses greedy decoding by default)
generated_ids = model.generate(input_values)
generated_text = processor.batch_decode(generated_ids, skip_special_tokens=True)[0]
print(generated_text)
Mr. Quilter ist der Apostel der Mittelschicht und wir freuen uns, sein Evangelium willkommen heißen zu können.Обучение
После создания модель можно дообучать аналогично BART, T5 или любой другой encoder-decoder модели на наборе данных пар (речь, текст).
Как видно, для вычисления функции потерь модели требуются только два входа: input_values (это
входные данные речи) и labels (это input_ids закодированной целевой последовательности).
from datasets import load_dataset
from transformers import AutoFeatureExtractor, AutoTokenizer, SpeechEncoderDecoderModel
encoder_id = "facebook/wav2vec2-base-960h" # acoustic model encoder
decoder_id = "google-bert/bert-base-uncased" # text decoder
feature_extractor = AutoFeatureExtractor.from_pretrained(encoder_id)
tokenizer = AutoTokenizer.from_pretrained(decoder_id)
# Combine pre-trained encoder and pre-trained decoder to form a Seq2Seq model
model = SpeechEncoderDecoderModel.from_encoder_decoder_pretrained(encoder_id, decoder_id)
model.config.decoder_start_token_id = tokenizer.cls_token_id
model.config.pad_token_id = tokenizer.pad_token_id
# load an audio input and pre-process (normalise mean/std to 0/1)
ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
input_values = feature_extractor(ds[0]["audio"]["array"], return_tensors="pt").to(model.device).input_values
# load its corresponding transcription and tokenize to generate labels
labels = tokenizer(ds[0]["text"], return_tensors="pt").to(model.device).input_ids
# the forward function automatically creates the correct decoder_input_ids
loss = model(input_values=input_values, labels=labels).loss
loss.backward()SpeechEncoderDecoderConfig
класс transformers.SpeechEncoderDecoderConfig
< 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 = 0id2label: 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 = Noneis_encoder_decoder: bool | None = Trueencoder: transformers.configuration_utils.PreTrainedConfig | dict | None = Nonedecoder: transformers.configuration_utils.PreTrainedConfig | dict | None = None )
Параметры
- is_encoder_decoder (
bool, необязательный, по умолчаниюTrue) — Указывает, используется ли модель в качестве энкодера/декодера. - encoder (
Union[~configuration_utils.PreTrainedConfig, dict], необязательный) — Объект конфигурации или словарь конфигурации encoder-бэкбона. - decoder (
Union[~configuration_utils.PreTrainedConfig, dict], необязательный) — Объект конфигурации или словарь конфигурации декодера.
Это класс конфигурации для хранения конфигурации модели Speech Encoder Decoder. Он используется для создания модели Speech Encoder Decoder в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Примеры:
>>> from transformers import BertConfig, Wav2Vec2Config, SpeechEncoderDecoderConfig, SpeechEncoderDecoderModel
>>> # Initializing a Wav2Vec2 & BERT style configuration
>>> config_encoder = Wav2Vec2Config()
>>> config_decoder = BertConfig()
>>> config = SpeechEncoderDecoderConfig(encoder=config_encoder, decoder=config_decoder)
>>> # Initializing a Wav2Vec2Bert model from a Wav2Vec2 & google-bert/bert-base-uncased style configurations
>>> model = SpeechEncoderDecoderModel(config=config)
>>> # Accessing the model configuration
>>> config_encoder = model.config.encoder
>>> config_decoder = model.config.decoder
>>> # set decoder config to causal lm
>>> config_decoder.is_decoder = True
>>> config_decoder.add_cross_attention = True
>>> # Saving the model, including its configuration
>>> model.save_pretrained("my-model")
>>> # loading model and config from pretrained folder
>>> encoder_decoder_config = SpeechEncoderDecoderConfig.from_pretrained("my-model")
>>> model = SpeechEncoderDecoderModel.from_pretrained("my-model", config=encoder_decoder_config)from_encoder_decoder_configs
< source >( encoder_config: PreTrainedConfigdecoder_config: PreTrainedConfig**kwargs ) → SpeechEncoderDecoderConfig
Возвращает
Экземпляр объекта конфигурации
Создайте экземпляр SpeechEncoderDecoderConfig (или производного класса) на основе конфигурации предобученной модели-энкодера и конфигурации модели-декодера.
SpeechEncoderDecoderModel
класс transformers.SpeechEncoderDecoderModel
< source >( config: transformers.configuration_utils.PreTrainedConfig | None = Noneencoder: transformers.modeling_utils.PreTrainedModel | None = Nonedecoder: transformers.modeling_utils.PreTrainedModel | None = None )
Параметры
- config (PreTrainedConfig, optional) — Класс конфигурации модели, содержащий все параметры модели. Инициализация с помощью файла конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
- encoder (
PreTrainedModel, необязательный) — Модель-энкодер, которую следует использовать. - decoder (
PreTrainedModel, необязательный) — Модель декодера, которую следует использовать.
Модель Speech Encoder Decoder, которая выводит необработанные скрытые состояния без какого-либо специализированного слоя наверху.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
forward
< source >( inputs: typing.Optional[torch.FloatTensor] = Noneattention_mask: typing.Optional[torch.FloatTensor] = Nonedecoder_input_ids: typing.Optional[torch.LongTensor] = Nonedecoder_attention_mask: typing.Optional[torch.BoolTensor] = Noneencoder_outputs: tuple[torch.FloatTensor] | None = Nonepast_key_values: transformers.cache_utils.Cache | None = Nonedecoder_inputs_embeds: typing.Optional[torch.FloatTensor] = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = Noneoutput_attentions: bool | None = Noneoutput_hidden_states: bool | None = Noneinput_values: typing.Optional[torch.FloatTensor] = Noneinput_features: typing.Optional[torch.FloatTensor] = Nonereturn_dict: bool | None = None**kwargs ) → Seq2SeqLMOutput or tuple(torch.FloatTensor)
Параметры
- inputs (
torch.FloatTensorформы(batch_size, sequence_length)или(batch_size, sequence_length, feature_dim), необязательный) — Значения типа float для входной необработанной звуковой волны или речевых признаков. Значения можно получить, загрузив аудиофайл.flacили.wavв массив типаlist[float],numpy.ndarrayилиtorch.Tensor, например с помощью библиотеки torchcodec (pip install torchcodec) или библиотеки soundfile (pip install soundfile). Для подготовки массива вinputsследует использовать Wav2Vec2Processor или Speech2TextProcessor для дополнения нулями (padding) и преобразования в тензор типаtorch.FloatTensor. - attention_mask (
torch.FloatTensorформы(batch_size, sequence_length), , необязательный) — Маска для исключения токенов-заполнителей из внимания. Значения маски из диапазона[0, 1]:- 1 для токенов, которые не замаскированы,
- 0 для токенов, которые замаскированы.
- decoder_input_ids (
torch.LongTensorформы(batch_size, target_sequence_length), необязательный) — Индексы токенов входной последовательности декодера в словаре. Индексы можно получить с помощью PreTrainedTokenizer. Подробности — в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call(). Что такое входные идентификаторы? Если используется past_key_values, необязательно вводить все decoder_input_ids — достаточно только последних (см. past_key_values). При обучении decoder_input_ids автоматически создаются моделью путём сдвига labels вправо, замены -100 на pad_token_id и добавления в начало decoder_start_token_id.Индексы можно получить с помощью PreTrainedTokenizer. Подробности см. в PreTrainedTokenizer.encode() и PreTrainedTokenizer.call().
Что такое входные идентификаторы?
Если используется
past_key_values, то в качестве входных данных можно указать только последниеdecoder_input_ids(см.past_key_values).Для обучения
decoder_input_idsавтоматически создаются моделью путём сдвигаlabelsвправо, замены -100 наpad_token_idи добавления в началоdecoder_start_token_id. - decoder_attention_mask (
torch.BoolTensorформы(batch_size, target_sequence_length), необязательный) — Поведение по умолчанию: генерировать тензор, игнорирующий токены заполнения вdecoder_input_ids. По умолчанию также будет использоваться каузальная маска. - encoder_outputs (
tuple[torch.FloatTensor], необязательный) — Кортеж состоит из (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). - decoder_inputs_embeds (
torch.FloatTensorформы(batch_size, target_sequence_length, hidden_size), необязательно) — При необходимости, вместо передачиdecoder_input_idsможно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексыdecoder_input_idsпреобразуются в соответствующие векторы, по сравнению с внутренней матрицей поиска встраиваний модели. - labels (
torch.LongTensorформы(batch_size, sequence_length), необязательный) — Метки для вычисления потерь маскированного языкового моделирования для декодера. Индексы должны находиться в диапазоне[-100, 0, ..., config.vocab_size](см. docstringinput_ids). Токены с индексами, установленными в-100, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне[0, ..., config.vocab_size] - use_cache (
bool, необязательный) — Если установлено вTrue, возвращаются состояния ключей и значенийpast_key_values, которые можно использовать для ускорения декодирования (см.past_key_values). - output_attentions (
bool, необязательный) — Указывает, следует ли возвращать тензоры внимания всех слоев внимания. Подробности см. в описанииattentionsв разделе возвращаемых тензоров. - output_hidden_states (
bool, необязательный) — Указывает, следует ли возвращать скрытые состояния всех слоев. Подробности см. в описанииhidden_statesсреди возвращаемых тензоров. - input_values (
torch.FloatTensorформы(batch_size, sequence_length), необязательный) — Значения типа float для входной сырой аудиоволны. Значения можно получить, загрузив аудиофайл .flac или .wav в массив типа list[float] или numpy.ndarray, например, с помощью библиотеки torchcodec (pip install torchcodec) или библиотеки soundfile (pip install soundfile). Для подготовки массива в input_values следует использовать Wav2Vec2Processor для выравнивания (padding) и преобразования в тензор типа torch.FloatTensor. Подробности см. в Wav2Vec2Processor.call(). - input_features (
torch.FloatTensorформы(batch_size, sequence_length, feature_dim), необязательный) — Тензоры, соответствующие входным аудиопризнакам. Аудиопризнаки можно получить с помощьюfeature_extractor_class. Подробности см. вfeature_extractor_class.__call__(processor_classиспользуетfeature_extractor_classдля обработки аудио). - return_dict (
bool, необязательный) — Указывает, следует ли возвращать ModelOutput вместо обычного кортежа.
Возвращает
Seq2SeqLMOutput или tuple(torch.FloatTensor)
Объект Seq2SeqLMOutput или кортеж из
torch.FloatTensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (SpeechEncoderDecoderConfig) и входных данных.
Метод forward модели SpeechEncoderDecoderModel переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
loss (
torch.FloatTensorформы(1,), необязательный, возвращается, если заданlabels) — Потеря языковой модели.logits (
torch.FloatTensorформы(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.FloatTensor), необязательный, возвращается при передачеoutput_hidden_states=Trueили когдаconfig.output_hidden_states=True) — Кортежtorch.FloatTensor(один для вывода слоя встраиваний, если модель имеет слой встраиваний, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния декодера на выходе каждого слоя, а также выходные значения начального слоя встраивания.
decoder_attentions (
tuple(torch.FloatTensor), необязательный, возвращается, если переданоoutput_attentions=Trueили еслиconfig.output_attentions=True) — кортежtorch.FloatTensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
cross_attentions (
tuple(torch.FloatTensor), необязательный, возвращается при передачеoutput_attentions=Trueили когдаconfig.output_attentions=True) — Кортежtorch.FloatTensor(по одному для каждого слоя) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания кросс-внимания декодера после softmax внимания, используемые для вычисления взвешенного среднего в головах кросс-внимания.
encoder_last_hidden_state (
torch.FloatTensorформы(batch_size, sequence_length, hidden_size), необязательный) — Последовательность скрытых состояний на выходе последнего слоя энкодера модели.encoder_hidden_states (
tuple(torch.FloatTensor), необязательный, возвращается, если переданоoutput_hidden_states=Trueили еслиconfig.output_hidden_states=True) — Кортежtorch.FloatTensor(один для вывода слоя встраиваний, если у модели есть слой встраиваний, + один для вывода каждого слоя) формы(batch_size, sequence_length, hidden_size).Скрытые состояния кодировщика на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
encoder_attentions (
tuple(torch.FloatTensor), необязательный, возвращается при передачеoutput_attentions=Trueили приconfig.output_attentions=True) — Кортежtorch.FloatTensor(по одному на каждый слой) формы(batch_size, num_heads, sequence_length, sequence_length).Веса внимания энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
Примеры:
>>> from transformers import SpeechEncoderDecoderModel, AutoProcessor
>>> from datasets import load_dataset
>>> import torch
>>> processor = AutoProcessor.from_pretrained("facebook/wav2vec2-xls-r-300m-en-to-15")
>>> model = SpeechEncoderDecoderModel.from_pretrained("facebook/wav2vec2-xls-r-300m-en-to-15")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> input_values = processor(ds[0]["audio"]["array"], return_tensors="pt").input_values
>>> # Inference: Translate English speech to German
>>> generated = model.generate(input_values)
>>> decoded = processor.batch_decode(generated, skip_special_tokens=True)[0]
>>> decoded
'Mr. Quilter ist der Apostel der Mittelschicht und wir freuen uns, sein Evangelium willkommen heißen zu können.'
>>> # Training: Train model on English transcription
>>> labels = processor(text=ds[0]["text"], return_tensors="pt").input_ids
>>> loss = model(input_values, labels=labels).loss
>>> loss.backward()from_encoder_decoder_pretrained
< source >( encoder_pretrained_model_name_or_path: str | None = Nonedecoder_pretrained_model_name_or_path: str | None = None*model_args**kwargs )
Параметры
- encoder_pretrained_model_name_or_path (
str, необязательный) — Информация, необходимая для инициализации энкодера. Может быть:- Строка, model id предобученной модели, размещенной в репозитории моделей на huggingface.co.
- Путь к каталогу, содержащему веса модели, сохранённые с помощью
save_pretrained(), например,
./my_model_directory/.
- decoder_pretrained_model_name_or_path (
str, необязательный, по умолчаниюNone) — Информация, необходимая для инициализации декодера. Может быть:- Строка, model id предобученной модели, размещенной в репозитории моделей на huggingface.co.
- Путь к каталогу, содержащему веса модели, сохранённые с помощью
save_pretrained(), например,
./my_model_directory/.
- model_args (остальные позиционные аргументы, необязательные) —
Все оставшиеся позиционные аргументы передаются в метод
__init__базовой модели. - kwargs (остальные именованные аргументы, необязательный) —
Можно использовать для обновления объекта конфигурации (после его загрузки) и инициализации модели (например,
output_attentions=True).- Чтобы обновить конфигурацию энкодера, используйте префикс encoder_ для каждого параметра конфигурации.
- Чтобы обновить конфигурацию декодера, используйте префикс decoder_ для каждого параметра конфигурации.
- Чтобы обновить конфигурацию родительской модели, не используйте префикс для каждого параметра конфигурации.
Поведение зависит от того, предоставлен ли
configили он загружается автоматически.
Создайте энкодер и декодер из одного или двух базовых классов библиотеки на основе контрольных точек предобученной модели.
По умолчанию модель переводится в режим оценки с помощью model.eval() (модули Dropout отключаются). Для обучения модели необходимо сначала вернуть её в режим обучения с помощью model.train().
Пример:
>>> from transformers import SpeechEncoderDecoderModel
>>> # initialize a wav2vec2bert from a pretrained Wav2Vec2 and a pretrained BERT model. Note that the cross-attention layers will be randomly initialized
>>> model = SpeechEncoderDecoderModel.from_encoder_decoder_pretrained(
... "facebook/wav2vec2-base-960h", "google-bert/bert-base-uncased"
... )
>>> # saving model after fine-tuning
>>> model.save_pretrained("./wav2vec2bert")
>>> # load fine-tuned model
>>> model = SpeechEncoderDecoderModel.from_pretrained("./wav2vec2bert")