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

and get access to the augmented documentation experience

to get started

该模型于 2025-02-06 在 HF papers 上发布，并于 2026-06-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-Codec 进行了扩展，从而实现高效且高保真的音频表示。

关于其架构：

  • 统一语义-声学分词：X-Codec2 将语义编码器（例如 Wav2Vec2-BERT）和声学编码器的输出融合为单一嵌入，同时捕捉高层语义（例如文本内容、情感）和低层音频细节（例如音色）。
  • 单阶段特征标量量化（FSQ）：与大多数方法（例如 DAC、EnCodec、X-Codec、Mimi）中使用的多层残差 VQ 不同，X-Codec2 采用单层特征标量量化（FSQ），以确保稳定性并兼容因果自回归 LLM。
  • 对 Transformer 友好的设计：X-Codec2 的一维 token 结构与 LLaMA 等大语言模型中的自回归建模天然契合，从而提升了训练效率和下游兼容性。

模型检查点可在 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 倍的加速效果（脚本）。

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, 可选) — 词表中用于填充的 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）模型的配置对象实例。
  • 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.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) — 用于填充梅尔频谱图中填充向量的值。
  • hop_length (int，可选，默认为 320) — 每帧编码的音频采样点数。等于下采样率的乘积。 用于声学编码器的输入填充。

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

参数

  • audio_codes（形状为 (batch_size, 1, codes_length) 的 torch.LongTensor）— 使用 model.encode 计算得出的离散编码索引。
  • latents（形状为 (batch_size, dimension, time_steps) 的 torch.Tensor，可选） — 输入的量化连续表示。

返回值

Xcodec2DecoderOutput 或 tuple(torch.Tensor)

Xcodec2DecoderOutput 或 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'> ) → Xcodec2EncoderOutput 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) — 是否返回来自量化器的连续潜在表示。

返回值

Xcodec2EncoderOutput 或 tuple(torch.Tensor)

Xcodec2EncoderOutput 或 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'> ) → Xcodec2Output 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) — 是否返回来自量化器的连续潜在表示。

返回值

Xcodec2Output 或 tuple(torch.Tensor)

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

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

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

  • audio_values（形状为 (batch_size, 1, sequence_length) 的 torch.Tensor，可选）— 使用 Xcodec2 的解码器部分获得的时间域解码音频波形值。这些值代表重建后的音频信号。
  • 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, 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→