이 모델은 2025-09-11에 HF papers에 게시되었으며, 2026-09-02에 Hugging Face Transformers에 기여되었습니다.

NeuCodec

개요

NeuCodec 모델은 Finite Scalar Quantization Enables Redundant and Transmission-Robust Neural Audio Compression at Low Bit-rates에서 제안되었습니다.

NeuCodec은 XCodec2를 확장한 신경 오디오 코덱입니다. 다음 기능을 활용합니다:

단일 코드북을 생성하는 Finite Scalar Quantization(FSQ) 양자화는 Speech Language Models를 활용한 다운스트림 모델링에 이상적입니다.
비상업적 데이터 제한이 없도록 CC 데이터로 학습되었습니다.
초당 50개 토큰, 토큰당 16비트로 전송할 경우 전체 비트레이트는 0.8kbps입니다.
코덱은 16kHz 입력을 받아 업샘플링 디코더를 사용해 24kHz를 출력합니다.
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 decoder의 각 attention layer에 사용할 attention head의 수입니다.
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 헤드는 해당 그룹 내 모든 원래 헤드를 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) — rms 정규화 레이어에서 사용되는 epsilon 값입니다.
pad_token_id (int, 선택 사항) — 어휘에서 패딩에 사용되는 토큰 ID입니다.
tie_word_embeddings (bool, 선택, 기본값 False) — 모델의 tied_weights_keys 매핑에 따라 가중치 임베딩을 묶을지 여부.
rope_parameters (Union[~modeling_rope_utils.RopeParameters, dict], 선택) — RoPE 임베딩의 구성 매개변수를 포함하는 사전입니다. 사전에는 rope_theta 값이 포함되어야 하며, 더 긴 max_position_embeddings로 RoPE를 사용하려는 경우 스케일링에 사용되는 매개변수를 선택적으로 포함할 수 있습니다.
attention_bias (bool, 선택 사항, 기본값 False) — 자기 주의(self-attention) 시 query, key, value 및 출력 투영 계층에 bias를 사용할지 여부입니다.
attention_dropout (Union[int, float], 선택 사항, 기본값 0.0) — Attention 확률에 적용할 dropout 비율입니다.
head_dim (int, 선택 사항, 기본값 64) — Attention head의 차원입니다. 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], 선택) — semantic (Wav2Vec2BertConfig) 모델의 설정 객체 인스턴스입니다.
activation_dropout (float, 선택 사항, 기본값 0.1) — fully connected layer 내부 activation에 적용할 dropout 비율입니다.
quantization_dim (int, 선택 사항, 기본값 2048) — 벡터 양자화 코드북의 차원.
quantization_levels (list[int], 선택 사항, 기본값 [4, 4, 4, 4, 4, 4, 4, 4]) — 벡터 양자화 코드북의 레벨입니다.
input_sampling_rate (int, 선택 사항, 기본값 16000) — 인코더의 입력 오디오 웨이브폼 샘플링 주파수(Hz).
output_sampling_rate (int, 선택 사항, 기본값 24000) — 디코더 출력 오디오 웨이브폼의 샘플링 주파수(Hz).

이것은 NeuCodecModel의 설정을 저장하기 위한 설정 클래스입니다. 지정된 인자에 따라 Neucodec 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 설정을 인스턴스화하면 neuphonic/neucodec와 유사한 설정이 생성됩니다.

Configuration 객체는 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.config

NeuCodecFeatureExtractor

class transformers.NeuCodecFeatureExtractor

< source >

( feature_size = 80sampling_rate = 16000padding_value = 1.0hop_length = 320**kwargs )

매개변수

feature_size (int, 선택 사항, 기본값 80) — 추출된 특징의 차원입니다.
sampling_rate (int, 선택 사항, 기본값 16000) — 오디오 파일을 디지털화할 때 사용할 샘플링 레이트(헤르츠(Hz) 단위).
padding_value (float, 선택 사항, 기본값 1.0) — 멜 스펙트로그램의 패딩 벡터를 채우는 데 사용되는 값입니다.
hop_length (int, 선택 사항, 기본값 320) — 프레임당 인코딩되는 오디오 샘플 수. 다운샘플링 비율의 곱과 동일합니다. 음향 인코더 입력 패딩에 필요합니다.

의미 인코더를 위한 mel-filter bank 특징과 음향 인코더를 위한 패딩된 오디오를 계산하는 NeuCodec 특징 추출기를 생성합니다.

