Transformers documentation

VibeVoice 声学分词器

Transformers

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

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

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

VibeVoice 声学分词器

概述

VibeVoice 是一个新颖的框架，通过在大型语言模型（LLM）结构中采用下一 token 扩散方法，来合成高保真、长篇幅的多说话人语音。它旨在捕捉真实对话的“氛围”，尤其适合生成播客和多参与者有声读物等音频内容。

VibeVoice 的一个关键特性是使用了两个连续的音频分词器，一个用于提取声学特征，另一个用于提取语义特征。

模型检查点可在 microsoft/VibeVoice-AcousticTokenizer 获取

该模型由 Eric Bezzam 贡献。

架构

该架构采用镜像对称的编码器-解码器结构。编码器采用分层设计，包含 7 个类似 ConvNeXt 的块，这些块使用一维深度可分离因果卷积以实现高效的流式处理。六个下采样层实现了从 24kHz 输入到 3200 倍累计下采样率，从而产生每秒 7.5 个 token/帧。每个编码器/解码器组件约有 3.4 亿个参数，总计约 6.8 亿个参数。训练目标遵循 DAC，包括其判别器和损失函数设计。

Acoustic Tokenizer 采用了变分自编码器（VAE）的原理。编码器将输入音频映射到潜在分布的参数，即均值。结合固定的标准差，随后使用重参数化技巧采样得到潜在向量。有关更多细节，请参阅技术报告。

用法

以下是用于编码和解码音频的示例用法：

import torch
from scipy.io import wavfile

from transformers import AutoFeatureExtractor, VibeVoiceAcousticTokenizerModel
from transformers.audio_utils import load_audio_librosa


model_id = "microsoft/VibeVoice-AcousticTokenizer"

# load model
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
model = VibeVoiceAcousticTokenizerModel.from_pretrained(model_id, device_map="auto")
print("Model loaded on device:", model.device)
print("Model dtype:", model.dtype)

# load audio
audio = load_audio_librosa(
    "https://huggingface.co/datasets/bezzam/vibevoice_samples/resolve/main/voices/en-Alice_woman.wav",
    sampling_rate=feature_extractor.sampling_rate,
)

# preprocess audio
inputs = feature_extractor(
    audio,
    sampling_rate=feature_extractor.sampling_rate,
    pad_to_multiple_of=3200,
).to(model.device, model.dtype)
print("Input audio shape:", inputs.input_values.shape)
# Input audio shape: torch.Size([1, 1, 224000])

with torch.no_grad():
    # set VAE sampling to False for deterministic output
    encoded_outputs = model.encode(inputs.input_values, sample=False)
    print("Latent shape:", encoded_outputs.latents.shape)
    # Latent shape: torch.Size([1, 70, 64])

    decoded_outputs = model.decode(**encoded_outputs)
    print("Reconstructed audio shape:", decoded_outputs.audio.shape)
    # Reconstructed audio shape: torch.Size([1, 1, 224000])

# Save audio
output_fp = "vibevoice_acoustic_tokenizer_reconstructed.wav"
wavfile.write(output_fp, feature_extractor.sampling_rate, decoded_outputs.audio.squeeze().float().cpu().numpy())
print(f"Reconstructed audio saved to : {output_fp}")

流式

对于流式 ASR 或 TTS，由于需要跟踪缓存状态，在对音频进行编码或解码时可以使用 use_cache 参数：

import torch
from scipy.io import wavfile

from transformers import AutoFeatureExtractor, VibeVoiceAcousticTokenizerModel
from transformers.audio_utils import load_audio_librosa


model_id = "microsoft/VibeVoice-AcousticTokenizer"

# load model
feature_extractor = AutoFeatureExtractor.from_pretrained(model_id)
model = VibeVoiceAcousticTokenizerModel.from_pretrained(model_id, device_map="auto")
print("Model loaded on device:", model.device)
print("Model dtype:", model.dtype)

# load audio
audio = load_audio_librosa(
    "https://huggingface.co/datasets/bezzam/vibevoice_samples/resolve/main/voices/en-Alice_woman.wav",
    sampling_rate=feature_extractor.sampling_rate,
)

