Transformers documentation
NeuCodec
Эта модель была опубликована в HF papers 11.09.2025 и добавлена в Hugging Face Transformers 02.09.2026.
NeuCodec
Обзор
Модель NeuCodec была предложена в работе Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-rates.
NeuCodec — это нейронный аудиокодек, расширяющий возможности XCodec2. Он использует следующие возможности:
- Квантование конечных скаляров (FSQ), приводящее к одной книге кодов, что делает его идеальным для дальнейшего моделирования с помощью речевых языковых моделей.
- Обучен на данных CC, поэтому не содержит ограничений, связанных с некоммерческим использованием.
- При скорости 50 токенов/с и 16 битах на токен общая скорость передачи составляет 0.8 кбит/с.
- Кодировщик принимает входной сигнал частотой 16 кГц и выдает сигнал частотой 24 кГц с помощью декодера с повышением частоты дискретизации.
- Схема кодирования FSQ обеспечивает устойчивость к ошибкам на уровне битов, что делает её пригодной для работы в ненадёжных и зашумлённых каналах.
Исходный код моделирования можно найти здесь.
Пример использования
Вот краткий пример того, как закодировать и декодировать аудио с помощью этой модели:
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel
model_id = "neuphonic/neucodec"
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, 292])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)
# 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 = "neuphonic/neucodec"
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, 292])
audio_values = model.decode(audio_codes).audio_values
print("Audio values shape:", audio_values.shape)
# 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. Первые несколько вызовов будут медленнее из-за накладных расходов на компиляцию, но последующие вызовы будут выполняться быстрее.
import torch
from datasets import Audio, load_dataset
from transformers import AutoFeatureExtractor, AutoModel
batch_size = 4
model_id = "neuphonic/neucodec"
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)NeuCodecConfig
класс transformers.NeuCodecConfig
< 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 = Noneactivation_dropout: float = 0.1quantization_dim: int = 2048quantization_levels: list[int] | tuple[int, ...] = (4, 4, 4, 4, 4, 4, 4, 4)input_sampling_rate: int = 16000output_sampling_rate: int = 24000 )
Параметры
- 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). - activation_dropout (
float, необязательный, по умолчанию0.1) — Коэффициент dropout для активаций внутри полносвязного слоя. - quantization_dim (
int, необязательный, по умолчанию 2048) — Размерность для кодовой книги векторного квантования. - quantization_levels (
list[int], необязательный, по умолчанию[4, 4, 4, 4, 4, 4, 4, 4]) — Уровни для кодовой книги векторного квантования. - input_sampling_rate (
int, необязательный, по умолчанию 16000) — Частота дискретизации входной аудиоволны энкодера, в герцах (Гц). - output_sampling_rate (
int, необязательный, по умолчанию 24000) — Частота дискретизации (в герцах, Гц) выходной аудиоволны декодера.
Это класс конфигурации для хранения настроек модели NeuCodecModel. Он используется для создания модели Neucodec в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации neuphonic/neucodec
Объекты конфигурации наследуются от PreTrainedConfig и могут использоваться для управления выводами модели. Подробнее читайте в документации PreTrainedConfig.
Пример:
>>> from transformers import NeuCodecConfig, NeuCodecModel
>>> # Initializing configuration
>>> configuration = NeuCodecConfig()
>>> # Initializing a model (with random weights) from the configuration
>>> model = NeuCodecModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configNeuCodecFeatureExtractor
класс transformers.NeuCodecFeatureExtractor
< 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) — Количество аудиовыборок, кодируемых в каждом кадре. Эквивалентно произведению коэффициентов понижающей дискретизации. Необходимо для выравнивания входных данных акустического энкодера.
Создаёт экстрактор признаков NeuCodec, который вычисляет признаки mel-фильтробанка для семантического энкодера и дополненный аудио для акустического энкодера.
Этот экстрактор признаков наследуется от 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 (необязательный) — Остальные именованные аргументы в виде словаря, которые будут переданы в токенизатор или извлекатель признаков.
NeuCodecModel
класс transformers.NeuCodecModel
< source >( config: NeuCodecConfig )
Параметры
- config (NeuCodecConfig) — Класс конфигурации модели, содержащий все параметры модели. Инициализация по файлу конфигурации не загружает веса, связанные с моделью, а только конфигурацию. Чтобы загрузить веса модели, используйте метод from_pretrained().
Модель нейрального аудиокодека NeuCodec.
Эта модель наследуется от PreTrainedModel. См. документацию родительского класса для общих методов, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка голов и т. д.)
Эта модель также является подклассом torch.nn.Module в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.
decode
< source >( audio_codes: typing.Optional[torch.Tensor] = Nonelatents: typing.Optional[torch.Tensor] = Noneaudio_codes_mask: typing.Optional[torch.Tensor] = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → NeuCodecDecoderOutput or tuple(torch.Tensor)
Параметры
- audio_codes (
torch.LongTensorс формой(batch_size, 1, codes_length)) — Индексы дискретных кодов, вычисленные с помощьюmodel.encode. - latents (
torch.Tensorформы(batch_size, dimension, time_steps), необязательный) — Квантованное непрерывное представление входных данных. - audio_codes_mask (
torch.Tensorформы(batch_size, codes_length), необязательный) — Маска, отмечающая валидные (не заполняющие) позиции, как возвращаемаяmodel.encode. Необходима для корректного пакетного декодирования аудио переменной длины.
Возвращает
NeuCodecDecoderOutput или tuple(torch.Tensor)
NeuCodecDecoderOutput или кортеж из
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'> ) → NeuCodecEncoderOutput 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) — Указывает, следует ли возвращать непрерывное латентное представление из квантизатора.
Возвращает
NeuCodecEncoderOutput или tuple(torch.Tensor)
NeuCodecEncoderOutput или кортеж из
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'> ) → NeuCodecOutput or tuple(torch.Tensor)
Параметры
- input_values (
torch.Tensorформы(batch_size, 1, sequence_length)) — Входная аудиоволна, оцифрованная с частотойconfig.input_sampling_rate. - 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) — Указывает, следует ли возвращать непрерывное латентное представление из квантизатора.
Возвращает
NeuCodecOutput или tuple(torch.Tensor)
NeuCodecOutput или кортеж из
torch.Tensor (если передано return_dict=False или если config.return_dict=False), содержащий различные
элементы в зависимости от конфигурации (None) и входных данных.
Метод NeuCodecModel forward переопределяет специальный метод __call__.
Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр
Module, а не эту функцию, поскольку первый вариант обеспечивает выполнение шагов предварительной и последующей обработки, тогда как второй молча их игнорирует.
- audio_values (
torch.Tensorформы(batch_size, 1, sequence_length), необязательный) — Значения декодированной аудиоволны во временной области, полученные с помощью декодера NeuCodec. Эти значения представляют собой восстановленный аудиосигнал. - 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, NeuCodecModel
>>> dataset = load_dataset("hf-internal-testing/librispeech_asr_dummy", "clean", split="validation")
>>> audio = dataset["train"]["audio"][0]["array"]
>>> model_id = "neuphonic/neucodec"
>>> model = NeuCodecModel.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 # sampled at 24kHz