# HRM-Text

## 개요

HRM-Text는 Sapient AI 팀의 계층적 추론 모델(HRM, [Hierarchical Reasoning Model](https://huggingface.co/papers/2506.21734))의 개선된 자기회귀 언어 모델링 변형입니다. 이는 *계층적 재귀* 전방을 사용하는 베이스 모델로, 두 개의 트랜스포머 스택(`H`는 느리고 추상적인 계획, `L`는 빠르고 상세한 계산에 사용)이 중첩된 재귀 구조 안에서 재사용됩니다:

```
for h in range(H_cycles):
    for l in range(L_cycles):
        z_L = L(z_L + z_H)
    z_H = H(z_H + z_L)
```

아키텍처 특성:

- **PrefixLM attention**: instruction 토큰은 양방향으로, response 토큰은 인과적으로 attend합니다. `config.prefix_lm`(기본값 `True`)로 제어되며, 정형화된 형태는 [4D-masks 블로그](https://huggingface.co/blog/poedator/4d-masks) / [FlexAttention 블로그](https://pytorch.org/blog/flexattention/)를 참고하세요.
- `o_proj`에 적용되기 전 attention 출력에 적용되는 **헤드별 sigmoid 출력 게이트**(Qwen3-Next 스타일; [`Qwen3NextAttention`](./qwen3_next) 참조). 단일 융합된 `gqkv_proj`로 저장된 레거시 체크포인트는 등록된 HRM-Text 체크포인트 변환 매핑에 의해 로드 시 `gate_proj` / `q_proj` / `k_proj` / `v_proj`로 분리됩니다.
- **매개변수 없는 RMSNorm** — 학습 가능한 scale이 없는 `F.rms_norm`.
- **`L_bp_cycles`** — HRM의 *k-step grad trick*입니다. 학습 시 `L_cycles`의 저수준 반복 중 마지막 `L_bp_cycles[i]`개만 그래디언트를 전파하며, 이전 반복은 `torch.no_grad()` 아래에서 실행되어 활성화 값이 저장되지 않습니다. 추론 시에는 영향이 없습니다.

## 사용

HRM-Text-1B는 **기본 언어 모델**입니다. `chat_template`이 제공되지 않으며, 이번 릴리스에서는 `apply_chat_template`가 의도적으로 지원되지 않습니다. 사전 학습에 사용된 프롬프트 형식은 아직 발전 중이며, 안정적인 채팅 템플릿을 갖춘 지시 학습 변형은 별도의 릴리스로 제공될 예정입니다. 기본 모델은 일반 `AutoTokenizer` + `AutoModelForCausalLM.generate(...)`를 통해 구동하세요:

```python
from transformers import AutoTokenizer, AutoModelForCausalLM

tokenizer = AutoTokenizer.from_pretrained("sapientinc/HRM-Text-1B")
model = AutoModelForCausalLM.from_pretrained(
    "sapientinc/HRM-Text-1B", device_map="auto",
)

inputs = tokenizer("The quick brown fox", return_tensors="pt").to(model.device)
out = model.generate(**inputs, max_new_tokens=16, do_sample=False)
print(tokenizer.decode(out[0], skip_special_tokens=True))
```

### Attention 백엔드

`"sdpa"`가 기본값이며 대부분의 워크로드에 적합한 선택입니다. `"flex_attention"`도 지원되며 긴 컨텍스트에서 이점을 제공하지만, HRM-Text의 재귀 스택 재사용에서 기대할 수 있는 이점을 상쇄할 만큼 고정된 BlockMask 구성 비용이 각 forward마다 발생합니다. 공개된 1.2B base checkpoint와 기본값인 `H_cycles=2`, `L_cycles=3` 설정에서 단일 H100 기준의 참고용 prefill 지연 시간은 다음과 같습니다:

| seq_len | sdpa     | flex_attention | 권장 |
|---------|----------|----------------|----------------|
|   64    |  41 ms   |  70 ms         | sdpa           |
|  256    |  41 ms   |  70 ms         | sdpa           |
| 1024    |  42 ms   |  69 ms         | sdpa           |
| 2048    |  85 ms   |  78 ms         | flex (약 1.1배)  |

작업 부하에 따라 백엔드를 선택하세요:

```python
# Default — short / medium context
model = AutoModelForCausalLM.from_pretrained("sapientinc/HRM-Text-1B", device_map="auto")

# Long context (≥ 2K tokens) — FlexAttention's per-block sparsity overtakes SDPA
model = AutoModelForCausalLM.from_pretrained(
    "sapientinc/HRM-Text-1B", device_map="auto", attn_implementation="flex_attention",
)
```

두 백엔드는 동등한 logits를 생성합니다(토치 참조와 end-to-end top-1 100% 일치 확인). `"eager"`도 지원되며 동일한 logits를 생성하지만, 최신 하드웨어에서 가장 빠른 옵션인 경우는 드뭅니다. 주요 용도는 `output_attentions=True`입니다. SDPA / FlexAttention은 헤드별 attention weights를 반환하지 않으므로, 분석이나 시각화를 위해 이를 필요로 하는 패스는 `attn_implementation="eager"`로 실행해야 합니다.

> [!WARNING]
> FlashAttention의 모든 변형 — `flash_attention_*` 네이밍 규칙을 따르지 않을 수 있는 FA 2/3/4 및 HF Hub 커널 구현을 포함 — 은 `config.prefix_lm=True`(기본값)인 경우 [HrmTextModel](/docs/transformers/v5.23.0/ko/model_doc/hrm_text#transformers.HrmTextModel) 초기화 시 거부됩니다. FA 백엔드는 causal 및 non-causal 마스크만 지원하며 PrefixLM 4-D 오버레이를 표현할 수 없습니다. PrefixLM에는 `"sdpa"`(기본값) 또는 `"flex_attention"`를 사용하세요. `config.prefix_lm=False`로 설정하면 마스크가 순수 causal로 변경되어 FA가 다시 활성화됩니다. 이는 FA가 가장 빠른 옵션인 causal 전용 fine-tuning 또는 추론 경로에 유용합니다.

### PrefixLM 학습

지시/응답 경계를 준수하는 감독 기반 미세 조정(supervised fine-tuning)을 수행하려면, 데이터 콜레이터(data collator)에서 `input_ids`와 함께 `token_type_ids`를 출력해야 합니다. 지시(instruction) 내부 위치에는 `1`, 응답(response) 및 패딩(padding) 위치에는 `0`을 할당합니다. 모델은 `token_type_ids == 1`인 모든 위치를 단일 양방향(bidirectional) 블록의 일부로 취급하며, 나머지 위치는 인과(causal) 방식으로 처리됩니다:

```python
import torch

def collate_prefixlm(batch, pad_token_id=0, ignore_label_id=-100):
    """`batch[i] = {"instruction_ids": [...], "response_ids": [...]}`."""
    full_ids = [b["instruction_ids"] + b["response_ids"] for b in batch]
    prefix_lens = [len(b["instruction_ids"]) for b in batch]
    max_len = max(len(ids) for ids in full_ids)

    input_ids = torch.full((len(batch), max_len), pad_token_id, dtype=torch.long)
    token_type_ids = torch.zeros_like(input_ids)
    labels = torch.full_like(input_ids, ignore_label_id)
    attention_mask = torch.zeros_like(input_ids)

    for i, (ids, plen) in enumerate(zip(full_ids, prefix_lens)):
        input_ids[i, : len(ids)] = torch.tensor(ids)
        token_type_ids[i, :plen] = 1                      # bidirectional prefix
        labels[i, plen : len(ids)] = input_ids[i, plen : len(ids)]  # loss on response only
        attention_mask[i, : len(ids)] = 1
    return {
        "input_ids": input_ids,
        "token_type_ids": token_type_ids,
        "attention_mask": attention_mask,
        "labels": labels,
    }
```

수용되는 형태는 [HrmTextModel.forward()](/docs/transformers/v5.23.0/ko/model_doc/hrm_text#transformers.HrmTextModel.forward)를 참조하세요.

## HrmTextConfig[[transformers.HrmTextConfig]]

#### transformers.HrmTextConfig[[transformers.HrmTextConfig]]

```python
transformers.HrmTextConfig(transformers_version: str | None = None, architectures: list[str] | None = None, output_hidden_states: bool | None = False, return_dict: bool | None = True, dtype: str | torch.dtype | None = None, chunk_size_feed_forward: int = 0, is_encoder_decoder: bool = False, id2label: dict[int, str] | dict[str, str] | None = None, label2id: dict[str, int] | dict[str, str] | None = None, problem_type: Literal['regression', 'single_label_classification', 'multi_label_classification'] | None = None, vocab_size: int = 151808, hidden_size: int = 1536, intermediate_size: int = 4096, num_hidden_layers: int = 16, num_attention_heads: int = 12, hidden_act: str = 'silu', max_position_embeddings: int = 2048, initializer_range: float = 0.02, rms_norm_eps: float = 1e-06, use_cache: bool = True, pad_token_id: int | None = None, bos_token_id: int | None = None, eos_token_id: int | list[int] | None = None, tie_word_embeddings: bool = False, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, attention_bias: bool = False, attention_dropout: int | float | None = 0.0, mlp_bias: bool = False, head_dim: int = 128, H_cycles: int = 2, L_cycles: int = 3, L_bp_cycles: list[int] | None = None, embedding_scale: float | None = None, prefix_lm: bool = True, num_layers_per_stack: int | None = None)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/hrm_text/configuration_hrm_text.py#L32)

**매개변수:**

vocab_size (`int`, *선택 사항*, 기본값 `151808`) : 모델의 어휘 크기입니다. `input_ids`로 표현할 수 있는 서로 다른 토큰의 수를 정의합니다.

hidden_size (`int`, *선택 사항*, 기본값 `1536`) : 숨겨진 표현의 차원.

intermediate_size (`int`, *선택 사항*, 기본값 `4096`) : MLP 표현의 차원.

num_hidden_layers (`int`, *선택 사항*, 기본값 `16`) : Transformer 디코더의 숨겨진 레이어 수.

num_attention_heads (`int`, *선택 사항*, 기본값 `12`) : Transformer decoder의 각 attention layer에 사용되는 attention head의 수입니다.

hidden_act (`str`, *선택 사항*, 기본값 `silu`) : 디코더에서 사용되는 비선형 활성화 함수(함수 또는 문자열). 예를 들어, `"gelu"`, `"relu"`, `"silu"` 등이 있습니다.

max_position_embeddings (`int`, *선택 사항*, 기본값 `2048`) : 이 모델이 사용될 수 있는 최대 시퀀스 길이입니다.

initializer_range (`float`, *선택 사항*, 기본값 `0.02`) : 모든 가중치 행렬을 초기화하는 truncated_normal_initializer의 표준 편차입니다.

rms_norm_eps (`float`, *선택 사항*, 기본값 `1e-06`) : rms normalization 레이어에서 사용되는 epsilon 값입니다.

use_cache (`bool`, *선택 사항*, 기본값 `True`) : 모델이 마지막 key/values attention을 반환할지 여부입니다(모든 모델에서 사용되지 않음). `config.is_decoder=True`인 경우 또는 모델이 decoder-only 생성 모델인 경우에만 관련이 있습니다.

pad_token_id (`int`, *선택 사항*) : 어휘에서 패딩에 사용되는 토큰 ID입니다.

bos_token_id (`int`, *선택 사항*) : 어휘에서 스트림 시작에 사용되는 토큰 ID입니다.

eos_token_id (`Union[int, list[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 및 output projection layer에 bias를 사용할지 여부.

attention_dropout (`Union[int, float]`, *선택 사항*, 기본값 `0.0`) : attention 확률에 적용할 dropout 비율입니다.

mlp_bias (`bool`, *선택 사항*, 기본값 `False`) : MLP 레이어의 up_proj, down_proj, gate_proj 레이어에 bias를 사용할지 여부.

head_dim (`int`, *선택 사항*, 기본값 `128`) : attention head 차원입니다. None인 경우 hidden_size // num_attention_heads 값이 기본값으로 사용됩니다.

H_cycles (`int`, *선택 사항*, 기본값 2) : 상위 레벨 사이클의 수.

L_cycles (`int`, *선택 사항*, 기본값 3) : H-사이클당 저레벨 사이클 수.

L_bp_cycles (`list[int]`, *선택 사항*, 기본값 `[2]`) : 학습 시 그래디언트 라우팅 리스트입니다. 모델 내부에서 `L_cycles`까지 왼쪽에 `1`로 패딩됩니다. 추론 시에는 아무 동작도 하지 않습니다.

embedding_scale (`float`, *선택 사항*) : 토큰 임베딩 배율입니다. `None`인 경우 기본값은 `1 / initializer_range`입니다.

prefix_lm (`bool`, *선택 사항*, 기본값 `True`) : 지시 토큰은 양방향으로, 응답 토큰은 인과적으로 주의를 기울입니다.

num_layers_per_stack (`int`, *선택 사항*) : H / L 스택 각각 내부의 transformer 블록 실제 개수입니다. 최초 생성 시 자동으로 설정됩니다. `num_hidden_layers`로 전달된 값이 여기에 기억되고, `num_hidden_layers`는 `num_layers_per_stack * H_cycles * (L_cycles + 1)`로 다시 작성되어 `DynamicCache(config=...)`가 재귀적 forward에서 고유한 attention 호출마다 슬롯 하나를 사전 할당하도록 합니다. 최초 생성 시 이 값을 직접 설정하지 마세요. 스택별 실제 개수를 `num_hidden_layers`로 전달하고 `__post_init__`가 이를 분할하도록 하세요.

이것은 HrmTextModel의 구성을 저장하기 위한 구성 클래스입니다. 지정된 인자에 따라 Hrm Text 모델을 초기화하여 모델 아키텍처를 정의하는 데 사용됩니다. 기본값으로 구성을 초기화하면 [sapientinc/HRM-Text-1B](https://huggingface.co/sapientinc/HRM-Text-1B)와 유사한 구성이 생성됩니다.

Configuration 객체는 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)를 상속하며, 모델 출력을 제어하는 데 사용할 수 있습니다. 자세한 내용은 [PreTrainedConfig](/docs/transformers/v5.23.0/ko/main_classes/configuration#transformers.PreTrainedConfig)의 문서를 참고하세요.

## HrmTextModel[[transformers.HrmTextModel]]

#### transformers.HrmTextModel[[transformers.HrmTextModel]]

```python
transformers.HrmTextModel(config: HrmTextConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/hrm_text/modeling_hrm_text.py#L392)

**매개변수:**

config ([HrmTextConfig](/docs/transformers/v5.23.0/ko/model_doc/hrm_text#transformers.HrmTextConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

Text Text Model은 특정 헤드가 없는 상태에서 원시 hidden-states를 출력하는 Hrm입니다.

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

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.HrmTextModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, token_type_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/hrm_text/modeling_hrm_text.py#L416)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

token_type_ids (`torch.LongTensor`, shape `(batch, seq_len)`, *선택 사항*) : 위치별 양방향/인과성 지표. `token_type_ids == 1`인 토큰은 하나의 양방향 블록을 형성하며, 나머지 모든 위치는 인과적입니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

**반환값:** [BaseModelOutputWithPast](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `tuple(torch.Tensor)`

[BaseModelOutputWithPast](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.BaseModelOutputWithPast) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되었거나 `config.return_dict=False`인 경우)로, 구성([HrmTextConfig](/docs/transformers/v5.23.0/ko/model_doc/hrm_text#transformers.HrmTextConfig))과 입력에 따라 다양한 요소를 포함합니다.

[HrmTextModel](/docs/transformers/v5.23.0/ko/model_doc/hrm_text#transformers.HrmTextModel)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`) -- 모델의 마지막 레이어 출력에서 생성된 hidden-state 시퀀스입니다.

  `past_key_values`가 사용되면, `(batch_size, 1, hidden_size)` 형태의 시퀀스의 마지막 hidden-state만 출력됩니다.
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value, 그리고 `config.is_encoder_decoder=True`인 경우 크로스 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **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와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

## HrmTextForCausalLM[[transformers.HrmTextForCausalLM]]

#### transformers.HrmTextForCausalLM[[transformers.HrmTextForCausalLM]]

```python
transformers.HrmTextForCausalLM(config: HrmTextConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/hrm_text/modeling_hrm_text.py#L530)

**매개변수:**

config ([HrmTextConfig](/docs/transformers/v5.23.0/ko/model_doc/hrm_text#transformers.HrmTextConfig)) : 모델의 모든 매개변수를 포함하는 모델 구성 클래스입니다. 구성 파일로 초기화하는 것은 모델과 관련된 가중치를 로드하지 않으며, 구성 정보만 로드합니다. 모델 가중치를 로드하려면 [from_pretrained()](/docs/transformers/v5.23.0/ko/main_classes/model#transformers.PreTrainedModel.from_pretrained) 메서드를 확인하세요.

Hrm Text Model은 인과 언어 모델링을 위한 모델입니다.

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

이 모델은 또한 PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module)의 하위 클래스입니다. 일반적인 PyTorch Module처럼 사용하며, 일반적인 사용법과 동작에 관한 모든 사항은 PyTorch 문서를 참조하세요.

#### forward[[transformers.HrmTextForCausalLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.LongTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, token_type_ids: typing.Optional[torch.LongTensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, logits_to_keep: typing.Union[int, torch.Tensor] = 0, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/hrm_text/modeling_hrm_text.py#L545)

**매개변수:**

input_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 어휘(input sequence tokens)의 인덱스입니다. 기본적으로 패딩은 무시됩니다. [AutoTokenizer](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoTokenizer)를 사용하여 인덱스를 얻을 수 있습니다. 자세한 내용은 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 및 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)를 참조하세요. [입력 ID란 무엇인가요?](../glossary#input-ids)

attention_mask (`torch.Tensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 패딩 토큰 인덱스에 대한 attention을 수행하지 않도록 방지하는 마스크입니다. `[0, 1]`에서 선택된 마스크 값: - **마스크되지 않은** 토큰은 1, - **마스크된** 토큰은 0. [attention 마스크란?](../glossary#attention-mask)

position_ids (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 각 입력 시퀀스의 토큰 위치 인덱스입니다. `[0, config.n_positions - 1]` 범위에서 선택됩니다. [위치 ID란 무엇인가요?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *선택*) : 순차적 디코딩을 가속화할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록과 크로스 어텐션 블록의 key 및 value)입니다. 일반적으로 `use_cache=True` 또는 `config.use_cache=True`일 때 모델이 디코딩의 이전 단계에서 반환한 `past_key_values`로 구성됩니다. 입력으로 [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스만 허용되며, [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요. `past_key_values`가 전달되지 않으면 기본적으로 [DynamicCache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.DynamicCache)가 초기화됩니다. 모델은 입력으로 제공된 것과 동일한 캐시 형식을 출력합니다. `past_key_values`를 사용하는 경우, 이 모델에 과거 key value 상태가 제공되지 않은 `input_ids`(처리되지 않은 항목)만 `(batch_size, unprocessed_length)` 형식으로 입력해야 하며, `(batch_size, sequence_length)` 형식의 모든 `input_ids`를 입력하지 않습니다.

token_type_ids (`torch.LongTensor`, shape `(batch, seq_len)`, *선택 사항*) : 위치별 양방향/인과성 지표. `token_type_ids == 1`인 토큰은 하나의 양방향 블록을 형성하며, 나머지 모든 위치는 인과적입니다.

inputs_embeds (`torch.Tensor`, shape `(batch_size, sequence_length, hidden_size)`, *선택 사항*) : `input_ids`를 전달하는 대신 임베디드 표현을 직접 전달할 수 있습니다. 이는 모델의 내부 임베딩 조회 행렬보다 `input_ids` 인덱스를 관련 벡터로 변환하는 방식에 대해 더 많은 제어가 필요한 경우 유용합니다.

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : 인과 언어 모델링 손실을 계산하기 위한 라벨. 인덱스는 `[-100, 0, ..., config.vocab_size]` 범위여야 합니다(`input_ids` docstring 참조). 인덱스가 `-100`로 설정된 토큰은 무시(마스크)되며, 손실은 라벨이 `[0, ..., config.vocab_size]` 범위에 있는 토큰에 대해서만 계산됩니다. 라벨은 **내부적으로 시프트**되어 `labels[..., 1:]`이 `logits[..., :-1, :]`를 예측하는 데 사용됩니다. `input_ids`와 일치하는 시프트되지 않은 라벨을 전달하세요(즉, `labels = input_ids`). 라벨을 전달하기 전에 직접 시프트하지 마세요(**금지**). 라벨이 이미 시프트된 경우(예: 시퀀스 병렬 처리)에는 `shift_labels` 키워드 인수로 전달하면 그대로 사용됩니다. 손실이 계산되려면 `labels`를 전달해야 합니다.

use_cache (`bool`, *선택 사항*) : `True`로 설정하면 `past_key_values` 키 값 상태가 반환되며, 디코딩 속도를 높이는 데 사용할 수 있습니다(`past_key_values` 참조).

logits_to_keep (`Union[int, torch.Tensor]`, *선택 사항*, 기본값 `0`) : `int`인 경우, 마지막 `logits_to_keep` 토큰에 대한 logits를 계산합니다. `0`인 경우, 모든 `input_ids`에 대한 logits를 계산합니다(특수한 경우). 생성에는 마지막 토큰의 logits만 필요하며, 해당 토큰에 대해서만 계산하면 메모리를 절약할 수 있습니다. 이는 긴 시퀀스나 큰 어휘 크기의 경우 상당한 이점을 제공합니다. `torch.Tensor`인 경우, 시퀀스 길이 차원에서 유지할 인덱스에 해당하는 1차원 텐서여야 합니다. 이는 packed tensor 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

**반환값:** [CausalLMOutputWithPast](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.CausalLMOutputWithPast) 또는 `tuple(torch.Tensor)`

[HrmTextConfig](/docs/transformers/v5.23.0/ko/model_doc/hrm_text#transformers.HrmTextConfig) 및 입력에 따라 다양한 요소를 포함하는 [CausalLMOutputWithPast](/docs/transformers/v5.23.0/ko/main_classes/output#transformers.modeling_outputs.CausalLMOutputWithPast) 또는 `torch.Tensor`의 튜플(`return_dict=False`가 전달되거나 `config.return_dict=False`인 경우).

[HrmTextForCausalLM](/docs/transformers/v5.23.0/ko/model_doc/hrm_text#transformers.HrmTextForCausalLM)의 forward 메서드는 `__call__` 특수 메서드를 오버라이드합니다.

`Module` 인스턴스는 전처리 및 후처리 단계를 실행하는 것을 처리하지만, 이 함수는 해당 단계를 조용히 무시하므로, 순전파(forward pass) 레시피를 이 함수 내에서 정의해야 하더라도 이후에는 이 함수 대신 `Module` 인스턴스를 호출해야 합니다.

- **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 언어 모델링 손실(다음 토큰 예측용).
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.vocab_size)`) -- 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).
- **past_key_values** (`Cache`, *선택 사항*, `use_cache=True`가 전달되었거나 `config.use_cache=True`인 경우 반환됨) -- [Cache](/docs/transformers/v5.23.0/ko/internal/generation_utils#transformers.Cache) 인스턴스입니다. 자세한 내용은 [kv cache 가이드](https://huggingface.co/docs/transformers/en/kv_cache)를 참조하세요.

  순차적 디코딩을 가속화하는 데 사용할 수 있는 사전 계산된 hidden-states(셀프 어텐션 블록의 key와 value)를 포함합니다(입력 `past_key_values` 참조).
- **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와 선택적 초기 임베딩 출력을 포함합니다.
- **attentions** (`tuple(torch.Tensor)`, *선택 사항*, `output_attentions=True`가 전달되었거나 `config.output_attentions=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 모양은 `(batch_size, num_heads, sequence_length, sequence_length)`입니다.

  self-attention 헤드에서 가중 평균을 계산하는 데 사용되는 attention softmax 이후의 attention 가중치입니다.

예:

```python
```