Transformers documentation
xLSTM
이 모델은 2024-05-07에 HF papers에 게시되었으며, 2025-07-25에 Hugging Face Transformers에 기여되었습니다.
xLSTM
개요
xLSTM 모델은 Maximilian Beck, Korbinian Pöppel, Markus Spanring, Andreas Auer, Oleksandra Prudnikova, Michael Kopp, Günter Klambauer, Johannes Brandstetter, Sepp Hochreiter가 xLSTM: Extended Long Short-Term Memory에서 제안했습니다. xLSTM은 지수 게이팅, 행렬 메모리 확장, 병렬화 가능한 학습 및 데이터 입력을 도입하여 Transformer 모델과 경쟁할 수 있도록 기존 LSTM 아키텍처를 업데이트했습니다.
7B 모델 변형은 NXAI의 xLSTM 팀인 Maximilian Beck, Korbinian Pöppel, Phillip Lippe, Richard Kurle, Patrick Blies, Sebastian Böck, Sepp Hochreiter에 의해 학습되었습니다.
해당 논문의 초록은 다음과 같습니다:
1990년대, 상수 에러 캐러셀(constant error carousel)과 게이팅(gating)은 Long Short-Term Memory(LSTM)의 핵심 아이디어로 도입되었습니다. 이후 LSTM은 시대의 검증을 견뎌내며 수많은 딥러닝 성공 사례에 기여했으며, 특히 최초의 Large Language Model(LLM)을 구성했습니다. 그러나 병렬화가 가능한 self-attention을 핵심으로 하는 Transformer 기술의 등장은 새로운 시대의 시작을 알렸고, 대규모 환경에서 LSTM을 능가했습니다. 이제 우리는 단순한 질문을 제기합니다. 현대 LLM의 최신 기법을 활용하되 LSTM의 알려진 한계를 완화하면서, LSTM을 수십억 개의 파라미터 규모로 확장할 때 언어 모델링에서 얼마나 멀리 갈 수 있을까요? 첫째, 적절한 정규화 및 안정화 기법을 갖춘 지수 게이팅(exponential gating)을 도입합니다. 둘째, LSTM의 메모리 구조를 수정하여 다음을 얻습니다. (i) 스칼라 메모리, 스칼라 업데이트, 새로운 메모리 혼합을 갖춘 sLSTM, (ii) 행렬 메모리와 공분산 업데이트 규칙을 갖추고 완전히 병렬화 가능한 mLSTM. 이러한 LSTM 확장을 residual block 백본에 통합하면 xLSTM 블록이 생성되며, 이는 다시 residual 방식으로 쌓여 xLSTM 아키텍처를 구성합니다. 지수 게이팅과 수정된 메모리 구조는 xLSTM의 성능을 향상시켜, 성능과 스케일링 모두에서 최첨단 Transformer 및 State Space Model과 비교했을 때 유리한 결과를 보입니다.
이 모델은 NX-AI에서 기여했습니다. 원본 코드는 여기에서 찾을 수 있습니다.
The input is a single word "Notes". 참고
- 배치 생성에는 왼쪽 패딩을 사용합니다. 패딩 방향을 참조하세요.
xLSTMConfig
클래스 transformers.xLSTMConfig
< 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 = Nonevocab_size: int = 50304hidden_size: int = 4096embedding_dim: int | None = Nonenum_hidden_layers: int = 32num_blocks: int | None = Nonenum_heads: int = 8use_bias: bool = Falsenorm_reduction_force_float32: bool = Truetie_word_embeddings: bool = Falseadd_out_norm: bool = Truenorm_eps: float = 1e-06qk_dim_factor: float = 0.5v_dim_factor: float = 1.0chunkwise_kernel: typing.Literal['chunkwise--native_autograd', 'parallel--native_autograd'] = 'chunkwise--native_autograd'sequence_kernel: typing.Literal['native_sequence__native'] = 'native_sequence__native'step_kernel: typing.Literal['native'] = 'native'mode: typing.Literal['train', 'train_with_padding', 'inference'] = 'inference'chunk_size: int = 64return_last_states: bool = Trueautocast_kernel_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'bfloat16'eps: float = 1e-06inference_state_dtype: typing.Literal['float32', 'bfloat16', 'float16'] = 'float32'ffn_proj_factor: float = 2.667ffn_round_up_to_multiple_of: int = 64gate_soft_cap: float = 15.0output_logit_soft_cap: float = 30.0weight_mode: typing.Literal['single', 'fused'] = 'single'use_cache: bool = Truepad_token_id: int | None = 1bos_token_id: int | None = 0eos_token_id: int | list[int] | None = 2max_inference_chunksize: int = 16384 )
매개변수
- vocab_size (
int, 선택 사항, 기본값50304) — 모델의 어휘 크기입니다.input_ids로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다. - hidden_size (
int, 선택 사항, 기본값4096) — 숨겨진 표현의 차원입니다. - embedding_dim (
int, 선택 사항) — 임베딩 및 숨겨진 상태의 차원. - num_hidden_layers (
int, 선택 사항, 기본값32) — Transformer decoder의 숨겨진 레이어 수. - num_blocks (
int, 선택 사항, 선택 사항, 기본값 32) — xLSTM 모델의 블록 수입니다. None인 경우 num_hidden_layers를 사용합니다. - num_heads (
int, optional, 선택 사항, 기본값 8) — xLSTM Layer/Cell의 헤드 수입니다. - use_bias (
bool, optional, 선택 사항, 기본값False) — xLSTM 모델에서 bias를 사용할지 여부입니다. - norm_reduction_force_float32 (
bool, optional, 선택 사항, 기본값True) — float32 norm reduction 연산을 fp32 정밀도로 수행하도록 강제할지 여부. - tie_word_embeddings (
bool, 선택, 기본값False) — 모델의tied_weights_keys매핑에 따라 가중치 임베딩을 묶을지 여부. - add_out_norm (
bool, optional, 선택 사항, 기본값True) — LMHead 전에 블록 뒤에 출력 정규화를 추가할지 여부. - norm_eps (
float, 선택 사항, 기본값1e-06) — 레이어 정규화 레이어에서 사용되는 epsilon 값입니다. - qk_dim_factor (
float, optional, 선택 사항, 기본값 0.5) — 쿼리 및 키 차원의 스케일 팩터. - v_dim_factor (
float, optional, 선택 사항, 기본값 1.0) — value 차원의 스케일 팩터. - chunkwise_kernel (
ChunkwiseKernelType, optional, 선택 사항, 기본값"chunkwise--native_autograd") — chunkwise 처리 모드를 위한 Kernel 유형입니다. - sequence_kernel (
SequenceKernelType, optional, 선택 사항, 기본값"native_sequence__native") — 시퀀스 처리 모드의 Kernel 유형입니다. - step_kernel (
StepKernelType, optional, 선택 사항, 기본값"native") — step 처리 모드의 Kernel 유형입니다. - mode (
BackendModeType, 선택 사항, 선택 사항, 기본값"inference") — 작동 모드(생성을 위해 추론이 필요합니다). - chunk_size (
int, 선택 사항, 선택 사항, 기본값 64) — 내부 chunk 크기입니다. - return_last_states (
bool, optional, 선택 사항, 기본값True) — 마지막 상태/캐시를 내부적으로 반환할지 여부입니다. 생성 시 True로 설정해야 합니다. - autocast_kernel_dtype (
DtypeType, optional, 선택 사항, 기본값"bfloat16") — states에 사용할 Kernel dtype입니다. - eps (
float, 선택 사항, 기본값1e-06) — 레이어 정규화 레이어에서 사용되는 epsilon 값입니다. - inference_state_dtype (
DtypeType, optional, 선택 사항, 기본값"float32") — 추론 시 상태에 사용할 Kernel dtype입니다. - ffn_proj_factor (
float, optional, 선택 사항, 기본값 2.667) — 게이트드 Feed Forward 네트워크의 post-up projection 크기 계수입니다. - ffn_round_up_to_multiple_of (
int, optional, 선택 사항, 기본값 64) — 게이티드 Feed Forward 네트워크의 업 프로젝션 후 크기 요인 라운딩 값. - gate_soft_cap (
float, optional, 선택 사항, 기본값 15.0) — 게이트 소프트 캡 스케일입니다. - output_logit_soft_cap (
float, 선택 사항, 선택 사항, 기본값 30.0) — 출력 logit 소프트 캡 스케일입니다. - weight_mode (
Literal, 선택 사항, 기본값"single") — 병렬 선형 레이어를 분리할지, 아니면 결합(single)할지를 지정합니다. - use_cache (
bool, 선택 사항, 기본값True) — 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음).config.is_decoder=True인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다. - pad_token_id (
int, 선택 사항, 기본값1) — 어휘에서 패딩에 사용되는 토큰 ID입니다. - bos_token_id (
int, 선택 사항, 기본값0) — 어휘에서 스트림 시작에 사용되는 토큰 id입니다. - eos_token_id (
Union[int, list[int]], 선택 사항, 기본값2) — 어휘에서 스트림 종료에 사용되는 토큰 ID입니다. - max_inference_chunksize (
int, optional, 선택, 기본값 16384) — 메모리를 절약하기 위해 추론 시 청크 크기를 제한합니다.
이것은 xLSTMModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Xlstm 모델을 인스턴스화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 인스턴스화하면 NX-AI/xLSTM-7b와 유사한 구성이 생성됩니다.
Configuration 객체는 PreTrainedConfig를 상속하며 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 PreTrainedConfig의 문서를 참고하세요.
예:
>>> from transformers import xLSTMConfig, xLSTMModel
>>> # Initializing a xLSTM configuration
>>> configuration = xLSTMConfig()
>>> # Initializing a model (with random weights) from the configuration
>>> model = xLSTMModel(configuration)
>>> # Accessing the model configuration
>>> configuration = model.configxLSTMModel
클래스 transformers.xLSTMModel
< source >( config: xLSTMConfig )
매개변수
- config (xLSTMConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델에 연결된 가중치를 로드하지 않으며, 구성만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
특정 헤드가 위에 없는 Xlstm 모델로, 원시 hidden-state를 출력합니다.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.LongTensor] = Nonecache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → xLSTMOutput or tuple(torch.Tensor)
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- inputs_embeds (
torch.LongTensor, shape(batch_size, sequence_length, hidden_size), 선택) —input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다input_ids인덱스를 관련 벡터로 변환하는 방식을 더 세밀하게 제어하려는 경우에 유용합니다. - cache_params (
xLSTMCache, 선택 사항) — RNN 상태를 전달하는 xLSTMCache입니다. - use_cache (
bool, 선택 사항) —True로 설정하면past_key_values키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(past_key_values참조).
반환값
xLSTMOutput 또는 tuple(torch.Tensor)
xLSTMOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(xLSTMConfig)과 입력에 따라 다양한 요소를 포함합니다.
xLSTMModel의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
last_hidden_state (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택 사항) — 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.cache_params (
~models.xlstm.modeling_xlstm.xLSTMCache, 선택) — 마지막 시간 단계에서의 모델 상태입니다. 다음input_ids와 함께 forward 메서드에서 사용하여 이전input_ids를 제공하지 않도록 할 수 있습니다.hidden_states (
tuple[torch.Tensor], 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.
xLSTMLMHeadModel
클래스 transformers.xLSTMForCausalLM
< source >( config: xLSTMConfig )
매개변수
- config (xLSTMConfig) — 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델에 연결된 가중치를 로드하지 않으며, 구성만 로드합니다. 모델 가중치를 로드하려면 from_pretrained() 메서드를 확인하세요.
Xlstm 모델은 인과 언어 모델링에 사용됩니다.
이 모델은 PreTrainedModel에서 상속됩니다. 라이브러리가 모든 모델에 대해 구현하는 일반적 메서드(다운로드 또는 저장, 입력 임베딩 크기 조정, 헤드 프루닝 등)에 대한 세부 사항은 상위 클래스 문서를 확인하세요.
이 모델은 또한 PyTorch torch.nn.Module의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법 및 동작과 관련된 모든 사항은 PyTorch 문서를 참조하세요.
forward
< source >( input_ids: typing.Optional[torch.LongTensor] = Noneinputs_embeds: typing.Optional[torch.Tensor] = Nonecache_params: transformers.models.xlstm.modeling_xlstm.xLSTMCache | None = Nonelabels: typing.Optional[torch.LongTensor] = Noneuse_cache: bool | None = None**kwargs: *<class 'transformers.utils.generic.TransformersKwargs'> ) → xLSTMCausalLMOutput or tuple(torch.Tensor)
매개변수
- input_ids (
torch.LongTensor형상이(batch_size, sequence_length), 선택 사항) — 어휘(input vocabulary)에서 입력 시퀀스 토큰의 인덱스입니다. 기본적으로 패딩은 무시됩니다.AutoTokenizer를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 PreTrainedTokenizer.encode() 및 PreTrainedTokenizer.call()를 참조하세요.
- inputs_embeds (
torch.Tensor, shape(batch_size, sequence_length, hidden_size), 선택) —input_ids를 전달하는 대신 임베딩 표현을 직접 전달할 수 있습니다. 이는 모델 내부의 임베딩 조회 행렬보다input_ids인덱스를 관련 벡터로 변환하는 방식에 대해 더 세밀한 제어가 필요한 경우에 유용합니다. - cache_params (
xLSTMCache, 선택 사항) — RNN 상태를 전달하는 xLSTMCache입니다. - labels (
torch.LongTensor, shape(batch_size, sequence_length), 선택 사항) — 마스크 언어 모델링 손실을 계산하는 데 사용되는 라벨입니다. 인덱스는[0, ..., config.vocab_size]범위 내의 값이거나 -100이어야 합니다(input_idsdocstring 참조). 인덱스가-100으로 설정된 토큰은 무시(마스크)되며, 손실은[0, ..., config.vocab_size]범위의 라벨을 가진 토큰에 대해서만 계산됩니다. - use_cache (
bool, 선택 사항) —True로 설정하면past_key_values키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(past_key_values참조).
반환값
xLSTMCausalLMOutput 또는 tuple(torch.Tensor)
xLSTMCausalLMOutput 또는 torch.Tensor의 튜플(return_dict=False가 전달되었거나 config.return_dict=False인 경우)로, 구성(xLSTMConfig)과 입력에 따라 다양한 요소를 포함합니다.
xLSTMForCausalLM의 forward 메서드는 __call__ 특수 메서드를 오버라이드합니다.
이 함수 내에서 forward pass의 레시피를 정의해야 하지만, 이후에는 이 함수 대신
Module인스턴스를 호출해야 합니다. 전자는 전처리 및 후처리 단계를 실행하는 것을 처리하는 반면, 후자는 이를 조용히 무시하기 때문입니다.
loss (
torch.Tensor, shape(1,), 선택 사항,labels이 제공될 때 반환됨) — 언어 모델링 손실(다음 토큰 예측용).logits (
torch.Tensor, shape(batch_size, sequence_length, config.vocab_size)) — 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).cache_params (
xLSTMCache, 선택, RNN 상태를 포함) — 마지막 시간 단계에서의 모델 상태입니다. 다음input_ids와 함께 forward 메서드에서 사용하여 이전input_ids를 제공하지 않아도 됩니다.hidden_states (
tuple[torch.Tensor], 선택 사항,output_hidden_states=True가 전달되거나config.output_hidden_states=True인 경우 반환됨) —torch.Tensor의 튜플(모델에 임베딩 레이어가 있는 경우 임베딩 출력 1개 + 각 레이어의 출력 1개)로, 모양은(batch_size, sequence_length, hidden_size)입니다.각 레이어의 출력에서 모델의 Hidden-states와 선택적 초기 임베딩 출력을 포함합니다.