# preprocess audio
inputs = feature_extractor(
    audio,
    sampling_rate=feature_extractor.sampling_rate,
    pad_to_multiple_of=3200,
).to(model.device, model.dtype)
print("Input audio shape:", inputs.input_values.shape)
# Input audio shape: torch.Size([1, 1, 224000])

# cache will be initialized after a first pass
encoder_cache = None
decoder_cache = None
with torch.no_grad():
    # set VAE sampling to False for deterministic output
    encoded_outputs = model.encode(inputs.input_values, sample=False, padding_cache=encoder_cache, use_cache=True)
    print("Latent shape:", encoded_outputs.latents.shape)
    # Latent shape: torch.Size([1, 70, 64])

    decoded_outputs = model.decode(encoded_outputs.latents, padding_cache=decoder_cache, use_cache=True)
    print("Reconstructed audio shape:", decoded_outputs.audio.shape)
    # Reconstructed audio shape: torch.Size([1, 1, 224000])

    # `padding_cache` can be extracted from the outputs for subsequent passes
    encoder_cache = encoded_outputs.padding_cache
    print("Number of cached encoder layers:", len(encoder_cache.per_layer_in_channels))
    # Number of cached encoder layers: 34
    decoder_cache = decoded_outputs.padding_cache
    print("Number of cached decoder layers:", len(decoder_cache.per_layer_in_channels))
    # Number of cached decoder layers: 34

# Save audio
output_fp = "vibevoice_acoustic_tokenizer_reconstructed.wav"
wavfile.write(output_fp, feature_extractor.sampling_rate, decoded_outputs.audio.squeeze().float().cpu().numpy())
print(f"Reconstructed audio saved to : {output_fp}")

VibeVoiceAcousticTokenizerConfig

class transformers.VibeVoiceAcousticTokenizerConfig

< 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 = Nonechannels: int = 1hidden_size: int = 64kernel_size: int = 7rms_norm_eps: float = 1e-05layer_scale_init_value: float = 1e-06initializer_range: float = 0.01num_filters: int = 32downsampling_ratios: list[int] | tuple[int, ...] = (2, 2, 4, 5, 5, 8)depths: list[int] | tuple[int, ...] = (3, 3, 3, 3, 3, 3, 8)hidden_act: str = 'gelu'ffn_expansion: int = 4vae_std: float = 0.625 )

参数

