Hugging Face's logo

Transformers documentation

NeuCodec

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年9月11日にHF papersで公開され、2026年9月2日にHugging Face Transformersに貢献されました。

NeuCodec

SDPA

概要

NeuCodecモデルは、Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-ratesで提案されました。

NeuCodecは、XCodec2を拡張したニューラルオーディオコーデックです。以下の機能を活用しています。

  • 単一コードブックを生成する有限スカラー量子化（FSQ）により、Speech Language Models による下流モデリングに最適です。
  • Non-Commercial なデータ制限がないよう、CC データで学習されています。
  • 1秒あたり50トークン、1トークンあたり16ビットの場合、全体のビットレートは0.8kbpsになります。
  • このコーデックは16kHzの入力を取得し、アップサンプリングデコーダーを使用して24kHzを出力します。
  • FSQエンコーディング方式は、信頼性が低くノイズの多いチャネルに適したビットレベルのエラー耐性を備えています。

元のモデリングコードはこちらで確認できます。

使用例

このモデルを使用してオーディオをエンコードおよびデコードする簡単な例を以下に示します。

from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

model_id = "neuphonic/neucodec"
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, 292])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)

# 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 = "neuphonic/neucodec"
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, 292])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)

# 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 を使用して推論を高速化できます。コンパイルのオーバーヘッドにより最初の数回の呼び出しは遅くなりますが、その後の呼び出しは高速になります。

import torch
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel

batch_size = 4
model_id = "neuphonic/neucodec"
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)

NeuCodecConfig

class transformers.NeuCodecConfig

< >

( 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 = Noneactivation_dropout: float = 0.1quantization_dim: int = 2048quantization_levels: list[int] | tuple[int, ...] = (4, 4, 4, 4, 4, 4, 4, 4)input_sampling_rate: int = 16000output_sampling_rate: int = 24000 )

パラメータ

  • 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）の設定オブジェクトのインスタンスです。
  • activation_dropout (float、任意、デフォルトは 0.1) — 全結合層内の活性化に対する dropout 率です。
  • quantization_dim (int, 任意、デフォルトは 2048) — ベクトル量子化のコードブックの次元。
  • quantization_levels (list[int]、任意、デフォルトは [4, 4, 4, 4, 4, 4, 4, 4]) — ベクトル量子化のコードブックのレベルです。
  • input_sampling_rate (int, 任意、デフォルトは 16000) — エンコーダーに入力される音声波形のサンプリングレート (Hz)。
  • output_sampling_rate (int、任意、デフォルトは 24000) — デコーダーの出力音声波形のサンプリングレート（ヘルツ、Hz）。

これはNeuCodecModelの設定を保存するための設定クラスです。指定された引数に基づいてNeucodecモデルをインスタンス化し、モデルのアーキテクチャを定義するために使用されます。デフォルト値で設定をインスタンス化すると、neuphonic/neucodecと類似した設定が得られます。

設定オブジェクトはPreTrainedConfigを継承し、モデルの出力を制御するために使用できます。詳細については、PreTrainedConfigのドキュメントを参照してください。

例:

>>> from transformers import NeuCodecConfig, NeuCodecModel

>>> # Initializing configuration
>>> configuration = NeuCodecConfig()

>>> # Initializing a model (with random weights) from the configuration
>>> model = NeuCodecModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config

NeuCodecFeatureExtractor

class transformers.NeuCodecFeatureExtractor

< >

( 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 フレームごとにエンコードされるオーディオサンプル数。ダウンサンプリング比率の積に相当します。音響エンコーダーの入力パディングに必要です。

NeuCodecのフィーチャーエクストラクターを構築します。このエクストラクターは、セマンティックエンコーダー用のメルフィルタバンク特徴量と、アコースティックエンコーダー用のパディング済みオーディオを計算します。

このフィーチャーエクストラクターは、主要なメソッドの大部分を含む 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 (任意) — トークナイザまたはフィーチャーエクストラクターに渡される、残りのキーワード引数の辞書。

NeuCodecModel

class transformers.NeuCodecModel

< >

( config: NeuCodecConfig )

パラメータ

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

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

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

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

decode

< >

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

パラメータ

  • audio_codes (torch.LongTensor、形状 (batch_size, 1, codes_length)) — model.encode を使用して計算された離散コードのインデックス。
  • latents (torch.Tensor、形状 (batch_size, dimension, time_steps)、任意) — 入力の量子化された連続表現です。
  • audio_codes_mask (torch.Tensor、形状 (batch_size, codes_length)、任意) — model.encode が返す、有効（非パディング）な位置を示すマスクです。可変長のオーディオを正しくバッチデコードするために必要です。

戻り値

NeuCodecDecoderOutput または tuple(torch.FloatTensor)

NeuCodecDecoderOutput、または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'> ) → NeuCodecEncoderOutput 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) — 量子化器からの連続的な潜在表現を返すかどうかを指定します。

戻り値

NeuCodecEncoderOutput または tuple(torch.FloatTensor)

NeuCodecEncoderOutput、または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'> ) → NeuCodecOutput or tuple(torch.FloatTensor)

パラメータ

  • input_values (torch.Tensor、shape (batch_size, 1, sequence_length)) — config.input_sampling_rate でサンプリングされた入力音声波形。
  • 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) — 量子化器からの連続的な潜在表現を返すかどうかを指定します。

戻り値

NeuCodecOutput または tuple(torch.FloatTensor)

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

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

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

  • audio_values (torch.FloatTensor、形状 (batch_size, 1, sequence_length)、任意) — NeuCodec のデコーダー部分を用いて取得した、時間領域におけるデコード済み音声波形の値です。再構成された音声信号を表します。
  • 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, NeuCodecModel

>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> audio = dataset["train"]["audio"][0]["array"]

>>> model_id = "neuphonic/neucodec"
>>> model = NeuCodecModel.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  # sampled at 24kHz
Update on GitHub

←Nemotron ASR ストリーミング Parakeet→