# Beam

## 개요

[Beam](https://reflection.ai/blog/introducing-beam)은 Reflection의 첫 번째 오픈 웨이트 모델로, 총 501B 파라미터와 토큰당 활성 파라미터 23B를 가진 희소 mixture-of-experts(MoE) 언어 모델입니다. 코딩, 추론, 에이전트 워크로드를 위해 구축되었습니다. 23.8T 토큰으로 사전 학습되었으며, 대규모 비동기 강화 학습으로 사후 학습되었습니다. Beam은 텍스트 전용이며, 모든 답변 전에 추론을 수행합니다. 채팅 템플릿의 추론 노력 설정으로 추론의 정도를 제어할 수 있습니다.

Beam은 52개의 decoder 레이어를 갖추고 있으며 다음 기능을 결합합니다:

- **하이브리드 슬라이딩 및 전체 어텐션.** 6번째 층과 마지막 층은 전체 어텐션을 사용하고, 나머지 층은 최근 `sliding_window`(512) 토큰에 어텐션을 적용합니다. `layer_types`가 이 패턴을 설정합니다.
- **슬라이딩 레이어에는 RoPE, 전체 레이어에는 NoPE를 적용합니다.** `rope_parameters`은 레이어 유형을 키로 사용하며, `None`은 위치 인코딩이 없는 레이어 유형을 나타냅니다. 전체 어텐션 레이어는 쿼리를 스케일링합니다(스케일어블 softmax): 1-based 위치 `n`의 쿼리는 `(1 + n / 2048) ** 0.1`을 곱하며, 이를 통해 컨텍스트가 커져도 어텐션이 평탄해지지 않도록 합니다.
- **게이트드 어텐션.** 48개의 쿼리 헤드와 8개의 키/밸류 헤드를 사용하는 그룹드 쿼리 어텐션이며, 각 쿼리 및 키 헤드에 RMSNorm을 적용합니다. 어텐션 입력에서 계산된 시그모이드 게이트는 헤드별 학습된 바이어스를 가지며, 출력 투영 전에 어텐션 출력을 요소별로 스케일링합니다.
- **Sparse MoE.** 첫 3개 레이어는 dense SwiGLU MLP를 사용하고, 나머지 49개 레이어는 각 토큰을 256개 전문가 중 8개로 라우팅하며 공유 전문가가 없습니다(`mlp_layer_types`가 패턴을 설정합니다). 라우터는 시그모이드로 전문가를 점수화하고, 보조 손실 대신 학습된 전문가별 바이어스로 부하를 균형 있게 조절하며, 각 토큰을 `n_group`개 전문가 그룹 중 최상위 `topk_group`개 그룹으로 제한합니다. 라우팅 가중치는 정규화되며, MoE 출력은 `routed_scaling_factor`로 스케일링됩니다.
- **깊이에 따라 스케일링된 잔차와 샌드위치 노름.** 각 attention 및 MLP 블록은 앞뒤로 RMSNorm으로 감싸집니다. 잔차 가산은 `k`개의 기여(임베딩을 첫 번째로 계산) 이후, 잔차 스트림이 해당 기여들의 합을 `sqrt(k)`로 나눈 값이 되도록 다시 스케일링됩니다.
- **최종 logit softcapping.** Logit은 `30 * tanh(logits / 30)`(`final_logit_softcapping`)로 제한됩니다.

구현에서는 Beam이 학습 및 서빙될 때 사용된 수치와 일치하도록 RMSNorm 스케일링, SwiGLU 활성화 함수, RoPE, 쿼리 스케일링, 라우팅, softcapping을 FP32로 계산합니다. 라우터 가중치와 전문가 바이어스는 로드 시점에 FP32로 유지되며, 반환되는 `logits`는 항상 FP32입니다.

모든 원본 Beam 체크포인트는 [Reflection](https://huggingface.co/reflection) 조직에서 찾을 수 있습니다.

이 모델은 [yonigozlan](https://huggingface.co/yonigozlan)이(가) 기여했습니다.

## 사용 예시

Beam의 chat template는 대화를 Beam의 Harmony 형식으로 포맷하며, [response template](../chat_response_parsing)은 생성된 텍스트를 `thinking`, `content`, `tool_calls` 필드를 가진 메시지로 다시 파싱합니다. 아래 예제는 [Pipeline](/docs/transformers/v5.23.0/ko/main_classes/pipelines#transformers.Pipeline) 또는 [AutoModelForCausalLM](/docs/transformers/v5.23.0/ko/model_doc/auto#transformers.AutoModelForCausalLM) 클래스를 사용하여 응답을 생성합니다.

BF16 체크포인트는 약 1 TB 크기이므로, 예제에서는 [expert parallelism](../expert_parallelism)을 사용하여 전체 라우팅된 expert를 각 장치에 배치하는 방식으로 8개 장치에 걸쳐 샤딩합니다. `torchrun --nproc-per-node 8 <script.py>`로 실행하세요.

```python
from transformers import DistributedConfig, pipeline

pipe = pipeline(
    task="text-generation",
    model="reflection/Beam-1.0-501B-A23B",
    model_kwargs={"distributed_config": DistributedConfig(tp_size=8, ep_size=8)},
)

messages = [{"role": "user", "content": "Explain in one sentence why the sky is usually blue."}]
output = pipe(messages, max_new_tokens=2048)
reply = output[0]["generated_text"][-1]
print(reply["thinking"])
print(reply["content"])
```

```python
from transformers import AutoModelForCausalLM, AutoTokenizer, DistributedConfig

model_id = "reflection/Beam-1.0-501B-A23B"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, distributed_config=DistributedConfig(tp_size=8, ep_size=8))

messages = [{"role": "user", "content": "Explain in one sentence why the sky is usually blue."}]
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True, reasoning_effort="low"
).to(model.device)

outputs = model.generate(**inputs, max_new_tokens=2048)
generated = tokenizer.decode(outputs[0, inputs["input_ids"].shape[1] :])
message = tokenizer.parse_response(generated, prefix=inputs["input_ids"][0])
print(message["thinking"])
print(message["content"])
```

`device_map="auto"`는 각 장치에 전체 레이어를 배치하고 한 번에 하나의 장치에서 실행하며, 로딩 중 메모리가 부족해질 수 있으므로 이 방법을 사용하는 것이 좋습니다.

`temperature=0.7` 및 `top_p=0.99`는 Beam이 권장하는 값으로, 체크포인트의 [GenerationConfig](/docs/transformers/v5.23.0/ko/main_classes/text_generation#transformers.GenerationConfig)에서 기본값으로 설정되어 있습니다. `do_sample=False`를 전달하면 그리디 디코딩을 수행합니다.

### 추론 노력

`reasoning_effort`를 [apply_chat_template()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template)에 전달하여 Beam의 추론 정도를 제어할 수 있습니다. 정수 예산 또는 아래 라벨 중 하나를 허용합니다. Beam은 8 미만의 effort로 학습되지 않았으므로 더 작은 값은 반영되지 않습니다.

| 레이블 | `minimal` | `low` | `medium` | `high` | `xhigh` | `max` |
|---|---|---|---|---|---|---|
| 노력 | 8 | 32 | 64 | 128 | 256 | 512 |

`reasoning_effort`가 설정되지 않은 경우 템플릿은 `max`를 사용합니다. 추론 도중 `max_new_tokens`가 소진되면, 파싱된 메시지에는 `thinking`만 있고 `content`는 없습니다.

### 다중 턴 대화

해석된 메시지를 그대로 히스토리에 추가합니다. Beam은 이전 추론이 없으면 출력이 저하되며, 채팅 템플릿은 `thinking`에서 이를 읽습니다(`reasoning_content`와 `reasoning`도 허용됩니다). 기본적으로 추론이 없는 어시스턴트 턴은 빈 추론 블록으로 렌더링됩니다. Beam을 서빙할 때 권장되는 `add_generation_prompt=True`가 설정된 경우, `allow_missing_thinking=False`를 전달하여 대신 오류를 발생시킬 수 있습니다.

```python
messages.append(message)
messages.append({"role": "user", "content": "And why are sunsets red?"})
inputs = tokenizer.apply_chat_template(
    messages, add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(model.device)
```

### Tool calling

`tools`를 [apply_chat_template()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template)과 [parse_response()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.parse_response) 모두에 전달하세요. `tools`가 있으면 파싱된 인수는 각 도구의 스키마에 정의된 타입으로 캐스팅되고, 없으면 모든 인수가 문자열이 됩니다.

```python
def get_weather(city: str):
    """
    Get the current weather in a city.

    Args:
        city: The city name.
    """
    return "Sunny, 22 C"

messages = [{"role": "user", "content": "What's the weather like in Paris right now?"}]
inputs = tokenizer.apply_chat_template(
    messages, tools=[get_weather], add_generation_prompt=True, return_tensors="pt", return_dict=True
).to(model.device)
outputs = model.generate(**inputs, max_new_tokens=2048)
generated = tokenizer.decode(outputs[0, inputs["input_ids"].shape[1] :])
message = tokenizer.parse_response(generated, prefix=inputs["input_ids"][0], tools=[get_weather])
print(message["tool_calls"])
# [{'type': 'function', 'function': {'name': 'get_weather', 'arguments': {'city': 'Paris'}}}]

messages.append(message)
for call in message["tool_calls"]:
    result = get_weather(**call["function"]["arguments"])
    messages.append({"role": "tool", "name": call["function"]["name"], "content": result})
```

이후 `messages`에서 다시 생성하여 최종 답변을 얻습니다. 파싱된 tool call에는 `id`가 없으며, 포맷은 위치를 기준으로 결과를 호출에 매칭하므로 tool 결과를 호출 순서대로 반환해야 합니다. 생성은 최종 답변(`<|return|>`) 또는 tool call(`<|call|>`) 이후에 중단되며, `generation_config.json`에는 이 두 가지가 모두 나열되어 있습니다.

스트리밍의 경우, [get_response_parser()](/docs/transformers/v5.23.0/ko/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.get_response_parser)는 생성되는 텍스트 청크를 `feed()`로 전달하는 파서를 반환합니다. 자세한 내용은 [응답 파싱](../chat_response_parsing)을 참조하세요.

## The input is a single word "Notes".

참고

- **템플릿 인자.** `reasoning_effort` 외에도 채팅 템플릿은 `model_identity`(시스템 메시지의 첫 번째 줄을 대체), `builtin_tools`, `allow_missing_thinking`를 허용합니다. `builtin_tools`에는 `search`와 `browse` 도구만 지정할 수 있으며, Beam이 학습된 정의와 일치해야 합니다. 기타 도구는 `tools`만 필요합니다. `system` 및 `developer` 메시지는 대화의 시작 부분에서만 렌더링됩니다.
- **학습.** 채팅 템플릿은 `apply_chat_template(..., return_dict=True, return_assistant_tokens_mask=True)`에서 어시스턴트 출력을 표시하므로, TRL의 `SFTConfig(assistant_only_loss=True)`는 어시스턴트 토큰만 대상으로 학습합니다. 이 마스크는 각 어시스턴트 턴의 추론, 답변, 도구 호출을 포함합니다.
- **보조 손실이 없습니다.** 라우터가 바이어스를 통해 전문가 부하를 균형 있게 조절하므로, `BeamForCausalLM`은 부하 균형 손실을 계산하지 않습니다. `output_router_logits=True`를 사용하면 여전히 라우터 로짓을 반환합니다.

## BeamConfig[[transformers.BeamConfig]]

#### transformers.BeamConfig[[transformers.BeamConfig]]

```python
transformers.BeamConfig(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 = 151936, hidden_size: int = 5120, intermediate_size: int = 20480, num_hidden_layers: int = 52, num_attention_heads: int = 48, num_key_value_heads: int = 8, hidden_act: str = 'silu', max_position_embeddings: int = 8192, initializer_range: float = 0.02, rms_norm_eps: float = 1e-06, use_cache: bool = True, tie_word_embeddings: bool = False, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, attention_bias: bool = False, sliding_window: int | None = 512, attention_dropout: float | int = 0.0, moe_intermediate_size: int = 2560, num_experts_per_tok: int = 8, num_experts: int = 256, norm_topk_prob: bool = True, output_router_logits: bool = False, pad_token_id: int | None = None, bos_token_id: int | None = None, eos_token_id: int | list[int] | None = None, head_dim: int = 128, layer_types: list[str] | None = None, mlp_layer_types: list[str] | None = None, n_group: int | None = 8, topk_group: int | None = 4, routed_scaling_factor: int | float = 2.5, final_logit_softcapping: int | float | None = 30.0)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/beam/configuration_beam.py#L29)

**매개변수:**

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

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

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

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

num_attention_heads (`int`, *선택 사항*, 기본값 `48`) : Transformer 디코더의 각 어텐션 레이어에 사용할 어텐션 헤드 수입니다.

num_key_value_heads (`int`, *선택 사항*, 기본값 `8`) : 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하여 구성해야 합니다. 자세한 내용은 [이 논문](https://huggingface.co/papers/2305.13245)을 참고하세요. 지정되지 않으면 `num_attention_heads`가 기본값으로 사용됩니다.

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

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

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 생성 모델인 경우에만 관련이 있습니다.

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를 사용할지 여부.

sliding_window (`int`, *선택 사항*, 기본값 `512`) : Sliding window attention의 윈도우 크기입니다. `None`인 경우 sliding window가 적용되지 않습니다.

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

moe_intermediate_size (`int`, *선택 사항*, 기본값 `2560`) : 라우팅된 전문가 MLP의 중간 크기입니다.

num_experts_per_tok (`int`, *선택 사항*, 기본값 `8`) : 각 토큰을 라우팅할 전문가의 수입니다. 이는 토큰 선택 라우팅의 top-k 값입니다.

num_experts (`int`, *선택 사항*, 기본값 `256`) : MoE 레이어의 라우팅된 전문가(expert) 수입니다.

norm_topk_prob (`bool`, *선택 사항*, 기본값 `True`) : 라우팅된 전문가의 가중치를 정규화할지 여부.

output_router_logits (`bool`, *선택 사항*, 기본값 `False`) : 모델이 router logits를 반환할지 여부입니다. 이 옵션을 활성화하면 load balancing loss와 router z-loss를 포함한 auxiliary loss도 모델에서 출력할 수 있습니다.

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

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

eos_token_id (`Union[int, list[int]]`, *선택*) : 어휘에서 스트림 종료에 사용되는 토큰 ID입니다.

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

layer_types (`list[str]`, *선택 사항*) : 각 레이어 인덱스를 해당 레이어 유형에 명시적으로 매핑하는 리스트입니다. 제공되지 않으면 config 값에 기반하여 자동으로 생성됩니다.

mlp_layer_types (`list[str]`, *선택 사항*) : 레이어별 MLP 유형으로, SwiGLU MLP의 경우 `"dense"`, MoE 블록의 경우 `"sparse"`를 사용합니다. 길이는 `num_hidden_layers`와 같아야 합니다. 기본값은 세 개의 dense 레이어 뒤에 sparse 레이어가 오는 것입니다.

n_group (`int`, *선택 사항*, 기본값 8) : 라우팅된 전문가의 그룹 수.

topk_group (`int`, *선택 사항*, 기본값 `4`) : 각 토큰에 대해 선택할 그룹의 수 (각 토큰에 대해 선택된 전문가가 `topk_group` 그룹 내에서만 있도록 보장).

routed_scaling_factor (`Union[int, float]`, *선택 사항*, 기본값 `2.5`) : Scaling factor 또는 routed experts.

final_logit_softcapping (`Union[int, float]`, *선택 사항*, 기본값 `30.0`) : 확률 분포를 계산하기 전에 최종 logits에 적용되는 소프트 캡핑 값입니다. Logits는 `tanh(logit / cap) * cap`로 스케일링됩니다.

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

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)의 문서를 참고하세요.

```python
>>> from transformers import BeamConfig

>>> # Initializing a Beam configuration
>>> configuration = BeamConfig()
```

## BeamModel[[transformers.BeamModel]]

#### transformers.BeamModel[[transformers.BeamModel]]

```python
transformers.BeamModel(config: BeamConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/beam/modeling_beam.py#L498)

**매개변수:**

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

특정 헤드가 위에 없는 상태에서 원시 hidden-states를 출력하는 순수한 Beam 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.BeamModel.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, 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/beam/modeling_beam.py#L515)

**매개변수:**

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`를 입력하지 않습니다.

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` 참조).

**반환값:** `MoeModelOutputWithPast` 또는 `tuple(torch.Tensor)`

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

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

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

- **last_hidden_state** (`torch.Tensor`, shape `(batch_size, sequence_length, 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 가중치입니다.
- **router_logits** (`tuple(torch.Tensor)`, *선택 사항*, `output_router_probs=True`와 `config.add_router_probs=True`가 전달되었거나 `config.output_router_probs=True`인 경우 반환됨) -- 각 레이어마다 하나씩 포함된 `torch.Tensor`의 튜플로, 형태는 `(batch_size, sequence_length, num_experts)`입니다.

  MoE 라우터가 계산하는 softmax 적용 후의 원시 라우터 로짓(raw router logits)입니다. 이 값들은 Mixture of Experts 모델의 보조 손실을 계산하는 데 사용됩니다.

## BeamForCausalLM[[transformers.BeamForCausalLM]]

#### transformers.BeamForCausalLM[[transformers.BeamForCausalLM]]

```python
transformers.BeamForCausalLM(config: BeamConfig)
```

[소스](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/beam/modeling_beam.py#L587)

**매개변수:**

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

causal language modeling을 위한 Beam 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.BeamForCausalLM.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, 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/beam/modeling_beam.py#L602)

**매개변수:**

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`를 입력하지 않습니다.

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

labels (`torch.LongTensor`, shape `(batch_size, sequence_length)`, *선택 사항*) : masked language modeling loss를 계산하기 위한 라벨. 인덱스는 `[0, ..., config.vocab_size]` 범위 내이거나 -100이어야 합니다(`input_ids` docstring 참조). 인덱스가 `-100`으로 설정된 토큰은 무시(마스크)되며, loss는 `[0, ..., config.vocab_size]` 범위의 라벨을 가진 토큰에 대해서만 계산됩니다.

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 형식(배치와 시퀀스 길이를 단일 차원으로 사용하는 경우)을 사용할 때 유용합니다.

**반환값:** `MoeCausalLMOutputWithPast` 또는 `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor`, shape `(1,)`, *선택 사항*, `labels`가 제공될 때 반환됨) -- 언어 모델링 손실(다음 토큰 예측용).
- **logits** (`torch.Tensor`, shape `(batch_size, sequence_length, config.vocab_size)`) -- 언어 모델링 헤드에서 생성된 예측 점수(SoftMax 적용 전 각 어휘 토큰에 대한 점수).
- **aux_loss** (`torch.Tensor`, *선택*, `output_router_logits=True`가 전달되었거나 `config.output_router_logits=True`인 경우, 그리고 모델이 로드 밸런싱 손실로 라우터를 학습하는 경우 반환됨) -- 희소 모듈에 대한 로드 밸런싱 보조 손실입니다. 라우터 바이어스로 전문가를 균형 맞추는 모델(DeepSeek-V3 및 이를 기반으로 파생된 아키텍처)은 `router_logits`를 반환하되, 여기서는 `None`을 반환합니다.
- **router_logits** (`tuple(torch.Tensor)`, *선택*, `output_router_logits=True`가 전달되었거나 `config.output_router_logits=True`인 경우 반환됨) -- `torch.Tensor`의 튜플(스파스 레이어마다 하나)로, shape는 `(batch_size * sequence_length, num_experts)`입니다.

  MoE 라우터가 계산한 원시 라우터 로짓입니다. 로드 밸런싱 손실을 계산하거나 토큰이 전문가로 어떻게 분배되는지 확인하는 데 사용할 수 있습니다.
- **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
```