# UltraBERT

## Обзор

UltraBERT был представлен в работе [UltraBERT: Beyond the Limit of BERT Pre-Training](https://huggingface.co/papers/2610.15028) авторами Jungwoo Park, Taewhoo Lee и Jaewoo Kang. Это семейство двунаправленных текстовых энкодеров, обученных с использованием комбинации коэффициентов маскирования, обрезки и дистилляции для задач классификации и поиска.

Выпущенные энкодеры поддерживают последовательности длиной до 32 768 токенов. Они используют вращающиеся позиционные эмбеддинги (RoPE), RMSNorm, слои feed-forward SwiGLU, а также чередующиеся локальное и глобальное внимание. Каждые третий слой использует глобальное внимание. Остальные слои обращают внимание на текущий токен и до 128 токенов с каждой стороны. Базовое значение RoPE составляет 10 000 для локальных слоёв и 2 560 000 для глобальных слоёв.

| Чекпоинт | Слои | Размер скрытого слоя | Головки внимания | Использование |
|---|---|---|---|---|
| [UltraBERT-150M](https://huggingface.co/dmis-lab/UltraBERT-150M) | 24 | 768 | 6 | Маскированное моделирование языка и дообучение для прикладных задач |
| [UltraBERT-380M](https://huggingface.co/dmis-lab/UltraBERT-380M) | 24 | 1,024 | 8 | Маскированное моделирование языка и дообучение для прикладных задач |
| [UltraBERT-Embed-150M](https://huggingface.co/dmis-lab/UltraBERT-Embed-150M) | 24 | 768 | 6 | Векторные представления текста |

Чекпоинты для маскированного языкового моделирования содержат голову предсказания, обученную с низким коэффициентом маскирования. Веса её выхода не связаны с входными эмбеддингами. Токенайзер использует словарь SmolLM2, состоящий из 49 152 токенов.

## Примеры использования

### Маскированное моделирование языка

Используйте [Pipeline](/docs/transformers/v5.23.0/ru/main_classes/pipelines#transformers.Pipeline) или [AutoModelForMaskedLM](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoModelForMaskedLM) для предсказания замаскированного токена. Токен маски — `<|mask|>`.

```python
from transformers import pipeline

fill_mask = pipeline(
    task="fill-mask",
    model="dmis-lab/UltraBERT-150M",
    device_map="auto",
)
print(fill_mask("The capital of France is <|mask|>."))
# [
#     {'score': 0.9612365961074829, 'token': 7042, 'token_str': ' Paris',
#      'sequence': 'The capital of France is Paris.'},
#     {'score': 0.00930546224117279, 'token': 38034, 'token_str': ' Lyon',
#      'sequence': 'The capital of France is Lyon.'},
#     {'score': 0.008486305363476276, 'token': 44558, 'token_str': ' Nice',
#      'sequence': 'The capital of France is Nice.'},
#     {'score': 0.0034405170008540154, 'token': 37628, 'token_str': ' Versailles',
#      'sequence': 'The capital of France is Versailles.'},
#     {'score': 0.0014691735850647092, 'token': 4649, 'token_str': ' France',
#      'sequence': 'The capital of France is France.'}
# ]
```

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

checkpoint = "dmis-lab/UltraBERT-150M"
tokenizer = AutoTokenizer.from_pretrained(checkpoint)
model = AutoModelForMaskedLM.from_pretrained(checkpoint, device_map="auto")

inputs = tokenizer("The capital of France is <|mask|>.", return_tensors="pt").to(model.device)
with torch.no_grad():
    logits = model(**inputs).logits

masked_logits = logits[inputs.input_ids == tokenizer.mask_token_id]
print(tokenizer.batch_decode(masked_logits.argmax(dim=-1)[:, None]))
# [' Paris']
```

### Векторные представления текста

UltraBERT-Embed-150M использует скрытое состояние первого токена в качестве текстового эмбеддинга. Для поиска добавляйте инструкцию к запросу в начало, а документы кодируйте без инструкции. Используйте правое выравнивание (right padding), чтобы сохранить позицию первого токена. Инструкции для других задач см. в [карточке модели](https://huggingface.co/dmis-lab/UltraBERT-Embed-150M).

Приведённые ниже примеры выбирают скрытое состояние первого токена и нормализуют эмбеддинги так, чтобы их скалярное произведение давало косинусное сходство.

```python
import torch
import torch.nn.functional as F
from transformers import pipeline

extractor = pipeline(
    task="feature-extraction",
    model="dmis-lab/UltraBERT-Embed-150M",
    device_map="auto",
)

texts = [
    "Instruct: Given a question, retrieve passages that answer the question\nQuery: What is the capital of France?",
    "Paris is the capital of France.",
    "Berlin is the capital of Germany.",
]
features = extractor(texts, return_tensors=True, truncation=True, tokenize_kwargs={"max_length": 32768})
embeddings = F.normalize(torch.cat([output[:, 0] for output in features]), p=2, dim=-1)

print(embeddings[:1] @ embeddings[1:].T)
# tensor([[0.6527, 0.3981]])
```

```python
import torch
import torch.nn.functional as F
from transformers import AutoModel, AutoTokenizer

checkpoint = "dmis-lab/UltraBERT-Embed-150M"
tokenizer = AutoTokenizer.from_pretrained(checkpoint, padding_side="right")
model = AutoModel.from_pretrained(checkpoint, device_map="auto")

texts = [
    "Instruct: Given a question, retrieve passages that answer the question\nQuery: What is the capital of France?",
    "Paris is the capital of France.",
    "Berlin is the capital of Germany.",
]
inputs = tokenizer(texts, padding=True, truncation=True, max_length=32768, return_tensors="pt").to(model.device)
with torch.no_grad():
    embeddings = F.normalize(model(**inputs).last_hidden_state[:, 0], p=2, dim=-1)

print(embeddings[:1] @ embeddings[1:].T)
# tensor([[0.6527, 0.3981]], device='cuda:0')
```

## UltrabertConfig[[transformers.UltrabertConfig]]

#### transformers.UltrabertConfig[[transformers.UltrabertConfig]]

```python
transformers.UltrabertConfig(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 = 32000, hidden_size: int = 4096, intermediate_size: int = 11008, num_hidden_layers: int = 32, num_attention_heads: int = 32, num_key_value_heads: int | None = None, hidden_act: str = 'silu', max_position_embeddings: int = 32768, initializer_range: float = 0.02, rms_norm_eps: float = 1e-06, use_cache: bool = False, pad_token_id: int | None = 0, bos_token_id: int | None = 0, eos_token_id: int | list[int] | None = 0, tie_word_embeddings: bool = False, rope_parameters: transformers.modeling_rope_utils.RopeParameters | dict | None = None, attention_bias: bool = False, attention_dropout: int | float = 0.0, mlp_bias: bool = False, head_dim: int | None = None, classifier_pooling: typing.Literal['cls', 'mean'] = 'cls', sliding_window: int = 128, layer_types: list[str] | None = None, prediction_head_size: int = 768, classifier_dropout: float = 0.0)
```

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

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

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

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

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

num_hidden_layers (`int`, *необязательный*, по умолчанию `32`) : Количество скрытых слоев в декодере Transformer.

num_attention_heads (`int`, *необязательный*, по умолчанию `32`) : Количество головок внимания для каждого слоя внимания в декодере Transformer.

num_key_value_heads (`int`, *optional*) : Это количество ключевых и 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`, *необязательный*, по умолчанию `silu`) : Нелинейная функция активации (функция или строка) в декодере. Например, `"gelu"`, `"relu"`, `"silu"` и т. д.

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

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

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

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

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

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

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

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

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

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

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

mlp_bias (`bool`, *необязательный*, по умолчанию `False`) : Использовать ли смещение (bias) в слоях up_proj, down_proj и gate_proj в слоях MLP.

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

classifier_pooling (`str`, *необязательный*, по умолчанию `"cls"`) : Метод пулинга для классификации последовательностей. Либо `"cls"`, либо `"mean"`.

sliding_window (`int`, *optional*, по умолчанию 128) : Включительный радиус внимания с каждой стороны от каждого токена в слоях скользящего внимания.

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

prediction_head_size (`int`, *optional*, по умолчанию 768) : Промежуточное измерение двухслойной головы предсказания для маскированного языкового моделирования.

classifier_dropout (`float`, *необязательный*, по умолчанию `0.0`) : Коэффициент dropout для классификатора.

Это класс конфигурации для хранения настроек модели UltrabertModel. Он используется для создания модели Ultrabert в соответствии с указанными аргументами, определяя архитектуру модели. Создание конфигурации с параметрами по умолчанию даст конфигурацию, аналогичную конфигурации модели [dmis-lab/UltraBERT-150M](https://huggingface.co/dmis-lab/UltraBERT-150M)

Объекты конфигурации наследуются от [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig) и могут использоваться для управления выводами модели. Подробнее см. в документации [PreTrainedConfig](/docs/transformers/v5.23.0/ru/main_classes/configuration#transformers.PreTrainedConfig).

## UltrabertModel[[transformers.UltrabertModel]]

#### transformers.UltrabertModel[[transformers.UltrabertModel]]

```python
transformers.UltrabertModel(config: UltrabertConfig)
```

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

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

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

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

Эта модель наследуется от [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.UltrabertModel.forward]]

```python
forward(input_ids: typing.Optional[torch.Tensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

**Возвращает:** [BaseModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutput) или `tuple(torch.Tensor)`

[BaseModelOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.BaseModelOutput) или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([UltrabertConfig](/docs/transformers/v5.23.0/ru/model_doc/ultrabert#transformers.UltrabertConfig)) и входных данных.

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

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

- **last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`) -- Последовательность скрытых состояний на выходе последнего слоя модели.
- **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 в механизме внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

## UltrabertForMaskedLM[[transformers.UltrabertForMaskedLM]]

#### transformers.UltrabertForMaskedLM[[transformers.UltrabertForMaskedLM]]

```python
transformers.UltrabertForMaskedLM(config: UltrabertConfig)
```

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

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

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

Модель Ultrabert с декодерной головой, используемой для моделирования языка с маскированием.

Эта модель наследуется от [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.UltrabertForMaskedLM.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

labels (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Метки для вычисления потерь маскированного языкового моделирования. Индексы должны находиться в диапазоне `[-100, 0, ..., config.vocab_size]` (см. docstring `input_ids`). Токены с индексами, установленными в `-100`, игнорируются (маскируются); потери вычисляются только для токенов с метками в диапазоне `[0, ..., config.vocab_size]`.

**Возвращает:** [MaskedLMOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.MaskedLMOutput) или `tuple(torch.Tensor)`

[MaskedLMOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.MaskedLMOutput) или кортеж `torch.Tensor` (если передано `return_dict=False` или если `config.return_dict=False`), содержащий различные элементы в зависимости от конфигурации ([UltrabertConfig](/docs/transformers/v5.23.0/ru/model_doc/ultrabert#transformers.UltrabertConfig)) и входных данных.

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потери маскированного языкового моделирования (MLM).
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) — Оценки предсказаний языковой модели (оценки для каждого токена словаря до применения SoftMax).
- **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
>>> from transformers import AutoTokenizer, UltrabertForMaskedLM
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("dmis-lab/UltraBERT-150M")
>>> model = UltrabertForMaskedLM.from_pretrained("dmis-lab/UltraBERT-150M")

>>> inputs = tokenizer("The capital of France is <mask>.", return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> # retrieve index of <mask>
>>> mask_token_index = (inputs.input_ids == tokenizer.mask_token_id)[0].nonzero(as_tuple=True)[0]

>>> predicted_token_id = logits[0, mask_token_index].argmax(axis=-1)
>>> tokenizer.decode(predicted_token_id)
...

>>> labels = tokenizer("The capital of France is Paris.", return_tensors="pt")["input_ids"]
>>> # mask labels of non-<mask> tokens
>>> labels = torch.where(inputs.input_ids == tokenizer.mask_token_id, labels, -100)

>>> outputs = model(**inputs, labels=labels)
>>> round(outputs.loss.item(), 2)
...
```

## UltrabertForSequenceClassification[[transformers.UltrabertForSequenceClassification]]

#### transformers.UltrabertForSequenceClassification[[transformers.UltrabertForSequenceClassification]]

```python
transformers.UltrabertForSequenceClassification(config: UltrabertConfig)
```

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

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

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

Модель Ultrabert с головной частью для классификации последовательностей, выполняющей пулинг.

Эта модель наследуется от [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.UltrabertForSequenceClassification.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

labels (`torch.LongTensor` формы `(batch_size,)`, *необязательный*) : Метки для вычисления функции потерь классификации/регрессии последовательности. Индексы должны находиться в диапазоне `[0, ..., config.num_labels - 1]`. Если `config.num_labels == 1`, вычисляется функция потерь регрессии (среднеквадратичная ошибка), если `config.num_labels > 1` — функция потерь классификации (кросс-энтропия).

**Возвращает:** [SequenceClassifierOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.SequenceClassifierOutput) или `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потери классификации (или регрессии, если config.num_labels==1).
- **logits** (`torch.Tensor` формы `(batch_size, config.num_labels)`) — Оценки классификации (или регрессии, если config.num_labels==1) до применения SoftMax.
- **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
>>> import torch
>>> from transformers import AutoTokenizer, UltrabertForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("dmis-lab/UltraBERT-150M")
>>> model = UltrabertForSequenceClassification.from_pretrained("dmis-lab/UltraBERT-150M")

>>> inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> predicted_class_id = logits.argmax().item()
>>> model.config.id2label[predicted_class_id]
...

>>> # To train a model on `num_labels` classes, you can pass `num_labels=num_labels` to `.from_pretrained(...)`
>>> num_labels = len(model.config.id2label)
>>> model = UltrabertForSequenceClassification.from_pretrained("dmis-lab/UltraBERT-150M", num_labels=num_labels)

>>> labels = torch.tensor([1])
>>> loss = model(**inputs, labels=labels).loss
>>> round(loss.item(), 2)
...
```

Пример многоклассовой классификации:

```python
>>> import torch
>>> from transformers import AutoTokenizer, UltrabertForSequenceClassification

>>> tokenizer = AutoTokenizer.from_pretrained("dmis-lab/UltraBERT-150M")
>>> model = UltrabertForSequenceClassification.from_pretrained("dmis-lab/UltraBERT-150M", problem_type="multi_label_classification")

>>> inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> predicted_class_ids = torch.arange(0, logits.shape[-1])[torch.sigmoid(logits).squeeze(dim=0) > 0.5]

>>> # To train a model on `num_labels` classes, you can pass `num_labels=num_labels` to `.from_pretrained(...)`
>>> num_labels = len(model.config.id2label)
>>> model = UltrabertForSequenceClassification.from_pretrained(
...     "dmis-lab/UltraBERT-150M", num_labels=num_labels, problem_type="multi_label_classification"
... )

>>> labels = torch.sum(
...     torch.nn.functional.one_hot(predicted_class_ids[None, :].clone(), num_classes=num_labels), dim=1
... ).to(torch.float)
>>> loss = model(**inputs, labels=labels).loss
```

## UltrabertForTokenClassification[[transformers.UltrabertForTokenClassification]]

#### transformers.UltrabertForTokenClassification[[transformers.UltrabertForTokenClassification]]

```python
transformers.UltrabertForTokenClassification(config: UltrabertConfig)
```

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

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

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

Модель Ultrabert с головой для классификации токенов, например, для задач распознавания именованных сущностей (NER).

Эта модель наследуется от [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.UltrabertForTokenClassification.forward]]

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, position_ids: typing.Optional[torch.Tensor] = None, inputs_embeds: typing.Optional[torch.Tensor] = None, labels: typing.Optional[torch.Tensor] = None, **kwargs: *<class 'transformers.utils.generic.TransformersKwargs'>)
```

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

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

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

inputs_embeds (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : По желанию, вместо передачи `input_ids` можно напрямую передать встроенное представление. Это полезно, если требуется больший контроль над тем, как индексы `input_ids` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

labels (`torch.LongTensor` формы `(batch_size, sequence_length)`, *необязательно*) : Метки для вычисления функции потерь классификации токенов. Индексы должны находиться в диапазоне `[0, ..., config.num_labels - 1]`.

**Возвращает:** [TokenClassifierOutput](/docs/transformers/v5.23.0/ru/main_classes/output#transformers.modeling_outputs.TokenClassifierOutput) или `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потери классификации.
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.num_labels)`) — Оценки классификации (до SoftMax).
- **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
>>> from transformers import AutoTokenizer, UltrabertForTokenClassification
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("dmis-lab/UltraBERT-150M")
>>> model = UltrabertForTokenClassification.from_pretrained("dmis-lab/UltraBERT-150M")

>>> inputs = tokenizer(
...     "HuggingFace is a company based in Paris and New York", add_special_tokens=False, return_tensors="pt"
... )

>>> with torch.no_grad():
...     logits = model(**inputs).logits

>>> predicted_token_class_ids = logits.argmax(-1)

>>> # Note that tokens are classified rather then input words which means that
>>> # there might be more predicted token classes than words.
>>> # Multiple token classes might account for the same word
>>> predicted_tokens_classes = [model.config.id2label[t.item()] for t in predicted_token_class_ids[0]]
>>> predicted_tokens_classes
...

>>> labels = predicted_token_class_ids
>>> loss = model(**inputs, labels=labels).loss
>>> round(loss.item(), 2)
...
```

## UltrabertForQuestionAnswering[[transformers.UltrabertForQuestionAnswering]]

#### transformers.UltrabertForQuestionAnswering[[transformers.UltrabertForQuestionAnswering]]

```python
transformers.UltrabertForQuestionAnswering(config)
```

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

#### forward[[transformers.UltrabertForQuestionAnswering.forward]]

```python
forward(input_ids: torch.LongTensor | None = None, attention_mask: torch.Tensor | None = None, position_ids: torch.LongTensor | None = None, past_key_values: Cache | None = None, inputs_embeds: torch.Tensor | None = None, start_positions: torch.LongTensor | None = None, end_positions: torch.LongTensor | None = None, **kwargs: Unpack[TransformersKwargs])
```

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

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

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`, *необязательный*) : Предварительно вычисленные скрытые состояния (ключи и значения в блоках само-внимания и кросс-внимания), которые можно использовать для ускорения последовательного декодирования. Обычно это `past_key_values`, возвращаемые моделью на предыдущем этапе декодирования, когда `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` не переданы, по умолчанию будет инициализирован [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` преобразуются в соответствующие векторы, чем это обеспечивает внутренняя матрица поиска встраиваний модели.

start_positions (`torch.LongTensor` формы `(batch_size,)`, *необязательный*) : Метки для позиции (индекса) начала размеченного фрагмента для вычисления функции потерь классификации токенов. Позиции ограничиваются длиной последовательности (`sequence_length`). Позиции вне последовательности не учитываются при вычислении функции потерь.

end_positions (`torch.LongTensor` формы `(batch_size,)`, *необязательный*) : Метки для позиции (индекса) конца размеченного фрагмента для вычисления функции потерь классификации токенов. Позиции ограничиваются длиной последовательности (`sequence_length`). Позиции вне последовательности не учитываются при вычислении функции потерь.

**Возвращает:** `QuestionAnsweringModelOutput`

Метод `GenericForQuestionAnswering` forward переопределяет специальный метод `__call__`.

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