# RAG

  
    
  

[Retrieval-Augmented Generation (RAG)](https://huggingface.co/papers/2005.11401) объединяет предобученную языковую модель (параметрическую память) с доступом к внешнему источнику данных (непараметрическую память) с помощью предобученного нейронного ретривера. RAG извлекает релевантные фрагменты текста и использует их как условие для генерации во время инференса. Это часто делает ответы более фактологичными и позволяет обновлять знания, изменяя индекс, вместо переобучения всей модели.

Все исходные контрольные точки RAG можно найти в организации [AI at Meta](https://huggingface.co/facebook/models?search=rag).

> [!TIP]
> Эта модель была предоставлена пользователем [ola13](https://huggingface.co/ola13).
>
> Щёлкните по моделям RAG в боковой панели справа, чтобы увидеть больше примеров применения RAG к различным языковым задачам.

Приведённые ниже примеры демонстрируют, как генерировать текст с помощью [AutoModel](/docs/transformers/v5.23.0/ru/model_doc/auto#transformers.AutoModel).

```python
from transformers import RagRetriever, RagSequenceForGeneration, RagTokenizer

tokenizer = RagTokenizer.from_pretrained("facebook/rag-sequence-nq")
retriever = RagRetriever.from_pretrained(
    "facebook/rag-sequence-nq", dataset="wiki_dpr", index_name="compressed"
)

model = RagSequenceForGeneration.from_pretrained(
    "facebook/rag-sequence-nq",
    retriever=retriever,
    attn_implementation="flash_attention_2",
    device_map="auto",
)
inputs = tokenizer("How many people live in Paris?", return_tensors="pt").to(model.device)
generated = model.generate(input_ids=inputs["input_ids"])
print(tokenizer.batch_decode(generated, skip_special_tokens=True)[0])
```

Квантование уменьшает потребление памяти за счёт хранения весов с пониженной точностью. Список поддерживаемых бэкендов приведён в обзоре [Quantization](../quantization/overview). В примере ниже используется [bitsandbytes](../quantization/bitsandbytes) для квантования весов до 4 бит.

```python
import torch

from transformers import BitsAndBytesConfig, RagRetriever, RagSequenceForGeneration, RagTokenizer

bnb = BitsAndBytesConfig(load_in_4bit=True, bnb_4bit_compute_dtype=torch.bfloat16)

tokenizer = RagTokenizer.from_pretrained("facebook/rag-sequence-nq")
retriever = RagRetriever.from_pretrained(
    "facebook/rag-sequence-nq", dataset="wiki_dpr", index_name="compressed"
)

model = RagSequenceForGeneration.from_pretrained(
    "facebook/rag-sequence-nq",
    retriever=retriever,
    quantization_config=bnb,
    device_map="auto",
)
inputs = tokenizer("How many people live in Paris?", return_tensors="pt").to(model.device)
generated = model.generate(input_ids=inputs["input_ids"])
print(tokenizer.batch_decode(generated, skip_special_tokens=True)[0])
```

## RagConfig[[transformers.RagConfig]]

#### transformers.RagConfig[[transformers.RagConfig]]

```python
transformers.RagConfig(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, question_encoder: transformers.configuration_utils.PreTrainedConfig | dict | None = None, generator: transformers.configuration_utils.PreTrainedConfig | dict | None = None, vocab_size: int | None = None, prefix: str | None = None, bos_token_id: int | None = None, pad_token_id: int | None = None, eos_token_id: int | list[int] | None = None, decoder_start_token_id: int | None = None, title_sep: str = ' / ', doc_sep: str = ' // ', n_docs: int = 5, max_combined_length: int = 300, retrieval_vector_size: int = 768, retrieval_batch_size: int = 8, dataset: str = 'wiki_dpr', dataset_split: str = 'train', index_name: str = 'compressed', index_path: str | None = None, passages_path: str | None = None, use_dummy_dataset: bool = False, reduce_loss: bool = False, label_smoothing: float = 0.0, do_deduplication: bool = True, exclude_bos_score: bool = False, do_marginalize: bool = False, output_retrieved: bool = False, use_cache: bool = True, dataset_revision: str | None = None)
```

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

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

is_encoder_decoder (`bool`, *необязательный*, по умолчанию `True`) : Используется ли модель в качестве энкодера/декодера.

question_encoder (`PreTrainedConfig | dict`, *необязательный*) : объект конфигурации или словарь конфигурации базовой модели вопросного энкодера

generator (`PreTrainedConfig | dict`, *необязательный*) : объект конфигурации или словарь конфигурации базовой модели генератора ответов

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

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

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

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

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

decoder_start_token_id (`int`, *optional*) : Если модель с архитектурой «энкодер-декодер» начинает декодирование с токена, отличного от `bos`, то идентификатор этого токена.

title_sep (`str`, *необязательный*, по умолчанию  `" / "`) : Разделитель, вставляемый между заголовком и текстом извлечённого документа при вызове [RagRetriever](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagRetriever).

doc_sep (`str`, *необязательный*, по умолчанию  `" // "`) : Разделитель, вставляемый между текстом полученного документа и исходным входом при вызове [RagRetriever](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagRetriever).

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

max_combined_length (`int`, *необязательный*, по умолчанию 300) : Максимальная длина контекстуализированного входа, возвращаемого `__call__()`.

retrieval_vector_size (`int`, *необязательный*, по умолчанию 768) : Размерность векторов документов, индексируемых [RagRetriever](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagRetriever).

retrieval_batch_size (`int`, *optional*, по умолчанию 8) : Размер батча для поиска, определяемый как количество запросов, одновременно отправляемых в индекс faiss, инкапсулированный в [RagRetriever](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagRetriever).

dataset (`str`, *необязательный*, по умолчанию `"wiki_dpr"`) : Идентификатор набора данных, индексируемого в HuggingFace Datasets (полный список доступных наборов данных и их идентификаторов можно получить с помощью `datasets.list_datasets()`).

dataset_split (`str`, *необязательный*, по умолчанию `"train"`) : Какая часть `dataset` должна быть загружена.

index_name (`str`, *необязательный*, по умолчанию `"compressed"`) : Имя индекса, связанного с `dataset`. Можно выбрать один из вариантов: `"legacy"`, `"exact"` или `"compressed"`.

index_path (`str`, *необязательный*) : Путь к сериализованному индексу faiss на диске.

passages_path (`str`, *необязательный*) : Путь к текстовым фрагментам, совместимым с индексом faiss. Обязателен при использовании `LegacyIndex`

use_dummy_dataset (`bool`, *необязательный*, по умолчанию `False`) : Загружать ли «dummy»-вариант набора данных, указанного в `dataset`.

reduce_loss (`bool`, *необязательный*, по умолчанию `False`) : Сводить ли потерю NLL с помощью операции `torch.Tensor.sum`.

label_smoothing (`float`, *optional*, по умолчанию 0.0) : Актуально только если `return_loss` установлено в `True`. Управляет значением параметра `epsilon` для сглаживания меток при вычислении функции потерь. Если установлено в 0, сглаживание меток не выполняется.

do_deduplication (`bool`, *необязательный*, по умолчанию `True`) : Указывает, следует ли удалять дубликаты генераций из разных контекстных документов для данного входа. Должен быть установлен в `False`, если используется во время обучения с распределённым бэкендом.

exclude_bos_score (`bool`, *необязательный*, по умолчанию `False`) : Нужно ли игнорировать токен BOS при вычислении функции потерь.

do_marginalize (`bool`, *необязательный*, по умолчанию `False`) : Если `True`, логиты маргинализируются по всем документам с использованием `torch.nn.functional.log_softmax`.

output_retrieved (`bool`, *необязательный*, по умолчанию `False`) : Если установлено в `True`, возвращаются `retrieved_doc_embeds`, `retrieved_doc_ids`, `context_input_ids` и `context_attention_mask`. Подробности о возвращаемых тензорах см. ниже.

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

dataset_revision (`str`, *необязательный*,) : ревизия (хеш коммита, тег или ветка) набора данных Hugging Face, используемого для поиска.

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

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

#### from_question_encoder_generator_configs[[transformers.RagConfig.from_question_encoder_generator_configs]]

```python
from_question_encoder_generator_configs(question_encoder_config: PreTrainedConfig, generator_config: PreTrainedConfig, **kwargs)
```

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

**Возвращает:** [EncoderDecoderConfig](/docs/transformers/v5.23.0/ru/model_doc/encoder-decoder#transformers.EncoderDecoderConfig)

Экземпляр объекта конфигурации

Создайте экземпляр [EncoderDecoderConfig](/docs/transformers/v5.23.0/ru/model_doc/encoder-decoder#transformers.EncoderDecoderConfig) (или производного класса) на основе конфигурации предобученной модели-энкодера и конфигурации модели-декодера.

## RagTokenizer[[transformers.RagTokenizer]]

#### transformers.RagTokenizer[[transformers.RagTokenizer]]

```python
transformers.RagTokenizer(question_encoder, generator)
```

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

## Выводы, специфичные для Rag[[transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput]]

#### transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput[[transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput]]

```python
transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput(loss: typing.Optional[torch.Tensor] = None, logits: typing.Optional[torch.Tensor] = None, doc_scores: typing.Optional[torch.Tensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, retrieved_doc_embeds: typing.Optional[torch.Tensor] = None, retrieved_doc_ids: typing.Optional[torch.LongTensor] = None, context_input_ids: typing.Optional[torch.LongTensor] = None, context_attention_mask: typing.Optional[torch.LongTensor] = None, question_encoder_last_hidden_state: typing.Optional[torch.Tensor] = None, question_enc_hidden_states: tuple[torch.Tensor, ...] | None = None, question_enc_attentions: tuple[torch.Tensor, ...] | None = None, generator_enc_last_hidden_state: typing.Optional[torch.Tensor] = None, generator_enc_hidden_states: tuple[torch.Tensor, ...] | None = None, generator_enc_attentions: tuple[torch.Tensor, ...] | None = None, generator_dec_hidden_states: tuple[torch.Tensor, ...] | None = None, generator_dec_attentions: tuple[torch.Tensor, ...] | None = None, generator_cross_attentions: tuple[torch.Tensor, ...] | None = None)
```

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

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

loss (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если предоставлен `labels`) : Потеря языковой модели.

logits (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) : Оценки предсказаний языковой модели. Оценка может быть усреднена по всем документам для каждого токена словаря.

doc_scores (`torch.Tensor` формы `(batch_size, config.n_docs)`) : Оценки между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`.

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`) для ускорения последовательного декодирования.

retrieved_doc_embeds (`torch.Tensor` формы `(batch_size, config.n_docs, hidden_size)`, *необязательный*, возвращается, если *output_retrieved=True*) : Встроенные документы, полученные ретривером. Используется вместе с `question_encoder_last_hidden_state` для вычисления `doc_scores`.

retrieved_doc_ids (`torch.LongTensor` формы `(batch_size, config.n_docs)`, *необязательный*, возвращается, если *output_retrieved=True*) : Индексы встроенных документов, извлеченных поисковиком.

context_input_ids (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Вводные идентификаторы, обработанные ретривером из извлеченных документов и input_ids кодировщика вопроса.

context_attention_mask (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса.

question_encoder_last_hidden_state (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : Последовательность скрытых состояний на выходе последнего слоя кодировщика вопроса, агрегированный выход модели.

question_enc_hidden_states (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) : Кортеж из `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния кодировщика вопроса на выходе каждого слоя, а также начальные выводы эмбеддингов.

question_enc_attentions (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) : Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса внимания кодировщика вопроса после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

generator_enc_last_hidden_state (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) : Последовательность скрытых состояний на выходе последнего слоя кодировщика генератора модели.

generator_enc_hidden_states (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) : Кортеж из `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния генератора-энкодера на выходе каждого слоя, а также начальные выводы эмбеддингов.

generator_enc_attentions (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) : Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса внимания генератора-энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

generator_dec_hidden_states (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) : Кортеж из `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния декодера генератора на выходе каждого слоя, а также начальные выводы эмбеддингов.

generator_dec_attentions (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) : Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса внимания декодера генератора после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

generator_cross_attentions (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) : Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса кросс-внимания декодера генератора после softmax внимания, используемые для вычисления взвешенного среднего в головах кросс-внимания.

Базовый класс для выходов моделей с ретривером и маргинализацией.

#### transformers.models.rag.modeling_rag.RetrievAugLMOutput[[transformers.models.rag.modeling_rag.RetrievAugLMOutput]]

```python
transformers.models.rag.modeling_rag.RetrievAugLMOutput(logits: typing.Optional[torch.Tensor] = None, doc_scores: typing.Optional[torch.Tensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, retrieved_doc_embeds: typing.Optional[torch.Tensor] = None, retrieved_doc_ids: typing.Optional[torch.LongTensor] = None, context_input_ids: typing.Optional[torch.LongTensor] = None, context_attention_mask: typing.Optional[torch.LongTensor] = None, question_encoder_last_hidden_state: typing.Optional[torch.Tensor] = None, question_enc_hidden_states: tuple[torch.Tensor, ...] | None = None, question_enc_attentions: tuple[torch.Tensor, ...] | None = None, generator_enc_last_hidden_state: typing.Optional[torch.Tensor] = None, generator_enc_hidden_states: tuple[torch.Tensor, ...] | None = None, generator_enc_attentions: tuple[torch.Tensor, ...] | None = None, generator_dec_hidden_states: tuple[torch.Tensor, ...] | None = None, generator_dec_attentions: tuple[torch.Tensor, ...] | None = None, generator_cross_attentions: tuple[torch.Tensor, ...] | None = None)
```

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

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

logits (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) : Оценки предсказаний языковой модели. Оценка может быть усреднена по всем документам для каждого токена словаря.

doc_scores (`torch.Tensor` формы `(batch_size, config.n_docs)`) : Оценки между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`.

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`) для ускорения последовательного декодирования.

retrieved_doc_embeds (`torch.Tensor` формы `(batch_size, config.n_docs, hidden_size)`, *необязательный*, возвращается, если *output_retrieved=True*) : Встроенные документы, полученные ретривером. Используется вместе с `question_encoder_last_hidden_state` для вычисления `doc_scores`.

retrieved_doc_ids (`torch.LongTensor` формы `(batch_size, config.n_docs)`, *необязательный*, возвращается, если *output_retrieved=True*) : Индексы встроенных документов, извлеченных поисковиком.

context_input_ids (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Вводные идентификаторы, обработанные ретривером из извлеченных документов и input_ids кодировщика вопроса.

context_attention_mask (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса.

question_encoder_last_hidden_state (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательно*) : Последовательность скрытых состояний на выходе последнего слоя кодировщика вопроса, агрегированный выход модели.

question_enc_hidden_states (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) : Кортеж из `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния кодировщика вопроса на выходе каждого слоя, а также начальные выводы эмбеддингов.

question_enc_attentions (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) : Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса внимания кодировщика вопроса после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

generator_enc_last_hidden_state (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) : Последовательность скрытых состояний на выходе последнего слоя кодировщика генератора модели.

generator_enc_hidden_states (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) : Кортеж из `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния генератора-энкодера на выходе каждого слоя, а также начальные выводы эмбеддингов.

generator_enc_attentions (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) : Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса внимания генератора-энкодера после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

generator_dec_hidden_states (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_hidden_states=True` или если `config.output_hidden_states=True`) : Кортеж из `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`. Скрытые состояния декодера генератора на выходе каждого слоя, а также начальные выводы эмбеддингов.

generator_dec_attentions (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) : Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса внимания декодера генератора после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.

generator_cross_attentions (`tuple(torch.Tensor)`, *необязательный*, возвращается, если передано `output_attentions=True` или если `config.output_attentions=True`) : Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`. Веса кросс-внимания декодера генератора после softmax внимания, используемые для вычисления взвешенного среднего в головах кросс-внимания.

## RagRetriever[[transformers.RagRetriever]]

#### transformers.RagRetriever[[transformers.RagRetriever]]

```python
transformers.RagRetriever(config, question_encoder_tokenizer, generator_tokenizer, index = None, init_retrieval = True)
```

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

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

config ([RagConfig](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagConfig)) : конфигурация RAG-модели, с которой используется данный Retriever. Содержит параметры, указывающие, какой `Index` следует построить. Вы можете загрузить собственный пользовательский набор данных с помощью `config.index_name="custom"` или использовать стандартный (по умолчанию) из библиотеки datasets, например, с помощью `config.index_name="wiki_dpr"`.

question_encoder_tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.PythonBackend)) : токенизатор, который использовался для токенизации вопроса. Он используется для декодирования вопроса, после чего применяется generator_tokenizer.

generator_tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ru/main_classes/tokenizer#transformers.PythonBackend)) : токенизатор, используемый для генераторной части RagModel.

index (`Index`, необязательный параметр, по умолчанию используется тот, что определён в конфигурации): если указан, используется этот индекс вместо того, который строится на основе конфигурации

Retriever используется для получения документов по векторным запросам. Он извлекает эмбеддинги документов, а также их содержимое и форматирует их для использования с RagModel.

Примеры:

```python
>>> # To load the default "wiki_dpr" dataset with 21M passages from wikipedia (index name is 'compressed' or 'exact')
>>> from transformers import RagRetriever

>>> retriever = RagRetriever.from_pretrained(
...     "facebook/rag-sequence-nq", dataset="wiki_dpr", index_name="compressed"
... )

>>> # To load your own indexed dataset built with the datasets library.
>>> from transformers import RagRetriever

>>> dataset = (
...     ...
... )  # dataset must be a datasets.Datasets object with columns "title", "text" and "embeddings", and it must have a supported index (e.g., Faiss or other index types depending on your setup)
>>> retriever = RagRetriever.from_pretrained("facebook/rag-sequence-nq", indexed_dataset=dataset)

>>> # To load your own indexed dataset built with the datasets library that was saved on disk.
>>> from transformers import RagRetriever

>>> dataset_path = "path/to/my/dataset"  # dataset saved via *dataset.save_to_disk(...)*
>>> index_path = "path/to/my/index"  # index saved via *dataset.get_index("embeddings").save(...)*
>>> retriever = RagRetriever.from_pretrained(
...     "facebook/rag-sequence-nq",
...     index_name="custom",
...     passages_path=dataset_path,
...     index_path=index_path,
... )

>>> # To load the legacy index built originally for Rag's paper
>>> from transformers import RagRetriever

>>> retriever = RagRetriever.from_pretrained("facebook/rag-sequence-nq", index_name="legacy")
```

#### init_retrieval[[transformers.RagRetriever.init_retrieval]]

```python
init_retrieval()
```

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

Функция инициализации ретривера. Загружает индекс в память.

#### postprocess_docs[[transformers.RagRetriever.postprocess_docs]]

```python
postprocess_docs(docs, input_strings, prefix, n_docs, return_tensors = None)
```

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

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

docs (`dict`): Полученные документы.

input_strings (`str`) : Входящие строки, декодированные с помощью `preprocess_query`.

prefix (`str`) : Префикс, добавляемый в начало каждого входа; обычно используется с моделями на базе T5.

**Возвращает:** `tuple(tensors)`

кортеж, состоящий из двух элементов: контекстуализированные `input_ids` и совместимая `attention_mask`.

Постобработка полученных `docs` и их объединение с `input_strings`.

#### retrieve[[transformers.RagRetriever.retrieve]]

```python
retrieve(question_hidden_states: ndarray, n_docs: int)
```

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

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

question_hidden_states (`np.ndarray` формы `(batch_size, vector_size)`) : Пакет векторов запросов для извлечения.

n_docs (`int`) : количество документов, извлекаемых на каждый запрос.

**Возвращает:** `tuple[np.ndarray, np.ndarray, list[dict]]`

Кортеж со следующими объектами:

- **retrieved_doc_embeds** (`np.ndarray` формы `(batch_size, n_docs, dim)`) -- Векторы эмбеддингов извлечённых документов для каждого запроса.
- **doc_ids** (`np.ndarray` формы `(batch_size, n_docs)`) -- идентификаторы документов в индексе
- **doc_dicts** (`list[dict]`): примеры `retrieved_doc_embeds` для каждого запроса.

Получает документы для указанных `question_hidden_states`.

## RagModel[[transformers.RagModel]]

#### transformers.RagModel[[transformers.RagModel]]

```python
transformers.RagModel(config: transformers.configuration_utils.PreTrainedConfig | None = None, question_encoder: transformers.modeling_utils.PreTrainedModel | None = None, generator: transformers.modeling_utils.PreTrainedModel | None = None, retriever: transformers.models.rag.retrieval_rag.RagRetriever | None = None, **kwargs)
```

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

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

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

question_encoder (`PreTrainedModel`, *необязательный*) : Модель, отвечающая за кодирование вопроса в скрытые состояния для поиска.

generator (`PreTrainedModel`, *необязательный*) : Модель, ответственная за генерацию текста на основе извлечённых документов.

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

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

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, doc_scores: typing.Optional[torch.Tensor] = None, context_input_ids: typing.Optional[torch.LongTensor] = None, context_attention_mask: typing.Optional[torch.LongTensor] = None, use_cache: bool | None = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, output_retrieved: bool | None = None, n_docs: int | None = None, **kwargs)
```

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

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`) : Индексы токенов входной последовательности в словаре. [RagConfig](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagConfig), используемый для инициализации модели, определяет, какой генератор следует применять, а также указывает совместимый токенизатор генератора. Используйте класс этого токенизатора, чтобы получить индексы.  [Что такое входные идентификаторы?](../glossary#input-ids)

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

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : Кортеж состоит из (`generator_enc_last_hidden_state`, *optional*: `generator_enc_hidden_states`, *optional*: `generator_enc_attentions`). `generator_enc_last_hidden_state` формы `(batch_size, n_docs * sequence_length, hidden_size)` представляет собой последовательность скрытых состояний на выходе последнего слоя энкодера генератора. Используется моделью ([RagModel](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagModel)) во время декодирования.

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

decoder_input_ids (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Индексы токенов входной последовательности декодера в словаре. Индексы можно получить с помощью [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__). [Что такое входные ID декодера?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.BoolTensor` формы `(batch_size,  target_sequence_length)`, *необязательный*) : Поведение по умолчанию: генерировать тензор, игнорирующий токены заполнения в `decoder_input_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)`.

doc_scores (`torch.Tensor` формы `(batch_size, config.n_docs)`) : Оценки между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`. Если модель не была инициализирована с `retriever`, `doc_scores` необходимо передать в прямой проход. `doc_scores` можно вычислить с помощью `question_encoder_last_hidden_state` и `retrieved_doc_embeds`, см. примеры для получения дополнительной информации.

context_input_ids (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Вводные идентификаторы, обработанные ретривером на основе извлеченных документов и `input_ids` кодировщика вопроса. Если модель не была инициализирована с `retriever`, ``context_input_ids` необходимо передать в прямой проход. `context_input_ids` возвращаются методом `__call__()`.

context_attention_mask (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`,*необязательный*, возвращается, если *output_retrieved=True*) : Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса. Если модель не инициализирована с `retriever`, `context_attention_mask` необходимо передать в прямой проход. `context_attention_mask` возвращаются методом `__call__()`.

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

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

output_retrieved (`bool`, *optional*) : Нужно ли возвращать `retrieved_doc_embeds`, `retrieved_doc_ids`, `context_input_ids` и `context_attention_mask`. Подробности о возвращаемых тензорах см. ниже.

n_docs (`int`, *необязательный*) : Количество документов для извлечения.

**Возвращает:** [RetrievAugLMOutput](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMOutput) или `tuple(torch.Tensor)`

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

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

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

- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) -- Оценки предсказаний языковой модели. Оценка может быть усреднена по всем документам для каждого токена словаря.
- **doc_scores** (`torch.Tensor` формы `(batch_size, config.n_docs)`) -- Оценки соответствия между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`.
- **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`) для ускорения последовательного декодирования.
- **retrieved_doc_embeds** (`torch.Tensor` формы `(batch_size, config.n_docs, hidden_size)`, *необязательный*, возвращается при *output_retrieved=True*) -- Векторные представления документов, извлечённых ретривером. Используется вместе с `question_encoder_last_hidden_state` для вычисления `doc_scores`.
- **retrieved_doc_ids** (`torch.LongTensor` формы `(batch_size, config.n_docs)`, *необязательный*, возвращается при *output_retrieved=True*) -- Индексы встроенных документов, извлечённых ретривером.
- **context_input_ids** (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается при *output_retrieved=True*) — входные идентификаторы, обработанные ретривером на основе извлечённых документов и входных идентификаторов кодировщика вопроса.
- **context_attention_mask** (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается при *output_retrieved=True*) -- Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса.
- **question_encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя кодировщика вопроса, агрегированный выход модели.
- **question_enc_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния кодировщика вопроса на выходе каждого слоя, а также начальные выходные значения эмбеддингов.
- **question_enc_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кодировщика вопроса после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_enc_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя генератора-энкодера модели.
- **generator_enc_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния энкодера генератора на выходе каждого слоя, а также выходные значения начального эмбеддинга.
- **generator_enc_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кодировщика генератора, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_dec_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера генератора на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
- **generator_dec_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера генератора, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_cross_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, RagRetriever, RagModel
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("facebook/rag-token-base")
>>> retriever = RagRetriever.from_pretrained(
...     "facebook/rag-token-base", index_name="exact", use_dummy_dataset=True
... )
>>> # initialize with RagRetriever to do everything in one forward call
>>> model = RagModel.from_pretrained("facebook/rag-token-base", retriever=retriever)

>>> inputs = tokenizer("How many people live in Paris?", return_tensors="pt")
>>> outputs = model(input_ids=inputs["input_ids"])
```

## RagSequenceForGeneration[[transformers.RagSequenceForGeneration]]

#### transformers.RagSequenceForGeneration[[transformers.RagSequenceForGeneration]]

```python
transformers.RagSequenceForGeneration(config: transformers.configuration_utils.PreTrainedConfig | None = None, question_encoder: transformers.modeling_utils.PreTrainedModel | None = None, generator: transformers.modeling_utils.PreTrainedModel | None = None, retriever: transformers.models.rag.retrieval_rag.RagRetriever | None = None, **kwargs)
```

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

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

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

question_encoder (`PreTrainedModel`, *необязательный*) : Модель, отвечающая за кодирование вопроса в скрытые состояния для поиска.

generator (`PreTrainedModel`, *необязательный*) : Модель, ответственная за генерацию текста на основе извлечённых документов.

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

Реализация модели RAG-sequence. Выполняет маргинализацию, специфичную для RAG-sequence, в прямом проходе.

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, context_input_ids: typing.Optional[torch.LongTensor] = None, context_attention_mask: typing.Optional[torch.LongTensor] = None, doc_scores: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, output_retrieved: bool | None = None, exclude_bos_score: bool | None = None, reduce_loss: bool | None = None, labels: typing.Optional[torch.LongTensor] = None, n_docs: int | None = None, **kwargs)
```

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

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`) : Индексы токенов входной последовательности в словаре. [RagConfig](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagConfig), используемый для инициализации модели, определяет, какой генератор следует применять, а также указывает совместимый токенизатор генератора. Используйте класс этого токенизатора, чтобы получить индексы.  [Что такое входные идентификаторы?](../glossary#input-ids)

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

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : Кортеж состоит из (`generator_enc_last_hidden_state`, *optional*: `generator_enc_hidden_states`, *optional*: `generator_enc_attentions`). `generator_enc_last_hidden_state` формы `(batch_size, n_docs * sequence_length, hidden_size)` представляет собой последовательность скрытых состояний на выходе последнего слоя энкодера генератора. Используется моделью ([RagModel](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagModel)) во время декодирования.

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

decoder_input_ids (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Индексы токенов входной последовательности декодера в словаре. Индексы можно получить с помощью [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__). [Что такое входные ID декодера?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.BoolTensor` формы `(batch_size,  target_sequence_length)`, *необязательный*) : Поведение по умолчанию: генерировать тензор, игнорирующий токены заполнения в `decoder_input_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)`.

context_input_ids (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Вводные идентификаторы, обработанные ретривером на основе извлеченных документов и `input_ids` кодировщика вопроса. Если модель не была инициализирована с `retriever`, ``context_input_ids` необходимо передать в прямой проход. `context_input_ids` возвращаются методом `__call__()`.

context_attention_mask (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`,*необязательный*, возвращается, если *output_retrieved=True*) : Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса. Если модель не инициализирована с `retriever`, `context_attention_mask` необходимо передать в прямой проход. `context_attention_mask` возвращаются методом `__call__()`.

doc_scores (`torch.Tensor` формы `(batch_size, config.n_docs)`) : Оценки между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`. Если модель не была инициализирована с `retriever`, `doc_scores` необходимо передать в прямой проход. `doc_scores` можно вычислить с помощью `question_encoder_last_hidden_state` и `retrieved_doc_embeds`, см. примеры для получения дополнительной информации.

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

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

output_retrieved (`bool`, *optional*) : Нужно ли возвращать `retrieved_doc_embeds`, `retrieved_doc_ids`, `context_input_ids` и `context_attention_mask`. Подробности о возвращаемых тензорах см. ниже.

exclude_bos_score (`bool`, *необязательный*) : Актуально только при передаче `labels`. Если `True`, при вычислении потерь игнорируется оценка токена BOS.

reduce_loss (`bool`, *необязательный*) : Актуально только при передаче `labels`. Если `True`, потеря NLL сводится с помощью операции `torch.Tensor.sum`.

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

n_docs (`int`, *необязательный*) : Количество документов для извлечения.

**Возвращает:** [RetrievAugLMMarginOutput](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) или `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели.
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) -- Оценки предсказаний языковой модели. Оценка может быть усреднена по всем документам для каждого токена словаря.
- **doc_scores** (`torch.Tensor` формы `(batch_size, config.n_docs)`) -- Оценки соответствия между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`.
- **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`) для ускорения последовательного декодирования.
- **retrieved_doc_embeds** (`torch.Tensor` формы `(batch_size, config.n_docs, hidden_size)`, *необязательный*, возвращается при *output_retrieved=True*) -- Векторные представления документов, извлечённых ретривером. Используется вместе с `question_encoder_last_hidden_state` для вычисления `doc_scores`.
- **retrieved_doc_ids** (`torch.LongTensor` формы `(batch_size, config.n_docs)`, *необязательный*, возвращается при *output_retrieved=True*) -- Индексы встроенных документов, извлечённых ретривером.
- **context_input_ids** (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается при *output_retrieved=True*) — входные идентификаторы, обработанные ретривером на основе извлечённых документов и входных идентификаторов кодировщика вопроса.
- **context_attention_mask** (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается при *output_retrieved=True*) -- Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса.
- **question_encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя кодировщика вопроса, агрегированный выход модели.
- **question_enc_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния кодировщика вопроса на выходе каждого слоя, а также начальные выходные значения эмбеддингов.
- **question_enc_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кодировщика вопроса после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_enc_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя генератора-энкодера модели.
- **generator_enc_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния энкодера генератора на выходе каждого слоя, а также выходные значения начального эмбеддинга.
- **generator_enc_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кодировщика генератора, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_dec_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера генератора на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
- **generator_dec_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера генератора, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_cross_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, RagRetriever, RagSequenceForGeneration
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("facebook/rag-sequence-nq")
>>> retriever = RagRetriever.from_pretrained(
...     "facebook/rag-sequence-nq", index_name="exact", use_dummy_dataset=True
... )
>>> # initialize with RagRetriever to do everything in one forward call
>>> model = RagSequenceForGeneration.from_pretrained("facebook/rag-token-nq", retriever=retriever)

>>> inputs = tokenizer("How many people live in Paris?", return_tensors="pt")
>>> targets = tokenizer(text_target="In Paris, there are 10 million people.", return_tensors="pt")
>>> input_ids = inputs["input_ids"]
>>> labels = targets["input_ids"]
>>> outputs = model(input_ids=input_ids, labels=labels)

>>> # or use retriever separately
>>> model = RagSequenceForGeneration.from_pretrained("facebook/rag-sequence-nq", use_dummy_dataset=True)
>>> # 1. Encode
>>> question_hidden_states = model.question_encoder(input_ids)[0]
>>> # 2. Retrieve
>>> docs_dict = retriever(input_ids.numpy(), question_hidden_states.detach().numpy(), return_tensors="pt")
>>> doc_scores = torch.bmm(
...     question_hidden_states.unsqueeze(1), docs_dict["retrieved_doc_embeds"].float().transpose(1, 2)
... ).squeeze(1)
>>> # 3. Forward to generator
>>> outputs = model(
...     context_input_ids=docs_dict["context_input_ids"],
...     context_attention_mask=docs_dict["context_attention_mask"],
...     doc_scores=doc_scores,
...     decoder_input_ids=labels,
... )
```

#### generate[[transformers.RagSequenceForGeneration.generate]]

```python
generate(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, context_input_ids: typing.Optional[torch.LongTensor] = None, context_attention_mask: typing.Optional[torch.LongTensor] = None, doc_scores: typing.Optional[torch.Tensor] = None, do_deduplication: bool | None = None, num_return_sequences: int | None = None, num_beams: int | None = None, n_docs: int | None = None, **model_kwargs)
```

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

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

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

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

context_input_ids (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Вводные идентификаторы, обработанные ретривером на основе извлеченных документов и input_ids кодировщика вопроса.

context_attention_mask (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса. Если модель не инициализирована с `retriever` или `input_ids` не переданы, необходимо предоставить `context_input_ids` и `context_attention_mask` для прямого прохода. Они возвращаются методом `__call__()`.

doc_scores (`torch.Tensor` формы `(batch_size, config.n_docs)`) : Оценки между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`. Если модель не инициализирована с `retriever` или не переданы `input_ids`, то `doc_scores` необходимо предоставить для прямого прохода. `doc_scores` возвращаются методом `__call__()`.

do_deduplication (`bool`, *необязательный*) : Указывает, следует ли дедуплицировать генерации из разных контекстных документов для данного входа. Должен быть установлен в `False`, если используется при обучении с распределённым бэкендом.

num_return_sequences(`int`, *необязательный*, по умолчанию 1) : Количество независимо вычисленных возвращаемых последовательностей для каждого элемента в батче. Обратите внимание, что это не то значение, которое мы передаём в функцию `[generate()](/docs/transformers/v5.23.0/ru/main_classes/text_generation#transformers.GenerationMixin.generate)` объекта `generator`, где мы устанавливаем `num_return_sequences` равным `num_beams`.

num_beams (`int`, *optional*, по умолчанию 1) : Количество лучей для beam search. Значение 1 означает, что beam search не используется.

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

kwargs (`dict[str, Any]`, *необязательный*) : Дополнительные аргументы будут переданы в [generate()](/docs/transformers/v5.23.0/ru/main_classes/text_generation#transformers.GenerationMixin.generate).

**Возвращает:** `torch.LongTensor` формы `(batch_size * num_return_sequences, sequence_length)`

Сгенерированные последовательности. Вторая размерность (длина последовательности) равна `max_length` или меньше, если все батчи завершились досрочно из-за `eos_token_id`.

Реализует «тщательное» декодирование последовательности RAG. Подробности о том, как задать другие входные параметры generate, см. в документации [generate()](/docs/transformers/v5.23.0/ru/main_classes/text_generation#transformers.GenerationMixin.generate).

## RagTokenForGeneration[[transformers.RagTokenForGeneration]]

#### transformers.RagTokenForGeneration[[transformers.RagTokenForGeneration]]

```python
transformers.RagTokenForGeneration(config: transformers.configuration_utils.PreTrainedConfig | None = None, question_encoder: transformers.modeling_utils.PreTrainedModel | None = None, generator: transformers.modeling_utils.PreTrainedModel | None = None, retriever: transformers.models.rag.retrieval_rag.RagRetriever | None = None, **kwargs)
```

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

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

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

question_encoder (`PreTrainedModel`, *необязательный*) : Модель, отвечающая за кодирование вопроса в скрытые состояния для поиска.

generator (`PreTrainedModel`, *необязательный*) : Модель, ответственная за генерацию текста на основе извлечённых документов.

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

Реализация модели RAG-token. Выполняет маргинализацию, специфичную для RAG-token, в прямом проходе.

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

```python
forward(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.Tensor] = None, encoder_outputs: tuple[tuple[torch.Tensor]] | None = None, decoder_input_ids: typing.Optional[torch.LongTensor] = None, decoder_attention_mask: typing.Optional[torch.BoolTensor] = None, past_key_values: transformers.cache_utils.Cache | None = None, context_input_ids: typing.Optional[torch.LongTensor] = None, context_attention_mask: typing.Optional[torch.LongTensor] = None, doc_scores: typing.Optional[torch.Tensor] = None, use_cache: bool | None = None, output_attentions: bool | None = None, output_hidden_states: bool | None = None, output_retrieved: bool | None = None, do_marginalize: bool | None = None, reduce_loss: bool | None = None, labels: typing.Optional[torch.LongTensor] = None, n_docs: int | None = None, **kwargs)
```

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

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

input_ids (`torch.LongTensor` формы `(batch_size, sequence_length)`) : Индексы токенов входной последовательности в словаре. [RagConfig](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagConfig), используемый для инициализации модели, определяет, какой генератор следует применять, а также указывает совместимый токенизатор генератора. Используйте класс этого токенизатора, чтобы получить индексы.  [Что такое входные идентификаторы?](../glossary#input-ids)

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

encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : Кортеж состоит из (`generator_enc_last_hidden_state`, *optional*: `generator_enc_hidden_states`, *optional*: `generator_enc_attentions`). `generator_enc_last_hidden_state` формы `(batch_size, n_docs * sequence_length, hidden_size)` представляет собой последовательность скрытых состояний на выходе последнего слоя энкодера генератора. Используется моделью ([RagModel](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.RagModel)) во время декодирования.

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

decoder_input_ids (`torch.LongTensor` формы `(batch_size, target_sequence_length)`, *необязательный*) : Индексы токенов входной последовательности декодера в словаре. Индексы можно получить с помощью [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__). [Что такое входные ID декодера?](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.BoolTensor` формы `(batch_size,  target_sequence_length)`, *необязательный*) : Поведение по умолчанию: генерировать тензор, игнорирующий токены заполнения в `decoder_input_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)`.

context_input_ids (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Вводные идентификаторы, обработанные ретривером на основе извлеченных документов и `input_ids` кодировщика вопроса. Если модель не была инициализирована с `retriever`, ``context_input_ids` необходимо передать в прямой проход. `context_input_ids` возвращаются методом `__call__()`.

context_attention_mask (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`,*необязательный*, возвращается, если *output_retrieved=True*) : Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса. Если модель не инициализирована с `retriever`, `context_attention_mask` необходимо передать в прямой проход. `context_attention_mask` возвращаются методом `__call__()`.

doc_scores (`torch.Tensor` формы `(batch_size, config.n_docs)`) : Оценки между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`. Если модель не была инициализирована с `retriever`, `doc_scores` необходимо передать в прямой проход. `doc_scores` можно вычислить с помощью `question_encoder_last_hidden_state` и `retrieved_doc_embeds`, см. примеры для получения дополнительной информации.

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

output_attentions (`bool`, *необязательный*) : Нужно ли возвращать тензоры внимания всех слоев внимания. Подробнее см. `attentions` в разделе возвращаемых тензоров.

output_hidden_states (`bool`, *необязательный*) : Нужно ли возвращать скрытые состояния всех слоёв. Подробнее о `hidden_states` в разделе возвращаемых тензоров.

output_retrieved (`bool`, *optional*) : Нужно ли возвращать `retrieved_doc_embeds`, `retrieved_doc_ids`, `context_input_ids` и `context_attention_mask`. Подробности о возвращаемых тензорах см. ниже.

do_marginalize (`bool`, *необязательный*) : Если `True`, логиты маргинализируются по всем документам с использованием `torch.nn.functional.log_softmax`.

reduce_loss (`bool`, *необязательный*) : Актуально только при передаче `labels`. Если `True`, потеря NLL сводится с помощью операции `torch.Tensor.sum`.

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

n_docs (`int`, *необязательный*) : Количество документов для извлечения.

**Возвращает:** [RetrievAugLMMarginOutput](/docs/transformers/v5.23.0/ru/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) или `tuple(torch.Tensor)`

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

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

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

- **loss** (`torch.Tensor` формы `(1,)`, *необязательный*, возвращается, если задан `labels`) -- Потеря языковой модели.
- **logits** (`torch.Tensor` формы `(batch_size, sequence_length, config.vocab_size)`) -- Оценки предсказаний языковой модели. Оценка может быть усреднена по всем документам для каждого токена словаря.
- **doc_scores** (`torch.Tensor` формы `(batch_size, config.n_docs)`) -- Оценки соответствия между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`.
- **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`) для ускорения последовательного декодирования.
- **retrieved_doc_embeds** (`torch.Tensor` формы `(batch_size, config.n_docs, hidden_size)`, *необязательный*, возвращается при *output_retrieved=True*) -- Векторные представления документов, извлечённых ретривером. Используется вместе с `question_encoder_last_hidden_state` для вычисления `doc_scores`.
- **retrieved_doc_ids** (`torch.LongTensor` формы `(batch_size, config.n_docs)`, *необязательный*, возвращается при *output_retrieved=True*) -- Индексы встроенных документов, извлечённых ретривером.
- **context_input_ids** (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается при *output_retrieved=True*) — входные идентификаторы, обработанные ретривером на основе извлечённых документов и входных идентификаторов кодировщика вопроса.
- **context_attention_mask** (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается при *output_retrieved=True*) -- Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса.
- **question_encoder_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя кодировщика вопроса, агрегированный выход модели.
- **question_enc_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или когда `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния кодировщика вопроса на выходе каждого слоя, а также начальные выходные значения эмбеддингов.
- **question_enc_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кодировщика вопроса после softmax внимания, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_enc_last_hidden_state** (`torch.Tensor` формы `(batch_size, sequence_length, hidden_size)`, *необязательный*) -- Последовательность скрытых состояний на выходе последнего слоя генератора-энкодера модели.
- **generator_enc_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния энкодера генератора на выходе каждого слоя, а также выходные значения начального эмбеддинга.
- **generator_enc_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания кодировщика генератора, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_dec_hidden_states** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_hidden_states=True` или при `config.output_hidden_states=True`) -- Кортеж `torch.Tensor` (один для вывода эмбеддингов и один для вывода каждого слоя) формы `(batch_size, sequence_length, hidden_size)`.

  Скрытые состояния декодера генератора на выходе каждого слоя, а также выходные значения начального слоя встраиваний.
- **generator_dec_attentions** (`tuple(torch.Tensor)`, *необязательный*, возвращается при передаче `output_attentions=True` или при `config.output_attentions=True`) -- Кортеж `torch.Tensor` (по одному на каждый слой) формы `(batch_size, num_heads, sequence_length, sequence_length)`.

  Веса внимания декодера генератора, после применения softmax к вниманию, используемые для вычисления взвешенного среднего в головах само-внимания.
- **generator_cross_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, RagRetriever, RagTokenForGeneration
>>> import torch

>>> tokenizer = AutoTokenizer.from_pretrained("facebook/rag-token-nq")
>>> retriever = RagRetriever.from_pretrained(
...     "facebook/rag-token-nq", index_name="exact", use_dummy_dataset=True
... )
>>> # initialize with RagRetriever to do everything in one forward call
>>> model = RagTokenForGeneration.from_pretrained("facebook/rag-token-nq", retriever=retriever)

>>> inputs = tokenizer("How many people live in Paris?", return_tensors="pt")
>>> targets = tokenizer(text_target="In Paris, there are 10 million people.", return_tensors="pt")
>>> input_ids = inputs["input_ids"]
>>> labels = targets["input_ids"]
>>> outputs = model(input_ids=input_ids, labels=labels)

>>> # or use retriever separately
>>> model = RagTokenForGeneration.from_pretrained("facebook/rag-token-nq", use_dummy_dataset=True)
>>> # 1. Encode
>>> question_hidden_states = model.question_encoder(input_ids)[0]
>>> # 2. Retrieve
>>> docs_dict = retriever(input_ids.numpy(), question_hidden_states.detach().numpy(), return_tensors="pt")
>>> doc_scores = torch.bmm(
...     question_hidden_states.unsqueeze(1), docs_dict["retrieved_doc_embeds"].float().transpose(1, 2)
... ).squeeze(1)
>>> # 3. Forward to generator
>>> outputs = model(
...     context_input_ids=docs_dict["context_input_ids"],
...     context_attention_mask=docs_dict["context_attention_mask"],
...     doc_scores=doc_scores,
...     decoder_input_ids=labels,
... )

>>> # or directly generate
>>> generated = model.generate(
...     context_input_ids=docs_dict["context_input_ids"],
...     context_attention_mask=docs_dict["context_attention_mask"],
...     doc_scores=doc_scores,
... )
>>> generated_string = tokenizer.batch_decode(generated, skip_special_tokens=True)
```

#### generate[[transformers.RagTokenForGeneration.generate]]

```python
generate(input_ids: typing.Optional[torch.LongTensor] = None, attention_mask: typing.Optional[torch.LongTensor] = None, context_input_ids: typing.Optional[torch.LongTensor] = None, context_attention_mask: typing.Optional[torch.LongTensor] = None, doc_scores: typing.Optional[torch.Tensor] = None, n_docs: int | None = None, generation_config: transformers.generation.configuration_utils.GenerationConfig | None = None, prefix_allowed_tokens_fn: collections.abc.Callable[[int, torch.Tensor], list[int]] | None = None, logits_processor: transformers.generation.logits_process.LogitsProcessorList | None = [], stopping_criteria: transformers.generation.stopping_criteria.StoppingCriteriaList | None = [], **kwargs)
```

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

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

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

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

context_input_ids (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Вводные идентификаторы, обработанные ретривером на основе извлеченных документов и `input_ids` кодировщика вопроса. Если модель не инициализирована с `retriever`, `context_input_ids` необходимо передать в прямой проход. `context_input_ids` возвращаются методом `__call__()`.

context_attention_mask (`torch.LongTensor` формы `(batch_size * config.n_docs, config.max_combined_length)`, *необязательный*, возвращается, если *output_retrieved=True*) : Маска внимания, обработанная ретривером на основе извлечённых документов и `input_ids` кодировщика вопроса. Если модель не инициализирована с `retriever`, в прямой проход необходимо передать `context_input_ids`. `context_input_ids` возвращаются методом `__call__()`.

doc_scores (`torch.Tensor` формы `(batch_size, config.n_docs)`) : Оценки между эмбеддингами каждого извлечённого документа (см. `retrieved_doc_embeds`) и `question_encoder_last_hidden_state`. Если модель не инициализирована с `retriever`, в прямой проход необходимо передать `context_input_ids`. `context_input_ids` возвращаются методом `__call__()`.

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

generation_config (`~generation.GenerationConfig`, *optional*) : Конфигурация генерации, используемая в качестве базовой параметризации для вызова генерации. Аргументы `**kwargs`, переданные в generate и совпадающие с атрибутами `generation_config`, переопределяют их. Если `generation_config` не предоставлен, будет использован вариант по умолчанию, который имеет следующую приоритетность загрузки: 1) из файла модели `generation_config.json`, если он существует; 2) из конфигурации модели. Обратите внимание, что не указанные параметры наследуют значения по умолчанию [GenerationConfig](/docs/transformers/v5.23.0/ru/main_classes/text_generation#transformers.GenerationConfig), документация по которым должна быть проверена для параметризации генерации.

prefix_allowed_tokens_fn (`Callable[[int, torch.Tensor], list[int]]`, *необязательный*) : Если указан, эта функция ограничивает поиск луча (beam search) только разрешёнными токенами на каждом шаге. Если не указан, ограничения не применяются. Эта функция принимает два аргумента: `inputs_ids` и идентификатор батча `batch_id`. Она должна возвращать список разрешённых токенов для следующего шага генерации, обусловленный ранее сгенерированными токенами `inputs_ids` и идентификатором батча `batch_id`. Этот аргумент полезен для ограниченной генерации, обусловленной префиксом, как описано в [Autoregressive Entity Retrieval](https://huggingface.co/papers/2010.00904).

logits_processor (`LogitsProcessorList`, *необязательный*) : Пользовательские обработчики logits, дополняющие стандартные обработчики logits, создаваемые на основе аргументов и конфигурации модели. Если передан обработчик logits, который уже был создан с использованием этих аргументов или конфигурации модели, возникает ошибка.

stopping_criteria (`StoppingCriteriaList`, *необязательный*) : Пользовательские критерии остановки, дополняющие критерии остановки по умолчанию, формируемые на основе аргументов и конфигурации модели. Если передан критерий остановки, который уже создан на основе аргументов или конфигурации модели, возникает ошибка.

kwargs (`dict[str, Any]`, *необязательный*) : Произвольная параметризация `generate_config` и/или дополнительные модельно-специфичные kwargs, которые будут переданы в функцию `forward` модели.

**Возвращает:** `torch.LongTensor` формы `(batch_size * num_return_sequences, sequence_length)`

Сгенерированные последовательности. Второй размер (sequence_length) равен `max_length` или меньше, если все батчи завершились досрочно из-за `eos_token_id`.

Реализует декодирование токенов RAG.

