Transformers documentation
音声エンコーダーデコーダーモデル
このモデルは2021年4月14日にHF papersで公開され、2021年9月1日にHugging Face Transformersに貢献されました。
音声エンコーダーデコーダーモデル
SpeechEncoderDecoderModel は、事前学習済みの音声オートエンコーディングモデル（例: Wav2Vec2、Hubert など）をエンコーダーとして、事前学習済みの自己回帰モデルをデコーダーとして使用して、音声からテキストへの変換モデルを初期化するために使用できます。
音声認識および音声翻訳において、事前学習済みチェックポイントで音声シーケンスからテキストシーケンスへのモデルを初期化することの有効性は、Changhan Wang、Anne Wu、Juan Pino、Alexei Baevski、Michael Auli、Alexis Conneau による Large-Scale Self- and Semi-Supervised Learning for Speech Translation で 例えば 示されています。
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 クラスのファインチューニング済みチェックポイントを読み込むには、Transformers の他のモデルアーキテクチャと同様に、SpeechEncoderDecoderModel が from_pretrained(...) メソッドを提供しています。
推論を実行するには、generateメソッドを使用します。このメソッドにより、自己回帰的にテキストを生成できます。greedy、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 など他のエンコーダー・デコーダーモデルと同様にファインチューニングを行うことができます。
ご覧のとおり、損失を計算するには、モデルには2つの入力のみが必要です: 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 )
これは、Speech Encoder DecoderModel の設定を保存するための設定クラスです。指定された引数に基づいて 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、任意) — モデルのパラメータをすべて含むモデル設定クラス。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
- encoder (
PreTrainedModel、任意) — 使用するエンコーダーモデル。 - decoder (
PreTrainedModel、任意) — 使用するデコーダーモデル。
特定のヘッドを付加せずに生の隠れ状態を出力する、素のSpeech Encoder Decoder Model。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、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、shape(batch_size, sequence_length)または(batch_size, sequence_length, feature_dim)、任意) — 入力となる生音声波形または音声特徴量の浮動小数点値。.flacまたは.wav形式の音声ファイルをlist[float]、numpy.ndarray、またはtorch.Tensor型の配列として読み込むことで値を取得できます。例えば、torchcodec ライブラリ（pip install torchcodec）や soundfile ライブラリ（pip install soundfile）を通じて取得できます。inputsとして配列を準備するには、Wav2Vec2Processor または Speech2TextProcessor を使用して、パディングおよび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() を参照してください。入力 ID とは? past_key_values を使用する場合、任意で最後の decoder_input_ids のみを入力すれば十分です (past_key_values を参照)。学習時には、モデルがラベルを右にシフトし、-100 を pad_token_id に置き換えて、先頭に decoder_start_token_id を付加することで、decoder_input_ids を自動的に作成します。インデックスは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、shape(batch_size, target_sequence_length)、任意) — デフォルトの動作:decoder_input_ids内の pad トークンを無視するテンソルを生成します。デフォルトでは、causal mask も使用されます。 - 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 cache ガイドを参照してください。
past_key_valuesが渡されない場合、デフォルトで DynamicCache が初期化されます。モデルは、入力として与えられたのと同じキャッシュ形式を出力します。
past_key_valuesを使用する場合、すべてのinput_ids（形状(batch_size, sequence_length)）ではなく、このモデルに過去のキー・バリュー状態が与えられていない未処理のinput_ids（形状(batch_size, unprocessed_length)）のみを入力することになります。 - decoder_inputs_embeds (
torch.FloatTensor、shape(batch_size, target_sequence_length, hidden_size)、任意) —decoder_input_idsを渡す代わりに、埋め込み表現を直接渡すこともできます。これは、モデル内部の埋め込みルックアップ行列よりも、decoder_input_idsのインデックスを対応するベクトルに変換する方法をより細かく制御したい場合に有用です。 - labels (
torch.LongTensor、shape(batch_size, sequence_length)、任意) — デコーダーのマスク言語モデリング損失を計算するためのラベル。インデックスは[-100, 0, ..., config.vocab_size]の範囲である必要があります（input_idsの docstring を参照）。インデックスが-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 を返すかどうかを指定します。詳細は、返されるテンソルのhidden_statesを参照してください。 - input_values (
torch.FloatTensor、shape(batch_size, sequence_length)、任意) — 入力生の音声波形の浮動小数点値。値は、.flac または .wav 形式のオーディオファイルを list[float] または numpy.ndarray 型の配列として読み込むことで取得できます。例 として、torchcodec ライブラリ (pip install torchcodec) や soundfile ライブラリ (pip install soundfile) を使用できます。 配列を input_values に整えるには、パディングと torch.FloatTensor 型への変換のために Wav2Vec2Processor を使用してください。詳細は 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)
torch.FloatTensor のタプル、または return_dict=False が渡された場合、あるいは config.return_dict=False の場合は torch.FloatTensor のタプルとして、設定 (SpeechEncoderDecoderConfig) や入力に応じてさまざまな要素を含む Seq2SeqLMOutput を返します。
SpeechEncoderDecoderModel の forward メソッドは、__call__ という特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
loss (
torch.FloatTensor、shape(1,)、optional、labelsが指定された場合に返されます)— 言語モデリングの損失。logits (
torch.FloatTensor、shape(batch_size, sequence_length, config.vocab_size)) — 言語モデリングヘッドの予測スコア（SoftMax 適用前の各語彙トークンのスコア）。past_key_values (
EncoderDecoderCache、任意、use_cache=Trueが渡された場合またはconfig.use_cache=Trueの場合に返されます) — EncoderDecoderCache のインスタンスです。詳細については、kv cache ガイドを参照してください。自己注意ブロックおよび相互注意ブロック内のキーとバリューの事前計算済み隠れ状態（hidden-states）を保持しており、シーケンシャルデコーディングを高速化するために使用できます（
past_key_values入力参照）。decoder_hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返される) —torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力用が 1 つ、各層の出力用が 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力および初期埋め込み出力における、デコーダーの隠れ状態。
decoder_attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返されます) —torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。自己アテンションヘッドにおける加重平均を計算するために使用される、アテンションのsoftmax後のデコーダーのアテンション重み。
cross_attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返される) —torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(batch_size, num_heads, sequence_length, sequence_length)。クロスアテンション層のアテンション重みは、アテンションのsoftmax適用後に計算され、クロスアテンションヘッドにおける加重平均の計算に使用されます。
encoder_last_hidden_state (
torch.FloatTensor、shape(batch_size, sequence_length, hidden_size)、optional) — モデルのエンコーダーの最終層の出力における、隠れ状態のシーケンス。encoder_hidden_states (
tuple(torch.FloatTensor)、optional、output_hidden_states=Trueが渡された場合またはconfig.output_hidden_states=Trueの場合に返される) —torch.FloatTensorのタプル（埋め込み層を持つモデルの場合、埋め込みの出力が 1 つ、各層の出力がそれぞれ 1 つずつ）で、形状は(batch_size, sequence_length, hidden_size)です。各層の出力および初期埋め込み出力におけるエンコーダーの隠れ状態。
encoder_attentions (
tuple(torch.FloatTensor)、optional、output_attentions=Trueが渡された場合またはconfig.output_attentions=Trueの場合に返される) —torch.FloatTensorのタプル（各レイヤーごとに1つ）、形状は(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, 省略可) — エンコーダーの初期化に必要な情報。以下のいずれかです:- huggingface.co のモデルリポジトリにホストされている事前学習済みモデルの model id を示す文字列。
- save_pretrained() を使用して保存されたモデルの重みを含むディレクトリへのパス。例:
./my_model_directory/
- decoder_pretrained_model_name_or_path (
str, 省略可, デフォルトはNone) — デコーダーを初期化するために必要な情報。次のいずれかです:- huggingface.co のモデルリポジトリにホストされている事前学習済みモデルの model id を示す文字列。
- save_pretrained() を使用して保存されたモデルの重みを含むディレクトリへのパス。例:
./my_model_directory/
- model_args (残りの位置引数、任意) —
残りのすべての位置引数は、基盤となるモデルの
__init__メソッドに渡されます。 - kwargs (残りのキーワード引数の辞書、 省略可能) —
設定オブジェクト（読み込み後）を更新し、モデルを初期化するために使用できます（例:
output_attentions=True).- エンコーダーの設定を更新するには、各設定パラメータにプレフィックス encoder_ を使用します。
- デコーダーの設定を更新するには、各設定パラメータにプレフィックス decoder_ を使用します。
- 親モデルの設定を更新する場合は、各設定パラメータにプレフィックスを使用しないでください。
configが提供されるか、自動的に読み込まれるかによって、動作が異なります。
事前学習済みモデルのチェックポイントから、ライブラリの1つまたは2つのベースクラスを使用してエンコーダーとデコーダーをインスタンス化します。
モデルはデフォルトで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")