Transformers documentation
NeuCodec
이 모델은 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_valuestorch.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.configNeuCodecFeatureExtractor
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': TensorFlowtf.constant객체를 반환합니다.'pt': PyTorchtorch.Tensor객체를 반환합니다.'np': Numpynp.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: 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, 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