# Beam

## 概述

[Beam](https://reflection.ai/blog/introducing-beam) 是 Reflection 推出的首个开放权重模型，它是一个稀疏混合专家（MoE）语言模型，总参数量为 501B，每个 token 激活 23B 参数，专为编码、推理和智能体工作负载而构建。该模型在 23.8T token 上进行预训练，并通过大规模异步强化学习进行后训练。Beam 仅支持文本，并且会在给出每个答案之前进行推理。聊天模板中的推理努力设置可控制推理的程度。

Beam 拥有 52 个解码器层，并集成了以下特性：

- **混合滑动窗口与全注意力。** 每第六层以及最后一层使用全注意力，其余层则关注最近的 `sliding_window`（512）个 token。`layer_types` 用于设置该模式。
- **滑动层使用 RoPE，全注意力层使用 NoPE。** `rope_parameters` 以层类型作为键，`None` 表示该层类型不使用位置编码。全注意力层则对查询进行缩放（可扩展 softmax）：位于 1 起始位置 `n` 的查询会乘以 `(1 + n / 2048) ** 0.1`，从而避免上下文增长时注意力分布变得过于平坦。
- **门控注意力。**采用分组查询注意力，包含 48 个查询头和 8 个键/值头，并对每个查询头和键头应用 RMSNorm。一个从注意力输入计算得出的 sigmoid 门控，带有每个头独立学习的偏置，在输出投影之前对注意力输出进行逐元素缩放。
- **稀疏 MoE。** 前 3 层使用稠密 SwiGLU MLP，其余 49 层将每个 token 路由到 256 个专家中的 8 个，且没有共享专家（`mlp_layer_types` 用于设置该模式）。路由器使用 sigmoid 对专家进行评分，通过为每个专家学习一个偏置来平衡负载，而非使用辅助损失，并将每个 token 限制在 `n_group` 个专家组中得分最高的 `topk_group` 个组内。路由权重经过归一化，MoE 的输出会乘以 `routed_scaling_factor` 进行缩放。
- **采用深度缩放残差的三明治式归一化。** 每个注意力层和 MLP 块的前后都包裹了一层 RMSNorm。残差相加会进行重新缩放，使得在 `k` 次贡献之后（将嵌入视为第一次），残差流等于它们的总和除以 `sqrt(k)`。
- **最终 logit 软截断。**Logits 通过 `30 * tanh(logits / 30)`（`final_logit_softcapping`）进行截断。

该实现以 FP32 精度计算 RMSNorm 缩放、SwiGLU 激活、RoPE、查询缩放、路由以及 softcapping，以匹配 Beam 训练和推理时的数值表现。路由权重和专家偏置在加载时保持为 FP32，返回的 `logits` 始终为 FP32。

您可以在 [Reflection](https://huggingface.co/reflection) 组织下找到所有原始的 Beam 检查点。

该模型由 [yonigozlan](https://huggingface.co/yonigozlan) 贡献。

## 使用示例

Beam 的聊天模板将对话格式化为 Beam 的 Harmony 格式，其 [响应模板](../chat_response_parsing) 会将生成的文本解析回包含 `thinking`、`content` 和 `tool_calls` 字段的消息。以下示例使用 [Pipeline](/docs/transformers/main/zh/main_classes/pipelines#transformers.Pipeline) 或 [AutoModelForCausalLM](/docs/transformers/main/zh/model_doc/auto#transformers.AutoModelForCausalLM) 类生成回复。

BF16 检查点的大小约为 1 TB，因此示例通过 [专家并行](../expert_parallelism) 将其分片到 8 个设备上，并在每个设备上放置完整的 routed experts。请使用 `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"`。后者会将完整的层放置在每个设备上，逐个设备执行，并且在加载过程中可能会耗尽内存。

使用 Beam 推荐的 `temperature=0.7` 和 `top_p=0.99` 生成样本，这些值由检查点的 [GenerationConfig](/docs/transformers/main/zh/main_classes/text_generation#transformers.GenerationConfig) 设为默认值。传入 `do_sample=False` 以进行贪心解码。

### 推理努力

将 `reasoning_effort` 传递给 [apply_chat_template()](/docs/transformers/main/zh/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`）。默认情况下，没有推理过程的助手轮次会以空的推理块进行渲染。当 `add_generation_prompt=True` 时，传入 `allow_missing_thinking=False` 可以改为抛出错误，这在部署 Beam 时是推荐的做法。

```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)
```

### 工具调用

将 `tools` 同时传递给 [apply_chat_template()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.apply_chat_template) 和 [parse_response()](/docs/transformers/main/zh/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` 生成，以获取最终答案。解析后的工具调用没有 `id`，并且该格式通过位置将结果与调用匹配，因此请按调用的顺序返回工具结果。生成会在最终答案（`<|return|>`）或工具调用（`<|call|>`）之后停止；`generation_config.json` 中列出了这两者。

对于流式处理，[get_response_parser()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.get_response_parser) 会返回一个解析器，你可以在文本块生成时通过 `feed()` 向其输入这些文本块。有关更多详细信息，请参阅 [响应解析](../chat_response_parsing)。

## 备注

- **模板参数。** 除了 `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)`仅针对助手 token 进行训练。该掩码覆盖每个助手轮次的推理、答案和工具调用。
- **无辅助损失。**路由器通过其偏置来平衡专家负载，因此 `BeamForCausalLM` 不会计算负载均衡损失。`output_router_logits=True` 仍会返回路由器 logits。

## 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/main/src/transformers/models/beam/configuration_beam.py#L29)

**参数：**

vocab_size (`int`，*可选*，默认为 `151936`)：模型的词汇表大小。定义了 `input_ids` 可以表示的不同 token 数量。

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 头应通过对该组内所有原始头进行平均池化来构建。更多详情请参阅 [这篇论文](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 归一化层使用的 epsilon。

use_cache (`bool`，*可选*，默认为 `True`)：模型是否应返回最后的键/值注意力（并非所有模型都使用）。仅当 `config.is_decoder=True` 或模型为仅解码器生成模型时相关。

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`)：在自注意力机制中，是否在查询、键、值和输出投影层中使用偏置。

sliding_window (`int`, *可选*，默认为 `512`)：滑动窗口注意力机制的窗口大小。如果为 `None`，则不应用滑动窗口。

attention_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：注意力概率的 dropout 比率。

moe_intermediate_size (`int`，*可选*，默认为 `2560`)：路由专家 MLP 的中间层大小。

num_experts_per_tok (`int`，*可选*，默认为 `8`)：每个 token 路由到的专家数量。这是 token 选择路由的 top-k 值。

num_experts (`int`，*可选*，默认为 `256`)：MoE 层中路由专家的数量。

norm_topk_prob (`bool`, *可选*, 默认为 `True`) : 是否对路由专家的权重进行归一化。

output_router_logits (`bool`，*可选*，默认为 `False`)：是否由模型返回路由器 logits。启用此选项后，模型还将输出辅助损失，包括负载均衡损失和路由器 z-loss。

pad_token_id (`int`, *可选*) : 词表中用于填充的 Token id。

bos_token_id (`int`, *可选*) : 词表中用于表示流开始的 Token id。

eos_token_id (`Union[int, list[int]]`，*可选*)：词汇表中用于表示流结束（end-of-stream）的 Token ID。

head_dim (`int`，*可选*，默认为 `128`)：注意力头维度。如果为 None，则默认为 hidden_size // num_attention_heads

layer_types (`list[str]`，*可选*)：一个列表，用于显式地将每个层索引与其层类型进行映射。如果未提供，将根据配置值自动生成。

mlp_layer_types (`list[str]`, *可选*) : 每层 MLP 类型，`"dense"` 表示 SwiGLU MLP，`"sparse"` 表示 MoE 块。长度必须等于 `num_hidden_layers`。默认值为三个 dense 层后接 sparse 层。

n_group (`int`，*可选*，默认为 8)：路由专家的组数。

topk_group (`int`，*可选*，默认为 `4`)：每个 token 选中的组数（对于每个 token，确保所选专家仅位于 `topk_group` 个组内）。

routed_scaling_factor (`Union[int, float]`，*可选*，默认为 `2.5`)：缩放因子或路由专家。

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) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/main/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/main/zh/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/main/src/transformers/models/beam/modeling_beam.py#L498)

**参数：**

config ([BeamConfig](/docs/transformers/main/zh/model_doc/beam#transformers.BeamConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

未添加任何特定头部的裸 Beam 模型，直接输出原始隐藏状态。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/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/main/src/transformers/models/beam/modeling_beam.py#L515)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(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/main/zh/model_doc/beam#transformers.BeamConfig)）和输入。

[BeamModel](/docs/transformers/main/zh/model_doc/beam#transformers.BeamModel) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型最后一层输出的隐藏状态序列。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值，以及如果 `config.is_encoder_decoder=True` 则还包括交叉注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。
- **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 路由器计算的原始路由器 logits（softmax 之后），这些术语用于计算混合专家模型的辅助损失。

## BeamForCausalLM[[transformers.BeamForCausalLM]]

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

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

[来源](https://github.com/huggingface/transformers/blob/main/src/transformers/models/beam/modeling_beam.py#L587)

**参数：**

config ([BeamConfig](/docs/transformers/main/zh/model_doc/beam#transformers.BeamConfig))：模型配置类，包含模型的所有参数。通过配置文件进行初始化时，不会加载与模型关联的权重，仅加载配置。请查看 [from_pretrained()](/docs/transformers/main/zh/main_classes/model#transformers.PreTrainedModel.from_pretrained) 方法以加载模型权重。

用于因果语言建模的 Beam Model。

该模型继承自 [PreTrainedModel](/docs/transformers/main/zh/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/main/src/transformers/models/beam/modeling_beam.py#L602)

**参数：**

input_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中 token 在词汇表中的索引。默认情况下，填充（padding）将被忽略。可以使用 [AutoTokenizer](/docs/transformers/main/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/main/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。[什么是输入 ID？](../glossary#input-ids)

attention_mask (`torch.Tensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于避免对填充（padding）标记索引执行注意力机制的掩码。掩码值取自 `[0, 1]`： - 1 表示**未掩码**的标记， - 0 表示**已掩码**的标记。 [什么是注意力掩码？](../glossary#attention-mask)

position_ids (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：输入序列中每个 token 在位置嵌入中的位置索引。取值范围为 `[0, config.n_positions - 1]`。[什么是位置 ID？](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/main/zh/internal/generation_utils#transformers.DynamicCache)。 模型将输出与输入相同的缓存格式。 如果使用 `past_key_values`，则用户预期仅输入未处理的 `input_ids`（即未向此模型提供其过去键值状态的那些），其形状为 `(batch_size, unprocessed_length)`，而不是形状为 `(batch_size, sequence_length)` 的所有 `input_ids`。

inputs_embeds (`torch.Tensor`，形状为 `(batch_size, sequence_length, hidden_size)`，*可选*)：可选地，你可以选择直接传入嵌入表示，而不是传入 `input_ids`。如果你希望比模型内部的嵌入查找矩阵更精细地控制如何将 `input_ids` 索引转换为对应的向量，这将非常有用。

labels (`torch.LongTensor`，形状为 `(batch_size, sequence_length)`，*可选*)：用于计算掩码语言建模损失的标签。索引值应在 `[0, ..., config.vocab_size]` 范围内，或为 -100（参见 `input_ids` 的文档字符串）。索引值设为 `-100` 的 token 将被忽略（即被掩码），损失仅针对标签在 `[0, ..., config.vocab_size]` 范围内的 token 进行计算。

use_cache (`bool`，*可选*)：如果设置为 `True`，则会返回 `past_key_values` 键值状态，可用于加速解码（参见 `past_key_values`）。

logits_to_keep (`Union[int, torch.Tensor]`，*可选*，默认为 `0`)：如果为 `int`，则计算最后 `logits_to_keep` 个 token 的 logits。如果为 `0`，则计算所有 `input_ids` 的 logits（特殊情况）。生成过程只需要最后一个 token 的 logits，仅针对该 token 进行计算可以节省内存，对于长序列或大词汇量而言，这种节省相当可观。如果为 `torch.Tensor`，则必须是一维张量，对应于序列长度维度中需要保留的索引。这在使用打包张量格式（将批次和序列长度合并为单一维度）时非常有用。

**返回：** `MoeCausalLMOutputWithPast` 或 `tuple(torch.Tensor)`

`MoeCausalLMOutputWithPast` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[BeamConfig](/docs/transformers/main/zh/model_doc/beam#transformers.BeamConfig)）和输入。

[BeamForCausalLM](/docs/transformers/main/zh/model_doc/beam#transformers.BeamForCausalLM) 的 forward 方法重写了 `__call__` 特殊方法。

尽管前向传播的实现需要在此函数中定义，但之后应调用 `Module` 实例，而不是直接调用此函数，因为前者会负责执行预处理和后处理步骤，而后者会静默地忽略这些步骤。

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，当提供 `labels` 时返回) -- 语言建模损失（用于下一个 token 预测）。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **aux_loss** (`torch.Tensor`，*可选*，当传入 `output_router_logits=True` 或 `config.output_router_logits=True`，且模型使用负载均衡损失训练其路由器时返回) -- 稀疏模块的负载均衡辅助损失。使用路由器偏差来平衡其专家的模型（DeepSeek-V3 及由其衍生的架构）在此处返回 `None`，但仍会返回 `router_logits`。
- **router_logits** (`tuple(torch.Tensor)`，*可选*，在传入 `output_router_logits=True` 或 `config.output_router_logits=True` 时返回) -- 一个 `torch.Tensor` 元组（每个稀疏层对应一个），形状为 `(batch_size * sequence_length, num_experts)`。

  由 MoE 路由器计算的原始路由器 logits。可用于计算负载均衡损失，或检查 token 如何被分发到各个专家。
- **past_key_values**（`Cache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）—— 它是一个 [Cache](/docs/transformers/main/zh/internal/generation_utils#transformers.Cache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

  包含预计算的隐藏状态（自注意力块中的键和值），可用于（参见 `past_key_values` 输入）加速顺序解码。
- **hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

  模型在每一层输出处的隐藏状态，以及可选的初始嵌入输出。
- **attentions** (`tuple(torch.Tensor)`，*可选*，当传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  经过注意力 softmax 后的注意力权重，用于在自注意力头中计算加权平均值。

示例：

```python
```