channels (int，可选，默认为 1) — 输入通道数。
hidden_size (int，可选，默认为 64) — 潜在表示的维度。
kernel_size (int，可选，默认为 7) — 卷积层的核大小。
rms_norm_eps (float，可选，默认为 1e-05) — RMS 归一化层使用的 epsilon 值。
layer_scale_init_value (float, 可选, 默认值为 1e-06) — 用于自注意力层的缩放值。基础模型使用 0.1，大型模型使用 1e-6。设置为 0 可禁用 layer scale。
initializer_range (float，可选，默认为 0.01) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
num_filters (int，可选，默认为 32) — 初始卷积层的滤波器数量，每次下采样后数量翻倍。
downsampling_ratios (List[int]，可选，默认为 [2, 2, 4, 5, 5, 8]) — 各层的下采样比率。
depths（List[int]，可选，默认为 [3, 3, 3, 3, 3, 3, 8]）— 每个阶段的 ConvNeXt 块数量。
hidden_act (str，可选，默认为 gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、 "relu"、"silu" 等。
ffn_expansion (int，可选，默认值为 4) — 前馈网络的扩展因子。
vae_std (float，可选，默认值为 0.625) — 当向编码器潜在表示添加噪声（sample=True）时，用于绘制每个样本噪声尺度的高斯分布的标准差。

这是用于存储 VibeVoiceAcousticTokenizerModel 配置的类。它根据指定的参数实例化 Vibevoice Acoustic Tokenizer 模型，并定义模型架构。使用默认值实例化配置将得到与 microsoft/VibeVoice-1.5B 类似的配置。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

示例：

>>> from transformers import VibeVoiceAcousticTokenizerModel, VibeVoiceAcousticTokenizerConfig

>>> # Initializing a VibeVoice Acoustic Tokenizer configuration
>>> configuration = VibeVoiceAcousticTokenizerConfig()

>>> # Initializing a model (with random weights)
>>> model = VibeVoiceAcousticTokenizerModel(configuration)

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

VibeVoiceAcousticTokenizerEncoderConfig

类 transformers.VibeVoiceAcousticTokenizerEncoderConfig

< source >

参数

channels (int，可选，默认为 1) — 输入通道数。
hidden_size (int，可选，默认为 64) — 潜在表示的维度。
kernel_size (int，可选，默认为 7) — 卷积层的核大小。
rms_norm_eps (float，可选，默认为 1e-05) — RMS 归一化层使用的 epsilon 值。
layer_scale_init_value (float, 可选, 默认值为 1e-06) — 用于自注意力层的缩放值。基础模型使用 0.1，大型模型使用 1e-6。设置为 0 可禁用 layer scale。
initializer_range (float，可选，默认为 0.01) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
num_filters (int，可选，默认为 32) — 初始卷积层的滤波器数量，每次下采样后数量翻倍。
downsampling_ratios (List[int]，可选，默认为 [2, 2, 4, 5, 5, 8]) — 各层的下采样比率。
depths（List[int]，可选，默认为 [3, 3, 3, 3, 3, 3, 8]）— 每个阶段的 ConvNeXt 块数量。
hidden_act (str，可选，默认为 gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、 "relu"、"silu" 等。
ffn_expansion (int，可选，默认值为 4) — 前馈网络的扩展因子。
vae_std (float，可选，默认值为 0.625) — 当向编码器潜在表示添加噪声（sample=True）时，用于绘制每个样本噪声尺度的高斯分布的标准差。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

VibeVoiceAcousticTokenizerDecoderConfig

类 transformers.VibeVoiceAcousticTokenizerDecoderConfig

< source >

参数

channels (int，可选，默认为 1) — 输入通道数。
hidden_size (int，可选，默认为 64) — 潜在表示的维度。
kernel_size (int，可选，默认为 7) — 卷积层的核大小。
rms_norm_eps (float，可选，默认为 1e-05) — RMS 归一化层使用的 epsilon 值。
layer_scale_init_value (float, 可选, 默认值为 1e-06) — 用于自注意力层的缩放值。基础模型使用 0.1，大型模型使用 1e-6。设置为 0 可禁用 layer scale。
initializer_range (float，可选，默认为 0.01) — 用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。
num_filters (int，可选，默认为 32) — 初始卷积层的滤波器数量，每次下采样后数量翻倍。
downsampling_ratios (List[int]，可选，默认为 [2, 2, 4, 5, 5, 8]) — 各层的下采样比率。
depths（List[int]，可选，默认为 [3, 3, 3, 3, 3, 3, 8]）— 每个阶段的 ConvNeXt 块数量。
hidden_act (str，可选，默认为 gelu) — 解码器中的非线性激活函数（函数或字符串）。例如，"gelu"、 "relu"、"silu" 等。
ffn_expansion (int，可选，默认值为 4) — 前馈网络的扩展因子。
vae_std (float，可选，默认值为 0.625) — 当向编码器潜在表示添加噪声（sample=True）时，用于绘制每个样本噪声尺度的高斯分布的标准差。

配置对象继承自 PreTrainedConfig，可用于控制模型输出。有关更多信息，请参阅 PreTrainedConfig 的文档。

VibeVoiceAcousticTokenizerFeatureExtractor

class transformers.VibeVoiceAcousticTokenizerFeatureExtractor

< source >

( feature_size = 1sampling_rate = 24000padding_value = 0.0normalize_audio = Truetarget_dB_FS = -25eps = 1e-06pad_to_multiple_of = 3200**kwargs )

参数

feature_size (int，可选，默认为 1) — 通道数。
sampling_rate (int, 可选，默认为 24000) — 用于对音频波形进行数字化的采样率，以赫兹（Hz）为单位。
padding_value (float，可选，默认为 0.0) — 用于填充的值。
normalize_audio (bool，可选，默认为 True) — 是否将音频归一化到目标 dB FS。
target_dB_FS (float，可选，默认为 -25) — 用于归一化的目标 dB FS。
eps (float, 可选，默认为 1e-06) — 用于在归一化时避免除以零的小数值。
pad_to_multiple_of (int，可选，默认值为 3200) — 将音频填充为该值的整数倍，该值应对应声学分词器的跳跃长度（hop length），即其编码器的下采样因子。

构建 VibeVoiceAcousticTokenizer 特征提取器。

call

< source >

( audio: typing.Union[numpy.ndarray, ForwardRef('torch.Tensor'), collections.abc.Sequence[numpy.ndarray], collections.abc.Sequence['torch.Tensor']]sampling_rate: int | None = Nonepadding: bool | str | transformers.utils.generic.PaddingStrategy | None = Truepad_to_multiple_of: int | None = Nonemax_length: int | None = Nonereturn_attention_mask: bool | None = Truereturn_tensors: str | None = 'pt'**kwargs )

参数

audio (np.ndarray, torch.Tensor, list[np.ndarray], list[torch.Tensor] — 要处理的序列或序列批次。每个序列可以是 numpy 数组、torch 张量、numpy 数组列表或 torch 张量列表。
sampling_rate (int, 可选) — audio 输入被采样时的采样率。强烈建议在 forward 调用时传入 sampling_rate，以避免静默错误。
padding (bool, str 或 PaddingStrategy, 可选, 默认为 True) — 选择一种策略，根据模型的填充侧和填充索引对返回的序列进行填充，可选策略如下：
- True 或 'longest'：填充至批次中最长的序列（如果仅提供单个序列，则不进行填充）。
- 'max_length'：填充至由参数 max_length 指定的最大长度；若未提供该参数，则填充至模型可接受的最大输入长度。
- False 或 'do_not_pad'（默认值）：不进行填充（即可以输出包含不同长度序列的批次）。
pad_to_multiple_of (int, 可选) — 如果设置，则将序列填充为所提供值的倍数。如果未提供，则默认为 self.pad_to_multiple_of。

VibeVoiceAcousticTokenizerModel

class transformers.VibeVoiceAcousticTokenizerModel

< source >

( config: VibeVoiceAcousticTokenizerConfig )

参数

config (VibeVoiceAcousticTokenizerConfig) — 模型的配置类，包含模型的所有参数。使用配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 from_pretrained() 方法以加载模型权重。

VibeVoice 声学分词器，包含用于连续声学 token 的编码器和解码器。

该模型继承自 PreTrainedModel。请查阅父类文档，了解该库为所有模型实现的通用方法（例如下载或保存、调整输入嵌入大小、剪枝头等）。

该模型也是 PyTorch torch.nn.Module 的子类。请将其作为常规的 PyTorch Module 使用，有关通用用法和行为的所有事项，请参阅 PyTorch 文档。

encode

< source >

( input_valuespadding_cache = Noneuse_cache = Nonesample = True )

参数

input_values（形状为 (batch_size, channels, sequence_length) 的 torch.Tensor）— 要编码为潜在表示的输入音频波形。
padding_cache (VibeVoiceAcousticTokenizerConv1dPaddingCache，可选) — 用于流式模式的缓存对象，用于在层间保持卷积状态。
use_cache (bool，可选) — 是否使用缓存来存储卷积状态。
sample (bool, 可选) — 是否向潜在变量添加高斯噪声（σ-VAE：噪声尺度从 N(0, config.vae_std) 中按批次项抽取）。如果为 False，则直接返回编码器输出。

decode

< source >

( latentspadding_cache = Noneuse_cache = False )

参数

latents（形状为 (batch_size, channels, sequence_length) 的 torch.Tensor）— 要解码回音频的输入潜在表示。
padding_cache (VibeVoiceAcousticTokenizerConv1dPaddingCache，可选) — 用于流式模式的缓存对象，用于在层间保持卷积状态。
use_cache (bool，可选) — 是否使用缓存来存储卷积状态。

forward

< source >

( input_valuespadding_cache = Noneuse_cache = Falsesample = True**kwargs )

参数

input_values（形状为 (batch_size, channels, sequence_length) 的 torch.Tensor）— 要编码为潜在表示的输入音频波形。
padding_cache (VibeVoiceAcousticTokenizerConv1dPaddingCache，可选) — 用于流式模式的缓存对象，用于在层间保持卷积状态。注意仅由解码器使用。
use_cache (bool，可选) — 是否使用缓存来存储卷积状态。
sample (bool, 可选) — 是否向潜在变量添加高斯噪声（σ-VAE：噪声尺度从 N(0, config.vae_std) 中按批次项抽取）。如果为 False，则直接返回编码器输出。