gliner.decoding.decoder module

class gliner.decoding.decoder.BaseDecoder(config)[source]

Bases: ABC

Abstract base class for all decoders.

Parameters:

config – Configuration object containing decoder parameters.

__init__(config)[source]
abstract decode(*args, **kwargs)[source]

Decode model output into structured predictions.

Parameters:

  • *args – Variable positional arguments.

  • **kwargs – Variable keyword arguments.

Returns:

Decoded predictions in the appropriate format.

Perform greedy search to remove overlapping spans.

Sorts spans by confidence score (descending) and keeps only non-overlapping spans according to the specified NER mode.

Parameters:

  • spans (List[tuple]) – List of span tuples containing at minimum (start, end, …, score).

  • flat_ner (bool) – Whether to use flat NER (no nesting allowed) or nested NER (allows nesting).

  • multi_label (bool) – Whether to allow multiple labels for the same span position.

Returns:

Filtered list of non-overlapping spans, sorted by start position.

Return type:

List[tuple]

class gliner.decoding.decoder.BaseSpanDecoder(config)[source]

Bases: BaseDecoder

Base class for span-based decoders with common decoding logic.

Provides shared functionality for finding candidate spans, validating them, and decoding batch items.

decode(tokens, id_to_classes, model_output, flat_ner=False, threshold=0.5, multi_label=False, **kwargs)[source]

Decode model output to extract named entity spans.

Parameters:

  • tokens (List[List[str]]) – Tokenized input text for each sample in the batch.

  • id_to_classes (Union[Dict[int, str], List[Dict[int, str]]]) – Mapping from class IDs to class names. Can be a single dict (shared) or list (per-sample).

  • model_output (torch.Tensor) – Raw logits from the model with shape (B, L, K, C), where B is batch size, L is sequence length, K is max span width, C is number of classes.

  • flat_ner (bool) – Whether to enforce non-overlapping spans.

  • threshold (float) – Confidence threshold for span predictions.

  • multi_label (bool) – Whether to allow multiple labels per span.

  • **kwargs – Additional keyword arguments (unused in base class).

Returns:

For each sample in batch, list of span tuples.

Return type:

List[List[tuple]]

class gliner.decoding.decoder.SpanDecoder(config)[source]

Bases: BaseSpanDecoder

Simple span decoder without generative labels.

Returns spans in format: (start, end, entity_type, score)

class gliner.decoding.decoder.SpanGenerativeDecoder(config)[source]

Bases: BaseSpanDecoder

Span decoder with generative label support.

Supports two decoder modes: - ‘prompt’: Generated labels replace the original class names - ‘span’: Generated labels are added as additional fields to each span

Returns spans in format: (start, end, entity_type, generated_entity_type, score)

decode_generative(tokens, id_to_classes, model_output, gen_labels, sel_idx=None, num_gen_sequences=1, flat_ner=False, threshold=0.5, multi_label=False)[source]

Decode model output with generated labels.

Handles both ‘prompt’ and ‘span’ decoder modes: - prompt mode: Generated labels replace class names in id_to_classes - span mode: Generated labels are added to span tuples via span_label_map

Parameters:

  • tokens (List[List[str]]) – Tokenized input text for each sample in the batch.

  • id_to_classes (Union[Dict[int, str], List[Dict[int, str]]]) – Mapping from class IDs to class names.

  • model_output (torch.Tensor) – Raw logits from the model with shape (B, L, K, C).

  • gen_labels (List[str]) – Generated labels from the decoder, flattened across batch.

  • sel_idx (Optional[torch.LongTensor]) – Tensor of shape (B, M) with selected span indices. Required for span mode, unused for prompt mode.

  • num_gen_sequences (int) – Number of label sequences generated per span.

  • flat_ner (bool) – Whether to enforce non-overlapping spans.

  • threshold (float) – Confidence threshold for span predictions.

  • multi_label (bool) – Whether to allow multiple labels per span.

Returns:

For each sample, list of span tuples with generated labels.

Return type:

List[List[tuple]]

decode(tokens, id_to_classes, model_output, flat_ner=False, threshold=0.5, multi_label=False, gen_labels=None, sel_idx=None, num_gen_sequences=1, **kwargs)[source]

Decode model output, with optional generative label support.

If gen_labels are provided and decoder has a labels_decoder, uses generative decoding. Otherwise falls back to standard span decoding.

Parameters:

  • tokens (List[List[str]]) – Tokenized input text for each sample in the batch.

  • id_to_classes (Union[Dict[int, str], List[Dict[int, str]]]) – Mapping from class IDs to class names.

  • model_output (torch.Tensor) – Raw logits from the model with shape (B, L, K, C).

  • flat_ner (bool) – Whether to enforce non-overlapping spans.

  • threshold (float) – Confidence threshold for span predictions.

  • multi_label (bool) – Whether to allow multiple labels per span.

  • gen_labels (Optional[List[str]]) – Generated labels from decoder. If provided, triggers generative decoding.

  • sel_idx (Optional[torch.LongTensor]) – Selected span indices for span mode.

  • num_gen_sequences (int) – Number of label sequences generated per span.

  • **kwargs – Additional keyword arguments (unused).

