output.rst

Model outputs
-------------

PyTorch models have outputs that are instances of subclasses of :class:`~transformers.file_utils.ModelOutput`. Those
are data structures containing all the information returned by the model, but that can also be used as tuples or
dictionaries.

Let's see of this looks on an example:

.. code-block::

    from transformers import BertTokenizer, BertForSequenceClassification
    import torch

    tokenizer = BertTokenizer.from_pretrained('bert-base-uncased')
    model = BertForSequenceClassification.from_pretrained('bert-base-uncased')

    inputs = tokenizer("Hello, my dog is cute", return_tensors="pt")
    labels = torch.tensor([1]).unsqueeze(0)  # Batch size 1
    outputs = model(**inputs, labels=labels)

The ``outputs`` object is a :class:`~transformers.modeling_outputs.SequenceClassifierOutput`, as we can see in the
documentation of that class below, it means it has an optional ``loss``, a ``logits`` an optional ``hidden_states`` and
an optional ``attentions`` attribute. Here we have the ``loss`` since we passed along ``labels``, but we don't have
``hidden_states`` and ``attentions`` because we didn't pass ``output_hidden_states=True`` or
``output_attentions=True``.

You can access each attribute as you would usually do, and if that attribute has not been returned by the model, you
will get ``None``. Here for instance ``outputs.loss`` is the loss computed by the model, and ``outputs.attentions`` is
``None``.

When considering our ``outputs`` object as tuple, it only considers the attributes that don't have ``None`` values.
Here for instance, it has two elements, ``loss`` then ``logits``, so

.. code-block::

    outputs[:2]

will return the tuple ``(outputs.loss, outputs.logits)`` for instance.

When considering our ``outputs`` object as dictionary, it only considers the attributes that don't have ``None``
values. Here for instance, it has two keys that are ``loss`` and ``logits``.

We document here the generic model outputs that are used by more than one model type. Specific output types are
documented on their corresponding model page.

``ModelOutput``
~~~~~~~~~~~~~~~

.. autoclass:: transformers.file_utils.ModelOutput
    :members:

``BaseModelOutput``
~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.BaseModelOutput
    :members:

``BaseModelOutputWithPooling``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.BaseModelOutputWithPooling
    :members:

``BaseModelOutputWithPast``
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.BaseModelOutputWithPast
    :members:

``Seq2SeqModelOutput``
~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.Seq2SeqModelOutput
    :members:

``CausalLMOutput``
~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.CausalLMOutput
    :members:

``CausalLMOutputWithPast``
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.CausalLMOutputWithPast
    :members:

``MaskedLMOutput``
~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.MaskedLMOutput
    :members:

``Seq2SeqLMOutput``
~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.Seq2SeqLMOutput
    :members:

``NextSentencePredictorOutput``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.NextSentencePredictorOutput
    :members:

``SequenceClassifierOutput``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.SequenceClassifierOutput
    :members:

``Seq2SeqSequenceClassifierOutput``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.Seq2SeqSequenceClassifierOutput
    :members:

``MultipleChoiceModelOutput``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.MultipleChoiceModelOutput
    :members:

``TokenClassifierOutput``
~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.TokenClassifierOutput
    :members:

``QuestionAnsweringModelOutput``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.QuestionAnsweringModelOutput
    :members:

``Seq2SeqQuestionAnsweringModelOutput``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. autoclass:: transformers.modeling_outputs.Seq2SeqQuestionAnsweringModelOutput
    :members: