class_docstr: Abstract TorchRankerAgent class; only meant to be extended.
  
  TorchRankerAgents aim to provide convenient functionality for building ranking
  models. This includes:
  
  - Training/evaluating on candidates from a variety of sources.
  - Computing hits@1, hits@5, mean reciprical rank (MRR), and other metrics.
  - Caching representations for fast runtime when deploying models to production.
class_docstr_tok: ["Abstract","TorchRankerAgent","class",";","only","meant","to","be","extended",".","TorchRankerAgents","aim","to","provide","convenient","functionality","for","building","ranking","models",".","This","includes",":","-","Training\/evaluating","on","candidates","from","a","variety","of","sources",".","-","Computing","hits","@","1",",","hits","@","5",",","mean","reciprical","rank","(","MRR",")",",","and","other","metrics",".","-","Caching","representations","for","fast","runtime","when","deploying","models","to","production","."]
docstr: Train on a single batch of examples.
docstr_tok: ["Train","on","a","single","batch","of","examples","."]
code: def train_step(self, batch):
      """
      Train on a single batch of examples.
      """
      self._maybe_invalidate_fixed_encs_cache()
      if batch.text_vec is None and batch.image is None:
          return
      self.model.train()
      self.zero_grad()
  
      cands, cand_vecs, label_inds = self._build_candidates(
          batch, source=self.candidates, mode="train"
      )
      try:
          scores = self.score_candidates(batch, cand_vecs)
          loss = self.criterion(scores, label_inds)
          self.record_local_metric(
              "mean_loss", AverageMetric.many(loss)
          )
          loss = loss.mean()
          self.backward(loss)
          self.update_params()
      except RuntimeError as e:
          # catch out of memory exceptions during fwd/bck (skip batch)
          if "out of memory" in str(e):
              logging.error(
                  "Ran out of memory, skipping batch. "
                  "if this happens frequently, decrease batchsize or "
                  "truncate the inputs to the model."
              )
              return Output()
          else:
              raise e
  
      # Get train predictions
      if self.candidates == "batch":
          self._get_batch_train_metrics(scores)
          return Output()
      if not self.opt.get("train_predict", False):
          warn_once(
              "Some training metrics are omitted for speed. Set the flag "
              "`--train-predict` to calculate train metrics."
          )
          return Output()
      return self._get_train_preds(scores, label_inds, cands, cand_vecs)
  
imports: from typing import Optional
  from parlai.core.params import ParlaiParser
  from typing import Dict, Any
  from abc import abstractmethod
  from itertools import islice
  import os
  from tqdm import tqdm
  import random
  import torch
  from parlai.core.opt import Opt
  from parlai.utils.distributed import is_distributed
  from parlai.core.torch_agent import TorchAgent, Output
  from parlai.utils.misc import warn_once
  from parlai.utils.io import PathManager
  from parlai.utils.torch import padded_3d, total_parameters, trainable_parameters, PipelineHelper
  from parlai.utils.fp16 import FP16SafeCrossEntropy
  from parlai.core.metrics import AverageMetric
  import parlai.utils.logging
label_desc: Use image node_id 12 for calling the TorchRankerAgent obj's underlying member method code with example usage: obj.train_step(batch) and returns: self, Output, Output, Output