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);
}
}
}
}
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):
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 itsconfig.json.