# RAG

  
    
  

يجمع [توليد المعزَّز بالاسترجاع (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/ar/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](../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`, *اختياري*) : معرّف الرمز المستخدم لبدء البث في المفردات.

pad_token_id (`int`, *اختياري*) : معرّف الرمز (Token id) المستخدم للتعبئة (padding) في المفردات.

eos_token_id (`Union[int, list[int]]`، *اختياري*) : معرّف الرمز المستخدم لنهاية البث في المفردات.

decoder_start_token_id (`int`، *اختياري*) : إذا بدأ نموذج المُشفِّر-المُفكِّك (encoder-decoder) عملية فك التشفير برمز مختلف عن `bos`، فإن هذا هو المعرّف الخاص بذلك الرمز.

title_sep (`str`، *اختياري*، القيمة الافتراضية هي  `" / "`) : الفاصل الذي يُدرج بين عنوان المستند المسترجع ونصه عند استدعاء [RagRetriever](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagRetriever).

doc_sep (`str`، *اختياري*، القيمة الافتراضية هي  `" // "`) : الفاصل الذي يُدرج بين نص المستند المسترجع والمدخل الأصلي عند استدعاء [RagRetriever](/docs/transformers/v5.23.0/ar/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/ar/model_doc/rag#transformers.RagRetriever).

retrieval_batch_size (`int`، *اختياري*، القيمة الافتراضية 8) : حجم دفعة الاسترجاع، ويُعرَّف بأنه عدد الاستعلامات التي تُرسل بالتوازي إلى فهرس faiss المُغلف داخل [RagRetriever](/docs/transformers/v5.23.0/ar/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`) : ما إذا كان سيتم تحميل نسخة "تجريبية" من مجموعة البيانات المحددة بواسطة `dataset`.

reduce_loss (`bool`، *اختياري*، الافتراضي `False`) : ما إذا كان سيتم تقليل خسارة NLL باستخدام عملية `torch.Tensor.sum`.

label_smoothing (`float`، *اختياري*، القيمة الافتراضية 0.0) : لا ينطبق إلا إذا كانت قيمة `return_loss` مضبوطة على `True`. يتحكم في قيمة معامل `epsilon` لتنعيم التسميات (label smoothing) في حساب الدالة الخاسرة. إذا ضُبطت القيمة على 0، فلن يتم تنفيذ تنعيم التسميات.

do_deduplication (`bool`، *اختياري*، القيمة الافتراضية `True`) : ما إذا كان سيتم إزالة التكرار من المخرجات المولّدة من مستندات السياق المختلفة لإدخال معيّن. يجب تعيينه إلى `False` عند استخدامه أثناء التدريب مع واجهة موزّعة.

exclude_bos_score (`bool`، *اختياري*، القيمة الافتراضية `False`) : ما إذا كان سيتم تجاهل رمز BOS عند حساب الخسارة.

do_marginalize (`bool`، *اختياري*، القيمة الافتراضية `False`) : إذا كانت `True`، يتم تهميش القيم اللوجستية (logits) عبر جميع المستندات باستخدام `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`) : ما إذا كان يجب على النموذج إرجاع قيم المفاتيح/القيم الأخيرة للانتباه (لا تستخدمها جميع النماذج). لا ينطبق إلا إذا كان `config.is_decoder=True` أو عندما يكون النموذج نموذجًا توليديًا يعتمد على المُفكِّك فقط.

dataset_revision (`str`، *اختياري*،) : المراجعة (معرّف الالتزام، أو العلامة، أو الفرع) لمجموعة بيانات Hugging Face المستخدمة للاسترجاع.

