Transformers documentation
X-Codec2
이 모델은 2025-02-06에 HF papers에 게시되었으며, 2026-06-25에 Hugging Face Transformers에 기여되었습니다.
X-Codec2
개요
X-Codec2 모델은 Llasa: Scaling Train-Time and Inference-Time Compute for Llama-based Speech Synthesis에서 제안되었습니다.
X-Codec2는 대규모 언어 모델(LLM) 파이프라인의 음성 합성 및 일반 오디오 생성을 개선하도록 설계된 신경 오디오 코덱입니다. X-Codec2는 의미론적 정보와 음향 정보를 통합하고 토큰화하는 방식을 개선하여, 효율적이고 고충실도의 오디오 표현을 가능하게 합니다.
아키텍처에 대해:
- 통합 시맨틱-음향 토큰화: X-Codec2는 시맨틱 인코더(예: Wav2Vec2-BERT)와 음향 인코더의 출력을 하나의 임베딩으로 융합하여, 고수준 의미(예: 텍스트 내용, 감정)와 저수준 오디오 디테일(예: 음색)을 모두 포착합니다.
- 단일 단계 Feature Scalar Quantization (FSQ): 대부분의 접근 방식(예: DAC, EnCodec, X-Codec, Mimi)에서 사용되는 다층 residual VQ와 달리, X-Codec2는 안정성과 causal, autoregressive LLM과의 호환성을 위해 단일 레이어의 Feature Scalar Quantization (FSQ)를 사용합니다.
- Transformer 친화적 설계: X-Codec2의 1D 토큰 구조는 LLaMA와 같은 LLM의 자기회귀 모델링과 자연스럽게 정렬되어 학습 효율과 다운스트림 호환성을 높입니다.
모델 체크포인트는 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_valuestorch.compile을 통한 속도 향상
torch.compile를 사용하면 추론 속도를 높일 수 있습니다. 컴파일 오버헤드로 인해 처음 몇 번의 호출은 느릴 수 있지만, 이후 호출은 더 빨라집니다.
A100에서 배치 크기가 4일 때 약 1.35배의 속도 향상을 관찰했습니다(스크립트).
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 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) 모델의 설정 객체 인스턴스입니다. - sampling_rate (
int, 선택 사항, 기본값16000) — 오디오 파일을 디지털화할 때 사용할 샘플링 주파수입니다. 헤르츠(Hz) 단위로 표시됩니다. - 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]) — 벡터 양자화 코드북의 레벨입니다.
이것은 Xcodec2Model의 설정을 저장하기 위한 설정 클래스입니다. 지정된 인자에 따라 Xcodec2 모델을 인스턴스화하고 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 설정을 인스턴스화하면 HKUSTAudio/xcodec2-hf와 유사한 설정이 생성됩니다.
Configuration 객체는 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
class transformers.Xcodec2FeatureExtractor
< 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) — 프레임당 인코딩되는 오디오 샘플 수. 다운샘플링 비율의 곱과 동일합니다. 음향 인코더 입력 패딩에 필요합니다.
…
이 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 사전입니다.
Xcodec2Model
클래스 transformers.Xcodec2Model
< source >( config: Xcodec2Config )
매개변수
- config (Xcodec2Config) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 연관된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
Xcodec2 신경 오디오 코덱 모델.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 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, shape(batch_size, 1, codes_length)) —model.encode를 사용하여 계산된 이산 코드 인덱스. - latents (
torch.Tensor, shape(batch_size, dimension, time_steps), 선택 사항) — 입력의 양자화 연속 표현입니다.
반환값
Xcodec2DecoderOutput 또는 tuple(torch.Tensor)
Xcodec2DecoderOutput 또는 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'> ) → Xcodec2EncoderOutput 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 표현을 반환할지 여부입니다.
반환값
Xcodec2EncoderOutput 또는 tuple(torch.Tensor)
Xcodec2EncoderOutput 또는 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'> ) → Xcodec2Output 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 표현을 반환할지 여부입니다.
반환값
Xcodec2Output 또는 tuple(torch.Tensor)
Xcodec2Output 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(None)과 입력에 따라 다양한 요소를 포함합니다.
Xcodec2Model의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
- audio_values (
torch.Tensor, shape(batch_size, 1, sequence_length), 선택 사항) — Xcodec2의 decoder 부분을 사용하여 시간 영역에서 얻은 디코딩된 오디오 웨이브폼 값입니다. 이는 재구성된 오디오 신호를 나타냅니다. - 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, 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