Transformers 中的 X-Codec2面向 LLM 语音合成的单码本神经音频编解码器【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformersX-Codec2 是用于 LLaMA 系 LLM 语音合成管线的神经音频编解码器它通过语义编码器 声学编码器融合与单层 Finite Scalar QuantizationFSQ设计把音频压缩为一维离散 token 序列。本文基于 Transformers 官方文档与仓库源码系统讲解 X-Codec2 的架构原理、特征提取管线、配置参数并给出可直接运行的编码/解码、批量处理与torch.compile加速完整示例。X-Codec2 由 Eric Bezzam 与 Steven Zheng 贡献模型检查点托管于 Hugging Face模型仓库 IDHKUSTAudio/xcodec2-hf。本文的 API 说明可对照 docs/source/en/model_doc/xcodec2.md源码实现位于 src/transformers/models/xcodec2/ 目录下。背景与设计动机X-Codec2 在论文Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis中提出目标是解决以音频 token 为接口的 LLM 语音合成这一场景下的核心矛盾音频 token 既要保留足够语义信息文本内容、情感又要具备足够低的码率、稳定且适合自回归建模。与常见神经编解码器相比X-Codec2 的三个核心设计要点如下统一语义—声学 token 化Unified Semantic-Acoustic TokenizationX-Codec2 将语义编码器如 Wav2Vec2-BERT与声学编码器的输出融合进同一个 embedding。语义编码器负责捕获高层含义文字内容、情感声学编码器负责捕获底层音频细节如音色融合后的单一表示同时覆盖两者。单层特征标量量化Single-Stage FSQ不同于 DAC、EnCodec、X-Codec、Mimi 等模型常用的多层残差矢量量化residual VQX-Codec2 采用单层 Feature Scalar QuantizationFSQ训练更稳定也更兼容因果、自回归的 LLM。Transformer 友好的一维 token 结构X-Codec2 输出的一维离散 token 序列天然对齐 LLaMA 等模型的自回归建模方式从而提升训练效率与下游兼容性。从源码注释中也可以印证这一点量化器模块 Xcodec2FiniteScalarQuantization 说明中写道X-Codec2 的主要特性就是只用单一 codebook原实现使用含单一 quantizer 的ResidualFSQ此处直接以 FSQ 等价实现。架构总览编码器、量化器与解码器在 Xcodec2Model 中整个模型由五大子模块组装而成可以清晰地划分为三条处理链路语义链路语义编码器 语义适配器Xcodec2Model通过AutoModel.from_config(config.semantic_model_config)实例化语义编码器默认是 Wav2Vec2-BERT 结构随后经过 Xcodec2SemanticAdapter一组 1D 卷积 ReLU 的适配层得到语义隐状态。值得注意的实现细节是语义编码器的前向推理在torch.no_grad()上下文中完成即冻结、不参与梯度回传。声学链路声学编码器Xcodec2Encoder 以波形为输入先是 kernel size 为 7 的首个 1D 卷积随后按downsampling_ratios依次堆叠Xcodec2EncoderBlock每个 block 将通道数翻倍并按 stride 下采样最后经抗混叠激活与 1D 卷积输出声学隐状态。融合与量化语义与声学隐状态在通道维拼接后经过fc_encoder线性层再由 Xcodec2Quantizer 完成量化——内部为project_in映射到与quantization_levels等宽的维度、Xcodec2FiniteScalarQuantization 与project_out的串联输出量化后的连续 latent 与离散的audio_codes。解码链路声学解码器Xcodec2Decoder 是基于 Vocos 思路的声码器风格解码器包含输入线性层、embedding 卷积、两层Xcodec2ResNetBlock、12 层带旋转位置编码RoPE的 Transformer、两层后处理 ResNet最后经 Xcodec2ISTFTHeadSTFT 预测 Hann 窗 ISTFT 重建还原出波形。代码中还用F.fold手工实现了torch.istft缺失的 same padding 语义。模型的encode、decode、forward三个公开方法对应完整的单段处理、两段处理和端到端重建三种用法细节见下文。编码器与解码器均可独立用于流水线的不同阶段例如先用encode产出 token 供 LLM 自回归生成再把生成结果交给decode重建波形。环境准备与快速开始X-Codec2 在 Transformers 中以AutoModelXcodec2Model与AutoFeatureExtractorXcodec2FeatureExtractor的形式接入因此加载方式与一般模型一致from transformers import AutoFeatureExtractor, AutoModel model_id HKUSTAudio/xcodec2-hf model AutoModel.from_pretrained(model_id, device_mapauto) feature_extractor AutoFeatureExtractor.from_pretrained(model_id)一个典型的编码—解码工作流如下可直接复制运行from datasets import Audio, load_dataset from transformers import AutoFeatureExtractor, AutoModel model_id HKUSTAudio/xcodec2-hf model AutoModel.from_pretrained(model_id, device_mapauto) feature_extractor AutoFeatureExtractor.from_pretrained(model_id) dataset load_dataset(hf-internal-testing/librispeech_asr_dummy, clean, splitvalidation) dataset dataset.cast_column(audio, Audio(sampling_ratefeature_extractor.sampling_rate)) audio dataset[0][audio][array] inputs feature_extractor(audioaudio, sampling_ratefeature_extractor.sampling_rate, return_tensorspt).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注意上述打印的 shape 反映了一条重要的换算关系hop_length 320个采样点对应一个 code。9 万多个采样点的输入被压缩成 293 个离散 token93760 / 320 293这正是后续 LLM 自回归生成所需的粒度。关于输出结构model.encode(...)返回 Xcodec2EncoderOutputmodel(...)返回 Xcodec2Output它们共享以下字段audio_codestorch.LongTensor形状(batch_size, 1, codes_length)量化得到的离散 token用于存储、传输或交给 LLM 生成latentstorch.Tensor形状(batch_size, dimension, time_steps)量化的连续表示forward 默认不返回需设output_latentsTrueaudio_codes_masktorch.int32形状(batch_size, 1, codes_length)对padding_mask按hop_length下采样得到的有效 code 掩码便于判断哪些 token 是真实音频仅当 encode 传入padding_mask时生成audio_valuestorch.FloatTensor形状(batch_size, 1, sequence_length)解码重建的时域波形仅 decoder / forward 输出。端到端 forward 的截断逻辑使用model(**inputs)一步完成编码解码时forward内部先调用encode强制output_latentsTrue再把 latent 传给decode最后将重建波形截断回原始输入长度audio_values self.decode(latentsencoder_outputs.latents, return_dictTrue, **kwargs)[0][..., :length]这段逻辑位于 Xcodec2Model.forward 中length input_values.shape[-1]保证输出与输入等长便于直接计算重建误差或与参考波形对齐。批量处理官方实现未支持的增强能力与原始 X-Codec2 发布版指出原始的torchaudio.compliance.kaldi.fbank不支持批量输入原版实现只能逐条循环而这里的实现虽然也逐条计算 mel 特征但整体的 padding、mask 与波形前处理均已支持 batch且保留了与原实现一致的数值行为。批量处理示例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_mapauto) feature_extractor AutoFeatureExtractor.from_pretrained(model_id) dataset load_dataset(hf-internal-testing/librispeech_asr_dummy, clean, splitvalidation) dataset dataset.cast_column(audio, Audio(sampling_ratefeature_extractor.sampling_rate)) audios [dataset[i][audio][array] for i in range(batch_size)] inputs feature_extractor(audioaudios, sampling_ratefeature_extractor.sampling_rate, return_tensorspt).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在把音频列表交给特征提取器时建议显式传入paddingTrue或longest使同一 batch 内的样本按最长长度对齐特征提取器padding参数默认即为True。特征提取波形到双路输入的前处理Xcodec2FeatureExtractor 是理解 X-Codec2 输入格式的关键它把一段波形同时加工成模型所需的两路输入input_values给声学编码器使用的 padded 波形形状(batch_size, 1, sequence_length)padding_mask与input_values对应的掩码input_features给语义编码器使用的 mel 滤波器组特征其帧按 stride 压缩合并形状(batch_size, 特征帧数, 特征维度)input_features_mask语义编码器侧的注意力掩码1表示有效帧、0表示 padding。处理流程分为两步见其__call__声学编码器侧 padding内部定义了一个专门的SequenceFeatureExtractoracoustic_encoder_padder对波形按pad_to_multiple_ofself.hop_length320做对齐填充确保每个样本长度是 hop 长度的整数倍这是保证 code 数与 frame 数对齐的前提。语义编码器侧 mel 特征逐样本调用torchaudio.compliance.kaldi.fbank计算 mel 滤波器组特征窗口函数为 povey、预加重系数 0.97、mel 通道数 80、帧长 400 个采样点25 ms、帧移 160 个采样点10 ms随后做逐样本的均值/方差归一化再按 stride2 合并相邻帧并下采样掩码。该类同时做了输入校验若传入的sampling_rate与特征提取器内置的 16000 Hz 不一致会直接抛错若未传sampling_rate则输出告警日志提示可能引发难以排查的静默错误。因此请务必在调用时显式传入sampling_rate。Xcodec2Config 配置详解Xcodec2Config 负责描述完整模型结构。下表的默认值可直接从源码字段确认其中大部分配置项影响的是模型规模、采样率与量化行为参数默认值含义hidden_size1024Transformer 解码器以及声学编码器输出映射目标的隐层维度intermediate_size4096MLP 中间层维度num_hidden_layers12解码端 Transformer 层数也是 FSQ 之后的解码器层数num_attention_heads/num_key_value_heads16/16注意力头数与 KV 头数GQA 场景下可小于前者head_dim64每个注意力头的维度hidden_actsilu激活函数max_position_embeddings4096最大位置编码长度rms_norm_eps1e-6LayerNorm / RMSNorm 的 epsilonattention_biasFalse注意力投影是否使用偏置attention_dropout0.0注意力 dropout 率encoder_hidden_size48声学编码器首层通道数downsampling_ratios[2, 2, 4, 4, 5]声学编码器逐级下采样倍率sampling_rate16000模型期望的音频采样率Hzactivation_dropout0.1ResNet block 中激活后的 dropoutquantization_dim2048量化器输入/输出投影维度quantization_levels[4, 4, 4, 4, 4, 4, 4, 4]FSQ 每个维度上的量化级数semantic_model_configWav2Vec2-BERT16 层语义编码器的子配置几个值得展开的关键点downsampling_ratios与 hop 长度该配置项决定了声学编码器的下采样路径并间接派生出两个只读属性。hop_length定义为downsampling_ratios的乘积2 × 2 × 4 × 4 × 5 320即每个 token 覆盖的采样点数n_fft定义为hop_length × 4 1280用于解码端 ISTFT 头。这两个属性在 Xcodec2Config 中以property实现。quantization_levels与 codebook 规模8 个维度的级数全为 4意味着隐含 codebook 大小为4^8 65536。这解释了 FSQ 的单一 codebook语义——它不显式存储码本向量而是通过各维度级数穷举组合出索引再在Xcodec2FiniteScalarQuantization内用basistorch.cumprod前缀积完成索引 ↔ 码字的双向换算并通过_indices_to_codes/codebook缓冲实现查表。semantic_model_config子配置sub_configs {semantic_model_config: AutoConfig}声明了嵌套子配置。若传入 dict__post_init__会默认补上model_type wav2vec2-bert并交给对应配置类实例化若为None则自动创建一个 16 层的 Wav2Vec2-BERT 配置。架构校验配置类上的validate_architecture由strict装饰器驱动会检查hidden_size是否可被num_attention_heads整除不满足即抛错。实例化与随机初始化模型的方式与其他 Transformers 模型一致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.configAPI 速览encode / decode / forwardXcodec2Model.encode输入input_values、input_features以及可选的padding_mask、input_features_mask内部完成语义编码冻结→ 声学编码 → 拼接融合 → 量化的完整流程返回audio_codes可选latents与audio_codes_mask。output_latentsTrue时同时返回量化后的连续表示。Xcodec2Model.decode接受audio_codes此时内部经quantizer.from_codes按索引查 codebook或直接给定latents二者必须提供其一否则抛ValueError输出重建的audio_values。Xcodec2Model.forward等价于 encode decode 一步完成输出截断到原始输入长度。Xcodec2Model的父类 Xcodec2PreTrainedModel 声明了一系列能力标记支持 Flash Attention_supports_flash_attn True、SDPA_supports_sdpa True、Flex Attention、Cache类缓存、梯度检查点supports_gradient_checkpointing True以及fullgraph编译_can_compile_fullgraph True主输入名为input_values。也就是说除了默认的 eager 注意力路径你可以通过 Transformers 统一的注意力后端机制启用 Flash Attention 2 / SDPA 等加速实现。使用 torch.compile 加速推理得益于_can_compile_fullgraph True与针对torch.compile友好的实现细节例如 ISTFT 头中特意将频率轴保持在最后一维以兼容torch.polar编译该模型可直接用torch.compile做整图编译加速。据仓库文档记载在 A100 上、batch size 为 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_mapauto) feature_extractor AutoFeatureExtractor.from_pretrained(model_id) dataset load_dataset(hf-internal-testing/librispeech_asr_dummy, clean, splitvalidation) dataset dataset.cast_column(audio, Audio(sampling_ratefeature_extractor.sampling_rate)) audios [dataset[i][audio][array] for i in range(batch_size)] inputs feature_extractor( audioaudios, sampling_ratefeature_extractor.sampling_rate, paddingTrue, return_tensorspt ).to(model.device, model.dtype) compiled_model torch.compile(model, fullgraphTrue) # 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)注意批量输入时特征提取需设paddingTrue且编译/推理过程应包裹在torch.inference_mode()中。项目资源导航如果想深入研读实现或进行二次开发以下仓库路径可作为起点模型组装与前向/编解码主流程src/transformers/models/xcodec2/modeling_xcodec2.py配置文件类src/transformers/models/xcodec2/configuration_xcodec2.py特征提取器波形 → 双路输入src/transformers/models/xcodec2/feature_extraction_xcodec2.py模型的手工维护源modeling_xcodec2.py 由 modular_xcodec2.py 自动生成改动应落到 modular 文件官方检查点权重转换脚本src/transformers/models/xcodec2/convert_xcodec2_checkpoint.py包含 RoPE 置换、key 映射、weight norm 处理等逻辑相关编解码器对照阅读DAC、EnCodec、X-Codec、Mimi需要留意的是X-Codec2 面向 16 kHz 音频其 token 粒度每 320 个采样点一个 code与语义 声学融合、单码本 FSQ的组合是针对 LLaMA 系语音合成定制设计的。若需更高采样率或不同码率的编解码能力建议先横向对比上述同类模型再选型。【免费下载链接】transformers Transformers: the model-definition framework for state-of-the-art machine learning models in text, vision, audio, and multimodal models, for both inference and training.项目地址: https://gitcode.com/GitHub_Trending/tra/transformers创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考