이 feature extractor는 대부분의 주요 메서드를 포함하는 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]) — shape가 (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로 잘라내는 truncation을 활성화합니다.
return_tensors (str 또는 TensorType, 선택 사항) — 설정된 경우, Python 정수 목록 대신 텐서를 반환합니다. 허용되는 값은 다음과 같습니다:
- 'tf': TensorFlow tf.constant 객체를 반환합니다.
- 'pt': PyTorch torch.Tensor 객체를 반환합니다.
- 'np': Numpy np.ndarray 객체를 반환합니다.
sampling_rate (int, 선택 사항) — audio 입력이 샘플링된 샘플링 레이트입니다. 조용한 오류를 방지하려면 forward 호출 시 sampling_rate를 전달하는 것이 강력히 권장됩니다.
device (str, 선택 사항, 기본값 "cpu") — Mel 필터 뱅크 특징 추출 시 PyTorch 텐서에 사용할 장치.
kwargs (선택) — 토크나이저 또는 feature extractor에 전달될 나머지 keyword argument 사전입니다.

NeuCodecModel

클래스 transformers.NeuCodecModel

< source >

( config: NeuCodecConfig )

매개변수

config (NeuCodecConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.

NeuCodec 신경 오디오 코덱 모델.

이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.

이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 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, shape (batch_size, 1, codes_length)) — model.encode를 사용하여 계산된 이산 코드 인덱스.
latents (torch.Tensor, shape (batch_size, dimension, time_steps), 선택 사항) — 입력의 양자화 연속 표현입니다.
audio_codes_mask (torch.Tensor, shape (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, shape (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, shape (batch_size, 1, sequence_length)) — 입력 오디오 웨이브폼.
input_features (torch.Tensor, shape (batch_size, mel_bins, time_steps)) — 의미 인코딩을 위한 입력 오디오 멜 스펙트로그램.
padding_mask (torch.Tensor, shape (batch_size, 1, sequence_length)) — input_values에 패딩을 적용하는 데 사용되는 패딩 마스크입니다.
input_features_mask (torch.Tensor, shape (batch_size, time_steps), 선택 사항) — 의미 인코더에 입력되는 스펙트로그램의 어텐션 마스크입니다. 유효한 프레임은 1, 패딩은 0입니다.
output_latents (bool, 선택 사항, 기본값 False) — quantizer에서 생성된 연속형 latent 표현을 반환할지 여부입니다.

반환값

NeuCodecEncoderOutput 또는 tuple(torch.Tensor)

NeuCodecEncoderOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(None)과 입력에 따라 다양한 요소를 포함합니다.

audio_codes (torch.LongTensor, shape (batch_size, 1, codes_length), 선택 사항) — model.encode를 사용하여 계산된 이산 코드 임베딩입니다. 이는 저장, 전송 또는 생성에 사용할 수 있는 입력 오디오 신호의 압축 및 양자화된 형태를 나타냅니다.
latents (torch.Tensor, shape (batch_size, dimension, time_steps)) — 입력 임베딩의 양자화 연속 표현.
audio_codes_mask (torch.int32, shape (batch_size, 1, codes_length), 선택 사항) — audio_codes에서 유효한 오디오 코드를 나타내기 위한 다운샘플링된 padding_mask입니다.

forward

< source >

매개변수

input_values (torch.Tensor, shape (batch_size, 1, sequence_length)) — config.input_sampling_rate로 샘플링된 입력 오디오 웨이브폼입니다.
input_features (torch.Tensor, shape (batch_size, mel_bins, time_steps)) — 의미 인코딩을 위한 입력 오디오 멜 스펙트로그램.
padding_mask (torch.Tensor, shape (batch_size, 1, sequence_length)) — input_values에 패딩을 적용하는 데 사용되는 패딩 마스크입니다.
input_features_mask (torch.Tensor, shape (batch_size, time_steps), 선택 사항) — 의미 인코더에 입력되는 스펙트로그램의 어텐션 마스크입니다. 유효한 프레임은 1, 패딩은 0입니다.
output_latents (bool, 선택 사항, 기본값 False) — quantizer에서 생성된 연속형 latent 표현을 반환할지 여부입니다.

반환값

NeuCodecOutput 또는 tuple(torch.Tensor)

NeuCodecOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(None)과 입력에 따라 다양한 요소를 포함합니다.

NeuCodecModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.

이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신 Module 인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.

audio_values (torch.Tensor, shape (batch_size, 1, sequence_length), 선택 사항) — NeuCodec의 디코더 부분을 사용하여 시간 영역에서 얻은 디코딩된 오디오 웨이브폼 값입니다. 이는 재구성된 오디오 신호를 나타냅니다.
audio_codes (torch.LongTensor, shape (batch_size, 1, codes_length), 선택 사항) — model.encode를 사용하여 계산된 이산 코드 임베딩입니다. 이는 추가 처리 또는 생성에 사용되는 입력 오디오의 양자화 표현입니다.
latents (torch.Tensor, shape (batch_size, dimension, time_steps)) — 입력 임베딩의 양자화 연속 표현.
audio_codes_mask (torch.int32, shape (batch_size, 1, codes_length), 선택 사항) — audio_codes에서 유효한 오디오 코드를 나타내기 위한 다운샘플링된 padding_mask입니다.

예:

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

Update on GitHub