# NLLB-MOE

## 概述

NLLB 模型由 Marta R. Costa-jussà、James Cross、Onur Çelebi、Maha Elbayad、Kenneth Heafield、Kevin Heffernan、Elahe Kalbassi、Janice Lam、Daniel Licht、Jean Maillard、Anna Sun、Skyler Wang、Guillaume Wenzek、Al Youngblood、Bapi Akula、Loic Barrault、Gabriel Mejia Gonzalez、Prangthip Hansanti、John Hoffman、Semarley Jarrett、Kaushik Ram Sadagopan、Dirk Rowe、Shannon Spruit、Chau Tran、Pierre Andrews、Necip Fazil Ayan、Shruti Bhosale、Sergey Edunov、Angela Fan、Cynthia Gao、Vedanuj Goswami、Francisco Guzmán、Philipp Koehn、Alexandre Mourachko、Christophe Ropers、Safiyyah Saleem、Holger Schwenk 和 Jeff Wang 在 [No Language Left Behind: Scaling Human-Centered Machine Translation](https://huggingface.co/papers/2207.04672) 中提出。

该论文的摘要如下：

*在消除全球语言障碍这一目标的驱动下，机器翻译已成为当今人工智能研究的关键焦点。然而，相关努力大多集中在少数语言上，而绝大多数低资源语言则被忽视。在确保结果安全且高质量的同时，如何突破 200 种语言的壁垒，并始终将伦理考量纳入其中？在 No Language Left Behind 中，我们首先通过与母语者的探索性访谈，阐明了低资源语言翻译支持的需求背景，从而迎接这一挑战。随后，我们创建了旨在缩小低资源语言与高资源语言之间性能差距的数据集和模型。更具体地说，我们开发了一种基于 Sparsely Gated Mixture of Experts 的条件计算模型，该模型使用专为低资源语言量身定制的新型高效数据挖掘技术获取的数据进行训练。我们提出了多项架构和训练改进，以在数千个任务上训练时对抗过拟合。至关重要的是，我们使用人工翻译基准 Flores-200 评估了超过 40,000 种不同翻译方向的性能，并将人工评估与覆盖 Flores-200 中所有语言的新型毒性基准相结合，以评估翻译的安全性。我们的模型相较于先前的最先进方法实现了 44% 的 BLEU 提升，为实现通用翻译系统奠定了重要基础。*

该模型由 [Arthur Zucker](https://huggingface.co/ArthurZ) 贡献。原始代码可在[此处](https://github.com/facebookresearch/fairseq)找到。

## 使用技巧

- M2M100ForConditionalGeneration 是 NLLB 和 NLLB MoE 的基础模型
- NLLB-MoE 与 NLLB 模型非常相似，但其前馈层基于 SwitchTransformers 的实现。
- 分词器与 NLLB 模型相同。

## 与 SwitchTransformers 的实现差异

最大的区别在于 token 的路由方式。NLLB-MoE 使用 `top-2-gate`，这意味着对于每个输入，仅根据门控网络预测的最高概率选择前两个专家，其余专家则被忽略。在 `SwitchTransformers` 中，仅计算 top-1 概率，这意味着 token 被转发的概率更低。此外，如果一个 token 未被路由到任何专家，`SwitchTransformers` 仍会添加其未修改的隐藏状态（类似于残差连接），而在 `NLLB` 的 top-2 路由机制中，这些状态会被屏蔽。

## 使用 NLLB-MoE 进行生成

可用的检查点大约需要 350GB 的存储空间。如果您的机器内存不足，请务必使用 `accelerate`。

在生成目标文本时，将 `forced_bos_token_id` 设置为目标语言的 id。以下示例展示了如何使用 *facebook/nllb-200-distilled-600M* 模型将英语翻译为法语。

请注意，我们使用的是法语的 BCP-47 代码 `fra_Latn`。有关 Flores 200 数据集中所有 BCP-47 代码的列表，请参见 [此处](https://github.com/facebookresearch/flores/blob/main/flores200/README.md#languages-in-flores-200)。

```python
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("facebook/nllb-moe-54b")
model = AutoModelForSeq2SeqLM.from_pretrained("facebook/nllb-moe-54b", device_map="auto")

article = "Previously, Ring's CEO, Jamie Siminoff, remarked the company started when his doorbell wasn't audible from his shop in his garage."
inputs = tokenizer(article, return_tensors="pt").to(model.device)

translated_tokens = model.generate(
    **inputs, forced_bos_token_id=tokenizer.lang_code_to_id["fra_Latn"], max_length=50
)
tokenizer.batch_decode(translated_tokens, skip_special_tokens=True)[0]
"Auparavant, le PDG de Ring, Jamie Siminoff, a fait remarquer que la société avait commencé lorsque sa sonnette n'était pas audible depuis son magasin dans son garage."
```

### 从除英语以外的其他语言生成

English `eng_Latn` 被设置为默认的翻译源语言。若要指定从其他语言进行翻译，应在分词器初始化的 `src_lang` 关键字参数中指定 BCP-47 代码。

请参见下方从罗马尼亚语翻译到德语的示例：

```python
from transformers import AutoModelForSeq2SeqLM, AutoTokenizer

tokenizer = AutoTokenizer.from_pretrained("facebook/nllb-moe-54b", src_lang="ron_Latn")
model = AutoModelForSeq2SeqLM.from_pretrained("facebook/nllb-moe-54b", device_map="auto")

article = "Şeful ONU spune că nu există o soluţie militară în Siria"
inputs = tokenizer(article, return_tensors="pt").to(model.device)

translated_tokens = model.generate(
    **inputs, forced_bos_token_id=tokenizer.lang_code_to_id["deu_Latn"], max_length=30
)
tokenizer.batch_decode(translated_tokens, skip_special_tokens=True)[0]
```

## 资源

- [翻译任务指南](../tasks/translation)
- [摘要任务指南](../tasks/summarization)

## NllbMoeConfig[[transformers.NllbMoeConfig]]

#### transformers.NllbMoeConfig[[transformers.NllbMoeConfig]]

```python
transformers.NllbMoeConfig(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, 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, is_encoder_decoder: bool = True, vocab_size: int = 128112, max_position_embeddings: int = 1024, encoder_layers: int = 12, encoder_ffn_dim: int = 4096, encoder_attention_heads: int = 16, decoder_layers: int = 12, decoder_ffn_dim: int = 4096, decoder_attention_heads: int = 16, encoder_layerdrop: float | int = 0.05, decoder_layerdrop: float | int = 0.05, use_cache: bool = True, activation_function: str = 'relu', d_model: int = 1024, dropout: float | int = 0.1, attention_dropout: float | int = 0.1, activation_dropout: float | int = 0.0, init_std: float = 0.02, decoder_start_token_id: int | None = 2, scale_embedding: bool = True, router_bias: bool = False, router_dtype: typing.Literal['float32', 'float16', 'bfloat16'] = 'float32', router_ignore_padding_tokens: bool = False, num_experts: int = 128, expert_capacity: int = 64, encoder_sparse_step: int = 4, decoder_sparse_step: int = 4, router_z_loss_coef: float = 0.001, router_aux_loss_coef: float = 0.001, second_expert_policy: str = 'all', normalize_router_prob_before_dropping: bool = False, batch_prioritized_routing: bool = False, moe_eval_capacity_token_fraction: float = 1.0, moe_token_dropout: float | int = 0.2, pad_token_id: int | None = 1, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 2, tie_word_embeddings: bool = True, output_router_logits: bool = False)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/configuration_nllb_moe.py#L26)

**参数：**

is_encoder_decoder (`bool`，*可选*，默认为 `True`)：模型是否用作编码器/解码器。

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

max_position_embeddings (`int`，*可选*，默认为 `1024`)：该模型可能使用的最大序列长度。

encoder_layers (`int`，*可选*，默认为 `12`)：Transformer 编码器中的隐藏层数。如果未设置，将使用与 `num_layers` 相同的值。

encoder_ffn_dim (`int`, *可选*，默认为 `4096`)：编码器中“中间”（通常称为前馈）层的维度。

encoder_attention_heads (`int`，*可选*，默认为 `16`)：Transformer 编码器中每个注意力层的注意力头数量。

decoder_layers (`int`，*可选*，默认为 `12`)：Transformer 解码器中的隐藏层数。如果未设置，将使用与 `num_layers` 相同的值。

decoder_ffn_dim (`int`，*可选*，默认为 `4096`)：解码器中“中间”（通常称为前馈）层的维度。

decoder_attention_heads (`int`，*可选*，默认为 `16`)：Transformer 解码器中每个注意力层的注意力头数量。

encoder_layerdrop (`Union[float, int]`，*可选*，默认值为 `0.05`)：编码器的 LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](see https://huggingface.co/papers/1909.11556)。

decoder_layerdrop (`Union[float, int]`，*可选*，默认值为 `0.05`)：解码器的 LayerDrop 概率。有关更多详细信息，请参阅 [LayerDrop 论文](see https://huggingface.co/papers/1909.11556)。

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

activation_function (`str`，*可选*，默认为 `relu`)：解码器中的非线性激活函数（函数或字符串）。例如，`"gelu"`、`"relu"`、`"silu"` 等。

d_model (`int`，*可选*，默认为 `1024`)：编码器层和池化层的大小。

dropout (`Union[float, int]`，*可选*，默认为 `0.1`)：所有 dropout 层的比率。

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

activation_dropout (`Union[float, int]`，*可选*，默认值为 `0.0`)：全连接层内部激活值的 dropout 比率。

init_std (`float`，*可选*，默认值为 `0.02`)：用于初始化所有权重矩阵的 truncated_normal_initializer 的标准差。

decoder_start_token_id (`int`，*可选*，默认为 `2`)：如果编码器-解码器模型以不同于 `bos` 的 token 开始解码，则该 token 的 id。

scale_embedding (`bool`, *可选*, 默认为 `True`) : 是否通过将嵌入除以 sqrt(d_model) 来对其进行缩放。

router_bias (`bool`，*可选*，默认为 `False`)：路由器的分类器是否应包含偏置。

router_dtype (`str`, *可选*，默认为 `"float32"`)：用于路由器的 `dtype`。建议将 `dtype` 保持为 `"float32"`，如 [该论文](https://huggingface.co/papers/2101.03961) 中关于 *选择性精度* 的讨论所述。

router_ignore_padding_tokens (`bool`，*可选*，默认为 `False`)：是否在路由时忽略填充标记。如果为 `False`，则填充标记不会被路由到任何专家。

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

expert_capacity (`int`，*可选*，默认为 64)：每个专家可以存储的 token 数量。

encoder_sparse_step (`int`, *可选*，默认为 4)：编码器中稀疏层的频率。4 表示每 4 层中有 1 层为稀疏层。

decoder_sparse_step (`int`, *可选*，默认为 4)：解码器中稀疏层的频率。4 表示每 4 层中有 1 层为稀疏层。

router_z_loss_coef (`float`, *可选*，默认为 `0.001`)：路由器 z-loss 的系数，用于惩罚较大的路由器 logits，以提升训练稳定性。

router_aux_loss_coef (`float`, *可选*，默认为 `0.001`)：辅助负载均衡损失系数。用于惩罚 MoE 模型中专家路由的不均衡。

second_expert_policy (`str`, *可选*, 默认为 `"all"`) : 用于对每个 token 被采样到第二个专家的概率进行采样的策略。

normalize_router_prob_before_dropping (`bool`, *可选*, 默认为 `True`) : 是否根据专家容量（容量丢弃）应用掩码之前，对路由器概率进行归一化。

batch_prioritized_routing (`bool`，*可选*，默认为 `True`)：是否在容量丢弃之前按路由概率对 token 进行排序。这意味着概率最高的 token 会优先于序列中位置更靠后的其他 token 被路由。

moe_eval_capacity_token_fraction (`float`, *可选*，默认为 1.0)：验证期间作为容量的 token 比例，如果设置为负值，则使用与训练相同的值。应在以下范围内：(0.0, 1.0]。

moe_token_dropout (`float`, *optional*, 默认值为 0.2) : MoE 专家输出掩码（EOM）的掩码率，该功能通过对专家输出应用 Dropout2d 来实现。

pad_token_id (`int`，*可选*，默认为 `1`)：词表中用于填充的 token id。

bos_token_id (`int`，*可选*，默认为 `0`)：词汇表中用于表示流开始的 token id。

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

tie_word_embeddings (`bool`，*可选*，默认为 `True`)：是否根据模型的 `tied_weights_keys` 映射来绑定权重嵌入。

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

这是用于存储 Nllb Moe 模型配置的类。它根据指定的参数实例化 Nllb Moe 模型，并定义模型架构。使用默认值实例化配置将得到与 [facebook/nllb-moe-54b](https://huggingface.co/facebook/nllb-moe-54b) 类似的配置。

配置对象继承自 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig)，可用于控制模型输出。有关更多信息，请参阅 [PreTrainedConfig](/docs/transformers/v5.23.0/zh/main_classes/configuration#transformers.PreTrainedConfig) 的文档。

示例：

```python
>>> from transformers import NllbMoeModel, NllbMoeConfig

>>> # Initializing a NllbMoe facebook/nllb-moe-54b style configuration
>>> configuration = NllbMoeConfig()

>>> # Initializing a model from the facebook/nllb-moe-54b style configuration
>>> model = NllbMoeModel(configuration)

>>> # Accessing the model configuration
>>> configuration = model.config
```

## NllbMoeTop2Router[[transformers.NllbMoeTop2Router]]

#### transformers.NllbMoeTop2Router[[transformers.NllbMoeTop2Router]]

```python
transformers.NllbMoeTop2Router(config: NllbMoeConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L168)

使用 token 的 Router 选择 top-2 专家分配。

该路由器使用了与 fairseq 仓库中 NLLB-MoE 相同的机制。各项按 router_probs 排序，然后路由到其选择的专家，直到该专家的 expert_capacity 达到上限。**不保证每个 token 都由某个专家处理**，也不保证每个专家至少接收一个 token。

组合权重也会由路由器返回，以确保未更新的状态会被屏蔽。

#### route_tokens[[transformers.NllbMoeTop2Router.route_tokens]]

```python
route_tokens(router_logits: Tensor, input_dtype: dtype = torch.float32, padding_mask: typing.Optional[torch.LongTensor] = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L209)

计算每个专家的 `dispatch_mask` 和 `dispatch_weights`。这些掩码会根据专家容量进行调整。

#### forward[[transformers.NllbMoeTop2Router.forward]]

```python
forward(hidden_states: Tensor, padding_mask: typing.Optional[torch.LongTensor] = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L294)

**参数：**

hidden_states (`torch.Tensor`) : 形状为 (batch_size, sequence_length, hidden_dim) 的张量，用于计算路由器概率。

**返回：** top_1_mask（形状为 (batch_size, sequence_length) 的 `torch.Tensor`）

形状为 [batch_size, sequence_length] 的索引张量，对应于使用路由器的 top1 概率为每个 token 选定的专家。router_probabilities (`torch.Tensor`，形状为 (batch_size, sequence_length, nump_experts))：形状为 (batch_size, sequence_length, num_experts) 的张量，对应于每个 token 和专家的概率。用于将 token 路由到专家。router_logits (`torch.Tensor`，形状为 (batch_size, sequence_length))：形状为 (batch_size, sequence_length, num_experts) 的 logits 张量，对应于原始路由器 logits。这将在后续用于计算路由器 z-loss。

隐藏状态会被重塑，以简化路由器概率的计算（将每个专家的权重合并。）

## NllbMoeSparseMLP[[transformers.NllbMoeSparseMLP]]

#### transformers.NllbMoeSparseMLP[[transformers.NllbMoeSparseMLP]]

```python
transformers.NllbMoeSparseMLP(config: NllbMoeConfig, ffn_dim: int)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L370)

NLLB-MoE 稀疏 MLP 模块的实现。

#### forward[[transformers.NllbMoeSparseMLP.forward]]

```python
forward(hidden_states: Tensor, padding_mask: typing.Optional[torch.Tensor] = None)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L381)

## NllbMoeModel[[transformers.NllbMoeModel]]

#### transformers.NllbMoeModel[[transformers.NllbMoeModel]]

```python
transformers.NllbMoeModel(config: NllbMoeConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L865)

**参数：**

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

未添加任何特定头部的裸 Nllb Moe Model，直接输出原始隐藏状态。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/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.NllbMoeModel.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.LongTensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, past_key_values: transformers.cache_utils.Cache | None = None, inputs_embeds: typing.Optional[torch.Tensor] = None, decoder_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/nllb_moe/modeling_nllb_moe.py#L892)

**参数：**

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

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：解码器输入序列中词元在词汇表中的索引。 可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。 有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。 [什么是解码器输入 ID？](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：用于避免对特定 token 索引执行注意力机制的掩码。默认情况下，会使用因果掩码，以确保模型只能查看之前的输入来预测未来。

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *可选*) : 元组由 (`last_hidden_state`, *可选*: `hidden_states`, *可选*: `attentions`) 组成。`last_hidden_state` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*) 是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力中。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/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` 索引转换为对应的向量，这将非常有用。

decoder_inputs_embeds (`torch.Tensor`，形状为 `(batch_size, target_sequence_length, hidden_size)`，*可选*)：可选地，您可以选择直接传入嵌入表示，而不是传入 `decoder_input_ids`。如果使用了 `past_key_values`，则只需输入最后一段 `decoder_inputs_embeds`（参见 `past_key_values`）。如果您希望比模型内部的嵌入查找矩阵更精细地控制将 `decoder_input_ids` 索引转换为对应向量的方式，这将非常有用。如果 `decoder_input_ids` 和 `decoder_inputs_embeds` 均未设置，则 `decoder_inputs_embeds` 将取 `inputs_embeds` 的值。

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

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

`Seq2SeqMoEModelOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（`None`）和输入。

[NllbMoeModel](/docs/transformers/v5.23.0/zh/model_doc/nllb-moe#transformers.NllbMoeModel) 的 forward 方法重写了 `__call__` 特殊方法。

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

- **last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`）-- 模型解码器最后一层输出的隐藏状态序列。

  如果使用了 `past_key_values`，则仅输出形状为 `(batch_size, 1, hidden_size)` 的序列的最后一个隐藏状态。
- **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

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

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

  解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **decoder_router_logits** (`tuple(torch.Tensor)`，*可选*，在传入 `output_router_logits=True` 或 `config.add_router_probs=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, sequence_length, num_experts)`。

  解码器模型的 Router logits，可用于计算混合专家（Mixture of Experts）模型的辅助损失。
- **cross_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。
- **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。
- **encoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

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

  编码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **encoder_router_logits** (`tuple(torch.Tensor)`，*可选*，在传入 `output_router_logits=True` 或 `config.add_router_probs=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, sequence_length, num_experts)`。

  编码器模型的 Router logits，可用于计算稀疏模块的辅助损失和 z_loss。

## NllbMoeForConditionalGeneration[[transformers.NllbMoeForConditionalGeneration]]

#### transformers.NllbMoeForConditionalGeneration[[transformers.NllbMoeForConditionalGeneration]]

```python
transformers.NllbMoeForConditionalGeneration(config: NllbMoeConfig)
```

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L1044)

**参数：**

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

带有语言建模头的 NllbMoe 模型。可用于摘要生成。

该模型继承自 [PreTrainedModel](/docs/transformers/v5.23.0/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.NllbMoeForConditionalGeneration.forward]]

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

[来源](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/nllb_moe/modeling_nllb_moe.py#L1060)

**参数：**

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

decoder_input_ids (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：解码器输入序列中词元在词汇表中的索引。 可以使用 [AutoTokenizer](/docs/transformers/v5.23.0/zh/model_doc/auto#transformers.AutoTokenizer) 获取索引。 有关详细信息，请参阅 [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) 和 [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/zh/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__)。 [什么是解码器输入 ID？](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.LongTensor`，形状为 `(batch_size, target_sequence_length)`，*可选*)：用于避免对特定 token 索引执行注意力机制的掩码。默认情况下，会使用因果掩码，以确保模型只能查看之前的输入来预测未来。

encoder_outputs (`tuple[tuple[torch.Tensor]]`, *可选*) : 元组由 (`last_hidden_state`, *可选*: `hidden_states`, *可选*: `attentions`) 组成。`last_hidden_state` 的形状为 `(batch_size, sequence_length, hidden_size)`，*可选*) 是编码器最后一层输出的隐藏状态序列。用于解码器的交叉注意力中。

past_key_values (`~cache_utils.Cache`，*可选*)：预计算的隐藏状态（自注意力块和交叉注意力块中的键和值），可用于加速顺序解码。这通常由模型在解码的先前阶段返回的 `past_key_values` 组成，前提是 `use_cache=True` 或 `config.use_cache=True`。 仅允许 [Cache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.Cache) 实例作为输入，请参阅我们的 [kv cache guide](https://huggingface.co/docs/transformers/en/kv_cache)。如果未传入 `past_key_values`，则默认初始化 [DynamicCache](/docs/transformers/v5.23.0/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` 索引转换为对应的向量，这将非常有用。

decoder_inputs_embeds (`torch.Tensor`，形状为 `(batch_size, target_sequence_length, hidden_size)`，*可选*)：可选地，您可以选择直接传入嵌入表示，而不是传入 `decoder_input_ids`。如果使用了 `past_key_values`，则只需输入最后一段 `decoder_inputs_embeds`（参见 `past_key_values`）。如果您希望比模型内部的嵌入查找矩阵更精细地控制将 `decoder_input_ids` 索引转换为对应向量的方式，这将非常有用。如果 `decoder_input_ids` 和 `decoder_inputs_embeds` 均未设置，则 `decoder_inputs_embeds` 将取 `inputs_embeds` 的值。

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`）。

output_router_logits (`bool`, *可选*) : 是否返回所有路由器的 logits。它们对于计算路由器损失很有用，在推理期间不应返回。

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

`Seq2SeqMoEOutput` 或 `torch.Tensor` 元组（如果传入 `return_dict=False` 或 `config.return_dict=False`），其包含的元素取决于配置（[NllbMoeConfig](/docs/transformers/v5.23.0/zh/model_doc/nllb-moe#transformers.NllbMoeConfig)）和输入。

[NllbMoeForConditionalGeneration](/docs/transformers/v5.23.0/zh/model_doc/nllb-moe#transformers.NllbMoeForConditionalGeneration) 的 forward 方法重写了 `__call__` 特殊方法。

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

- **loss** (`torch.Tensor`，形状为 `(1,)`，*可选*，在提供 `labels` 时返回) -- 语言建模损失。
- **logits**（形状为 `(batch_size, sequence_length, config.vocab_size)` 的 `torch.Tensor`）-- 语言建模头的预测分数（SoftMax 之前每个词汇表 token 的分数）。
- **past_key_values**（`EncoderDecoderCache`，*可选*，在传入 `use_cache=True` 或 `config.use_cache=True` 时返回）-- 它是一个 [EncoderDecoderCache](/docs/transformers/v5.23.0/zh/internal/generation_utils#transformers.EncoderDecoderCache) 实例。更多详情，请参阅我们的 [kv cache 指南](https://huggingface.co/docs/transformers/en/kv_cache)。

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

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

  解码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **decoder_router_logits** (`tuple(torch.Tensor)`，*可选*，在传入 `output_router_logits=True` 或 `config.add_router_probs=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, sequence_length, num_experts)`。

  解码器模型的 Router logits，可用于计算混合专家（Mixture of Experts）模型的辅助损失。
- **cross_attentions** (`tuple(torch.Tensor)`，*可选*，在传入 `output_attentions=True` 或 `config.output_attentions=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, num_heads, sequence_length, sequence_length)`。

  解码器交叉注意力层在注意力 softmax 之后的注意力权重，用于在交叉注意力头中计算加权平均值。
- **encoder_last_hidden_state**（形状为 `(batch_size, sequence_length, hidden_size)` 的 `torch.Tensor`，*可选*）-- 模型编码器最后一层输出的隐藏状态序列。
- **encoder_hidden_states** (`tuple(torch.Tensor)`，*可选*，在传入 `output_hidden_states=True` 或 `config.output_hidden_states=True` 时返回) -- 一个 `torch.Tensor` 元组（如果模型具有嵌入层，则包含嵌入层的输出，以及每一层的输出），形状为 `(batch_size, sequence_length, hidden_size)`。

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

  编码器在注意力 softmax 之后的注意力权重，用于在自注意力头中计算加权平均值。
- **encoder_router_logits** (`tuple(torch.Tensor)`，*可选*，在传入 `output_router_logits=True` 或 `config.add_router_probs=True` 时返回) -- 一个 `torch.Tensor` 元组（每层一个），形状为 `(batch_size, sequence_length, num_experts)`。

  编码器模型的 Router logits，可用于计算混合专家（Mixture of Experts）模型的辅助损失和 z_loss。

示例：

```python
```

