Transformers documentation
UnivNet
このモデルは2021年6月15日にHF papersで公開され、2023年11月22日にHugging Face Transformersに貢献されました。
UnivNet
概要
UnivNetモデルは、Won Jang、Dan Lim、Jaesam Yoon、Bongwan Kin、Juntae Kim によって提案された UnivNet: A Neural Vocoder with Multi-Resolution Spectrogram Discriminators for High-Fidelity Waveform Generation に記載されています。
UnivNetモデルは、高忠実度の音声波形を合成するように学習される生成敵対ネットワーク（GAN）です。transformers で共有されている UnivNet モデルは generator であり、条件付けされた log-mel スペクトログラムと任意のノイズシーケンスを音声波形（例：vocoder）にマッピングします。推論には generator のみが必要です。generator の学習に使用される discriminator は実装されていません。
論文の抄録は以下の通りです。
ほとんどのニューラルボコーダーは、帯域制限されたメルスペクトログラムを用いて波形を生成します。入力として全帯域のスペクトル特徴量を使用する場合、ボコーダーには可能な限り多くの音響情報が提供されます。しかし、全帯域メルスペクトログラムを用いる一部のモデルでは、スペクトログラムが鋭くならない過平滑化の問題が発生します。この問題に対処するため、リアルタイムで高忠実度の波形を合成するニューラルボコーダーであるUnivNetを提案します。音声活動検出分野の研究に着想を得て、さまざまなパラメータセットを用いて計算される複数の線形スペクトログラムの振幅を利用する、マルチリゾリューションスペクトログラムディスクリミネーターを追加しました。入力として全帯域メルスペクトログラムを使用し、複数の解像度のスペクトログラムを入力とするディスクリミネーターを追加することで、高解像度の信号を生成できると期待しています。数百人の話者の情報を含むデータセットでの評価において、UnivNetは、既知の話者および未知の話者の両方において、競合するモデルの中で主観的・客観的ないずれの評価でも最良の結果を獲得しました。これらの結果、特にテキスト読み上げ（TTS）における最良の主観的スコアは、ゼロからの学習を必要とせずに新しい話者に素早く適応できる可能性を示しています。
ヒント:
- UnivNetModel.forward() の
noise_sequence引数には、([batch_size], noise_length, model.config.model_in_channels)の形状を持つ標準ガウスノイズ（torch.randnなど）を指定します。ここで、noise_lengthはinput_features引数の長さ次元（次元 1）と一致する必要があります。指定しない場合は、ノイズがランダムに生成されます。フォワードパスを再現できるようにするため、generator引数にtorch.Generatorを渡すこともできます。（なお、UnivNetFeatureExtractor はデフォルトで生成されたノイズを返すため、noise_sequenceを手動で生成する必要はありません。） - UnivNetFeatureExtractorによって追加されたパディングは、
UnivNetFeatureExtractor.batch_decode()メソッドを通じてUnivNetModelの出力から除去できます。以下の使用例を参照してください。 - 各波形の末尾に無音をパディングすることで、生成された音声サンプルの末尾に生じるアーティファクトを軽減できます。これは、UnivNetFeatureExtractor.call() に
pad_end = Trueを指定することで実行できます。詳細はこの issueを参照してください。
使用例:
import torch
from datasets import Audio, load_dataset
from scipy.io.wavfile import write
from transformers import UnivNetFeatureExtractor, UnivNetModel
model_id_or_path = "dg845/univnet-dev"
model = UnivNetModel.from_pretrained(model_id_or_path, device_map="auto")
feature_extractor = UnivNetFeatureExtractor.from_pretrained(model_id_or_path)
ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
# Resample the audio to the model and feature extractor's sampling rate.
ds = ds.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
# Pad the end of the converted waveforms to reduce artifacts at the end of the output audio samples.
inputs = feature_extractor(
ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], pad_end=True, return_tensors="pt"
)
with torch.no_grad():
audio = model(**inputs)
# Remove the extra padding at the end of the output.
audio = feature_extractor.batch_decode(**audio)[0]
# Convert to wav file
write("sample_audio.wav", feature_extractor.sampling_rate, audio)このモデルは dg845 によって提供されました。 私の知る限り、公式のコードリリースはありませんが、maum-ai/univnet に非公式の実装があり、事前学習済みチェックポイントは こちら で入手できます。
UnivNetConfig
クラス transformers.UnivNetConfig
< 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 = Nonemodel_in_channels: int = 64model_hidden_channels: int = 32num_mel_bins: int = 100resblock_kernel_sizes: list[int] | tuple[int, ...] = (3, 3, 3)resblock_stride_sizes: list[int] | tuple[int, ...] = (8, 8, 4)resblock_dilation_sizes: list | tuple = ((1, 3, 9, 27), (1, 3, 9, 27), (1, 3, 9, 27))kernel_predictor_num_blocks: int = 3kernel_predictor_hidden_channels: int = 64kernel_predictor_conv_size: int = 3kernel_predictor_dropout: float | int = 0.0initializer_range: float = 0.01leaky_relu_slope: float = 0.2 )
パラメータ
- model_in_channels (
int、任意、デフォルト値は 64)— UnivNet 残差ネットワークの入力チャネル数です。noise_sequence.shape[1]および UnivNetFeatureExtractor クラスで使用される値と一致する必要があります。 - model_hidden_channels (
int、省略可、デフォルトは 32) — UnivNet の残差ネットワークにおける、各残差ブロックの隠れチャネル数です。 - num_mel_bins (
int, オプション、デフォルト値は 100) — 条件付け用の log-mel スペクトログラムにおける周波数ビンの数です。UnivNetFeatureExtractor クラスで使用された値と一致させる必要があります。 - resblock_kernel_sizes (
tuple[int]またはlist[int]、省略可、デフォルトは[3, 3, 3]) — UnivNet の残差ネットワークにおける 1 次元畳み込み層のカーネルサイズを定義する整数のタプルです。resblock_kernel_sizesの長さが resnet ブロックの数を定義し、resblock_stride_sizesおよびresblock_dilation_sizesの長さと一致する必要があります。 - resblock_stride_sizes (
tuple[int]またはlist[int]、省略可能、デフォルトは[8, 8, 4]) — UnivNet の残差ネットワークにおける 1 次元畳み込み層のストライドサイズを定義する整数のタプルです。resblock_stride_sizesの長さは、resblock_kernel_sizesおよびresblock_dilation_sizesの長さと一致する必要があります。 - resblock_dilation_sizes (
tuple[tuple[int]]またはlist[list[int]]、任意、デフォルトは[[1, 3, 9, 27], [1, 3, 9, 27], [1, 3, 9, 27]]) — UnivNet の残差ネットワークにおける、拡張 1 次元畳み込み層の拡張率を定義する整数のネストされたタプルです。resblock_dilation_sizesの長さは、resblock_kernel_sizesおよびresblock_stride_sizesの長さと一致する必要があります。resblock_dilation_sizes内の各ネストされたリストの長さは、各 resnet ブロックあたりの畳み込み層の数を定義します。 - kernel_predictor_num_blocks (
int、任意、デフォルトは 3) — UnivNet の残差ネットワークにおける各位置変数畳み込み層のカーネルとバイアスを計算するカーネル予測器ネットワークの、残差ブロックの数です。 - kernel_predictor_hidden_channels (
int、任意、デフォルトは 64) — カーネル予測ネットワークにおける各残差ブロックの隠れチャネル数です。 - kernel_predictor_conv_size (
int、任意、デフォルトは 3) — カーネル予測ネットワーク内の各 1 次元畳み込み層のカーネルサイズです。 - kernel_predictor_dropout (
float、任意、デフォルト値は 0.0) — カーネル予測ネットワークの各残差ブロックにおける dropout の確率です。 - initializer_range (
float、任意、デフォルトは0.01) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。 - leaky_relu_slope (
float、任意、デフォルト値は 0.2) — Leaky ReLU 活性化関数で使用する負の傾きの角度です。
これは UnivNetModel の設定を保存するための設定クラスです。指定された引数に基づいて Univnet モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、dg845/univnet-dev と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
例:
>>> from transformers import UnivNetModel, UnivNetConfig
>>> # Initializing a Tortoise TTS style configuration
>>> configuration = UnivNetConfig()
>>> # Initializing a model (with random weights) from the Tortoise TTS style configuration
>>> model = UnivNetModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configUnivNetFeatureExtractor
class transformers.UnivNetFeatureExtractor
< source >( feature_size: int = 1sampling_rate: int = 24000padding_value: float = 0.0do_normalize: bool = Falsenum_mel_bins: int = 100hop_length: int = 256win_length: int = 1024win_function: str = 'hann_window'filter_length: int | None = 1024max_length_s: int = 10fmin: float = 0.0fmax: float | None = Nonemel_floor: float = 1e-09center: bool = Falsecompression_factor: float = 1.0compression_clip_val: float = 1e-05normalize_min: float = -11.512925148010254normalize_max: float = 2.3143386840820312model_in_channels: int = 64pad_end_length: int = 10return_attention_mask = True**kwargs )
パラメータ
- feature_size (
int、任意、デフォルトは 1) — 抽出された特徴量の次元数。 - sampling_rate (
int, 任意、デフォルトは 24000) — オーディオファイルをデジタル化するためのサンプリングレート (Hz)。 - padding_value (
float、任意、デフォルトは 0.0) —padding引数で定義されたパディング戦略を適用する際に、UnivNetFeatureExtractor.call() で使用する埋め込み値です。音声の無音に対応する値である必要があります。__call__のpad_end引数も、このパディング値を使用します。 - do_normalize (
bool、省略可、デフォルトはFalse) — 入力に対して Tacotron 2 の正規化を実行するかどうか。正規化を行うことで、一部のモデルではパフォーマンスが大幅に向上する場合があります。 - num_mel_bins (
int, 任意、デフォルトは 100) — 抽出されたスペクトログラム特徴におけるメルフリクエンシビンの数です。UnivNetModel.config.num_mel_binsと一致させる必要があります。 - hop_length (
int、任意、デフォルト値は 256) — スライディングウィンドウ間の直接のサンプル数です。多くの論文では「shift」とも呼ばれます。なお、SpeechT5FeatureExtractor などの他の音声特徴抽出器とは異なり、それらはhop_lengthをミリ秒単位で受け取ります。 - win_length (
int、任意、デフォルトは 1024) — 各スライディングウィンドウの直接のサンプル数です。SpeechT5FeatureExtractor などの他の音声特徴抽出器とは異なり、それらはwin_lengthをミリ秒単位で受け取ります。 - win_function (
str、任意、デフォルトは"hann_window") — ウィンドウ処理に使用するウィンドウ関数の名前です。torch.{win_function}経由でアクセス可能である必要があります。 - filter_length (
int、任意、デフォルトは 1024) — 使用する FFT 成分の数です。Noneの場合、transformers.audio_utils.optimal_fft_lengthを用いて決定されます。 - max_length_s (
int、任意、デフォルト値は 10)— モデルの最大入力長（秒）です。これは音声のパディングに使用されます。 - fmin (
float、任意、デフォルトは 0.0) — 最小の mel 周波数 (Hz)。 - fmax (
float, 任意) — Hz 単位の最大メル周波数。設定されていない場合、デフォルト値はsampling_rate / 2です。 - mel_floor (
float, 任意、デフォルト値は 1e-09) — mel 周波数バンクの最小値です。なお、UnivNetFeatureExtractor がmel_floorを使用する仕方は、transformers.audio_utils.spectrogram() と異なります。 - center (
bool、省略可、デフォルトはFalse) — フレームtが時刻t * hop_lengthの中心に来るように、波形をパディングするかどうか。Falseの場合、フレームtは時刻t * hop_lengthから始まります。 - compression_factor (
float、任意、デフォルトは 1.0) — スペクトル正規化におけるダイナミックレンジ圧縮のための乗算圧縮係数です。 - compression_clip_val (
float、任意、デフォルト値は 1e-05) — スペクトル正規化においてダイナミックレンジ圧縮を適用する前に、波形に適用されるクリップ値です。 - normalize_min (
float, 任意、デフォルト値は -11.512925148010254) — Tacotron 2 形式の線形正規化に使用される最小値です。デフォルト値は、Tacotron 2 の実装から引用された元の値です。 - normalize_max (
float, 任意、デフォルト値は 2.3143386840820312) — Tacotron 2 方式の線形正規化に使用される最大値です。デフォルト値は、Tacotron 2 の実装における元の値です。 - model_in_channels (
int, 任意、デフォルトは 64) — UnivNetModel モデルへの入力チャネル数です。UnivNetModel.config.model_in_channelsと一致する必要があります。 - pad_end_length (
int, 任意、デフォルトは 10) — 各波形の末尾をパディングする場合に追加するサンプル数（スペクトログラムフレーム数相当）です。追加されるサンプル数はpad_end_length * hop_lengthになります。 - return_attention_mask (
bool、任意、デフォルトはTrue) — call() がattention_maskを返すかどうか。
UnivNetのフィーチャーエクストラクターを構築します。
このクラスは、短時間フーリエ変換（STFT）を使用して、生音声からlog-mel-filter bank特徴量を抽出します。STFTの実装は、TacoTron 2およびHifi-GANの実装に準拠しています。
このフィーチャーエクストラクターは、主要なメソッドの大部分を含む SequenceFeatureExtractor を継承しています。これらのメソッドに関する詳細については、このスーパークラスを参照してください。
__call__
< source >( raw_speech: numpy.ndarray | list[float] | list[numpy.ndarray] | list[list[float]]sampling_rate: int | None = Nonepadding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonetruncation: bool = Truepad_to_multiple_of: int | None = Nonereturn_noise: bool = Truegenerator: numpy.random._generator.Generator | None = Nonepad_end: bool = Falsepad_length: int | None = Nonedo_normalize: str | None = Nonereturn_attention_mask: bool | None = Nonereturn_tensors: str | transformers.utils.generic.TensorType | None = None )
パラメータ
- raw_speech (
np.ndarray、list[float]、list[np.ndarray]、list[list[float]]) — パディング対象のシーケンスまたはシーケンスのバッチです。各シーケンスは、NumPy 配列、浮動小数点数の値のリスト、NumPy 配列のリスト、または浮動小数点数の値のリストのリストであることができます。モノラル音声（ステレオではなく、タイムステップごとに単一の浮動小数点数）である必要があります。 - sampling_rate (
int, 任意) —raw_speech入力がサンプリングされたレートです。サイレントエラーを防ぎ、自動音声認識パイプラインを有効にするため、forward 呼び出し時にsampling_rateを渡すことを強く推奨します。 - padding (
bool,strまたは PaddingStrategy, 省略可, デフォルトはTrue) — 入力のraw_speech波形にパディングを適用する戦略を、以下から選択します（モデルのパディング側およびパディングインデックスに従います）：Trueまたは'longest': バッチ内の最長のシーケンスの長さにパディングします（単一のシーケンスのみが提供された場合は、パディングを行いません）。'max_length': 引数max_lengthで指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。Falseまたは'do_not_pad'（デフォルト）：パディングを行いません（つまり、長さが異なるシーケンスのバッチを出力できます）。
pad_end = Trueの場合、padding戦略が適用される前に、そのパディングが行われます。 - max_length (
int, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ（上記を参照）。 - truncation (
bool、省略可、デフォルトはTrue) —max_lengthを超える入力シーケンスをmax_lengthに切り詰めるための切り詰め処理を有効にします。 - pad_to_multiple_of (
int, 省略可能) — 設定すると、シーケンスを指定された値の倍数にパディングします。これは、計算能力が
>= 7.5（Volta）のNVIDIAハードウェアでTensor Coresの利用を有効にするために、また、シーケンス長が128の倍数であることで恩恵を受けるTPUにおいて、特に有用です。 - return_noise (
bool、省略可能、デフォルトはTrue) — UnivNetModel.forward() で使用するためのノイズ波形を生成して返すかどうかを指定します。 - generator (
numpy.random.Generator、任意、デフォルトはNone) — ノイズを生成する際に使用する、任意のnumpy.random.Generator乱数生成器。 - pad_end (
bool、任意、デフォルトはFalse) — 各波形の末尾に無音をパディングするかどうかを指定します。これにより、生成された音声サンプルの末尾で生じるアーティファクトを軽減できる場合があります。詳細は https://github.com/seungwonpark/melgan/issues/8 を参照してください。このパディングは、paddingで指定されたパディング戦略が実行される前に適用されます。 - pad_length (
int、任意、デフォルトはNone) — 各波形の末尾をパディングする場合、スペクトログラムフレーム単位でのパディングの長さです。設定されていない場合、self.config.pad_end_lengthがデフォルトとして使用されます。 - do_normalize (
bool, 省略可) — 入力に対して Tacotron 2 の正規化を実行するかどうか。正規化を行うことで、一部のモデルではパフォーマンスが大幅に向上する場合があります。設定されていない場合、self.config.do_normalizeの値がデフォルトとして使用されます。 - return_attention_mask (
bool, 省略可能) — attention mask を返すかどうか。デフォルトのままにすると、特定の feature_extractor のデフォルトに従って attention mask を返します。 - return_tensors (
strまたは TensorType, 省略可能) — 設定すると、Python の整数のリストではなくテンソルを返します。指定可能な値は以下の通りです:'pt': PyTorchのtorch.np.arrayオブジェクトを返します。'np': Numpy のnp.ndarrayオブジェクトを返します。
1つ以上のシーケンスを特徴量化し、モデル用に準備するための主要なメソッド。
UnivNetModel
クラス transformers.UnivNetModel
< source >( config: UnivNetConfig )
パラメータ
- config (UnivNetConfig) — モデルのパラメータをすべて含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
特定のヘッドを付加せずに、生のhidden-statesを出力する素のUnivnet Modelです。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
forward
< source >( input_features: FloatTensornoise_sequence: typing.Optional[torch.FloatTensor] = Nonepadding_mask: typing.Optional[torch.FloatTensor] = Nonegenerator: typing.Optional[torch.Generator] = Nonereturn_dict: bool | None = None**kwargs ) → UnivNetModelOutput or tuple(torch.FloatTensor)
パラメータ
- input_features (
torch.FloatTensor、shape(batch_size, sequence_length, feature_dim)) — 入力音声特徴に対応するテンソルです。音声特徴は、UnivNetFeatureExtractor を使用して取得できます。詳細については、UnivNetFeatureExtractor.call() を参照してください（processor_classは音声の処理に UnivNetFeatureExtractor を使用します）。 - noise_sequence (
torch.FloatTensor, 任意) — 標準ガウスノイズのノイズシーケンスを含むテンソル。バッチ化して形状が(batch_size, sequence_length, config.model_in_channels)、またはバッチ化せずに形状が(sequence_length, config.model_in_channels)のいずれかです。指定しない場合は、ランダムに生成されます。 - padding_mask (
torch.BoolTensor, 省略可) — 各シーケンスのどの部分がパディングされているかを示すマスク。マスクの値は[0, 1]:- マスクされていないトークンに対して1
- マスクされたトークンに対しては 0
マスクは、
(batch_size, sequence_length)の形状でバッチ化されたもの、または(sequence_length,)の形状でバッチ化されていないもののいずれかです。 - generator (
torch.Generator、任意) — 生成を決定論的にするための torch generator。 return_dict: 通常のタプルではなく ModelOutput のサブクラスを返すかどうか。 - return_dict (
bool, 任意) — プレーンなタプルではなく ModelOutput を返すかどうか。
戻り値
UnivNetModelOutput または tuple(torch.FloatTensor)
UnivNetModelOutput、またはtorch.FloatTensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（UnivNetConfig）と入力に応じて、さまざまな要素で構成されます。
UnivNetModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
- 波形（
torch.FloatTensor、形状(batch_size, sequence_length)）— バッチ化された1次元（モノラル）出力音声波形。 - waveform_lengths (
torch.FloatTensor、shape(batch_size,)) —waveforms内の各パディングなし波形のサンプル単位のバッチ長。
例:
>>> from transformers import UnivNetFeatureExtractor, UnivNetModel
>>> from datasets import load_dataset, Audio
>>> model = UnivNetModel.from_pretrained("dg845/univnet-dev")
>>> feature_extractor = UnivNetFeatureExtractor.from_pretrained("dg845/univnet-dev")
>>> ds = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> # Resample the audio to the feature extractor's sampling rate.
>>> ds = ds.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
>>> inputs = feature_extractor(
... ds[0]["audio"]["array"], sampling_rate=ds[0]["audio"]["sampling_rate"], return_tensors="pt"
... )
>>> audio = model(**inputs).waveforms
>>> list(audio.shape)
[1, 140288]