trl/pr_4331/en/models.md

# Models

With the `AutoModelForCausalLMWithValueHead` class TRL supports all decoder model architectures in transformers such as GPT-2, OPT, and GPT-Neo. In addition, with `AutoModelForSeq2SeqLMWithValueHead` you can use encoder-decoder architectures such as T5. TRL also requires reference models which are frozen copies of the model that is trained. With `create_reference_model` you can easily create a frozen copy and also share layers between the two models to save memory.

## PreTrainedModelWrapper[[trl.PreTrainedModelWrapper]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>class trl.PreTrainedModelWrapper</name><anchor>trl.PreTrainedModelWrapper</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L58</source><parameters>[{"name": "pretrained_model", "val": " = None"}, {"name": "score_module", "val": " = None"}, {"name": "supports_rm_adapter", "val": " = False"}, {"name": "rm_adapter_name", "val": " = None"}, {"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- **pretrained_model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) --
  The model to be wrapped.
- **parent_class** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) --
  The parent class of the model to be wrapped.
- **supported_args** (`list`) --
  The list of arguments that are supported by the wrapper class.</paramsdesc><paramgroups>0</paramgroups></docstring>

Wrapper for a [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) implemented as a standard PyTorch `torch.nn.Module`.

This class provides a compatibility layer that preserves the key attributes and methods of the original
[PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel), while exposing a uniform interface consistent with PyTorch modules. It enables
seamless integration of pretrained Transformer models into custom training, evaluation, or inference workflows.





<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>add_and_load_reward_modeling_adapter</name><anchor>trl.PreTrainedModelWrapper.add_and_load_reward_modeling_adapter</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L444</source><parameters>[{"name": "pretrained_model", "val": ""}, {"name": "adapter_model_id", "val": ""}, {"name": "adapter_name", "val": " = 'reward_model_adapter'"}, {"name": "token", "val": " = None"}]</parameters></docstring>

Add and load a reward modeling adapter. This method can only be used if the model is a `PeftModel` and if you
have initialized the model with the `reward_modeling_adapter_id` argument, pointing to the id of the reward
modeling adapter. The latest needs also to contain the score head in order to produce the reward.


</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>compute_reward_score</name><anchor>trl.PreTrainedModelWrapper.compute_reward_score</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L569</source><parameters>[{"name": "input_ids", "val": ""}, {"name": "attention_mask", "val": " = None"}, {"name": "**kwargs", "val": ""}]</parameters></docstring>

Computes the reward score for a given input. The method has first to enable the adapter and then compute the
reward score. After that the model disables the reward modeling adapter and enables the default ppo adapter
again.


</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>from_pretrained</name><anchor>trl.PreTrainedModelWrapper.from_pretrained</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L112</source><parameters>[{"name": "pretrained_model_name_or_path", "val": ""}, {"name": "*model_args", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- **pretrained_model_name_or_path** (`str` or [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) --
  The path to the pretrained model or its name.
- ***model_args** (`list`, *optional*) --
  Additional positional arguments passed along to the underlying model's `from_pretrained` method.
- ****kwargs** (`dict`, *optional*) --
  Additional keyword arguments passed along to the underlying model's `from_pretrained` method. We also
  pre-process the kwargs to extract the arguments that are specific to the
  [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) class and the arguments that are specific to trl models. The kwargs
  also support `prepare_model_for_kbit_training` arguments from `peft` library.</paramsdesc><paramgroups>0</paramgroups></docstring>

Instantiates a new model from a pretrained model from `transformers`. The pretrained model is loaded using the
`from_pretrained` method of the [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) class. The arguments that are specific to the
[PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) class are passed along this method and filtered out from the `kwargs`
argument.




</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>post_init</name><anchor>trl.PreTrainedModelWrapper.post_init</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L562</source><parameters>[{"name": "*args", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters></docstring>

Post initialization method. This method is called after the model is instantiated and loaded from a checkpoint.
It can be used to perform additional operations such as loading the state_dict.


</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>push_to_hub</name><anchor>trl.PreTrainedModelWrapper.push_to_hub</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L515</source><parameters>[{"name": "*args", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- ***args** (`list`, *optional*) --
  Positional arguments passed along to the underlying model's `push_to_hub` method.
- ****kwargs** (`dict`, *optional*) --
  Keyword arguments passed along to the underlying model's `push_to_hub` method.</paramsdesc><paramgroups>0</paramgroups></docstring>

Push the pretrained model to the hub. This method is a wrapper around
[push_to_hub](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.push_to_hub). Please refer to the documentation of
[push_to_hub](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.push_to_hub) for more information.




</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>save_pretrained</name><anchor>trl.PreTrainedModelWrapper.save_pretrained</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L529</source><parameters>[{"name": "*args", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- ***args** (`list`, *optional*) --
  Positional arguments passed along to the underlying model's `save_pretrained` method.
- ****kwargs** (`dict`, *optional*) --
  Keyword arguments passed along to the underlying model's `save_pretrained` method.</paramsdesc><paramgroups>0</paramgroups></docstring>

Save the pretrained model to a directory. This method is a wrapper around
[save_pretrained](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.save_pretrained). Please refer to the documentation of
[save_pretrained](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel.save_pretrained) for more information.




</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>state_dict</name><anchor>trl.PreTrainedModelWrapper.state_dict</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L556</source><parameters>[{"name": "*args", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters></docstring>

Return the state_dict of the pretrained model.


</div></div>

## AutoModelForCausalLMWithValueHead[[trl.AutoModelForCausalLMWithValueHead]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>class trl.AutoModelForCausalLMWithValueHead</name><anchor>trl.AutoModelForCausalLMWithValueHead</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L62</source><parameters>[{"name": "pretrained_model", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters></docstring>

An autoregressive model with a value head in addition to the language model head. This class inherits from
[PreTrainedModelWrapper](/docs/trl/pr_4331/en/models#trl.PreTrainedModelWrapper) and wraps a [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) class. The wrapper class supports classic
functions such as `from_pretrained`, `push_to_hub` and `generate`. To call a method of the wrapped model, simply
manipulate the `pretrained_model` attribute of this class.

Class attributes:
- **transformers_parent_class** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) -- The parent class of the wrapped model.
  This
  should be set to `transformers.AutoModelForCausalLM` for this class.
- **supported_args** (`tuple`) -- A tuple of strings that are used to identify the arguments that are supported
  by the `ValueHead` class. Currently, the supported args are:
  - **summary_dropout_prob** (`float`, `optional`, defaults to `None`) -- The dropout probability for the
    `ValueHead` class.
  - **v_head_initializer_range** (`float`, `optional`, defaults to `0.2`) -- The initializer range for the
    `ValueHead` if a specific initialization strategy is selected.
  - **v_head_init_strategy** (`str`, `optional`, defaults to `None`) -- The initialization strategy for the
    `ValueHead`. Currently, the supported strategies are:
    - **`None`** -- Initializes the weights of the `ValueHead` with a random distribution. This is the
      default strategy.
    - **"normal"** -- Initializes the weights of the `ValueHead` with a normal distribution.



<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>__init__</name><anchor>trl.AutoModelForCausalLMWithValueHead.__init__</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L93</source><parameters>[{"name": "pretrained_model", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- **pretrained_model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) --
  The model to wrap. It should be a causal language model such as GPT2. or any model mapped inside the
  `AutoModelForCausalLM` class.
- **kwargs** (`dict`, `optional`) --
  Additional keyword arguments, that are passed to the `ValueHead` class.</paramsdesc><paramgroups>0</paramgroups></docstring>

Initializes the model.




</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>forward</name><anchor>trl.AutoModelForCausalLMWithValueHead.forward</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L131</source><parameters>[{"name": "input_ids", "val": " = None"}, {"name": "past_key_values", "val": " = None"}, {"name": "attention_mask", "val": " = None"}, {"name": "return_past_key_values", "val": " = False"}, {"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- **input_ids** (*torch.LongTensor* of shape *(batch_size, sequence_length)*) --
  Indices of input sequence tokens in the vocabulary.
- **past_key_values** (*tuple(tuple(torch.FloatTensor))*, *optional*) --
  Contains pre-computed hidden-states (key and values in the attention blocks) as computed by the model
  (see *past_key_values* input) to speed up sequential decoding.
- **attention_mask** (*torch.FloatTensor* of shape *(batch_size, sequence_length)*, *optional*) --
  Mask to avoid performing attention on padding token indices. Mask values selected in `[0, 1]`:
  - 1 for tokens that are **not masked**,
  - 0 for tokens that are **masked**.
- **return_past_key_values** (bool) -- A flag indicating if the computed hidden-states should be returned.
- **kwargs** (*dict*, *optional*) --
  Additional keyword arguments, that are passed to the wrapped model.</paramsdesc><paramgroups>0</paramgroups></docstring>

Applies a forward pass to the wrapped model and returns the logits of the value head.




</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>generate</name><anchor>trl.AutoModelForCausalLMWithValueHead.generate</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L186</source><parameters>[{"name": "*args", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- ***args** (`list`, *optional*) --
  Positional arguments passed to the `generate` method of the wrapped model.
- ****kwargs** (`dict`, *optional*) --
  Keyword arguments passed to the `generate` method of the wrapped model.</paramsdesc><paramgroups>0</paramgroups></docstring>

A simple wrapper around the `generate` method of the wrapped model. Please refer to the
[`generate`](https://huggingface.co/docs/transformers/internal/generation_utils) method of the wrapped model
for more information about the supported arguments.




</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>_init_weights</name><anchor>trl.AutoModelForCausalLMWithValueHead._init_weights</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L109</source><parameters>[{"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- ****kwargs** (`dict`, `optional`) --
  Additional keyword arguments, that are passed to the `ValueHead` class. These arguments can contain
  the `v_head_init_strategy` argument as well as the `v_head_initializer_range` argument.</paramsdesc><paramgroups>0</paramgroups></docstring>

Initializes the weights of the value head. The default initialization strategy is random. Users can pass a
different initialization strategy by passing the `v_head_init_strategy` argument when calling
`.from_pretrained`. Supported strategies are:
- `normal`: initializes the weights with a normal distribution.




</div></div>

## AutoModelForSeq2SeqLMWithValueHead[[trl.AutoModelForSeq2SeqLMWithValueHead]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>class trl.AutoModelForSeq2SeqLMWithValueHead</name><anchor>trl.AutoModelForSeq2SeqLMWithValueHead</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L266</source><parameters>[{"name": "pretrained_model", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters><paramsdesc>- **pretrained_model** ([PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel)) --
  The model to wrap. It should be a causal language model such as GPT2. or any model mapped inside the
  [AutoModelForSeq2SeqLM](https://huggingface.co/docs/transformers/main/en/model_doc/auto#transformers.AutoModelForSeq2SeqLM) class.
- **kwargs** --
  Additional keyword arguments passed along to the `ValueHead` class.</paramsdesc><paramgroups>0</paramgroups></docstring>

A seq2seq model with a value head in addition to the language model head. This class inherits from
[PreTrainedModelWrapper](/docs/trl/pr_4331/en/models#trl.PreTrainedModelWrapper) and wraps a [PreTrainedModel](https://huggingface.co/docs/transformers/main/en/main_classes/model#transformers.PreTrainedModel) class. The wrapper class supports classic
functions such as `from_pretrained` and `push_to_hub` and also provides some additional functionalities such as
`generate`.





<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>__init__</name><anchor>trl.AutoModelForSeq2SeqLMWithValueHead.__init__</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L289</source><parameters>[{"name": "pretrained_model", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters></docstring>


</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>forward</name><anchor>trl.AutoModelForSeq2SeqLMWithValueHead.forward</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L397</source><parameters>[{"name": "input_ids", "val": " = None"}, {"name": "past_key_values", "val": " = None"}, {"name": "attention_mask", "val": " = None"}, {"name": "return_past_key_values", "val": " = False"}, {"name": "**kwargs", "val": ""}]</parameters></docstring>


</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>generate</name><anchor>trl.AutoModelForSeq2SeqLMWithValueHead.generate</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L431</source><parameters>[{"name": "*args", "val": ""}, {"name": "**kwargs", "val": ""}]</parameters></docstring>

We call `generate` on the wrapped model.


</div>
<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>_init_weights</name><anchor>trl.AutoModelForSeq2SeqLMWithValueHead._init_weights</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_value_head.py#L383</source><parameters>[{"name": "**kwargs", "val": ""}]</parameters></docstring>

We initialize the weights of the value head.


</div></div>

## create_reference_model[[trl.create_reference_model]]

<div class="docstring border-l-2 border-t-2 pl-4 pt-3.5 border-gray-100 rounded-tl-xl mb-6 mt-8">


<docstring><name>trl.create_reference_model</name><anchor>trl.create_reference_model</anchor><source>https://github.com/huggingface/trl/blob/vr_4331/trl/models/modeling_base.py#L600</source><parameters>[{"name": "model", "val": ": PreTrainedModelWrapper"}, {"name": "num_shared_layers", "val": ": int | None = None"}, {"name": "pattern", "val": ": str | None = None"}]</parameters><paramsdesc>- **model** ([PreTrainedModelWrapper](/docs/trl/pr_4331/en/models#trl.PreTrainedModelWrapper)) -- The model to be copied.
- **num_shared_layers** (`int`, *optional*) --
  The number of initial layers that are shared between both models and kept frozen.
- **pattern** (`str`, *optional*) -- The shared layers are selected with a string pattern
  (e.g. "transformer.h.{layer}" for GPT2) and if a custom pattern is necessary it can be passed here.</paramsdesc><paramgroups>0</paramgroups><retdesc>[PreTrainedModelWrapper](/docs/trl/pr_4331/en/models#trl.PreTrainedModelWrapper)</retdesc></docstring>

Creates a static reference copy of a model. Note that model will be in `.eval()` mode.






</div>

<EditOnGithub source="https://github.com/huggingface/trl/blob/main/docs/source/models.md" />