Hugging Face's logo

Transformers documentation

X-Codec2

You are viewing main version, which requires installation from source. If you'd like regular pip install, checkout the latest stable version (v5.22.1).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

このモデルは2025年2月6日にHF papersで公開され、2026年6月25日にHugging Face Transformersに貢献されました。

X-Codec2

SDPA

概要

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_values

torch.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

< >

( 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]) — ベクトル量子化のコードブックのレベルです。

This is the configuration class to store the configuration of a Xcodec2Model. It is used to instantiate a Xcodec2 model according to the specified arguments, defining the model architecture. Instantiating a configuration with the defaults will yield a similar configuration to that of the 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.config

Xcodec2FeatureExtractor

class transformers.Xcodec2FeatureExtractor

< >

( 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__

< >

( 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

< >

( config: Xcodec2Config )

パラメータ

  • config (Xcodec2Config) — モデルのすべてのパラメータを含むモデル設定クラスです。設定ファイルで初期化しても、モデルに関連する重みは読み込まれず、設定のみが読み込まれます。モデルの重みをロードするには、from_pretrained() メソッドを参照してください。

Xcodec2 ニューラルオーディオコーデックモデル。

このモデルは PreTrainedModel を継承しています。すべてのモデルに実装されている汎用的なメソッド（ダウンロードや保存、入力埋め込みのリサイズ、ヘッドのプルーニングなど）については、スーパークラスのドキュメントを参照してください。

このモデルは、PyTorchのtorch.nn.Moduleのサブクラスでもあります。 通常のPyTorch Moduleとして使用し、一般的な使用方法や動作に関する詳細については、PyTorchのドキュメントを参照してください。

decode

< >

( audio_codes: typing.Optional[torch.Tensor] = Nonelatents: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → Xcodec2DecoderOutput or tuple(torch.FloatTensor)

パラメータ

  • audio_codes (torch.LongTensor、形状 (batch_size, 1, codes_length)) — model.encode を使用して計算された離散コードのインデックス。
  • latents (torch.Tensor、形状 (batch_size, dimension, time_steps)、任意) — 入力の量子化された連続表現です。

戻り値

Xcodec2DecoderOutput または tuple(torch.FloatTensor)

Xcodec2DecoderOutput、またはtorch.FloatTensorのタプル(return_dict=Falseが渡された場合、またはconfig.return_dict=Falseの場合)。設定(None)と入力に応じて、さまざまな要素で構成されます。

  • audio_values (torch.FloatTensor、形状 (batch_size, 1, segment_length)、任意) — 離散コードを連続的な音声信号へ変換して得られる、時間領域におけるデコード済み音声波形の値です。再生可能な再構成音声を表します。

encode

< >

( 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.FloatTensor)

パラメータ

  • 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.FloatTensor)

Xcodec2EncoderOutput、またはtorch.FloatTensorのタプル（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

< >

( 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.FloatTensor)

パラメータ

  • 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.FloatTensor)

Xcodec2Output または、torch.FloatTensor のタプル（return_dict=False が渡された場合、または config.return_dict=False の場合）。設定（None）と入力に応じて、さまざまな要素で構成されます。

Xcodec2Modelのforwardメソッドは、__call__特殊メソッドをオーバーライドします。

この関数内でフォワードパスの手順を定義する必要がありますが、その後、この関数ではなくModuleインスタンスを呼び出すべきです。前者は前処理と後処理の実行を適切に処理するのに対し、後者はそれらを黙って無視するためです。

  • audio_values (torch.FloatTensor、形状 (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
Update on GitHub

←X-Codec XLS-R→