Transformers documentation
X-Codec2
Эта модель была опубликована в HF papers 06.02.2025 и добавлена в Hugging Face Transformers 25.06.2026.
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): В отличие от многослойного остаточного VQ, используемого в большинстве подходов (например, DAC, EnCodec, X-Codec, Mimi), X-Codec2 использует один слой скалярного квантования признаков (FSQ) для обеспечения стабильности и совместимости с каузальными авто-регрессивными LLM.
- Дизайн, удобный для трансформеров: одномерная структура токенов X-Codec2 естественным образом согласуется с авторегрессионным моделированием в LLM, таких как 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 мы наблюдали ускорение примерно в 1,35 раза при размере батча 4 (скрипт).
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
класс 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) — Это количество ключевых и value-голов, используемых для реализации Grouped Query Attention. Еслиnum_key_value_heads=num_attention_heads, модель использует Multi Head Attention (MHA); еслиnum_key_value_heads=1— Multi Query Attention (MQA); в остальных случаях применяется GQA. При конвертации мультиголовного чекпоинта в GQA-чекпоинт каждая групповая ключевая и value-голова должна построиться путём усреднения (meanpooling) всех исходных голов в этой группе. Дополнительные сведения см. в этой статье. Если значение не указано, по умолчанию используется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) — Значение epsilon, используемое слоями нормализации rms. - pad_token_id (
int, необязательный) — Идентификатор токена, используемого для выравнивания в словаре. - 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) — Использовать ли смещение (bias) в слоях проекции 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) — Частота дискретизации, с которой аудиофайлы должны быть оцифрованы, выраженная в герцах (Гц). - 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
класс transformers.Xcodec2FeatureExtractor
< source >( feature_size = 80sampling_rate = 16000padding_value = 1.0hop_length = 320**kwargs )
Параметры
- feature_size (
int, необязательный, по умолчанию 80) — Размерность признаков извлечённых признаков. - sampling_rate (
int, необязательный, по умолчанию 16000) — Частота дискретизации, с которой аудиофайлы должны быть оцифрованы, выраженная в герцах (Гц). - padding_value (
float, необязательный, по умолчанию 1.0) — Значение, используемое для заполнения векторов отступов в мел-спектрограмме. - hop_length (
int, необязательный, по умолчанию 320) — Количество аудиовыборок, кодируемых в каждом кадре. Эквивалентно произведению коэффициентов понижающей дискретизации. Необходимо для выравнивания входных данных акустического энкодера.
Создаёт экстрактор признаков 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]) — Массив Numpy или тензор torch с формой (num_channels, sequence_length). Для батча входных данных также можно передать список таких массивов или тензоров. - 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': возвращает объектыtf.constantTensorFlow.'pt': возвращает объектыtorch.TensorPyTorch.'np': возвращает объекты Numpynp.ndarray.
- sampling_rate (
int, необязательный) — Частота дискретизации, с которой была оцифрована входнаяaudio. Настоятельно рекомендуется передаватьsampling_rateпри вызове forward, чтобы избежать скрытых ошибок. - device (
str, необязательный, по умолчанию"cpu") — Устройство для тензоров PyTorch при извлечении признаков банка мел-фильтров. - kwargs (необязательный) — Остальные именованные аргументы в виде словаря, которые будут переданы в токенизатор или извлекатель признаков.
Xcodec2Model
класс transformers.Xcodec2Model
< source >( config: Xcodec2Config )
Параметры
- config (Xcodec2Config) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
Модель нейронного аудиокодека Xcodec2.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации 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 (
torch.LongTensorс формой(batch_size, 1, codes_length)) — Индексы дискретных кодов, вычисленные с помощьюmodel.encode. - latents (
torch.Tensorформы(batch_size, dimension, time_steps), необязательный) — Квантованное непрерывное представление входных данных.
Возвращает
Xcodec2DecoderOutput или tuple(torch.Tensor)
Xcodec2DecoderOutput или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (None) и входных данных.
- audio_values (
torch.Tensorформы(batch_size, 1, segment_length), необязательный) — Значения декодированной аудиоволны во временной области, полученные путём преобразования дискретных кодов обратно в непрерывные аудиосигналы. Это представляет собой реконструированный звук, который можно воспроизвести.
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 (
torch.Tensorформы(batch_size, 1, sequence_length)) — Входная аудиоволна. - input_features (
torch.Tensorформы(batch_size, mel_bins, time_steps)) — Входная мел-спектрограмма аудио для семантического кодирования. - padding_mask (
torch.Tensorформы(batch_size, 1, sequence_length)) — Маска отступов, используемая для дополненияinput_values. - input_features_mask (
torch.Tensorформы(batch_size, time_steps), необязательный) — Маска внимания для входных спектрограмм семантического энкодера.1для валидных кадров,0для заполнителей. - output_latents (
bool, необязательный, по умолчаниюFalse) — Указывает, следует ли возвращать непрерывное латентное представление из квантизатора.
Возвращает
Xcodec2EncoderOutput или tuple(torch.Tensor)
Xcodec2EncoderOutput или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (None) и входных данных.
- audio_codes (
torch.LongTensorформы(batch_size, 1, codes_length), необязательный) — Вложения дискретных кодов, вычисленные с помощьюmodel.encode. Они представляют собой сжатую, квантованную форму входного аудиосигнала, которую можно использовать для хранения, передачи или генерации. - latents (
torch.Tensorформы(batch_size, dimension, time_steps)) — Квантованное непрерывное представление эмбеддинга входных данных. - audio_codes_mask (
torch.int32формы(batch_size, 1, codes_length), необязательный) — Довыбранный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 (
torch.Tensorформы(batch_size, 1, sequence_length)) — Входная аудиоволна. - input_features (
torch.Tensorформы(batch_size, mel_bins, time_steps)) — Входная мел-спектрограмма аудио для семантического кодирования. - padding_mask (
torch.Tensorформы(batch_size, 1, sequence_length)) — Маска отступов, используемая для дополненияinput_values. - input_features_mask (
torch.Tensorформы(batch_size, time_steps), необязательный) — Маска внимания для входных спектрограмм семантического энкодера.1для валидных кадров,0для заполнителей. - output_latents (
bool, необязательный, по умолчаниюFalse) — Указывает, следует ли возвращать непрерывное латентное представление из квантизатора.
Возвращает
Xcodec2Output или tuple(torch.Tensor)
Xcodec2Output или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (None) и входных данных.
Метод forward модели Xcodec2Model переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
- audio_values (
torch.Tensorформы(batch_size, 1, sequence_length), необязательный) — Значения декодированной аудиоволны во временной области, полученные с помощью декодера Xcodec2. Эти значения представляют собой восстановленный аудиосигнал. - audio_codes (
torch.LongTensorформы(batch_size, 1, codes_length), необязательный) — Вложения дискретных кодов, вычисленные с помощьюmodel.encode. Это квантованные представления входного аудио, используемые для дальнейшей обработки или генерации. - latents (
torch.Tensorформы(batch_size, dimension, time_steps)) — Квантованное непрерывное представление эмбеддинга входных данных. - audio_codes_mask (
torch.int32формы(batch_size, 1, codes_length), необязательный) — Довыбранный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