Returns:

For each sample, list of span tuples.

Return type:

List[List[tuple]]

class gliner.decoding.decoder.SpanRelexDecoder(config)[source]

Bases: BaseSpanDecoder

Span decoder with relation extraction support.

Extends the base span decoder to decode both entity spans and the relations between them. Entity spans are extracted first using the parent class logic, then relations are decoded by identifying pairs of entities and their relationship types based on model predictions.

The decoder supports: - Entity span extraction with confidence thresholding - Relation extraction between detected entities - Flexible entity and relation label mappings (per-sample or global) - Optional flat NER (non-overlapping entities) - Multi-label entity classification

decode(tokens, id_to_classes, model_output, rel_idx=None, rel_logits=None, rel_mask=None, flat_ner=False, threshold=0.5, relation_threshold=0.5, multi_label=False, rel_id_to_classes=None, **kwargs)[source]

Decode model output to extract entities and relations.

Main decoding method that extracts both entity spans and relations from model outputs. First decodes entity spans using the parent class logic, then decodes relations between the detected entities.

Parameters:

  • tokens (List[List[str]]) – Tokenized input text for each sample in the batch. Each sample is a list of token strings.

  • id_to_classes (Dict[int, str] | List[Dict[int, str]]) – Mapping from entity class IDs to entity type names. Can be either: - Dict: Single mapping used for all samples (global entity schema) - List[Dict]: Per-sample mappings for different entity schemas Class IDs are 1-indexed (0 is reserved for padding).

  • model_output – Model output object containing both entity logits and optionally relation predictions. Must have a logits attribute for entity extraction. May have rel_idx, rel_logits, and rel_mask for relation extraction.

  • rel_idx (Tensor | None) – Optional tensor of shape (batch_size, num_relations, 2) containing head and tail entity indices for each potential relation.

  • rel_logits (Tensor | None) – Optional tensor of shape (batch_size, num_relations, num_relation_classes) containing relation classification logits.

  • rel_mask (Tensor | None) – Optional boolean tensor of shape (batch_size, num_relations) indicating valid relations. If None, all relations are considered valid.

  • flat_ner (bool) – If True, applies greedy filtering to ensure non-overlapping entity spans. If False, allows overlapping entities. Defaults to False.

  • threshold (float) – Minimum confidence score (0-1) for both entity predictions to be included in the output. Defaults to 0.5.

  • relation_threshold (float) – Minimum confidence score (0-1) for both relation predictions to be included in the output. Defaults to 0.5.

  • multi_label (bool) – If True, allows multiple entity types per span. If False, only the highest-scoring entity type per span is kept. Defaults to False.

  • rel_id_to_classes (Dict[int, str] | List[Dict[int, str]] | None) – Optional mapping from relation class IDs to relation names. If None, relation decoding is skipped and empty relation lists are returned. Can be either a single Dict or List[Dict] for per-sample mappings. Class IDs are 1-indexed.

  • **kwargs – Additional keyword arguments passed to the parent class decode method.

Returns:

  • spans: List of entity span lists, one per sample. Each entity span is a tuple: (start, end, entity_type, score)

  • relations: List of relation lists, one per sample. Each relation is a tuple: (head_idx, relation_label, tail_idx, score) where head_idx and tail_idx are indices into the corresponding sample’s spans list.

Return type:

Tuple of (spans, relations) where

Examples

>>> decoder = SpanRelexDecoder()
>>> tokens = [["John", "works", "at", "Microsoft"]]
>>> id_to_classes = {1: "PERSON", 2: "ORG"}
>>> rel_id_to_classes = {1: "works_at"}
>>> spans, relations = decoder.decode(
...     tokens=tokens,
...     id_to_classes=id_to_classes,
...     model_output=output,
...     rel_id_to_classes=rel_id_to_classes,
...     threshold=0.5,
... )
>>> # spans[0] might be: [(0, 1, "PERSON", 0.9), (3, 4, "ORG", 0.85)]
>>> # relations[0] might be: [(0, "works_at", 1, 0.8)]
class gliner.decoding.decoder.TokenDecoder(config)[source]

Bases: BaseDecoder

Token-based decoder for sequence labeling tasks.

Uses BIO-style tagging with separate start, end, and inside predictions to identify entity spans.

decode(tokens, id_to_classes, model_output, flat_ner=False, threshold=0.5, multi_label=False, **kwargs)[source]

Decode token-level predictions to extract spans.

Parameters:

  • tokens (List[List[str]]) – Tokenized input text for each sample in the batch.

  • id_to_classes (Union[Dict[int, str], List[Dict[int, str]]]) – Mapping from class IDs to class names.

  • model_output (torch.Tensor) – Raw logits from the model with shape ( B, L, C, 3), where the first dimension represents [start, end, inside] predictions.

  • flat_ner (bool) – Whether to enforce non-overlapping spans.

  • threshold (float) – Confidence threshold for predictions.

  • multi_label (bool) – Whether to allow multiple labels per span.

  • **kwargs – Additional keyword arguments (unused).

Returns:

For each sample, list of span tuples in format

(start, end, entity_type, None, score).

Return type:

List[List[tuple]]