Skip to content

Sentiment Analysis

Classify text as positive or negative (or any custom label set) using a fine-tuned DistilBERT model.

Quick example

try (var classifier = DistilBertTextClassifier.builder().build()) {
    List<TextClassification> results = classifier.classify("This movie was fantastic!");
    // [TextClassification[label=POSITIVE, confidence=0.9998]]
}

Full example

import io.github.inference4j.nlp.DistilBertTextClassifier;
import io.github.inference4j.nlp.TextClassification;
import java.util.List;

public class SentimentAnalysis {
    public static void main(String[] args) {
        try (var classifier = DistilBertTextClassifier.builder().build()) {
            List<String> reviews = List.of(
                "This movie was fantastic!",
                "Terrible experience, would not recommend.",
                "It was okay, nothing special."
            );

            for (String review : reviews) {
                List<TextClassification> results = classifier.classify(review);
                TextClassification top = results.get(0);
                System.out.printf("%-45s → %s (%.2f%%)%n",
                    review, top.label(), top.confidence() * 100);
            }
        }
    }
}
Screenshot from showcase app
Screenshot from showcase app

Builder options

Method Type Default Description
.modelId(String) String inference4j/distilbert-base-uncased-finetuned-sst-2-english HuggingFace model ID
.modelSource(ModelSource) ModelSource HuggingFaceModelSource Model resolution strategy
.sessionOptions(SessionConfigurer) SessionConfigurer default ONNX Runtime session config
.tokenizer(Tokenizer) Tokenizer auto-loaded WordPieceTokenizer Custom tokenizer
.config(ModelConfig) ModelConfig auto-loaded from config.json Model config with labels
.outputOperator(OutputOperator) OutputOperator auto-detected (softmax or sigmoid) Output activation
.maxLength(int) int 512 Maximum token sequence length
.truncation(TruncationPolicy) TruncationPolicy TRUNCATE Input longer than the token limit: TRUNCATE keeps the first tokens and logs a warning, FAIL throws InputTooLongException. See Input length
.stride(int) int off Classify long input in full, in overlapping windows sharing this many tokens. See Long texts
.windowAggregation(WindowAggregation) WindowAggregation mean() How window scores combine into one score per label: mean(), max(), or your own. Requires .stride(int)

Input length

Limit When exceeded Long-input strategies
maxLength tokens (512 by default), including [CLS] and [SEP] Truncated with a warning (default), or rejected with .truncation(TruncationPolicy.FAIL) .stride(int): overlapping windows, whole input classified

By default only the beginning of a long text contributes to the classification.

Long texts

With .stride(int) set, a text longer than maxLength tokens is split into windows that share stride tokens. Each window is classified, and a WindowAggregation combines the window scores into one score per label:

try (var classifier = DistilBertTextClassifier.builder()
        .stride(128)
        .windowAggregation(WindowAggregation.mean())   // the default
        .build()) {
    classifier.classify(longReview);
}
Aggregation Score per label Use it for
WindowAggregation.mean() Average across windows; with softmax models still sums to 1 An overall verdict for the whole text, such as sentiment
WindowAggregation.max() Highest score in any window; with softmax models no longer sums to 1 "Fires anywhere" labels, such as moderation and multi-label tagging, where one passage should decide
your own lambda Anything, e.g. median or trimmed mean Custom rules

WindowAggregation is a functional interface, so a custom rule is a lambda over the list of window scores (one float[] of label probabilities per window, in text order):

WindowAggregation lastWindow = windowScores -> windowScores.get(windowScores.size() - 1);

Input that fits in one window is classified in a single pass, exactly as without stride.

Measured accuracy

The default SST-2 model on 500 IMDB movie reviews longer than 512 tokens (balanced positive and negative; median 719 tokens):

Mode Accuracy Time
Truncate (default) 84.8% 1×
.stride(128) + mean() 87.4% 2.3×
.stride(128) + max() 87.2% 2.3×

Truncated, the result matches the HuggingFace transformers pipeline on the same reviews prediction for prediction. Windowing classifies the whole review, at the cost of one model pass per window. For a two-label sentiment model, mean() and max() perform alike; max() matters for models where a single passage should decide.

Result type

TextClassification is a record with:

Field Type Description
label() String Classification label (e.g., POSITIVE)
index() int Numeric class index
confidence() float Confidence score (0.0 to 1.0)

Using custom models

Any HuggingFace text classification model exported to ONNX will work, as long as it includes vocab.txt and config.json with id2label mappings.

try (var classifier = DistilBertTextClassifier.builder()
        .modelId("your-org/your-model")
        .build()) {
    classifier.classify("Some text");
}

The output activation (softmax vs sigmoid) is auto-detected from config.json:

  • problem_type: "multi_label_classification" → sigmoid
  • Everything else → softmax

Tips

  • The default model is fine-tuned on SST-2 (movie reviews). For other domains (product reviews, support tickets), use a model fine-tuned on relevant data.
  • Use .classify(text, topK) to limit the number of returned classifications.
  • For multi-label classification (where multiple labels can be true simultaneously), use a model with problem_type: "multi_label_classification" in its config.json.