Implementation:Pytorch Serve Index To Name Mapping

Field	Value
Page Type	Implementation
Title	Index To Name Mapping
Type	Pattern Doc
Short Description	JSON mapping file that translates model output class indices to human-readable label names, bundled as an extra file in the model archive
Domains	NLP, Data_Processing
Source	examples/Huggingface_Transformers/index_to_name.json:L1-4
Knowledge Sources	TorchServe
Workflow	HuggingFace_Transformer_Serving
Last Updated	2026-02-13 00:00 GMT

Overview

The index_to_name.json file provides a mapping from model output indices (as string keys) to human-readable label names. This file is bundled into the TorchServe model archive as an extra file and loaded by the handler at initialization time. It enables the handler to return meaningful label strings (e.g., "Accepted") instead of raw integer predictions (e.g., 1).

Description

The mapping file follows a minimal JSON object pattern where each key is a string representation of an integer class index and each value is the corresponding label name. The file is loaded by TransformersSeqClassifierHandler.initialize() into self.mapping and used during inference to translate argmax predictions into labels.

The file is only required for classification tasks (sequence classification and token classification). Question answering and text generation tasks do not need this file, as their outputs are text spans and generated sequences respectively.

Usage

The file is included when creating the model archive:

torch-model-archiver --model-name my_model \
  --version 1.0 \
  --handler Transformer_handler_generalized.py \
  --extra-files "index_to_name.json,model-config.yaml" \
  --export-path model_store

Code Reference

Source Location

Field	Value
Repository	pytorch/serve
File	examples/Huggingface_Transformers/index_to_name.json
Lines	L1-4

Full Content

{
 "0":"Not Accepted",
 "1":"Accepted"
}

Pattern Structure

{
  "<index_as_string>": "<label_name>",
  "<index_as_string>": "<label_name>"
}

Import / Loading

The file is loaded in the handler's initialize() method (L142-153 of Transformer_handler_generalized.py):

# Read the mapping file, index to object name
mapping_file_path = os.path.join(model_dir, "index_to_name.json")
# Question answering does not need the index_to_name.json file.
if not (
    self.setup_config["mode"] == "question_answering"
    or self.setup_config["mode"] == "text_generation"
):
    if os.path.isfile(mapping_file_path):
        with open(mapping_file_path) as f:
            self.mapping = json.load(f)
    else:
        logger.warning("Missing the index_to_name.json file.")

During inference, the mapping is used as a dictionary lookup (L255-256):

y_hat = out.argmax(1).item()
predicted_idx = str(y_hat)
inferences.append(self.mapping[predicted_idx])

I/O Contract

Input

Input	Format	Description
JSON file	JSON object	Keys are string representations of integer indices; values are label name strings

Constraints

• Keys must be strings (JSON requirement for object keys)
• Keys must cover all possible output indices from the model (0 through num_labels - 1)
• Values should be descriptive, human-readable label names
• The number of entries must match the num_labels parameter in the handler configuration

Output

Consumer	How Used
TransformersSeqClassifierHandler.initialize()	Loaded into self.mapping as a Python dictionary
TransformersSeqClassifierHandler.inference()	Sequence classification: self.mapping[predicted_idx] returns the label name
TransformersSeqClassifierHandler.inference()	Token classification: self.mapping["label_list"] returns the list of NER/POS tags

Usage Examples

Example 1: Binary Sentiment Classification

{
  "0": "Negative",
  "1": "Positive"
}

Example 2: Multi-Class Topic Classification

{
  "0": "Sports",
  "1": "Politics",
  "2": "Technology",
  "3": "Entertainment",
  "4": "Science"
}

Example 3: Token Classification (NER)

For token classification, the format uses a "label_list" key:

{
  "label_list": "[O, B-PER, I-PER, B-ORG, I-ORG, B-LOC, I-LOC, B-MISC, I-MISC]"
}

Example 4: Acceptance Classification (From Source)

{
 "0":"Not Accepted",
 "1":"Accepted"
}

Related Pages

• Principle:Pytorch_Serve_Label_Mapping - The principle of mapping model output indices to human-readable labels
• Implementation:Pytorch_Serve_TransformersSeqClassifierHandler - The handler that loads and uses this mapping file