Transformers documentation
X-Codec2
该模型于 2025-02-06 在 HF papers 上发布，并于 2026-06-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-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
< 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, 可选) — 词表中用于填充的 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.configXcodec2FeatureExtractor
class transformers.Xcodec2FeatureExtractor
< source >( feature_size = 80sampling_rate = 16000padding_value = 1.0hop_length = 320**kwargs )
构建 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'：返回 TensorFlowtf.constant对象。'pt'：返回 PyTorchtorch.Tensor对象。'np'：返回 Numpynp.ndarray对象。
- sampling_rate (
int, 可选) —audio输入被采样时的采样率。强烈建议在 forward 调用时传入sampling_rate，以避免静默错误。 - device (
str，可选，默认为"cpu") — 在梅尔滤波器组特征提取过程中，用于 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（形状为
(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
< 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（形状为
(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
< 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（形状为
(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