# RAG [Retrieval-Augmented Generation (RAG)](https://huggingface.co/papers/2005.11401) combina um modelo de linguagem pré-treinado (memória paramétrica) com acesso a uma fonte de dados externa (memória não paramétrica) por meio de um recuperador neural pré-treinado. O RAG busca trechos relevantes e condiciona sua geração a eles durante a inferência. Isso frequentemente torna as respostas mais factuais e permite atualizar o conhecimento alterando o índice, em vez de retreinar o modelo inteiro. Você pode encontrar todos os checkpoints originais de RAG na organização [AI at Meta](https://huggingface.co/facebook/models?search=rag). > [!TIP] > Este modelo foi contribuído por [ola13](https://huggingface.co/ola13). > > Clique nos modelos de RAG na barra lateral à direita para ver mais exemplos de como aplicar RAG a diferentes tarefas de linguagem. Os exemplos abaixo demonstram como gerar texto com [AutoModel](/docs/transformers/main/pt/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]) ``` A quantização reduz o uso de memória armazenando os pesos em menor precisão. Consulte a visão geral de [Quantização](../quantization/overview) para os backends suportados. O exemplo abaixo usa [bitsandbytes](../quantization/bitsandbytes) para quantizar os pesos para 4 bits. ```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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/configuration_rag.py#L25) **Parâmetros:** is_encoder_decoder (`bool`, *opcional*, padrão `True`) : Indica se o modelo é usado como codificador/decodificador ou não. question_encoder (`PreTrainedConfig | dict`, *opcional*) : O objeto de configuração ou dicionário do backbone do codificador de perguntas generator (`PreTrainedConfig | dict`, *opcional*) : O objeto de configuração ou dicionário do backbone do gerador de respostas vocab_size (`int`, *opcional*) : Tamanho do vocabulário do modelo. Define o número de tokens diferentes que podem ser representados pelos `input_ids`. prefix (`str`, *opcional*) : Um prefixo de string adicionado a cada entrada antes de passá-la ao modelo gerador. bos_token_id (`int`, *opcional*) : ID do token usado para o início do fluxo no vocabulário. pad_token_id (`int`, *opcional*) : ID do token usado para preenchimento (padding) no vocabulário. eos_token_id (`Union[int, list[int]]`, *opcional*) : ID do token usado para o fim do fluxo no vocabulário. decoder_start_token_id (`int`, *opcional*) : Se um modelo encoder-decoder inicia a decodificação com um token diferente de `bos`, o id desse token. title_sep (`str`, *opcional*, padrão `" / "`) : Separador inserido entre o título e o texto do documento recuperado ao chamar [RagRetriever](/docs/transformers/main/pt/model_doc/rag#transformers.RagRetriever). doc_sep (`str`, *opcional*, padrão `" // "`) : Separador inserido entre o texto do documento recuperado e a entrada original ao chamar [RagRetriever](/docs/transformers/main/pt/model_doc/rag#transformers.RagRetriever). n_docs (`int`, *opcional*, padrão 5) : Número de documentos a recuperar. max_combined_length (`int`, *opcional*, padrão 300) : Comprimento máximo da entrada contextualizada retornada por `__call__()`. retrieval_vector_size (`int`, *opcional*, padrão 768) : Dimensionalidade dos embeddings de documentos indexados pelo [RagRetriever](/docs/transformers/main/pt/model_doc/rag#transformers.RagRetriever). retrieval_batch_size (`int`, *opcional*, padrão 8) : Tamanho do lote de recuperação, definido como o número de consultas emitidas simultaneamente ao índice faiss encapsulado em [RagRetriever](/docs/transformers/main/pt/model_doc/rag#transformers.RagRetriever). dataset (`str`, *opcional*, padrão `"wiki_dpr"`) : Um identificador de dataset do dataset indexado em HuggingFace Datasets (liste todos os datasets e ids disponíveis usando `datasets.list_datasets()`). dataset_split (`str`, *opcional*, padrão `"train"`) : Qual divisão do `dataset` carregar. index_name (`str`, *opcional*, padrão `"compressed"`) : O nome do índice do índice associado ao `dataset`. É possível escolher entre `"legacy"`, `"exact"` e `"compressed"`. index_path (`str`, *opcional*) : O caminho para o índice faiss serializado no disco. passages_path (`str`, *opcional*) : Um caminho para passagens de texto compatíveis com o índice faiss. Obrigatório ao usar `LegacyIndex` use_dummy_dataset (`bool`, *opcional*, padrão `False`) : Se deve carregar uma variante "dummy" do dataset especificado por `dataset`. reduce_loss (`bool`, *opcional*, padrão `False`) : Se a perda NLL deve ser reduzida usando a operação `torch.Tensor.sum`. label_smoothing (`float`, *opcional*, padrão 0.0) : Relevante apenas se `return_loss` estiver definido como `True`. Controla o valor do parâmetro `epsilon` para o label smoothing no cálculo da perda. Se definido como 0, nenhum label smoothing é realizado. do_deduplication (`bool`, *opcional*, padrão `True`) : Se as gerações de diferentes documentos de contexto para uma determinada entrada devem ser deduplicadas ou não. Deve ser definido como `False` se usado durante o treinamento com backend distribuído. exclude_bos_score (`bool`, *opcional*, padrão `False`) : Se deve ou não ignorar o token BOS ao calcular a perda. do_marginalize (`bool`, *opcional*, padrão `False`) : Se `True`, os logits são marginalizados sobre todos os documentos, utilizando `torch.nn.functional.log_softmax`. output_retrieved (`bool`, *opcional*, padrão `False`) : Se definido como `True`, `retrieved_doc_embeds`, `retrieved_doc_ids`, `context_input_ids` e `context_attention_mask` são retornados. Consulte os tensores retornados para mais detalhes. use_cache (`bool`, *opcional*, padrão `True`) : Indica se o modelo deve retornar as últimas atenções de chave/valor (não utilizado por todos os modelos). Relevante apenas se `config.is_decoder=True` ou quando o modelo for um modelo generativo somente de decodificador. dataset_revision (`str`, *opcional*,) : A revisão (hash do commit, tag ou branch) do conjunto de dados do Hugging Face usado para recuperação. Esta é a classe de configuração para armazenar a configuração de um RagModel. Ela é usada para instanciar um modelo Rag de acordo com os argumentos especificados, definindo a arquitetura do modelo. Instanciar uma configuração com os padrões resultará em uma configuração semelhante à do [](https://huggingface.co/) Os objetos de configuração herdam de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) e podem ser usados para controlar as saídas do modelo. Leia a documentação de [PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig) para mais informações. #### 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/configuration_rag.py#L129) **Retorna:** [EncoderDecoderConfig](/docs/transformers/main/pt/model_doc/encoder-decoder#transformers.EncoderDecoderConfig) Uma instância de um objeto de configuração Instancie um [EncoderDecoderConfig](/docs/transformers/main/pt/model_doc/encoder-decoder#transformers.EncoderDecoderConfig) (ou uma classe derivada) a partir de uma configuração de modelo de codificador pré-treinado e de uma configuração de modelo de decodificador. ## RagTokenizer[[transformers.RagTokenizer]] #### transformers.RagTokenizer[[transformers.RagTokenizer]] ```python transformers.RagTokenizer(question_encoder, generator) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/tokenization_rag.py#L25) ## Saídas específicas de 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L42) **Parâmetros:** loss (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) : Perda de modelagem de linguagem. logits (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) : Pontuações de previsão da cabeça de modelagem de linguagem. A pontuação pode ser marginalizada sobre todos os documentos para cada token do vocabulário. doc_scores (`torch.Tensor` de forma `(batch_size, config.n_docs)`) : Pontuação entre cada incorporação de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. past_key_values (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) : Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contém estados ocultos pré-computados (chaves e valores nos blocos de atenção) do decodificador que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial. retrieved_doc_embeds (`torch.Tensor` de forma `(batch_size, config.n_docs, hidden_size)`, *opcional*, retornado quando *output_retrieved=True*) : Documentos incorporados recuperados pelo recuperador. É usado com `question_encoder_last_hidden_state` para calcular os `doc_scores`. retrieved_doc_ids (`torch.LongTensor` de forma `(batch_size, config.n_docs)`, *opcional*, retornado quando *output_retrieved=True*) : Os índices dos documentos incorporados recuperados pelo recuperador. context_input_ids (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : ids de entrada pós-processados a partir dos documentos recuperados e dos input_ids do codificador da pergunta pelo retriever. context_attention_mask (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. question_encoder_last_hidden_state (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Sequência de estados ocultos na saída da última camada da saída agrupada do codificador de perguntas do modelo. question_enc_hidden_states (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) : Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador da pergunta na saída de cada camada, além das saídas iniciais dos embeddings. question_enc_attentions (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) : Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador da pergunta, após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção. generator_enc_last_hidden_state (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Sequência de estados ocultos na saída da última camada do codificador do gerador do modelo. generator_enc_hidden_states (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) : Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador do gerador na saída de cada camada, além das saídas dos embeddings iniciais. generator_enc_attentions (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) : Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção. generator_dec_hidden_states (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) : Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do decodificador do gerador na saída de cada camada, além das saídas dos embeddings iniciais. generator_dec_attentions (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) : Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção. generator_cross_attentions (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) : Tupla de `torch.Tensor` (um para cada camada) com forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos das atenções cruzadas do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de atenção cruzada. Classe base para as saídas de modelos marginalizados com retrieval aumentado. #### 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L134) **Parâmetros:** logits (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) : Pontuações de previsão da cabeça de modelagem de linguagem. A pontuação pode ser marginalizada sobre todos os documentos para cada token do vocabulário. doc_scores (`torch.Tensor` de forma `(batch_size, config.n_docs)`) : Pontuação entre cada incorporação de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. past_key_values (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) : Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contém estados ocultos pré-computados (chaves e valores nos blocos de atenção) do decodificador que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial. retrieved_doc_embeds (`torch.Tensor` de forma `(batch_size, config.n_docs, hidden_size)`, *opcional*, retornado quando *output_retrieved=True*) : Documentos incorporados recuperados pelo recuperador. É usado com `question_encoder_last_hidden_state` para calcular os `doc_scores`. retrieved_doc_ids (`torch.LongTensor` de forma `(batch_size, config.n_docs)`, *opcional*, retornado quando *output_retrieved=True*) : Os índices dos documentos incorporados recuperados pelo recuperador. context_input_ids (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : ids de entrada pós-processados a partir dos documentos recuperados e dos input_ids do codificador da pergunta pelo retriever. context_attention_mask (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. question_encoder_last_hidden_state (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Sequência de estados ocultos na saída da última camada da saída agrupada do codificador de perguntas do modelo. question_enc_hidden_states (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) : Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador da pergunta na saída de cada camada, além das saídas iniciais dos embeddings. question_enc_attentions (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) : Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador da pergunta, após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção. generator_enc_last_hidden_state (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) : Sequência de estados ocultos na saída da última camada do codificador do gerador do modelo. generator_enc_hidden_states (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) : Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) com a forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador do gerador na saída de cada camada, além das saídas dos embeddings iniciais. generator_enc_attentions (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) : Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção. generator_dec_hidden_states (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) : Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do decodificador do gerador na saída de cada camada, além das saídas dos embeddings iniciais. generator_dec_attentions (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) : Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nos cabeçalhos de autoatenção. generator_cross_attentions (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) : Tupla de `torch.Tensor` (um para cada camada) com forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos das atenções cruzadas do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de atenção cruzada. ## RagRetriever[[transformers.RagRetriever]] #### transformers.RagRetriever[[transformers.RagRetriever]] ```python transformers.RagRetriever(config, question_encoder_tokenizer, generator_tokenizer, index = None, init_retrieval = True) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/retrieval_rag.py#L347) **Parâmetros:** config ([RagConfig](/docs/transformers/main/pt/model_doc/rag#transformers.RagConfig)) : A configuração do modelo de RAG com o qual este Retriever é utilizado. Contém parâmetros que indicam qual `Index` construir. Você pode carregar seu próprio dataset personalizado com `config.index_name="custom"` ou usar um padrão (padrão) da biblioteca datasets com `config.index_name="wiki_dpr"`, por exemplo. question_encoder_tokenizer ([PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend)) : O tokenizer usado para tokenizar a pergunta. Ele é usado para decodificar a pergunta e, em seguida, usar o generator_tokenizer. generator_tokenizer ([PreTrainedTokenizer](/docs/transformers/main/pt/main_classes/tokenizer#transformers.PythonBackend)) : O tokenizer usado para a parte geradora do RagModel. index (`Index`, opcional, padrão é o definido pela configuração) : Se especificado, use este índice em vez do construído usando a configuração Retriever usado para obter documentos a partir de consultas vetoriais. Ele recupera os embeddings dos documentos, bem como o conteúdo dos documentos, e os formata para serem usados com um RagModel. Exemplos: ```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() ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/retrieval_rag.py#L482) Função de inicialização do Retriever. Ela carrega o índice na memória. #### postprocess_docs[[transformers.RagRetriever.postprocess_docs]] ```python postprocess_docs(docs, input_strings, prefix, n_docs, return_tensors = None) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/retrieval_rag.py#L490) **Parâmetros:** docs (`dict`) : Documentos recuperados. input_strings (`str`) : Strings de entrada decodificadas por `preprocess_query`. prefix (`str`) : Prefixo adicionado no início de cada entrada, geralmente usado com modelos baseados em T5. **Retorna:** `tuple(tensors)` uma tupla consistindo de dois elementos: `input_ids` contextualizados e uma `attention_mask` compatível. Pós-processamento dos `docs` recuperados e combinação com `input_strings`. #### recuperar[[transformers.RagRetriever.retrieve]] ```python retrieve(question_hidden_states: ndarray, n_docs: int) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/retrieval_rag.py#L559) **Parâmetros:** question_hidden_states (`np.ndarray` de forma `(batch_size, vector_size)`) : Um lote de vetores de consulta para recuperar. n_docs (`int`) : O número de documentos recuperados por consulta. **Retorna:** `tuple[np.ndarray, np.ndarray, list[dict]]` Uma tupla com os seguintes objetos: - **retrieved_doc_embeds** (`np.ndarray` de forma `(batch_size, n_docs, dim)`) -- Os embeddings de recuperação dos documentos recuperados por consulta. - **doc_ids** (`np.ndarray` de forma `(batch_size, n_docs)`) -- Os ids dos documentos no índice - **doc_dicts** (`list[dict]`): Os exemplos de `retrieved_doc_embeds` por consulta. Recupera documentos para os `question_hidden_states` especificados. ## 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L372) **Parâmetros:** config ([PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig), *opcional*) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo. question_encoder (`PreTrainedModel`, *opcional*) : O modelo responsável por codificar a pergunta em estados ocultos para recuperação. generator (`PreTrainedModel`, *opcional*) : O modelo responsável por gerar texto com base nos documentos recuperados. retriever (`RagRetriever`, *opcional*) : O componente responsável por recuperar documentos de uma base de conhecimento com base na pergunta codificada. O modelo Rag puro que produz estados ocultos brutos, sem nenhum head específico no topo. Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.). Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais. #### 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L425) **Parâmetros:** input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`) : Índices dos tokens da sequência de entrada no vocabulário. O [RagConfig](/docs/transformers/main/pt/model_doc/rag#transformers.RagConfig), usado para inicializar o modelo, especifica qual gerador usar e também especifica um tokenizer de gerador compatível. Use a classe desse tokenizer para obter os índices. [O que são IDs de entrada?](../glossary#input-ids) attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`: - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**. [O que são máscaras de atenção?](../glossary#attention-mask) encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : Tuple consiste em (`generator_enc_last_hidden_state`, *optional*: `generator_enc_hidden_states`, *optional*: `generator_enc_attentions`). `generator_enc_last_hidden_state` de forma `(batch_size, n_docs * sequence_length, hidden_size)` é uma sequência de hidden-states na saída da última camada do encoder do gerador. Usado pelo modelo ([RagModel](/docs/transformers/main/pt/model_doc/rag#transformers.RagModel)) durante a decodificação. decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Forneça para tarefas de geração. `None` por padrão, construa conforme as instruções do modelo gerador que você está usando com sua instância de RAG. decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada do decodificador no vocabulário. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada do decodificador?](../glossary#decoder-input-ids) decoder_attention_mask (`torch.BoolTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Comportamento padrão: gerar um tensor que ignora tokens de preenchimento em `decoder_input_ids`. A máscara causal também será usada por padrão. past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`. Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão. O modelo sairá no mesmo formato de cache que foi fornecido como entrada. Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`. doc_scores (`torch.Tensor` de forma `(batch_size, config.n_docs)`) : Pontuação entre cada incorporação de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. Se o modelo não foi inicializado com um `retriever`, `doc_scores` deve ser fornecido para a passagem direta. `doc_scores` pode ser calculado via `question_encoder_last_hidden_state` e `retrieved_doc_embeds`, veja os exemplos para mais informações. context_input_ids (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : IDs de entrada pós-processados a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não foi inicializado com um `retriever`, ``context_input_ids` precisa ser fornecido para a passagem direta. `context_input_ids` são retornados por `__call__()`. context_attention_mask (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`,*opcional*, retornado quando *output_retrieved=True*) : Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não foi inicializado com um `retriever`, o `context_attention_mask` deve ser fornecido para a passagem direta. O `context_attention_mask` é retornado por `__call__()`. use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`). output_attentions (`bool`, *opcional*) : Indica se os tensores de atenção de todas as camadas de atenção devem ser retornados. Consulte `attentions` nos tensores retornados para mais detalhes. output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes. output_retrieved (`bool`, *opcional*) : Se deve ou não retornar os `retrieved_doc_embeds`, `retrieved_doc_ids`, `context_input_ids` e `context_attention_mask`. Veja os tensores retornados para mais detalhes. n_docs (`int`, *opcional*) : O número de documentos a serem recuperados. **Retorna:** [RetrievAugLMOutput](/docs/transformers/main/pt/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMOutput) ou `tuple(torch.Tensor)` Um [RetrievAugLMOutput](/docs/transformers/main/pt/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMOutput) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos, dependendo da configuração ([RagConfig](/docs/transformers/main/pt/model_doc/rag#transformers.RagConfig)) e das entradas. O método forward do [RagModel](/docs/transformers/main/pt/model_doc/rag#transformers.RagModel) substitui o método especial `__call__`. Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente. - **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem. A pontuação pode ser marginalizada sobre todos os documentos para cada token do vocabulário. - **doc_scores** (`torch.Tensor` de forma `(batch_size, config.n_docs)`) -- Pontuação entre cada embedding de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. - **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contém estados ocultos pré-computados (chaves e valores nos blocos de atenção) do decodificador que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial. - **retrieved_doc_embeds** (`torch.Tensor` de forma `(batch_size, config.n_docs, hidden_size)`, *opcional*, retornado quando *output_retrieved=True*) -- Documentos incorporados recuperados pelo recuperador. É usado com `question_encoder_last_hidden_state` para calcular os `doc_scores`. - **retrieved_doc_ids** (`torch.LongTensor` de forma `(batch_size, config.n_docs)`, *opcional*, retornado quando *output_retrieved=True*) -- Os índices dos documentos incorporados recuperados pelo recuperador. - **context_input_ids** (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) -- IDs de entrada pós-processados a partir dos documentos recuperados e dos input_ids do codificador da pergunta pelo recuperador. - **context_attention_mask** (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) -- Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. - **question_encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do codificador de perguntas, saída agregada do modelo. - **question_enc_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador da pergunta na saída de cada camada, além das saídas do embedding inicial. - **question_enc_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador da pergunta, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_enc_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do codificador do gerador do modelo. - **generator_enc_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) com forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador do gerador na saída de cada camada, além das saídas do embedding inicial. - **generator_enc_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_dec_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) com forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do decodificador do gerador na saída de cada camada, mais as saídas do embedding inicial. - **generator_dec_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_cross_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos das cross-attentions do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de cross-atenção. Exemplo: ```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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L663) **Parâmetros:** config ([PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig), *opcional*) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo. question_encoder (`PreTrainedModel`, *opcional*) : O modelo responsável por codificar a pergunta em estados ocultos para recuperação. generator (`PreTrainedModel`, *opcional*) : O modelo responsável por gerar texto com base nos documentos recuperados. retriever (`RagRetriever`, *opcional*) : O componente responsável por recuperar documentos de uma base de conhecimento com base na pergunta codificada. Uma implementação de modelo RAG-sequence. Ele executa a marginalização específica do RAG-sequence na passagem direta. Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.). Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais. #### 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L702) **Parâmetros:** input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`) : Índices dos tokens da sequência de entrada no vocabulário. O [RagConfig](/docs/transformers/main/pt/model_doc/rag#transformers.RagConfig), usado para inicializar o modelo, especifica qual gerador usar e também especifica um tokenizer de gerador compatível. Use a classe desse tokenizer para obter os índices. [O que são IDs de entrada?](../glossary#input-ids) attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`: - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**. [O que são máscaras de atenção?](../glossary#attention-mask) encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : Tuple consiste em (`generator_enc_last_hidden_state`, *optional*: `generator_enc_hidden_states`, *optional*: `generator_enc_attentions`). `generator_enc_last_hidden_state` de forma `(batch_size, n_docs * sequence_length, hidden_size)` é uma sequência de hidden-states na saída da última camada do encoder do gerador. Usado pelo modelo ([RagModel](/docs/transformers/main/pt/model_doc/rag#transformers.RagModel)) durante a decodificação. decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Forneça para tarefas de geração. `None` por padrão, construa conforme as instruções do modelo gerador que você está usando com sua instância de RAG. decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada do decodificador no vocabulário. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada do decodificador?](../glossary#decoder-input-ids) decoder_attention_mask (`torch.BoolTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Comportamento padrão: gerar um tensor que ignora tokens de preenchimento em `decoder_input_ids`. A máscara causal também será usada por padrão. past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`. Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão. O modelo sairá no mesmo formato de cache que foi fornecido como entrada. Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`. context_input_ids (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : IDs de entrada pós-processados a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não foi inicializado com um `retriever`, ``context_input_ids` precisa ser fornecido para a passagem direta. `context_input_ids` são retornados por `__call__()`. context_attention_mask (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`,*opcional*, retornado quando *output_retrieved=True*) : Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não foi inicializado com um `retriever`, o `context_attention_mask` deve ser fornecido para a passagem direta. O `context_attention_mask` é retornado por `__call__()`. doc_scores (`torch.Tensor` de forma `(batch_size, config.n_docs)`) : Pontuação entre cada incorporação de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. Se o modelo não foi inicializado com um `retriever`, `doc_scores` deve ser fornecido para a passagem direta. `doc_scores` pode ser calculado via `question_encoder_last_hidden_state` e `retrieved_doc_embeds`, veja os exemplos para mais informações. use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`). output_attentions (`bool`, *opcional*) : Indica se os tensores de atenção de todas as camadas de atenção devem ser retornados. Consulte `attentions` nos tensores retornados para mais detalhes. output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes. output_retrieved (`bool`, *opcional*) : Se deve ou não retornar os `retrieved_doc_embeds`, `retrieved_doc_ids`, `context_input_ids` e `context_attention_mask`. Veja os tensores retornados para mais detalhes. exclude_bos_score (`bool`, *opcional*) : Relevante apenas se `labels` for passado. Se `True`, a pontuação do token BOS é ignorada ao calcular a perda. reduce_loss (`bool`, *opcional*) : Relevante apenas se `labels` for passado. Se `True`, a perda NLL é reduzida usando a operação `torch.Tensor.sum`. labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`. n_docs (`int`, *opcional*) : O número de documentos a serem recuperados. **Retorna:** [RetrievAugLMMarginOutput](/docs/transformers/main/pt/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) ou `tuple(torch.Tensor)` Um [RetrievAugLMMarginOutput](/docs/transformers/main/pt/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração ([RagConfig](/docs/transformers/main/pt/model_doc/rag#transformers.RagConfig)) e das entradas. O método forward da [RagSequenceForGeneration](/docs/transformers/main/pt/model_doc/rag#transformers.RagSequenceForGeneration) substitui o método especial `__call__`. Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente. - **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem. - **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem. A pontuação pode ser marginalizada sobre todos os documentos para cada token do vocabulário. - **doc_scores** (`torch.Tensor` de forma `(batch_size, config.n_docs)`) -- Pontuação entre cada embedding de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. - **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contém estados ocultos pré-computados (chaves e valores nos blocos de atenção) do decodificador que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial. - **retrieved_doc_embeds** (`torch.Tensor` de forma `(batch_size, config.n_docs, hidden_size)`, *opcional*, retornado quando *output_retrieved=True*) -- Documentos incorporados recuperados pelo recuperador. É usado com `question_encoder_last_hidden_state` para calcular os `doc_scores`. - **retrieved_doc_ids** (`torch.LongTensor` de forma `(batch_size, config.n_docs)`, *opcional*, retornado quando *output_retrieved=True*) -- Os índices dos documentos incorporados recuperados pelo recuperador. - **context_input_ids** (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) -- IDs de entrada pós-processados a partir dos documentos recuperados e dos input_ids do codificador da pergunta pelo recuperador. - **context_attention_mask** (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) -- Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. - **question_encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do codificador de perguntas, saída agregada do modelo. - **question_enc_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador da pergunta na saída de cada camada, além das saídas do embedding inicial. - **question_enc_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador da pergunta, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_enc_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do codificador do gerador do modelo. - **generator_enc_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) com forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador do gerador na saída de cada camada, além das saídas do embedding inicial. - **generator_enc_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_dec_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) com forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do decodificador do gerador na saída de cada camada, mais as saídas do embedding inicial. - **generator_dec_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_cross_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos das cross-attentions do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de cross-atenção. Exemplo: ```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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L875) **Parâmetros:** input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : A sequência usada como prompt para a geração. Se `input_ids` não for passado, então `context_input_ids` deve ser fornecido. attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`: - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**. [O que são máscaras de atenção?](../glossary#attention-mask) context_input_ids (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : IDs de entrada pós-processados a partir dos documentos recuperados e dos input_ids do codificador da pergunta pelo recuperador. context_attention_mask (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não for inicializado com um `retriever` ou se `input_ids` não for fornecido, `context_input_ids` e `context_attention_mask` devem ser fornecidos para a passagem direta. Eles são retornados por `__call__()`. doc_scores (`torch.Tensor` de forma `(batch_size, config.n_docs)`) : Pontuação entre cada incorporação de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. Se o modelo não for inicializado com um `retriever` ou `input_ids` não for fornecido, `doc_scores` deve ser fornecido para a passagem direta. `doc_scores` são retornados por `__call__()`. do_deduplication (`bool`, *opcional*) : Se as gerações de diferentes documentos de contexto para uma determinada entrada devem ser deduplicadas ou não. Deve ser definido como `False` se usado durante o treinamento com backend distribuído. num_return_sequences(`int`, *opcional*, padrão 1) : O número de sequências retornadas, calculadas de forma independente, para cada elemento do lote. Observe que este não é o valor que passamos para a função `[generate()](/docs/transformers/main/pt/main_classes/text_generation#transformers.GenerationMixin.generate)` do `generator`, onde definimos `num_return_sequences` como `num_beams`. num_beams (`int`, *opcional*, padrão 1) : Número de feixes para a busca por feixes. 1 significa que não há busca por feixes. n_docs (`int`, *opcional*, padrão `config.n_docs`) : Número de documentos a recuperar e/ou número de documentos para os quais gerar uma resposta. kwargs (`dict[str, Any]`, *opcional*) : Kwargs adicionais serão passados para [generate()](/docs/transformers/main/pt/main_classes/text_generation#transformers.GenerationMixin.generate). **Retorna:** `torch.LongTensor` de forma `(batch_size * num_return_sequences, sequence_length)` As sequências geradas. A segunda dimensão (comprimento da sequência) é igual a `max_length` ou mais curta, caso todos os lotes tenham terminado antecipadamente devido ao `eos_token_id`. Implementa a decodificação "thorough" de sequência RAG. Leia a documentação de [generate()](/docs/transformers/main/pt/main_classes/text_generation#transformers.GenerationMixin.generate)` para mais informações sobre como definir outros parâmetros de entrada de 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L1102) **Parâmetros:** config ([PreTrainedConfig](/docs/transformers/main/pt/main_classes/configuration#transformers.PreTrainedConfig), *opcional*) : Classe de configuração do modelo com todos os parâmetros do modelo. A inicialização com um arquivo de configuração não carrega os pesos associados ao modelo, apenas a configuração. Consulte o método [from_pretrained()](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel.from_pretrained) para carregar os pesos do modelo. question_encoder (`PreTrainedModel`, *opcional*) : O modelo responsável por codificar a pergunta em estados ocultos para recuperação. generator (`PreTrainedModel`, *opcional*) : O modelo responsável por gerar texto com base nos documentos recuperados. retriever (`RagRetriever`, *opcional*) : O componente responsável por recuperar documentos de uma base de conhecimento com base na pergunta codificada. Uma implementação de modelo RAG-token. Ele realiza a marginalização específica de RAG-token na passagem direta. Este modelo herda de [PreTrainedModel](/docs/transformers/main/pt/main_classes/model#transformers.PreTrainedModel). Consulte a documentação da classe pai para os métodos genéricos que a biblioteca implementa para todos os seus modelos (como download ou salvamento, redimensionamento dos embeddings de entrada, poda de cabeças, etc.). Este modelo também é uma subclasse de [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) do PyTorch. Use-o como um Módulo PyTorch regular e consulte a documentação do PyTorch para todos os assuntos relacionados ao uso e comportamento gerais. #### 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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L1227) **Parâmetros:** input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`) : Índices dos tokens da sequência de entrada no vocabulário. O [RagConfig](/docs/transformers/main/pt/model_doc/rag#transformers.RagConfig), usado para inicializar o modelo, especifica qual gerador usar e também especifica um tokenizer de gerador compatível. Use a classe desse tokenizer para obter os índices. [O que são IDs de entrada?](../glossary#input-ids) attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`: - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**. [O que são máscaras de atenção?](../glossary#attention-mask) encoder_outputs (`tuple(tuple(torch.Tensor)`, *optional*) : Tuple consiste em (`generator_enc_last_hidden_state`, *optional*: `generator_enc_hidden_states`, *optional*: `generator_enc_attentions`). `generator_enc_last_hidden_state` de forma `(batch_size, n_docs * sequence_length, hidden_size)` é uma sequência de hidden-states na saída da última camada do encoder do gerador. Usado pelo modelo ([RagModel](/docs/transformers/main/pt/model_doc/rag#transformers.RagModel)) durante a decodificação. decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Forneça para tarefas de geração. `None` por padrão, construa conforme as instruções do modelo gerador que você está usando com sua instância de RAG. decoder_input_ids (`torch.LongTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Índices dos tokens da sequência de entrada do decodificador no vocabulário. Os índices podem ser obtidos usando [AutoTokenizer](/docs/transformers/main/pt/model_doc/auto#transformers.AutoTokenizer). Consulte [PreTrainedTokenizer.encode()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.encode) e [PreTrainedTokenizer.__call__()](/docs/transformers/main/pt/internal/tokenization_utils#transformers.PreTrainedTokenizerBase.__call__) para mais detalhes. [O que são IDs de entrada do decodificador?](../glossary#decoder-input-ids) decoder_attention_mask (`torch.BoolTensor` de forma `(batch_size, target_sequence_length)`, *opcional*) : Comportamento padrão: gerar um tensor que ignora tokens de preenchimento em `decoder_input_ids`. A máscara causal também será usada por padrão. past_key_values (`~cache_utils.Cache`, *opcional*) : hidden-states pré-computados (chaves e valores nos blocos de autoatenção e nos blocos de atenção cruzada) que podem ser usados para acelerar a decodificação sequencial. Isso geralmente consiste nos `past_key_values` retornados pelo modelo em uma etapa anterior da decodificação, quando `use_cache=True` ou `config.use_cache=True`. Apenas uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache) é permitida como entrada, consulte nosso [guia de kv cache](https://huggingface.co/docs/transformers/en/kv_cache). Se nenhum `past_key_values` for passado, [DynamicCache](/docs/transformers/main/pt/internal/generation_utils#transformers.DynamicCache) será inicializado por padrão. O modelo sairá no mesmo formato de cache que foi fornecido como entrada. Se `past_key_values` forem usados, espera-se que o usuário insira apenas `input_ids` não processados (aqueles que não têm seus estados de chave e valor passados para este modelo) com a forma `(batch_size, unprocessed_length)` em vez de todos os `input_ids` com a forma `(batch_size, sequence_length)`. context_input_ids (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : IDs de entrada pós-processados a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não foi inicializado com um `retriever`, ``context_input_ids` precisa ser fornecido para a passagem direta. `context_input_ids` são retornados por `__call__()`. context_attention_mask (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`,*opcional*, retornado quando *output_retrieved=True*) : Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não foi inicializado com um `retriever`, o `context_attention_mask` deve ser fornecido para a passagem direta. O `context_attention_mask` é retornado por `__call__()`. doc_scores (`torch.Tensor` de forma `(batch_size, config.n_docs)`) : Pontuação entre cada incorporação de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. Se o modelo não foi inicializado com um `retriever`, `doc_scores` deve ser fornecido para a passagem direta. `doc_scores` pode ser calculado via `question_encoder_last_hidden_state` e `retrieved_doc_embeds`, veja os exemplos para mais informações. use_cache (`bool`, *opcional*) : Se definido como `True`, os estados de chave-valor de `past_key_values` são retornados e podem ser usados para acelerar a decodificação (veja `past_key_values`). output_attentions (`bool`, *opcional*) : Indica se os tensores de atenção de todas as camadas de atenção devem ser retornados. Consulte `attentions` nos tensores retornados para mais detalhes. output_hidden_states (`bool`, *opcional*) : Indica se os estados ocultos de todas as camadas devem ser retornados. Consulte `hidden_states` em tensores retornados para mais detalhes. output_retrieved (`bool`, *opcional*) : Se deve ou não retornar os `retrieved_doc_embeds`, `retrieved_doc_ids`, `context_input_ids` e `context_attention_mask`. Veja os tensores retornados para mais detalhes. do_marginalize (`bool`, *opcional*) : Se `True`, os logits são marginalizados sobre todos os documentos fazendo uso de `torch.nn.functional.log_softmax`. reduce_loss (`bool`, *opcional*) : Relevante apenas se `labels` for passado. Se `True`, a perda NLL é reduzida usando a operação `torch.Tensor.sum`. labels (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : Rótulos para calcular a perda de modelagem de linguagem mascarada. Os índices devem estar em `[0, ..., config.vocab_size]` ou ser -100 (veja a docstring de `input_ids`). Tokens com índices definidos como `-100` são ignorados (mascarados); a perda é calculada apenas para os tokens com rótulos em `[0, ..., config.vocab_size]`. n_docs (`int`, *opcional*) : O número de documentos a serem recuperados. **Retorna:** [RetrievAugLMMarginOutput](/docs/transformers/main/pt/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) ou `tuple(torch.Tensor)` Um [RetrievAugLMMarginOutput](/docs/transformers/main/pt/model_doc/rag#transformers.models.rag.modeling_rag.RetrievAugLMMarginOutput) ou uma tupla de `torch.Tensor` (se `return_dict=False` for passado ou quando `config.return_dict=False`) contendo vários elementos dependendo da configuração ([RagConfig](/docs/transformers/main/pt/model_doc/rag#transformers.RagConfig)) e das entradas. O método forward de [RagTokenForGeneration](/docs/transformers/main/pt/model_doc/rag#transformers.RagTokenForGeneration) substitui o método especial `__call__`. Embora a receita para a passagem direta precise ser definida dentro desta função, deve-se chamar a instância de `Module` em seguida, em vez desta, pois a primeira cuida da execução das etapas de pré e pós-processamento, enquanto a segunda as ignora silenciosamente. - **loss** (`torch.Tensor` de forma `(1,)`, *opcional*, retornado quando `labels` é fornecido) -- Perda de modelagem de linguagem. - **logits** (`torch.Tensor` de forma `(batch_size, sequence_length, config.vocab_size)`) -- Pontuações de previsão da cabeça de modelagem de linguagem. A pontuação pode ser marginalizada sobre todos os documentos para cada token do vocabulário. - **doc_scores** (`torch.Tensor` de forma `(batch_size, config.n_docs)`) -- Pontuação entre cada embedding de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. - **past_key_values** (`Cache`, *opcional*, retornado quando `use_cache=True` é passado ou quando `config.use_cache=True`) -- Trata-se de uma instância de [Cache](/docs/transformers/main/pt/internal/generation_utils#transformers.Cache). Para mais detalhes, consulte nosso [guia de cache kv](https://huggingface.co/docs/transformers/en/kv_cache). Contém estados ocultos pré-computados (chaves e valores nos blocos de atenção) do decodificador que podem ser usados (veja a entrada `past_key_values`) para acelerar a decodificação sequencial. - **retrieved_doc_embeds** (`torch.Tensor` de forma `(batch_size, config.n_docs, hidden_size)`, *opcional*, retornado quando *output_retrieved=True*) -- Documentos incorporados recuperados pelo recuperador. É usado com `question_encoder_last_hidden_state` para calcular os `doc_scores`. - **retrieved_doc_ids** (`torch.LongTensor` de forma `(batch_size, config.n_docs)`, *opcional*, retornado quando *output_retrieved=True*) -- Os índices dos documentos incorporados recuperados pelo recuperador. - **context_input_ids** (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) -- IDs de entrada pós-processados a partir dos documentos recuperados e dos input_ids do codificador da pergunta pelo recuperador. - **context_attention_mask** (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) -- Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. - **question_encoder_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do codificador de perguntas, saída agregada do modelo. - **question_enc_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) de forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador da pergunta na saída de cada camada, além das saídas do embedding inicial. - **question_enc_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador da pergunta, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_enc_last_hidden_state** (`torch.Tensor` de forma `(batch_size, sequence_length, hidden_size)`, *opcional*) -- Sequência de estados ocultos na saída da última camada do codificador do gerador do modelo. - **generator_enc_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) com forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do codificador do gerador na saída de cada camada, além das saídas do embedding inicial. - **generator_enc_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do codificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_dec_hidden_states** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_hidden_states=True` é passado ou quando `config.output_hidden_states=True`) -- Tupla de `torch.Tensor` (um para a saída dos embeddings e um para a saída de cada camada) com forma `(batch_size, sequence_length, hidden_size)`. Estados ocultos do decodificador do gerador na saída de cada camada, mais as saídas do embedding inicial. - **generator_dec_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos de atenção do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de autoatenção. - **generator_cross_attentions** (`tuple(torch.Tensor)`, *opcional*, retornado quando `output_attentions=True` é passado ou quando `config.output_attentions=True`) -- Tupla de `torch.Tensor` (um para cada camada) com a forma `(batch_size, num_heads, sequence_length, sequence_length)`. Pesos das cross-attentions do decodificador do gerador, após o softmax de atenção, usados para calcular a média ponderada nas cabeças de cross-atenção. Exemplo: ```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) ``` [Origem](https://github.com/huggingface/transformers/blob/main/src/transformers/models/rag/modeling_rag.py#L1400) **Parâmetros:** input_ids (`torch.LongTensor` de forma `(batch_size, sequence_length)`, *opcional*) : A sequência usada como prompt para a geração. Se `input_ids` não for passado, então `context_input_ids` deve ser fornecido. attention_mask (`torch.Tensor` de forma `(batch_size, sequence_length)`, *opcional*) : Máscara para evitar a execução de atenção nos índices de tokens de preenchimento. Valores de máscara selecionados em `[0, 1]`: - 1 para tokens que **não estão mascarados**, - 0 para tokens que **estão mascarados**. [O que são máscaras de atenção?](../glossary#attention-mask) context_input_ids (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : IDs de entrada pós-processados a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não for inicializado com um `retriever`, `context_input_ids` deve ser fornecido para a passagem direta. `context_input_ids` são retornados por `__call__()`. context_attention_mask (`torch.LongTensor` de forma `(batch_size * config.n_docs, config.max_combined_length)`, *opcional*, retornado quando *output_retrieved=True*) : Máscara de atenção pós-processada a partir dos documentos recuperados e dos `input_ids` do codificador da pergunta pelo recuperador. Se o modelo não for inicializado com um `retriever`, `context_input_ids` deve ser fornecido para a passagem direta. `context_input_ids` são retornados por `__call__()`. doc_scores (`torch.Tensor` de forma `(batch_size, config.n_docs)`) : Pontuação entre cada incorporação de documento recuperado (veja `retrieved_doc_embeds`) e `question_encoder_last_hidden_state`. Se o modelo não for inicializado com um `retriever`, `context_input_ids` deve ser fornecido para a passagem direta. `context_input_ids` são retornados por `__call__()`. n_docs (`int`, *opcional*, padrão `config.n_docs`) : Número de documentos a recuperar e/ou número de documentos para os quais gerar uma resposta. generation_config (`~generation.GenerationConfig`, *opcional*) : A configuração de geração a ser usada como parametrização base para a chamada de geração. Os `**kwargs` passados para generate que correspondam aos atributos de `generation_config` os sobrescreverão. Se `generation_config` não for fornecido, o padrão será usado, que tem a seguinte prioridade de carregamento: 1) do arquivo de modelo `generation_config.json`, se existir; 2) da configuração do modelo. Observe que os parâmetros não especificados herdarão os valores padrão de [GenerationConfig](/docs/transformers/main/pt/main_classes/text_generation#transformers.GenerationConfig), cuja documentação deve ser consultada para parametrizar a geração. prefix_allowed_tokens_fn (`Callable[[int, torch.Tensor], list[int]]`, *opcional*) : Se fornecida, esta função restringe a busca por feixe apenas aos tokens permitidos em cada etapa. Se não for fornecida, nenhuma restrição é aplicada. Esta função recebe 2 argumentos, `inputs_ids` e o ID do lote `batch_id`. Ela deve retornar uma lista com os tokens permitidos para a próxima etapa de geração, condicionada aos tokens gerados anteriormente `inputs_ids` e ao ID do lote `batch_id`. Este argumento é útil para geração condicionada ao prefixo, conforme descrito em [Autoregressive Entity Retrieval](https://huggingface.co/papers/2010.00904). logits_processor (`LogitsProcessorList`, *opcional*) : Processadores de logits personalizados que complementam os processadores de logits padrão criados a partir dos argumentos e da configuração de um modelo. Se um processador de logits for passado que já foi criado com os argumentos ou com a configuração de um modelo, um erro é lançado. stopping_criteria (`StoppingCriteriaList`, *opcional*) : Critérios de parada personalizados que complementam os critérios de parada padrão criados a partir dos argumentos e da configuração de um modelo. Se um critério de parada for passado que já tenha sido criado com os argumentos ou com a configuração de um modelo, um erro é lançado. kwargs (`dict[str, Any]`, *opcional*) : Parametrização ad hoc de `generate_config` e/ou kwargs específicos do modelo adicionais que serão encaminhados para a função `forward` do modelo. **Retorna:** `torch.LongTensor` de forma `(batch_size * num_return_sequences, sequence_length)` As sequências geradas. A segunda dimensão (sequence_length) é igual a `max_length` ou mais curta, caso todos os lotes tenham terminado antecipadamente devido ao `eos_token_id`. Implementa a decodificação de tokens RAG.