Transformers documentation
X-Codec2
このモデルは2025年2月6日にHF papersで公開され、2026年6月25日にHugging Face Transformersに貢献されました。
X-Codec2
概要
X-Codec2モデルは、Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesisで提案されました。
X-Codec2 は、大規模言語モデル（LLM）パイプラインにおける音声合成および一般的な音声生成の向上を目的として設計されたニューラル音声コーデックです。X-Codec2 は、意味情報と音響情報の統合およびトークン化の方法を改善することで、X-Codec を拡張し、効率的かつ高忠実度の音声表現を可能にしています。
そのアーキテクチャについて:
- Unified Semantic-Acoustic Tokenization: X-Codec2 は、セマンティックエンコーダー（例: Wav2Vec2-BERT）とアコースティックエンコーダーの出力を単一の埋め込みに融合し、高レベルの意味（例: テキスト内容、感情）と低レベルの音声詳細（例: ティンバー）の両方を捉えます。
- 単一ステージのFeature Scalar Quantization (FSQ): 多くのアプローチ（DAC、EnCodec、X-Codec、Mimi など）が採用する多層の残差VQとは異なり、X-Codec2は安定性と、因果的な自己回帰型LLMとの互換性を確保するために、単一層のFeature Scalar Quantization (FSQ)を使用しています。
- Transformer 向けの設計: X-Codec2 の 1 次元トークン構造は、LLaMA などの LLM における自己回帰モデリングと自然に整合しており、学習効率と下流タスクとの互換性が向上します。
モデルのチェックポイントは HKUSTAudio/xcodec2-hf で利用可能です。
このモデルは、Eric Bezzam氏とSteven Zheng氏によって提供されました。 元のモデリングコードはこちらで、トレーニングコードはこちらで確認できます。
使用例
このモデルを使用してオーディオをエンコードおよびデコードする簡単な例を以下に示します。
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel
model_id = "HKUSTAudio/xcodec2-hf"
model = AutoModel.from_pretrained(model_id, device_map="auto")
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 = dataset[0]["audio"]["array"]
inputs = feature_extractor(audio=audio, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(
model.device, model.dtype
)
print("Input waveform shape:", inputs["input_values"].shape)
# Input waveform shape: torch.Size([1, 1, 93760])
# encoder and decoder
audio_codes = model.encode(**inputs).audio_codes
print("Audio codes shape:", audio_codes.shape)
# Audio codes shape: torch.Size([1, 1, 293])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)
# Audio values shape: torch.Size([1, 1, 93760])
# Equivalently, you can do encoding and decoding in one step
model_output = model(**inputs)
audio_codes = model_output.audio_codes
audio_values = model_output.audio_valuesバッチ処理
この実装は、元のリリースとは異なり、バッチ入力にも対応しています!
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel
batch_size = 2
model_id = "HKUSTAudio/xcodec2-hf"
model = AutoModel.from_pretrained(model_id, device_map="auto")
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))
audios = [dataset[i]["audio"]["array"] for i in range(batch_size)]
inputs = feature_extractor(audio=audios, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt").to(
model.device, model.dtype
)
print("Input waveform shape:", inputs["input_values"].shape)
# Input waveform shape: torch.Size([2, 1, 93760])
# encoder and decoder
encoder_output = model.encode(**inputs)
audio_codes = encoder_output.audio_codes
print("Audio codes shape:", audio_codes.shape)
# Audio codes shape: torch.Size([2, 1, 293])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)
# Audio values shape: torch.Size([2, 1, 93760])
# Equivalently, you can do encoding and decoding in one step
model_output = model(**inputs)
audio_codes = model_output.audio_codes
audio_values = model_output.audio_valuestorch.compile による高速化
torch.compile を使用して推論を高速化できます。コンパイルのオーバーヘッドにより最初の数回の呼び出しは遅くなりますが、その後の呼び出しは高速になります。
A100では、バッチサイズが4の場合、約1.35倍の高速化を確認しました(script)。
import torch
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel
batch_size = 4
model_id = "HKUSTAudio/xcodec2-hf"
model = AutoModel.from_pretrained(model_id, device_map="auto")
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))
audios = [dataset[i]["audio"]["array"] for i in range(batch_size)]
inputs = feature_extractor(
audio=audios, sampling_rate=feature_extractor.sampling_rate, padding=True, return_tensors="pt"
).to(model.device, model.dtype)
compiled_model = torch.compile(model, fullgraph=True)
# Warmup (includes compilation on first call)
for _ in range(10):
with torch.inference_mode():
_ = compiled_model(**inputs)
with torch.inference_mode():
output = compiled_model(**inputs)
print("Audio values shape:", output.audio_values.shape)Xcodec2Config
class transformers.Xcodec2Config
< 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 = Nonehidden_size: int = 1024intermediate_size: int = 4096num_hidden_layers: int = 12num_attention_heads: int = 16num_key_value_heads: int = 16hidden_act: str = 'silu'max_position_embeddings: int = 4096initializer_range: float = 0.02rms_norm_eps: float = 1e-06pad_token_id: int | None = Nonetie_word_embeddings: bool = Falserope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = Noneattention_bias: bool = Falseattention_dropout: int | float | None = 0.0head_dim: int = 64encoder_hidden_size: int = 48downsampling_ratios: list[int] | tuple[int, ...] = (2, 2, 4, 4, 5)semantic_model_config: dict | transformers.configuration_utils.PreTrainedConfig | None = Nonesampling_rate: int = 16000activation_dropout: float = 0.1quantization_dim: int = 2048quantization_levels: list[int] | tuple[int, ...] = (4, 4, 4, 4, 4, 4, 4, 4) )
パラメータ
- hidden_size (
int、任意、デフォルトは1024) — 隠れ表現の次元数。 - intermediate_size (
int、任意、デフォルトは4096) — MLP 表現の次元数。 - num_hidden_layers (
int、任意、デフォルトは12) — Transformer デコーダーの隠れ層の数。 - num_attention_heads (
int、任意、デフォルトは16) — Transformer デコーダーの各アテンション層におけるアテンションヘッドの数。 - num_key_value_heads (
int、任意、デフォルトは16) — Grouped Query Attention を実装するために使用する key_value ヘッドの数です。num_key_value_heads=num_attention_headsの場合、モデルは Multi Head Attention (MHA) を使用し、num_key_value_heads=1の場合は Multi Query Attention (MQA) を使用し、それ以外の場合は GQA が使用されます。 マルチヘッドのチェックポイントを GQA のチェックポイントに変換する際は、各グループの key ヘッドと value ヘッドを、そのグループ内の元のすべてのヘッドの平均プーリングによって構築する必要があります。詳細については、この論文を参照してください。指定されない場合、デフォルトでnum_attention_headsが使用されます。 - hidden_act (
str、任意、デフォルトはsilu) — デコーダーで使用する非線形活性化関数（関数または文字列）。例えば、"gelu"、"relu"、"silu"など。 - max_position_embeddings (
int、任意、デフォルトは4096) — このモデルが使用される可能性のある最大シーケンス長です。 - initializer_range (
float、任意、デフォルトは0.02) — すべての重み行列を初期化するための truncated_normal_initializer の標準偏差です。 - rms_norm_eps (
float、任意、デフォルトは1e-06) — RMS 正規化レイヤーで使用する epsilon。 - pad_token_id (
int, 任意) — 語彙内でパディングに使用されるトークン ID。 - tie_word_embeddings (
bool、任意、デフォルトはFalse) — モデルのtied_weights_keysマッピングに従って重み埋め込みを共有するかどうかを指定します。 - rope_parameters (
Union[~modeling_rope_utils.RopeParameters, dict], 省略可) — RoPE 埋め込みの設定パラメータを含む辞書です。この辞書にはrope_thetaの値が含まれており、より長いmax_position_embeddingsで RoPE を使用する場合にスケーリングに使用されるパラメータが任意で含まれます。 - attention_bias (
bool、任意、デフォルトはFalse) — 自己注意機構において、クエリ、キー、バリュー、出力の投影層にバイアスを使用するかどうかを指定します。 - attention_dropout (
Union[int, float]、任意、デフォルトは0.0) — アテンション確率のドロップアウト率です。 - head_dim (
int、任意、デフォルトは64) — アテンションヘッドの次元です。None の場合、hidden_size // num_attention_heads がデフォルトとして使用されます。 - encoder_hidden_size (
int、任意、デフォルトは48) — 隠れ表現の次元数。 - downsampling_ratios (
list[int]、任意、デフォルトは[2, 2, 4, 4, 5]) — エンコーダーにおけるダウンサンプリングの比率です。 - semantic_model_config (
Union[Dict, Wav2Vec2BertConfig], 省略可) — セマンティックモデル（Wav2Vec2BertConfig）の設定オブジェクトのインスタンスです。 - sampling_rate (
int、任意、デフォルトは16000) — オーディオファイルをデジタル化するためのサンプリングレート (Hz)。 - activation_dropout (
float、任意、デフォルトは0.1) — 全結合層内の活性化に対する dropout 率です。 - quantization_dim (
int, 任意、デフォルトは 2048) — ベクトル量子化のコードブックの次元。 - quantization_levels (
list[int]、任意、デフォルトは[4, 4, 4, 4, 4, 4, 4, 4]) — ベクトル量子化のコードブックのレベルです。
これは Xcodec2Model の設定を保存するための設定クラスです。指定された引数に基づいて Xcodec2 モデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、HKUSTAudio/xcodec2-hf と類似した設定が得られます。
設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。
例:
>>> from transformers import Xcodec2Config, Xcodec2Model
>>> # Initializing configuration
>>> configuration = Xcodec2Config()
>>> # Initializing a model (with random weights) from the configuration
>>> model = Xcodec2Model(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configXcodec2FeatureExtractor
class transformers.Xcodec2FeatureExtractor
< source >( feature_size = 80sampling_rate = 16000padding_value = 1.0hop_length = 320**kwargs )
パラメータ
- feature_size (
int、任意、デフォルトは 80) — 抽出された特徴量の次元数。 - sampling_rate (
int, 任意、デフォルトは 16000) — オーディオファイルをデジタル化するためのサンプリングレート（ヘルツ (Hz) 表記）。 - padding_value (
float、任意、デフォルトは 1.0) — Mel スペクトラムのパディングベクトルを埋めるために使用される値です。 - hop_length (
int, 任意、デフォルトは 320) — 1 フレームごとにエンコードされるオーディオサンプル数。ダウンサンプリング比率の積に相当します。音響エンコーダーの入力パディングに必要です。
Xcodec2 の特徴抽出器を構築します。この抽出器は、セマンティックエンコーダー用のメルフイルターバンク特徴量と、アコースティックエンコーダー用のパディング済みオーディオを計算します。
このフィーチャーエクストラクターは、主要なメソッドの大部分を含む SequenceFeatureExtractor を継承しています。これらのメソッドに関する詳細については、このスーパークラスを参照してください。
__call__
< source >( audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']]padding: bool | str | transformers.utils.generic.PaddingStrategy = Truemax_length: int | None = Nonetruncation: bool = Falsereturn_tensors: str | transformers.utils.generic.TensorType | None = Nonesampling_rate: int | None = Nonedevice: str = 'cpu'**kwargs )
パラメータ
- audio (
np.ndarray、torch.Tensor、list[np.ndarray]、list[torch.Tensor]) — 形状が (num_channels, sequence_length) の Numpy 配列または torch テンソル。入力バッチに対して、これらの配列またはテンソルのリストを指定することもできます。 - padding (
bool,strまたは PaddingStrategy, 省略可, デフォルトはTrue) — 返されるシーケンスのパディング戦略（モデルのパディング側およびパディングインデックスに従う）として、以下から選択します:Trueまたは'longest': バッチ内の最長のシーケンスの長さにパディングします（単一のシーケンスのみが提供された場合は、パディングを行いません）。'max_length': 引数max_lengthで指定された最大長、またはその引数が指定されていない場合はモデルが受け入れ可能な最大入力長までパディングします。Falseまたは'do_not_pad'（デフォルト）：パディングを行いません（つまり、長さが異なるシーケンスのバッチを出力できます）。
- max_length (
int, 任意) — 返されるリストの最大長、および必要に応じてパディングの長さ（上記を参照）。 - truncation (
bool) — max_length を超える長さの入力シーケンスを max_length に切り詰めるための切り詰め処理を有効にします。 - return_tensors (
strまたは TensorType, 省略可) — 設定すると、Python の整数のリストではなくテンソルを返します。指定可能な値は以下の通りです:'tf': TensorFlow のtf.constantオブジェクトを返します。'pt': PyTorchのtorch.Tensorオブジェクトを返します。'np': Numpy のnp.ndarrayオブジェクトを返します。
- sampling_rate (
int, 任意) —audio入力がサンプリングされた際のサンプリングレートです。サイレントエラーを防ぐため、forward 呼び出し時にsampling_rateを渡すことを強く推奨します。 - device (
str、省略可能、デフォルトは"cpu") — Mel フィルターバンク特徴量抽出時の PyTorch テンソルに使用するデバイス。 - kwargs (任意) — トークナイザまたはフィーチャーエクストラクターに渡される、残りのキーワード引数の辞書。
Xcodec2Model
class transformers.Xcodec2Model
< source >( config: Xcodec2Config )
パラメータ
- config (Xcodec2Config) — モデルのすべてのパラメータを含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。
Xcodec2 ニューラルオーディオコーデックモデル。
このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。
このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。
decode
< source >( audio_codes: typing.Optional[torch.Tensor] = Nonelatents: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Xcodec2DecoderOutput or tuple(torch.Tensor)
パラメータ
- audio_codes (
torch.LongTensor、形状(batch_size, 1, codes_length)) —model.encodeを使用して計算された離散コードのインデックス。 - latents (
torch.Tensor、形状(batch_size, dimension, time_steps)、任意) — 入力の量子化された連続表現です。
戻り値
Xcodec2DecoderOutput または tuple(torch.Tensor)
Xcodec2DecoderOutput、またはtorch.Tensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（None）や入力に応じて、さまざまな要素で構成されます。
- audio_values (
torch.Tensor、形状(batch_size, 1, segment_length)、任意) — 離散コードを連続的な音声信号に変換して得られる、時間領域におけるデコード済み音声波形の値です。再生可能な再構成された音声を表します。
encode
< source >( input_values: Tensorinput_features: Tensorpadding_mask: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneoutput_latents: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Xcodec2EncoderOutput or tuple(torch.Tensor)
パラメータ
- input_values (
torch.Tensor、形状(batch_size, 1, sequence_length)) — 入力音声波形。 - input_features (
torch.Tensor、shape(batch_size, mel_bins, time_steps)) — セマンティックエンコーディング用の入力音声メロスペクトログラム。 - padding_mask (
torch.Tensor、shape(batch_size, 1, sequence_length)) —input_valuesをパディングするために使用されるパディングマスク。 - input_features_mask (
torch.Tensor、形状(batch_size, time_steps)、任意) — セマンティックエンコーダーへのスペクトログラム入力用のアテンションマスク。有効なフレームは1、パディングは0です。 - output_latents (
bool、任意、デフォルトはFalse) — 量子化器からの連続的な潜在表現を返すかどうかを指定します。
戻り値
Xcodec2EncoderOutput または tuple(torch.Tensor)
Xcodec2EncoderOutput、またはtorch.Tensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（None）や入力に応じて、さまざまな要素で構成されます。
- audio_codes（
torch.LongTensor、形状(batch_size, 1, codes_length)、任意）—model.encodeを使用して計算された離散コードの埋め込み。これは、入力音声信号の圧縮・量子化された形式を表し、保存、送信、または生成に使用できます。 - latents (
torch.Tensor、形状(batch_size, dimension, time_steps)) — 入力の埋め込みの量子化された連続表現。 - audio_codes_mask（
torch.int32、shape(batch_size, 1, codes_length)、optional）—audio_codesにおける有効なオーディオコードを示すために、padding_maskをダウンサンプリングしたものです。
forward
< source >( input_values: Tensorinput_features: Tensorpadding_mask: typing.Optional[torch.Tensor] = Noneinput_features_mask: typing.Optional[torch.Tensor] = Noneoutput_latents: bool = False**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Xcodec2Output or tuple(torch.Tensor)
パラメータ
- input_values (
torch.Tensor、形状(batch_size, 1, sequence_length)) — 入力音声波形。 - input_features (
torch.Tensor、shape(batch_size, mel_bins, time_steps)) — セマンティックエンコーディング用の入力音声メロスペクトログラム。 - padding_mask (
torch.Tensor、shape(batch_size, 1, sequence_length)) —input_valuesをパディングするために使用されるパディングマスク。 - input_features_mask (
torch.Tensor、形状(batch_size, time_steps)、任意) — セマンティックエンコーダーへのスペクトログラム入力用のアテンションマスク。有効なフレームは1、パディングは0です。 - output_latents (
bool、任意、デフォルトはFalse) — 量子化器からの連続的な潜在表現を返すかどうかを指定します。
戻り値
Xcodec2Outputまたはtuple(torch.Tensor)
Xcodec2Output、またはtorch.Tensorのタプル（return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合）。設定（None）や入力に応じて、さまざまな要素で構成されます。
Xcodec2Modelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。
この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなく
Moduleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。
- audio_values (
torch.Tensor、形状(batch_size, 1, sequence_length)、任意) — Xcodec2 のデコーダー部分を使用して取得した、時間領域におけるデコード済みオーディオ波形の値です。再構成されたオーディオ信号を表します。 - audio_codes（
torch.LongTensor、形状(batch_size, 1, codes_length)、任意）—model.encodeを使用して計算された離散コード埋め込みです。これは、さらなる処理や生成のために使用される、入力音声の量子化された表現です。 - latents (
torch.Tensor、形状(batch_size, dimension, time_steps)) — 入力の埋め込みの量子化された連続表現。 - audio_codes_mask（
torch.int32、shape(batch_size, 1, codes_length)、optional）—audio_codesにおける有効なオーディオコードを示すために、padding_maskをダウンサンプリングしたものです。
例:
>>> from datasets import load_dataset
>>> from transformers import AutoFeatureExtractor, Xcodec2Model
>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> audio = dataset["train"]["audio"][0]["array"]
>>> model_id = "HKUSTAudio/xcodec2-hf"
>>> model = Xcodec2Model.from_pretrained(model_id)
>>> feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
>>> inputs = feature_extractor(audio=audio, sampling_rate=feature_extractor.sampling_rate, return_tensors="pt")
>>> outputs = model(**inputs)
>>> audio_codes = outputs.audio_codes
>>> audio_values = outputs.audio_values