هذه فئة الإعدادات المخزنة لإعدادات RagModel. تُستخدم لاستحداث نموذج Rag وفقاً للحجج المحددة، مع تعريف بنية النموذج. إن استحداث إعدادات باستخدام القيم الافتراضية سيؤدي إلى إعدادات مشابهة لتلك الخاصة بـ [](https://huggingface.co/)

ترث كائنات الإعداد من [PreTrainedConfig](/docs/transformers/v5.23.0/ar/main_classes/configuration#transformers.PreTrainedConfig) ويمكن استخدامها للتحكم في مخرجات النموذج. اقرأ التوثيق الخاص بـ [PreTrainedConfig](/docs/transformers/v5.23.0/ar/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/ar/model_doc/encoder-decoder#transformers.EncoderDecoderConfig)

مثال من كائن التهيئة

أنشئ كائنًا من [EncoderDecoderConfig](/docs/transformers/v5.23.0/ar/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/ar/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 على الانتباه، وتُستخدم لحساب المتوسط المرجح في رؤوس الانتباه المتقاطع.

الفئة الأساسية لمخرجات النماذج المُحسَّنة بالاسترجاع والمُهمَّشة.

#### 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/ar/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 على الانتباه، وتُستخدم لحساب المتوسط المرجح في رؤوس الانتباه المتقاطع.

## 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/ar/model_doc/rag#transformers.RagConfig)) : إعدادات نموذج RAG الذي يُستخدم معه هذا المسترجع. يحتوي على معاملات تُحدد أي `Index` يجب بناؤه. يمكنك تحميل مجموعة بيانات مخصصة خاصة بك باستخدام `config.index_name="custom"` أو استخدام مجموعة قياسية (افتراضية) من مكتبة datasets مثل `config.index_name="wiki_dpr"`.

question_encoder_tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ar/main_classes/tokenizer#transformers.PythonBackend)) : هو المُجزِّئ الذي استُخدم لتجزئة السؤال. يُستخدم لفك ترميز السؤال ثم استخدام generator_tokenizer.

generator_tokenizer ([PreTrainedTokenizer](/docs/transformers/v5.23.0/ar/main_classes/tokenizer#transformers.PythonBackend)) : المُجزِّئ المستخدم للجزء الخاص بالمولّد في RagModel.

index (`Index`، اختياري، الافتراضي هو ما تحدده الإعدادات): إذا تم تحديده، استخدم هذا الفهرس بدلاً من ذلك الذي يُبنى باستخدام الإعدادات

المسترجع المستخدم للحصول على المستندات من الاستعلامات المتجهية. يسترجع المسترجع تمثيلات المستندات (embeddings) بالإضافة إلى محتويات المستندات، ويصيغها بحيث يمكن استخدامها مع نموذج 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)`

مجموعة (tuple) تتكون من عنصرين: `input_ids` السياقية و`attention_mask` متوافقة.

معالجة المستندات `docs` المسترجعة بعد الاسترجاع ودمجها مع `input_strings`.

#### استرجاع[[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]]`

مجموعة (tuple) تحتوي على الكائنات التالية:

- **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/ar/main_classes/configuration#transformers.PreTrainedConfig)، *اختياري*) : فئة تكوين النموذج التي تحتوي على جميع معاملات النموذج. التهيئة باستخدام ملف التكوين لا تُحمّل الأوزان المرتبطة بالنموذج، بل التكوين فقط. راجع طريقة [from_pretrained()](/docs/transformers/v5.23.0/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

question_encoder (`PreTrainedModel`، *اختياري*) : النموذج المسؤول عن ترميز السؤال إلى حالات خفية للاسترجاع.

generator (`PreTrainedModel`، *اختياري*) : النموذج المسؤول عن توليد النص بناءً على المستندات المسترجعة.

retriever (`RagRetriever`، *اختياري*) : المكوّن المسؤول عن استرجاع المستندات من قاعدة المعرفة بناءً على السؤال المُرمَّز.

نموذج Rag العاري الذي يُخرج حالات مخفية خام دون أي رأس محدد في الأعلى.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/v5.23.0/ar/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/ar/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)`, *اختياري*) : يتكوّن المجمع (Tuple) من (`generator_enc_last_hidden_state`, *اختياري*: `generator_enc_hidden_states`, *اختياري*: `generator_enc_attentions`). `generator_enc_last_hidden_state` ذو الشكل `(batch_size, n_docs * sequence_length, hidden_size)` هو تسلسل من حالات الخفاء (hidden-states) عند مخرج الطبقة الأخيرة من مُشفِّر المولّد. يُستخدم بواسطة نموذج ([RagModel](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagModel)) أثناء فك الترميز.

decoder_input_ids (`torch.LongTensor` من الشكل `(batch_size, target_sequence_length)`، *اختياري*) : يُقدَّم لمهام التوليد. القيمة الافتراضية هي `None`، ويُبنى وفقاً للتعليمات الخاصة بنموذج المولّد الذي تستخدمه مع مثيل RAG الخاص بك.

decoder_input_ids (`torch.LongTensor` of shape `(batch_size, target_sequence_length)`, *اختياري*) : مؤشرات رموز تسلسل مدخلات المُفكِّك في قاموس النموذج. يمكن الحصول على المؤشرات باستخدام [AutoTokenizer](/docs/transformers/v5.23.0/ar/model_doc/auto#transformers.AutoTokenizer). راجع [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) و [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) للتفاصيل. [ما هي معرّفات مدخلات المُفكِّك؟](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.BoolTensor` من الشكل `(batch_size,  target_sequence_length)`، *اختياري*) : السلوك الافتراضي: توليد متجه يتجاهل رموز الحشو في `decoder_input_ids`. كما سيتم استخدام القناع السببي (Causal mask) افتراضيًا.

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/v5.23.0/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/v5.23.0/ar/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`, *اختياري*) : ما إذا كان سيتم إرجاع `retrieved_doc_embeds` و`retrieved_doc_ids` و`context_input_ids` و`context_attention_mask` أم لا. راجع الأوتاد المُرجعة لمزيد من التفاصيل.

n_docs (`int`, *اختياري*) : عدد المستندات التي يجب استرجاعها.

**يعيد:** [RetrievAugLMOutput](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMOutput) أو `tuple(torch.Tensor)`

[RetrievAugLMOutput](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMOutput) أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([RagConfig](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagConfig)) والمدخلات.

تتجاوز طريقة [RagModel](/docs/transformers/v5.23.0/ar/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/ar/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/ar/main_classes/configuration#transformers.PreTrainedConfig)، *اختياري*) : فئة تكوين النموذج التي تحتوي على جميع معاملات النموذج. التهيئة باستخدام ملف التكوين لا تُحمّل الأوزان المرتبطة بالنموذج، بل التكوين فقط. راجع طريقة [from_pretrained()](/docs/transformers/v5.23.0/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

question_encoder (`PreTrainedModel`، *اختياري*) : النموذج المسؤول عن ترميز السؤال إلى حالات خفية للاسترجاع.

generator (`PreTrainedModel`، *اختياري*) : النموذج المسؤول عن توليد النص بناءً على المستندات المسترجعة.

retriever (`RagRetriever`، *اختياري*) : المكوّن المسؤول عن استرجاع المستندات من قاعدة المعرفة بناءً على السؤال المُرمَّز.

تنفيذ لنموذج RAG-sequence. يقوم بتنفيذ التهميش الخاص بـ RAG-sequence في مسار الأمامي.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/v5.23.0/ar/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/ar/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)`, *اختياري*) : يتكوّن المجمع (Tuple) من (`generator_enc_last_hidden_state`, *اختياري*: `generator_enc_hidden_states`, *اختياري*: `generator_enc_attentions`). `generator_enc_last_hidden_state` ذو الشكل `(batch_size, n_docs * sequence_length, hidden_size)` هو تسلسل من حالات الخفاء (hidden-states) عند مخرج الطبقة الأخيرة من مُشفِّر المولّد. يُستخدم بواسطة نموذج ([RagModel](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagModel)) أثناء فك الترميز.

decoder_input_ids (`torch.LongTensor` من الشكل `(batch_size, target_sequence_length)`، *اختياري*) : يُقدَّم لمهام التوليد. القيمة الافتراضية هي `None`، ويُبنى وفقاً للتعليمات الخاصة بنموذج المولّد الذي تستخدمه مع مثيل RAG الخاص بك.

decoder_input_ids (`torch.LongTensor` of shape `(batch_size, target_sequence_length)`, *اختياري*) : مؤشرات رموز تسلسل مدخلات المُفكِّك في قاموس النموذج. يمكن الحصول على المؤشرات باستخدام [AutoTokenizer](/docs/transformers/v5.23.0/ar/model_doc/auto#transformers.AutoTokenizer). راجع [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) و [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) للتفاصيل. [ما هي معرّفات مدخلات المُفكِّك؟](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.BoolTensor` من الشكل `(batch_size,  target_sequence_length)`، *اختياري*) : السلوك الافتراضي: توليد متجه يتجاهل رموز الحشو في `decoder_input_ids`. كما سيتم استخدام القناع السببي (Causal mask) افتراضيًا.

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/v5.23.0/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/v5.23.0/ar/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`, *اختياري*) : ما إذا كان سيتم إرجاع `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 (انظر `input_ids` docstring). يتم تجاهل الرموز التي تكون فهارسها مضبوطة على `-100` (مقنّعة)، ولا تُحسب الخسارة إلا للرموز التي تسمياتها ضمن `[0, ..., config.vocab_size]`.

n_docs (`int`, *اختياري*) : عدد المستندات التي يجب استرجاعها.

**يعيد:** [RetrievAugLMMarginOutput](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) أو `tuple(torch.Tensor)`

[RetrievAugLMMarginOutput](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([RagConfig](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagConfig)) والمدخلات.

تتجاوز طريقة [RagSequenceForGeneration](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagSequenceForGeneration) الخاصة بالتقديم (forward) الطريقة الخاصة `__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/ar/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*) : معرّفات الإدخال بعد المعالجة من المستندات المسترجعة ومعرّفات الإدخال لمشفّر السؤال بواسطة المسترجع.

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/ar/main_classes/text_generation#transformers.GenerationMixin.generate)` الخاصة بـ `generator`، حيث نضبط `num_return_sequences` على `num_beams`.

num_beams (`int`، *اختياري*، القيمة الافتراضية 1) : عدد الحزم في بحث الحزم. القيمة 1 تعني عدم استخدام بحث الحزم.

n_docs (`int`، *اختياري*، القيمة الافتراضية `config.n_docs`) : عدد المستندات التي يجب استرجاعها و/أو عدد المستندات التي سيتم توليد إجابة لها.

kwargs (`dict[str, Any]`، *اختياري*) : سيتم تمرير معاملات kwargs الإضافية إلى [generate()](/docs/transformers/v5.23.0/ar/main_classes/text_generation#transformers.GenerationMixin.generate).

**يعيد:** `torch.LongTensor` من الشكل `(batch_size * num_return_sequences, sequence_length)`

التسلسلات المولّدة. يكون البُعد الثاني (طول التسلسل) مساوياً لـ`max_length` أو أقصر منه إذا أنهت جميع الدفعات (batches) عملها مبكراً بسبب `eos_token_id`.

يُنفّذ فكّ الترميز "الشامل" لتسلسل RAG. اقرأ توثيق [generate()](/docs/transformers/v5.23.0/ar/main_classes/text_generation#transformers.GenerationMixin.generate)` لمزيد من المعلومات حول كيفية ضبط معاملات الإدخال الأخرى لـ 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/ar/main_classes/configuration#transformers.PreTrainedConfig)، *اختياري*) : فئة تكوين النموذج التي تحتوي على جميع معاملات النموذج. التهيئة باستخدام ملف التكوين لا تُحمّل الأوزان المرتبطة بالنموذج، بل التكوين فقط. راجع طريقة [from_pretrained()](/docs/transformers/v5.23.0/ar/main_classes/model#transformers.PreTrainedModel.from_pretrained) لتحميل أوزان النموذج.

question_encoder (`PreTrainedModel`، *اختياري*) : النموذج المسؤول عن ترميز السؤال إلى حالات خفية للاسترجاع.

generator (`PreTrainedModel`، *اختياري*) : النموذج المسؤول عن توليد النص بناءً على المستندات المسترجعة.

retriever (`RagRetriever`، *اختياري*) : المكوّن المسؤول عن استرجاع المستندات من قاعدة المعرفة بناءً على السؤال المُرمَّز.

تنفيذ لنموذج RAG-token. يقوم بإجراء التهميش الخاص بـ RAG-token في مسار التقدّم الأمامي.

يرث هذا النموذج من [PreTrainedModel](/docs/transformers/v5.23.0/ar/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/ar/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)`, *اختياري*) : يتكوّن المجمع (Tuple) من (`generator_enc_last_hidden_state`, *اختياري*: `generator_enc_hidden_states`, *اختياري*: `generator_enc_attentions`). `generator_enc_last_hidden_state` ذو الشكل `(batch_size, n_docs * sequence_length, hidden_size)` هو تسلسل من حالات الخفاء (hidden-states) عند مخرج الطبقة الأخيرة من مُشفِّر المولّد. يُستخدم بواسطة نموذج ([RagModel](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagModel)) أثناء فك الترميز.

decoder_input_ids (`torch.LongTensor` من الشكل `(batch_size, target_sequence_length)`، *اختياري*) : يُقدَّم لمهام التوليد. القيمة الافتراضية هي `None`، ويُبنى وفقاً للتعليمات الخاصة بنموذج المولّد الذي تستخدمه مع مثيل RAG الخاص بك.

decoder_input_ids (`torch.LongTensor` of shape `(batch_size, target_sequence_length)`, *اختياري*) : مؤشرات رموز تسلسل مدخلات المُفكِّك في قاموس النموذج. يمكن الحصول على المؤشرات باستخدام [AutoTokenizer](/docs/transformers/v5.23.0/ar/model_doc/auto#transformers.AutoTokenizer). راجع [PreTrainedTokenizer.encode()](/docs/transformers/v5.23.0/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) و [PreTrainedTokenizer.__call__()](/docs/transformers/v5.23.0/ar/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) للتفاصيل. [ما هي معرّفات مدخلات المُفكِّك؟](../glossary#decoder-input-ids)

decoder_attention_mask (`torch.BoolTensor` من الشكل `(batch_size,  target_sequence_length)`، *اختياري*) : السلوك الافتراضي: توليد متجه يتجاهل رموز الحشو في `decoder_input_ids`. كما سيتم استخدام القناع السببي (Causal mask) افتراضيًا.

past_key_values (`~cache_utils.Cache`، *اختياري*) : حالات مخفية محسوبة مسبقًا (المفاتيح والقيم في كتل الانتباه الذاتي وكتل الانتباه المتقاطع) يمكن استخدامها لتسريع فك الترميز التسلسلي. يتكوّن هذا عادةً من `past_key_values` التي يعيدها النموذج في مرحلة سابقة من فك الترميز، عندما يكون `use_cache=True` أو `config.use_cache=True`. يُسمح فقط بتمرير كائن [Cache](/docs/transformers/v5.23.0/ar/internal/generation_utils#transformers.Cache) كمدخل، راجع [دليل ذاكرة kv](https://huggingface.co/docs/transformers/en/kv_cache). إذا لم يتم تمرير `past_key_values`، فسيتم تهيئة [DynamicCache](/docs/transformers/v5.23.0/ar/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`, *اختياري*) : ما إذا كان سيتم إرجاع `retrieved_doc_embeds` و`retrieved_doc_ids` و`context_input_ids` و`context_attention_mask` أم لا. راجع الأوتاد المُرجعة لمزيد من التفاصيل.

do_marginalize (`bool`, *اختياري*) : إذا كان `True`، يتم تهميش القيم اللوجستية (logits) عبر جميع المستندات باستخدام `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 (انظر `input_ids` docstring). يتم تجاهل الرموز التي تكون فهارسها مضبوطة على `-100` (مقنّعة)، ولا تُحسب الخسارة إلا للرموز التي تسمياتها ضمن `[0, ..., config.vocab_size]`.

n_docs (`int`, *اختياري*) : عدد المستندات التي يجب استرجاعها.

**يعيد:** [RetrievAugLMMarginOutput](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) أو `tuple(torch.Tensor)`

[RetrievAugLMMarginOutput](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) أو مجموعة من `torch.Tensor` (إذا تم تمرير `return_dict=False` أو عندما يكون `config.return_dict=False`) وتتضمن عناصر مختلفة اعتماداً على الإعداد ([RagConfig](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagConfig)) والمدخلات.

تُعيد طريقة [RagTokenForGeneration](/docs/transformers/v5.23.0/ar/model_doc/rag#transformers.RagTokenForGeneration) الخاصة بالتقديم (forward) تعريف الطريقة الخاصة `__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/ar/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`، *اختياري*) : إعدادات التوليد التي سيتم استخدامها كإعدادات أساسية لاستدعاء التوليد. أي `**kwargs` تُمرَّر إلى generate وتتطابق مع سمات `generation_config` ستُلغي قيمها. إذا لم يتم تقديم `generation_config`، فسيتم استخدام الإعداد الافتراضي، والذي له أولوية تحميل كالتالي: 1) من ملف النموذج `generation_config.json`، إذا كان موجودًا؛ 2) من إعدادات النموذج. يرجى ملاحظة أن المعلمات غير المحددة ستورث القيم الافتراضية لـ [GenerationConfig](/docs/transformers/v5.23.0/ar/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` و/أو معاملات إضافية خاصة بالنموذج سيتم تمريرها إلى دالة `forward` الخاصة بالنموذج.

**يعيد:** `torch.LongTensor` من الشكل `(batch_size * num_return_sequences, sequence_length)`

التسلسلات المولّدة. يكون البُعد الثاني (sequence_length) مساوياً لـ`max_length` أو أقصر منه إذا انتهت جميع الدفعات مبكراً بسبب `eos_token_id`.

يُنفّذ فكّ ترميز رموز RAG.

