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.2).
Hugging Face's logo
Join the Hugging Face community

and get access to the augmented documentation experience

to get started

该模型于 2025-09-11 在 HF papers 上发布，并于 2026-09-02 贡献至 Hugging Face Transformers。

NeuCodec

SDPA

概述

NeuCodec 模型在 Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-rates 中提出。

NeuCodec 是一种基于 XCodec2 扩展的神经音频编解码器。它具有以下特性：

  • 有限标量量化（FSQ）量化会产生单一码本，使其非常适合用于语音语言模型的下游建模。
  • 使用 CC 数据训练，因此没有非商业数据限制。
  • 在 50 tokens/sec 且每个 token 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, 可选) — 词表中用于填充的 token id。
  • tie_word_embeddings (bool，可选，默认为 False) — 是否根据模型的 tied_weights_keys 映射来绑定权重嵌入。
  • rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], 可选) — 包含 RoPE 嵌入配置参数的字典。该字典应包含 rope_theta 的值，并且如果希望使用 RoPE 处理更长的 max_position_embeddings，则可选地包含用于缩放的参数。
  • attention_bias (bool，可选，默认为 False) — 在自注意力机制中，是否在 query、key、value 和 output 投影层中使用偏置。
  • attention_dropout (Union[int, float]，可选，默认为 0.0) — 注意力概率的 dropout 比率。
  • 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) — 用于填充梅尔频谱图中填充向量的值。
  • hop_length (int，可选，默认为 320) — 每帧编码的音频采样点数。等于下采样率的乘积。 用于声学编码器的输入填充。

构建一个 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") — 在梅尔滤波器组特征提取过程中，用于 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.Tensor)

参数

  • audio_codes（形状为 (batch_size, 1, codes_length) 的 torch.LongTensor）— 使用 model.encode 计算得出的离散编码索引。
  • latents（形状为 (batch_size, dimension, time_steps) 的 torch.Tensor，可选） — 输入的量化连续表示。
  • audio_codes_mask（形状为 (batch_size, codes_length) 的 torch.Tensor，可选） — 标记有效（非填充）位置的掩码，由 model.encode 返回。用于正确解码变长音频的批量数据。

返回值

NeuCodecDecoderOutput 或 tuple(torch.Tensor)

NeuCodecDecoderOutput 或 torch.Tensor 元组（如果传入 return_dict=False 或 config.return_dict=False），包含根据配置（None）和输入而定的各种元素。

  • audio_values（形状为 (batch_size, 1, segment_length) 的 torch.Tensor，可选）— 时域中的解码音频波形值，通过将离散编码转换回连续音频信号获得。这表示可以播放的重建音频。

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.Tensor)

参数

  • input_values（形状为 (batch_size, 1, sequence_length) 的 torch.Tensor）— 输入音频波形。
  • input_features（形状为 (batch_size, mel_bins, time_steps) 的 torch.Tensor）— 用于语义编码的输入音频梅尔频谱图。
  • padding_mask（形状为 (batch_size, 1, sequence_length) 的 torch.Tensor）— 用于填充 input_values 的填充掩码。
  • input_features_mask（形状为 (batch_size, time_steps) 的 torch.Tensor，可选） — 用于语义编码器频谱图输入的注意力掩码。有效帧为 1，填充为 0。
  • output_latents (bool，可选，默认为 False) — 是否返回来自量化器的连续潜在表示。

返回值

NeuCodecEncoderOutput 或 tuple(torch.Tensor)

NeuCodecEncoderOutput 或 torch.Tensor 元组（如果传入 return_dict=False 或 config.return_dict=False），包含根据配置（None）和输入而定的各种元素。

  • audio_codes（形状为 (batch_size, 1, codes_length) 的 torch.LongTensor，可选）— 使用 model.encode 计算得到的离散码嵌入。这些嵌入表示输入音频信号的压缩、量化形式，可用于存储、传输或生成。
  • latents（形状为 (batch_size, dimension, time_steps) 的 torch.Tensor）— 输入嵌入的量化连续表示。
  • audio_codes_mask（形状为 (batch_size, 1, codes_length) 的 torch.int32，可选）— 下采样后的 padding_mask，用于指示 audio_codes 中有效的音频编码。

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.Tensor)

参数

  • input_values（形状为 (batch_size, 1, sequence_length) 的 torch.Tensor）— 输入音频波形，采样率为 config.input_sampling_rate。
  • input_features（形状为 (batch_size, mel_bins, time_steps) 的 torch.Tensor）— 用于语义编码的输入音频梅尔频谱图。
  • padding_mask（形状为 (batch_size, 1, sequence_length) 的 torch.Tensor）— 用于填充 input_values 的填充掩码。
  • input_features_mask（形状为 (batch_size, time_steps) 的 torch.Tensor，可选） — 用于语义编码器频谱图输入的注意力掩码。有效帧为 1，填充为 0。
  • output_latents (bool，可选，默认为 False) — 是否返回来自量化器的连续潜在表示。

返回值

NeuCodecOutput 或 tuple(torch.Tensor)

NeuCodecOutput 或 torch.Tensor 元组（如果传入 return_dict=False 或 config.return_dict=False），其包含的元素取决于配置（None）和输入。

NeuCodecModel 的 forward 方法重写了 __call__ 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 Module 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者则会静默地忽略这些步骤。

  • audio_values（形状为 (batch_size, 1, sequence_length) 的 torch.Tensor，可选）— 使用 NeuCodec 的解码器部分在时域中获得的解码音频波形值。这些值代表重建后的音频信号。
  • audio_codes（形状为 (batch_size, 1, codes_length) 的 torch.LongTensor，可选）— 使用 model.encode 计算得到的离散码嵌入。这些是输入音频的量化表示，用于后续处理或生成。
  • latents（形状为 (batch_size, dimension, time_steps) 的 torch.Tensor）— 输入嵌入的量化连续表示。
  • audio_codes_mask（形状为 (batch_size, 1, codes_length) 的 torch.int32，可选）— 下采样后的 padding_mask，用于指示 audio_codes 中有效的音频编码。

示例：

>>> 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→