Principle:Pytorch Serve Label Mapping

Field	Value
Page Type	Principle
Title	Label Mapping
Short Description	Mapping model output indices to human-readable labels - providing class name lookups for classification tasks through JSON configuration files bundled into model archives
Domains	NLP, Data_Processing
Knowledge Sources	TorchServe
Workflow	HuggingFace_Transformer_Serving
Last Updated	2026-02-13 00:00 GMT

Overview

Label Mapping is the principle of translating raw numerical model outputs into human-readable labels through an external mapping file. Neural network classifiers produce output tensors where each position corresponds to a class index. Without a mapping, API consumers receive opaque integers (e.g., 0 or 1) rather than meaningful labels (e.g., "Not Accepted" or "Accepted"). By bundling a JSON mapping file into the model archive, the serving handler can automatically convert predicted indices to descriptive strings at inference time.

Description

The Index-to-Name Pattern

Classification models produce logits or probabilities over a fixed set of classes. The argmax of these outputs yields a class index. The label mapping file provides the translation layer between these indices and their semantic meanings.

The mapping follows a simple convention:

• Keys are string representations of integer indices (e.g., "0", "1", "2")
• Values are human-readable label strings (e.g., "Not Accepted", "Accepted")

String keys are used (rather than integer keys) because JSON object keys must be strings, and the predicted index is converted to a string via str(y_hat) before lookup.

Task Applicability

Label mapping is not universally required across all NLP tasks:

Task Mode	Label Mapping Required	Reason
sequence_classification	Yes	The output is a class index that needs a label name
token_classification	Yes	Each token receives a class prediction (e.g., NER tags); the mapping provides the label list
question_answering	No	The output is extracted text spans, not class indices
text_generation	No	The output is generated text decoded from token IDs

For token classification, the mapping format differs slightly: it contains a "label_list" key whose value is a string representation of a Python list of labels, which is parsed at inference time.

Integration with TorchServe

The mapping file is included as an extra file when creating the Model Archive (.mar) using torch-model-archiver. At initialization time, the handler checks for the file at os.path.join(model_dir, "index_to_name.json") and loads it into self.mapping. The TorchServe BaseHandler also provides a load_label_mapping() utility for this purpose.

Usage

To use label mapping in a HuggingFace Transformer serving workflow:

1. Create a JSON file named index_to_name.json with string index keys mapping to label names
2. Include the file as an extra file when archiving the model: torch-model-archiver --extra-files index_to_name.json ...
3. The handler automatically loads and uses the mapping during inference for classification tasks

The mapping must be consistent with the model's training configuration. If the model was trained with label 0 as "Negative" and label 1 as "Positive", the mapping file must reflect this same assignment.

Theoretical Basis

Label mapping addresses the semantic gap between a model's numerical output space and the problem domain's vocabulary. This is a form of output post-processing that belongs at the serving layer rather than inside the model itself, for several reasons:

• Model portability - The same model weights can be served with different label schemes (e.g., different languages) by swapping only the mapping file
• Separation of concerns - The model is responsible for learning discriminative features; the mapping layer is responsible for presentation
• Maintainability - Label names can be updated without retraining or re-exporting the model

This pattern is common across serving frameworks (TensorFlow Serving uses label vocabularies, ONNX Runtime uses class labels metadata) and reflects the general principle that serving-time configuration should be decoupled from training-time artifacts.

Related Pages

• Implementation:Pytorch_Serve_Index_To_Name_Mapping - The JSON mapping file that implements this label mapping principle
• Principle:Pytorch_Serve_Generalized_NLP_Handler - The handler that loads and applies the label mapping during inference