# Laguna

Laguna — это семейство языковых моделей с архитектурой mixture-of-experts от Poolside. Специфические для Laguna отличия от стандартного SwiGLU MoE-трансформера:

- **Число голов на слой** через `num_attention_heads_per_layer` — разные слои декодера могут иметь разное количество query-голов, при этом общая форма KV-кэша остаётся неизменной.
- **Маршрутизатор Sigmoid MoE со сбалансировкой нагрузки без вспомогательной функции потерь** ([arXiv:2408.15664](https://huggingface.co/papers/2408.15664)) и необязательное ограничение логитов (`moe_router_logit_softcapping`) — оценки маршрутизатора представляют собой поэлементный сигмоид логитов гейта плюс обучаемое смещение для каждого эксперта (`e_score_correction_bias`), которое добавляется только на этапе выбора.

## Использование

```python
from transformers import pipeline

pipe = pipeline(
    "text-generation",
    model="poolside/Laguna-XS.2",
    dtype="auto",
    device_map="auto",
)
print(pipe("The capital of France is", max_new_tokens=20, do_sample=False)[0]["generated_text"])
```

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

model_id = "poolside/Laguna-XS.2"
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(
    model_id,
    dtype=torch.bfloat16,
    device_map="auto",
)

prompt = "The capital of France is"
inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
generated = model.generate(**inputs, max_new_tokens=20, do_sample=False)
print(tokenizer.decode(generated[0], skip_special_tokens=True))
```

## Примечания

- **Бэкенды внимания.** Поддерживаются SDPA (по умолчанию), FlashAttention-2 и flex attention. Гейтинг выхода внимания применяется вне вызова ядра, поэтому работает со всеми бэкендами.
- **`num_attention_heads_per_layer`.** Если параметр задан, его длина должна быть равна `num_hidden_layers`. Каждое значение должно делиться нацело на `num_key_value_heads`.
- **`layer_types`.** По умолчанию равно `["full_attention"] * num_hidden_layers`, если не задано. Чтобы включить скользящее окно внимания, передайте список значений `"full_attention"` / `"sliding_attention"`.
- **`mlp_layer_types`.** Тип MLP для каждого слоя, значения `"dense"` или `"sparse"`. Длина должна быть равна `num_hidden_layers`. По умолчанию `["dense"] + ["sparse"] * (num_hidden_layers - 1)` (первый слой dense, остальные MoE), если значение не задано.
- **`moe_apply_router_weight_on_input=True`** в настоящее время не поддерживается в сочетании с ядром объединённых экспертов (`grouped_mm_experts_forward`); `validate_architecture` вызывает ошибку на этапе создания конфигурации. Установите значение `False` (по умолчанию).

## LagunaConfig[[transformers.LagunaConfig]]

#### transformers.LagunaConfig[[transformers.LagunaConfig]]

```python
transformers.LagunaConfig(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 = 100352, hidden_size: int = 2048, intermediate_size: int = 8192, num_hidden_layers: int = 40, num_attention_heads: int = 48, num_key_value_heads: int = 8, hidden_act: str = 'silu', max_position_embeddings: int = 131072, 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, sliding_window: int = 512, attention_dropout: float | int = 0.0, moe_intermediate_size: int = 512, shared_expert_intermediate_size: int = 512, num_experts_per_tok: int = 8, num_experts: int = 256, output_router_logits: bool = False, router_aux_loss_coef: float = 0.001, layer_types: list[str] | None = None, pad_token_id: int | None = None, bos_token_id: int | None = None, eos_token_id: int | list[int] | None = None, head_dim: int = 128, attention_bias: bool = False, gating: bool | str = True, num_attention_heads_per_layer: list[int] | None = None, mlp_layer_types: list[str] | None = None, moe_routed_scaling_factor: float = 1.0, moe_apply_router_weight_on_input: bool = False, moe_router_logit_softcapping: float = 0.0)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/laguna/configuration_laguna.py#L31)

**Параметры:**

vocab_size (*int*, *optional*, по умолчанию *100352*) : Размер словаря модели. Определяет количество различных токенов, которые могут быть представлены в *input_ids*.

hidden_size (*int*, *optional*, по умолчанию *2048*) : Размерность скрытых представлений.

intermediate_size (*int*, *optional*, по умолчанию *8192*) : Размерность представлений MLP.

num_hidden_layers (*int*, *optional*, по умолчанию *40*) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (*int*, *optional*, по умолчанию *48*) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

num_key_value_heads (*int*, *optional*, по умолчанию *8*) : Это количество ключевых и value-голов, которое следует использовать для реализации Grouped Query Attention. Если *num_key_value_heads=num_attention_heads*, модель будет использовать Multi Head Attention (MHA), если *num_key_value_heads=1* — Multi Query Attention (MQA), в противном случае используется GQA. При конвертации multi-head checkpoint в GQA checkpoint каждая группа ключевых и value-голов должна быть построена путем усреднения (meanpooling) всех исходных голов в этой группе. Подробнее см. в [этой статье](https://huggingface.co/papers/2305.13245). Если значение не указано, по умолчанию используется *num_attention_heads*.

hidden_act (*str*, *optional*, по умолчанию *silu*) : Нелинейная функция активации (функция или строка) в декодере. Например, *"gelu"*, *"relu"*, *"silu"* и т. д.

max_position_embeddings (*int*, *optional*, по умолчанию *131072*) : Максимальная длина последовательности, с которой может использоваться данная модель.

initializer_range (*float*, *optional*, по умолчанию *0.02*) : Стандартное отклонение truncated_normal_initializer для инициализации всех матриц весов.

rms_norm_eps (*float*, *optional*, по умолчанию *1e-06*) : Эпсилон, используемый слоями нормализации rms.

use_cache (*bool*, *optional*, по умолчанию *True*) : Следует ли модели возвращать последние значения внимания key/values (не используется во всех моделях). Актуально только если *config.is_decoder=True* или если модель является генеративной моделью только с декодером.

tie_word_embeddings (*bool*, *optional*, по умолчанию *False*) : Связывать ли веса эмбеддингов согласно маппингу *tied_weights_keys* модели.

rope_parameters (*Union[~modeling_rope_utils.RopeParameters, dict]*, *optional*) : Словарь, содержащий параметры конфигурации для вложений RoPE. Словарь должен содержать значение для *rope_theta* и, при необходимости, параметры, используемые для масштабирования, если вы хотите использовать RoPE с более длинными *max_position_embeddings*.

sliding_window (*int*, *optional*, по умолчанию *512*) : Размер окна скользящего внимания. Если *None*, скользящее окно не применяется.

attention_dropout (*Union[float, int]*, *optional*, по умолчанию *0.0*) : Доля dropout для вероятностей внимания.

moe_intermediate_size (*int*, *optional*, по умолчанию *512*) : Промежуточный размер MLP маршрутизированных экспертов.

shared_expert_intermediate_size (*int*, *optional*, по умолчанию *512*) : Промежуточный размер общих экспертных MLP.

num_experts_per_tok (*int*, *optional*, по умолчанию *8*) : Количество экспертов, к которым маршрутизируется каждый токен. Это значение top-k для маршрутизации по выбору токена.

num_experts (*int*, *optional*, по умолчанию *256*) : Количество маршрутизируемых экспертов в слоях MoE.

output_router_logits (*bool*, *optional*, по умолчанию *False*) : Определяет, следует ли модели возвращать логиты маршрутизатора. Включение этого параметра также позволит модели выводить вспомогательную потерю, включая потерю балансировки нагрузки и z-потерю маршрутизатора.

router_aux_loss_coef (*float*, *optional*, по умолчанию *0.001*) : Коэффициент вспомогательной функции потерь для балансировки нагрузки. Используется для штрафования неравномерного маршрутизирования запросов к экспертам в MoE-моделях.

layer_types (*list[str]*, *optional*) : Список, который явно сопоставляет каждый индекс слоя с его типом. Если не указан, будет автоматически сгенерирован на основе значений конфигурации.

pad_token_id (*int*, *optional*) : Идентификатор токена, используемый для выравнивания (padding) в словаре.

bos_token_id (*int*, *optional*) : Идентификатор токена, используемый для обозначения начала потока в словаре.

eos_token_id (*Union[int, list[int]]*, *optional*) : Идентификатор токена, используемый для обозначения конца потока в словаре.

head_dim (*int*, *optional*, по умолчанию *128*) : Размер измерения головы внимания. Если None, по умолчанию будет hidden_size // num_attention_heads

attention_bias (*bool*, *optional*, по умолчанию *False*) : Использовать ли смещение (bias) в слоях проекции запроса, ключа, значения и вывода при само-внимании.

gating (*bool* или *str*, *необязательный*, по умолчанию *True*) : Гранулярность выходного шлюза Softplus. `True` или `"per-head"` применяет один шлюз на каждую голову, с распространением по `head_dim`; `"per-element"` применяет один шлюз на каждый канал `(head, head_dim)`.

num_attention_heads_per_layer (*list[int]*, *optional*) : Переопределение для `num_attention_heads` на каждый слой. Длина должна быть равна `num_hidden_layers`.

mlp_layer_types (*list[str]*, *optional*) : Тип MLP для каждого слоя — `"dense"` или `"sparse"`. Длина должна быть равна `num_hidden_layers`. По умолчанию первый слой — dense, остальные — sparse.

moe_routed_scaling_factor (*float*, *optional*, по умолчанию 1.0) : Скаляр, применяемый к выводу маршрутизированных экспертов перед объединением с выводом общего эксперта.

moe_apply_router_weight_on_input (*bool*, *optional*, по умолчанию *False*) : Применяются ли веса роутера к входу MoE, а не к выходу. В transformers пока не поддерживается; `True` на данный момент вызывает `NotImplementedError`.

moe_router_logit_softcapping (*float*, *optional*, по умолчанию 0.0) : Коэффициент масштабирования при применении tanh softcapping к логитам MoE-роутера.

Это класс конфигурации для хранения настроек LagunaModel. Он используется для создания модели Laguna в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации [poolside/laguna-XS.2](https://huggingface.co/poolside/laguna-XS.2)

Объекты конфигурации наследуются от [*PreTrainedConfig*] и могут использоваться для управления выводами модели. Подробнее см. в документации по [*PreTrainedConfig*].

Пример:

```python
>>> from transformers import LagunaModel, LagunaConfig

>>> configuration = LagunaConfig()
>>> model = LagunaModel(configuration)
>>> configuration = model.config
```

#### validate_architecture[[transformers.LagunaConfig.validate_architecture]]

```python
validate_architecture()
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/laguna/configuration_laguna.py#L150)

Часть валидации, работающей на базе `@strict`.

## LagunaModel[[transformers.LagunaModel]]

#### transformers.LagunaModel[[transformers.LagunaModel]]

```python
transformers.LagunaModel(config: LagunaConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/laguna/modeling_laguna.py#L497)

**Параметры:**

config ([LagunaConfig](/docs/transformers/v5.23.0/ru/model_doc/laguna#transformers.LagunaConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Laguna без дополнительных слоёв, выводящая необработанные скрытые состояния.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.LagunaModel.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/laguna/modeling_laguna.py#L514)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

position_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона `[0, config.n_positions - 1]`.  [Что такое position IDs?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

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`), содержащий различные элементы в зависимости от конфигурации ([LagunaConfig](/docs/transformers/v5.23.0/ru/model_doc/laguna#transformers.LagunaConfig)) и входных данных.

Метод forward модели [LagunaModel](/docs/transformers/v5.23.0/ru/model_doc/laguna#transformers.LagunaModel) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache). Подробнее см. в нашем [руководстве по кэшированию kv](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)`.

  Сырые логиты маршрутизатора (после softmax), вычисляемые маршрутизаторами MoE; эти значения используются для вычисления вспомогательной функции потерь в моделях Mixture of Experts.

## LagunaForCausalLM[[transformers.LagunaForCausalLM]]

#### transformers.LagunaForCausalLM[[transformers.LagunaForCausalLM]]

```python
transformers.LagunaForCausalLM(config: LagunaConfig)
```

[Источник](https://github.com/huggingface/transformers/blob/v5.23.0/src/transformers/models/laguna/modeling_laguna.py#L653)

**Параметры:**

config ([LagunaConfig](/docs/transformers/v5.23.0/ru/model_doc/laguna#transformers.LagunaConfig)) : Класс конфигурации модели со всеми параметрами модели. Инициализация с файлом конфигурации не загружает веса, связанные с моделью, только конфигурацию. Используйте метод [from_pretrained()](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel.from_pretrained) для загрузки весов модели.

Модель Laguna для каузального моделирования языка.

Эта модель наследуется от [PreTrainedModel](/docs/transformers/v5.23.0/ru/main_classes/model#transformers.PreTrainedModel). Общие методы, которые библиотека реализует для всех своих моделей (например, загрузка или сохранение, изменение размера входных эмбеддингов, обрезка головок и т. д.), описаны в документации родительского класса.

Эта модель также является подклассом [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) в PyTorch. Используйте её как обычный модуль PyTorch и обращайтесь к документации PyTorch по всем вопросам, связанным с общим использованием и поведением.

#### forward[[transformers.LagunaForCausalLM.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, output_router_logits: 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/laguna/modeling_laguna.py#L672)

**Параметры:**

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы токенов входной последовательности в словаре. По умолчанию заполнение (padding) игнорируется. Индексы можно получить с помощью [AutoTokenizer](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoTokenizer). Подробности см. в [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) и [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ru/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__). [Что такое входные идентификаторы?](../glossary#input-ids)

attention_mask (`torch.Tensor` формы `(batch_size, sequence_length)`, *необязательный*) : Маска для предотвращения применения внимания к индексам токенов отсечки. Значения маски выбираются из `[0, 1]`:  - 1 для токенов, которые **не замаскированы**, - 0 для токенов, которые **замаскированы**.  [Что такое маски внимания?](../glossary#attention-mask)

position_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Индексы позиций токенов каждого входного последовательности в позиционных эмбеддингах. Выбираются из диапазона `[0, config.n_positions - 1]`.  [Что такое position IDs?](../glossary#position-ids)

past_key_values (`~cache_utils.Cache`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `use_cache=True` или `config.use_cache=True`. В качестве входного значения допускается только экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache), см. наше [руководство по kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Если `past_key_values` не переданы, по умолчанию будет инициализирован [DynamicCache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.DynamicCache). Модель будет выводить тот же формат кэша, который был передан на вход. Если используются `past_key_values`, ожидается, что пользователь передаст только необработанные `input_ids` (те, для которых не заданы их прошлые состояния ключей и значений в этой модели) с формой `(batch_size, unprocessed_length)` вместо всех `input_ids` с формой `(batch_size, sequence_length)`.

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 (см. docstring `input_ids`). Токены с индексами, установленными в `-100`, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне `[0, ..., config.vocab_size]`.

use_cache (`bool`, *необязательный*) : Если установлено в `True`, состояния ключей и значений `past_key_values` возвращаются и могут использоваться для ускорения декодирования (см. `past_key_values`).

output_router_logits (`bool`, *необязательный*) : Нужно ли возвращать логиты всех роутеров. Они полезны для вычисления потери роутера и не должны возвращаться во время инференса.

logits_to_keep (`Union[int, torch.Tensor]`, *необязательный*, по умолчанию `0`) : Если передано значение типа `int`, вычисляются logits для последних `logits_to_keep` токенов. Если передано `0`, logits вычисляются для всех `input_ids` (специальный случай). Для генерации нужны logits только последнего токена, и вычисление их только для этого токена позволяет сэкономить память, что становится весьма значимым для длинных последовательностей или большого размера словаря. Если передано значение типа `torch.Tensor`, оно должно быть одномерным и соответствовать индексам, которые нужно сохранить в измерении длины последовательности. Это полезно при использовании упакованного формата тензоров (одно измерение для batch и длины последовательности).

**Возвращает:** `MoeCausalLMOutputWithPast` или `tuple(torch.Tensor)`

Объект `MoeCausalLMOutputWithPast` или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([LagunaConfig](/docs/transformers/v5.23.0/ru/model_doc/laguna#transformers.LagunaConfig)) и входных данных.

Метод forward класса [LagunaForCausalLM](/docs/transformers/v5.23.0/ru/model_doc/laguna#transformers.LagunaForCausalLM) переопределяет специальный метод `__call__`.

Хотя рецепт для прямого прохода должен быть определён внутри этой функции, после этого следует вызывать экземпляр `Module`, а не эту функцию, поскольку первый выполняет шаги предварительной и постобработки, тогда как второй молча их игнорирует.

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели (для предсказания следующего токена).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **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. Их можно использовать для вычисления функции потерь балансировки нагрузки или для анализа того, как токены распределяются по экспертам.
- **past_key_values** (`Cache`, *необязательный*, возвращается при передаче `use_cache=True` или когда `config.use_cache=True`) -- это экземпляр [Cache](/docs/transformers/v5.23.0/ru/internal/generation_utils#transformers.Cache). Подробнее см. в нашем [руководстве по кэшированию kv](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
```

