Transformers documentation
X-Codec
このモデルは2024年8月30日にHF papersで公開され、2025年8月15日にHugging Face Transformersに貢献されました。
X-Codec
概要
X-Codecモデルは、Zhen Ye、Peiwen Sun、Jiahe Lei、Hongzhan Lin、Xu Tan、Zheqi Dai、Qiuqiang Kong、Jianyi Chen、Jiahao Pan、Qifeng Liu、Yike Guo、Wei Xue による Codec Does Matter: Exploring the Semantic Shortcoming of Codec for Audio Language Model で提案されました。
X-Codecモデルは、自己教師ありモデル（例：HuBERT）からの意味情報と従来の音響情報を統合したニューラルオーディオコーデックです。これにより、以下が可能になります。
- 音楽の継続生成: 音楽的意味のモデリングが向上することで、より一貫性のある継続生成が可能になります。
- テキストからサウンドを合成: X-Codec は、テキストプロンプトと生成されたオーディオの間の意味的な整合性を捉えます。
- セマンティック認識型オーディオトークナイズ: X-Codec は、YuE の歌詞から楽曲を生成するモデルにおいて、オーディオトークナイザーとして使用されています。
この論文の要旨には、次のように記載されています。
音声生成における最近の進歩は、大規模言語モデル（LLM）の能力によって大きく後押しされてきました。既存の音声LLMに関する研究は、主に音声言語モデルのアーキテクチャと規模の向上、およびより大規模なデータセットの活用に取り組んできおり、一般的にはEnCodecのような音響コーデックが音声のトークン化に使用されています。しかし、これらのコーデックは元々音声圧縮のために設計されており、音声LLMの文脈では最適でないパフォーマンスにつながる可能性があります。本研究では、現在の音声LLMコーデックの欠点、特に生成された音声における意味的一貫性の維持に関する課題に対処することを目的としています。例えば、VALL-Eのような既存の方法は、テキストの文字起こしを条件として音響トークンの生成を行うため、音響トークンの意味的誤解釈により、内容の不正確さや単語誤り率（WER）の上昇、すなわち単語のスキップや誤りが生じることがよくあります。これらの問題を克服するために、X-Codecと呼ばれるシンプルかつ効果的なアプローチを提案します。X-Codecは、Residual Vector Quantization（RVQ）ステージの前に事前学習された意味エンコーダーの意味的特徴を取り入れ、RVQの後に意味再構成損失を導入します。コーデックの意味的処理能力を強化することで、X-Codecは音声合成タスクにおけるWERを大幅に削減し、音楽やサウンド生成を含む非音声アプリケーションにもこれらの利点を拡張します。テキストから音声への変換、音楽の継続生成、テキストからサウンドへの変換タスクにおける実験により、意味情報の統合が音声生成における言語モデルの全体パフォーマンスを大幅に向上させることが示されました。
モデルカード:
- xcodec-hubert-librispeech（音声用）
- xcodec-wavlm-mls(音声用)
- xcodec-wavlm-more-data（音声用）
- xcodec-hubert-general（一般的な音声用）
- xcodec-hubert-general-balanced（一般的な音声向け）
このモデルは Manal El Aidouni によって提供されました。元のコードは こちら で、5つの異なるモデルの元のチェックポイントは こちら で確認できます。
デモはこのページで確認できます。
使用例
このモデルを使用してオーディオをエンコードおよびデコードする簡単な例を以下に示します。
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, XcodecModel
dummy_dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
# load model and feature extractor
model_id = "hf-audio/xcodec-hubert-librispeech"
model = XcodecModel.from_pretrained(model_id, device_map="auto")
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
# load audio sample
dummy_dataset = dummy_dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
audio_sample = dummy_dataset[-1]["audio"]["array"]
inputs = feature_extractor(raw_audio=audio_sample, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(model.device)
# encode and decode
encoder_outputs = model.encode(inputs["input_values"])
decoder_outputs = model.decode(encoder_outputs.audio_codes)
audio_values = decoder_outputs.audio_values
# or the equivalent with a forward pass
audio_values = model(inputs["input_values"]).audio_values元の音声と再構成された音声を聴くには、以下のスニペットを実行し、生成されたoriginal.wavとreconstruction.wavファイルを音楽プレーヤーで開いて比較してください。
import soundfile as sf
original = audio_sample
reconstruction = audio_values[0].cpu().detach().numpy()
sampling_rate = feature_extractor.sampling_rate
sf.write("original.wav", original, sampling_rate)
sf.write("reconstruction.wav", reconstruction.T, sampling_rate)XcodecConfig
class transformers.XcodecConfig
< 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 = Nonetarget_bandwidths: list[int | float] | tuple[int | float, ...] = (0.5, 1, 1.5, 2, 4)sample_rate: int = 16000kernel_size: int = 3channel_ratios: list[int] | tuple[int, ...] = (1, 1)strides: list[int] | tuple[int, ...] = (1, 1)block_dilations: list[int] | tuple[int, ...] = (1, 1)unit_kernel_size: int = 3codebook_size: int = 1024codebook_dim: int | None = Noneinitializer_range: float = 0.02acoustic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonesemantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = None )
パラメータ
- target_bandwidths (
List[float]、任意、デフォルトは[0.5, 1, 1.5, 2, 4]) — モデルが音声エンコードに使用できる帯域幅(kbps)の範囲です。 - sample_rate (
int、任意、デフォルトは16000) — オーディオファイルをデジタル化するためのサンプリングレート（ヘルツ (Hz) 表記）。 - kernel_size (
int、任意、デフォルトは3) — 畳み込みカーネルのサイズです。 - channel_ratios (
List[float]、任意、デフォルトは[1, 1]) — 各セマンティックブロックにおける出力チャネル数の拡張係数です。 - strides (
List[int]、任意、デフォルトは[1, 1]) — 各セマンティックエンコーダーブロックのストライドです。 - block_dilations (
List[int]、任意、デフォルトは[1, 1]) — セマンティックブロック内の残差ユニットのディレーション係数です。 - unit_kernel_size (
int、任意、デフォルトは 3) — セマンティックブロック内の各 ResidualUnit におけるカーネルサイズ。 - codebook_size (
int、任意、デフォルトは1024) — モデルが使用する並列コードブックの数です。 - codebook_dim (
int, 省略可) — 各コードブック埋め込みベクトルの次元数です。 - initializer_range (
float、任意、デフォルトは0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。 - acoustic_model_config (
Union[Dict, DacConfig]、省略可) — 音響（DAC）モデルの設定のインスタンスです。 - semantic_model_config (
Union[Dict, HubertConfig, WavLMConfig]、任意) — セマンティック（HuBERT）モデルの設定オブジェクトのインスタンスです。
これは XcodecModel の設定を保存するための設定クラスです。指定された引数に基づいて Xcodec モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、Manel/X-Codec と同様の設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
例:
>>> from transformers import XcodecModel, XcodecConfig
>>> # Initializing configuration
>>> configuration = XcodecConfig()
>>> # Initializing a model (with random weights) from the configuration
>>> model = XcodecModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configXcodecModel
クラス transformers.XcodecModel
< source >( config: XcodecConfig )
パラメータ
- config (XcodecConfig) — モデルのすべてのパラメータを含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連付けられた重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
Xcodec ニューラルオーディオコーデックモデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
decode
< source >( audio_codes: Tensorreturn_dict: bool | None = None )
パラメータ
- audio_codes (
torch.LongTensor、形状(batch_size, num_quantizers, codes_length)) —model.encodeを使用して計算された離散コードのインデックス。 - return_dict (
bool、任意) — ModelOutput を返すかどうか
encode
< source >( input_values: Tensorbandwidth: float | None = Nonereturn_dict: bool | None = None )
パラメータ
- input_values (
torch.FloatTensor、shape(batch_size, channels, num_samples)) — 入力音声波形の浮動小数点値。 - bandwidth (
float, 任意) — 単位の目標帯域幅です。値はconfig.target_bandwidthsに含まれる値のみサポートされます。 デフォルトでは、利用可能な最高帯域幅である4.0kbps が使用されます。 - return_dict (
bool, 任意) — ModelOutput を返すかどうかを指定します。
forward
< source >( input_values: Tensoraudio_codes: typing.Optional[torch.Tensor] = Nonebandwidth: float | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → XcodecOutput or tuple (audio_codes, audio_values)
パラメータ
- input_values (
torch.FloatTensor、shape(batch_size, channels, num_samples)) — 入力音声波形の生の浮動小数点値です。 - audio_codes (
torch.LongTensor、形状(batch_size, num_quantizers, codes_length)—model.encodeを用いて計算された離散コードのインデックス。 - bandwidth (
float, 省略可) — kbps 単位の目標帯域幅。config.target_bandwidthsのいずれかの値である必要があります。デフォルトでは、利用可能な最大の帯域幅が使用されます。 - bandwidth (
float, 省略可) — kbps 単位の目標帯域幅。config.target_bandwidthsのいずれかの値である必要があります。デフォルトでは、利用可能な最大の帯域幅が使用されます。
戻り値
XcodecOutput またはタプル (audio_codes, audio_values)
audio_codes: 量子化された離散コード。形状は(batch_size, num_quantizers, codes_length)です。audio_values、形状(batch_size, channels, num_samples): コードから再構成されたオーディオ波形。
XcodecModelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
例:
>>> from datasets import load_dataset
>>> from transformers import AutoFeatureExtractor, XcodecModel
>>> model_id = "hf-audio/xcodec-hubert-librispeech"
>>> model = XcodecModel.from_pretrained(model_id)
>>> feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> dataset = dataset.cast_column("audio", Audio(sampling_rate=feature_extractor.sampling_rate))
>>> audio_sample = dataset[0]['audio']['array']
>>> inputs = feature_extractor(raw_audio=audio_sample, return_tensors="pt")
>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values