GLiNER & GLiREL Extraction Models

Relevant source files

The following files were used as context for generating this wiki page:

• am_diag/graph_construction/extract/gliner_entities.py
• am_diag/graph_construction/extract/glirel_relations.py
• am_diag/common/data_models/schema.py
• am_diag/graph_construction/extract/base.py
• am_diag/graph_construction/config.py
• README.md

GLiNER and GLiREL are specialized local, zero-shot extraction models utilized within the am_diag system to populate medical knowledge graphs. GLiNER performs batch Named Entity Recognition (NER), identifying clinical entities such as drugs and diseases based on natural language labels defined in the Graph Schema. GLiREL serves as a sequential relation extractor that processes the entity spans identified by GLiNER to establish directed subject-predicate-object triples.

Together, these models form a core part of the "Three-extractor fusion" strategy, which merges their local outputs with LLM-based extraction to ensure high-fidelity clinical knowledge capture. While GLiNER can operate independently on text chunks, GLiREL requires pre-extracted entity spans and character offsets provided by GLiNER to function effectively.

Sources: README.md:15-18, am_diag/graph_construction/extract/glirel_relations.py:86-90

Architecture and Data Flow

The extraction process follows a tiered approach where entity recognition precedes relationship identification. Both models utilize lazy loading to manage memory, initializing the underlying gliner and glirel libraries only upon the first execution of their respective extract or extract_from_entities methods.

Sequential Extraction Flow

The following diagram illustrates the dependency and data flow between GLiNER and GLiREL within a single text chunk processing cycle.

The pipeline relies on GLiNER to generate Entity objects containing character start/end positions, which are then mapped to tokens for GLiREL consumption.

Sources: am_diag/graph_construction/extract/gliner_entities.py:80-95, am_diag/graph_construction/extract/glirel_relations.py:100-115

GLiNER Entity Extraction

The GLiNEREntityExtractor is responsible for batch-predicting entities from text chunks. It uses the gliner_labels defined in the GraphSchema to steer the model toward specific medical categories.

Key Features

• Batch Prediction: Supports concurrent processing of multiple text chunks using gliner_batch_size.
• Thresholding: Filters extracted spans based on a configurable gliner_threshold.
• Normalization: Maps model-specific GLiNER labels back to standardized system labels using the GraphSchema.gliner_to_label mapping.

Component	Description
extract	Primary async method that converts Chunk text into Entity DataPoints.
_run_gliner_batch	Internal helper executing model.batch_predict_entities.
Provenance	Captures ExtractorName.GLINER, start_char, and end_char.

Sources: am_diag/graph_construction/extract/gliner_entities.py:21-70, am_diag/common/data_models/schema.py:44-48

GLiREL Relation Extraction

GLiRELRelationExtractor performs zero-shot relation extraction over entity pairs. Unlike GLiNER, it operates sequentially per chunk and requires localized entity spans to predict potential relationships.

Implementation Logic

1. Tokenization: Text is split into tokens using a whitespace regex.
2. Mapping: A character-to-token map is built to align GLiNER's character offsets with GLiREL's token requirements.
3. NER Transformation: System Entity objects are converted into a list format [start_tok, end_tok, label, name] compatible with the GLiREL model.
4. Relation Prediction: The model predicts relations between every pair of entities if the total count is $\ge 2$.

# Mapping character offsets to tokens for GLiREL
def _char_to_token_map(text: str, tokens: list[str]) -> dict[int, int]:
    mapping: dict[int, int] = {}
    pos = 0
    for token_idx, token in enumerate(tokens):
        start = text.find(token, pos)
        if start == -1: continue
        for c in range(start, start + len(token)):
            mapping[c] = token_idx
        pos = start + len(token)
    return mapping

Sources: am_diag/graph_construction/extract/glirel_relations.py:25-52, am_diag/graph_construction/extract/glirel_relations.py:105-115

Schema-Driven Extraction

Both extractors are strictly governed by a GraphSchema. This schema provides natural-language hints used to steer the zero-shot models, ensuring that the extracted entities and relations conform to the system's medical ontology.

Entity and Relation Types

• Entity Types: Defines the gliner_label (e.g., "Disease") and description.
• Relation Types: Defines the glirel_label (e.g., "treats") and the allowed head/tail labels (e.g., Drug $\rightarrow$ Disease).

Sources: am_diag/common/data_models/schema.py:18-38

Configuration Parameters

The behavior of these extractors is managed via the ExtractionPipelineConfig.

Parameter	Type	Description
use_gliner	bool	Enables or disables GLiNER extraction.
gliner_model	str	Pre-trained GLiNER model path/name.
gliner_threshold	float	Minimum confidence score for entity extraction.
gliner_batch_size	int	Number of chunks to process in a single GLiNER pass.
use_glirel	bool	Enables or disables GLiREL extraction (Requires GLiNER).
glirel_model	str	Pre-trained GLiREL model path/name.
glirel_threshold	float	Minimum confidence score for relation extraction.

Sources: am_diag/graph_construction/extract/gliner_entities.py:75-85, am_diag/graph_construction/extract/glirel_relations.py:90-100

Conclusion

The GLiNER and GLiREL models provide a robust, local alternative to LLM-only extraction. By utilizing a shared GraphSchema and a sequential data flow—where GLiNER identifies medical concepts and GLiREL connects them—the system achieves precise, structured extraction of clinical knowledge while maintaining spatial provenance through character and token offsets.