Usage

The examples below work with both GLiFormer v1 checkpoints and reuse this model:

import torch
from gliformer import GLiFormer

model = GLiFormer.from_pretrained(
    "knowledgator/gliformer-large-v1",
    load_tokenizer=True,
)
model = model.to("cuda" if torch.cuda.is_available() else "cpu").eval()

Named Entity Recognition

Specify the entity types at inference time. Pass a list of texts to process a batch:

texts = ["Alice works at Acme.", "Bob lives in Berlin."]
predictions = model.predict_entities(
    texts,
    ["person", "organization", "location"],
    threshold=0.5,
    batch_size=8,
)

for text, entities in zip(texts, predictions):
    for entity in entities:
        print(text[entity["start"]:entity["end"]], entity["label"], entity["score"])

Each entity includes text, label, start, end, and score. The end offset is exclusive. Set flat_ner=False to allow overlapping spans, or multi_label=True to allow multiple labels per span.

Text Classification

predictions = model.classify(
    "The new search feature is fast and easy to use.",
    ["positive", "negative", "neutral"],
    threshold=0.5,
)
print(predictions)

For a single group, predictions are label dictionaries containing class_name and score. Use named groups to classify several aspects of a text:

predictions = model.classify(
    "The new search feature is fast and easy to use.",
    {
        "sentiment": ["positive", "negative", "neutral"],
        "topic": ["product", "support", "billing"],
    },
)
print(predictions)

Joint Relation Extraction

Provide both entity types and relation types through joint_relations:

results = model.inference(
    "Alice works at Acme.",
    joint_relations={
        "employment": {
            "entities": ["person", "organization"],
            "relations": ["works_at"],
        }
    },
    threshold=0.5,
)

for relation in results["joint_relex"][0]:
    print(relation["head"]["text"], relation["relation"], relation["tail"]["text"])

Base v1 and Large v1 have a joint relation head. The predict_relations convenience method and the relations argument of inference require a separate open relation head, which these checkpoints do not contain.

Structured Extraction

Flat Records

Define a record name and the fields to extract:

records = model.structure(
    "Alice works at Acme.",
    {"employee": ["name", "company"]},
    threshold=0.5,
)
print(records)

Illustrative output:

{
  "employee": [{"name": "Alice", "company": "Acme"}]
}

Nested Records with Pydantic

Use nested Pydantic models to describe parent–child relationships:

import json
from pydantic import BaseModel


class Employee(BaseModel):
    name: str
    role: str


class Department(BaseModel):
    name: str
    employees: list[Employee]


class Company(BaseModel):
    name: str
    departments: list[Department]


records = model.structure(
    "At Acme, Engineering includes Alice, a software engineer, and Bob, "
    "a designer. Sales includes Carol, an account manager.",
    {"company": Company},
    validate_output=True,
)
print(json.dumps(records, indent=2))

The decoder assembles fields extracted from the source and connects employees to departments and departments to companies. validate_output=True validates the extracted result against the Pydantic schema and returns dictionaries and lists. Schema validation does not verify factual correctness.

Multiple Tasks in One Call

results = model.inference(
    "Alice joined Acme as a software engineer.",
    entities=["person", "organization"],
    classes=["business", "sports", "technology"],
    structures={"employee": ["name", "company"]},
    threshold=0.5,
)

print(results["ner"][0])
print(results["classification"][0])
print(results["structuring"][0])

For a reusable schema, use GLiFormerSchema:

from gliformer import GLiFormerSchema

schema = GLiFormerSchema(
    entities=["person", "organization"],
    classes=["business", "sports", "technology"],
    structures={"employee": ["name", "company"]},
)
results = model.inference_from_schema(
    ["Alice joined Acme as a software engineer."],
    schema,
    threshold=0.5,
)
print(results["structuring"][0])

inference and inference_from_schema return a dictionary of task outputs, each containing one result per input text. The convenience methods predict_entities, classify, and structure return a single result for a string input, or a list of results for a batch.

Text Embeddings

import torch.nn.functional as F

embeddings = model.embed_text([
    "A scientist works in a laboratory.",
    "A researcher conducts an experiment.",
])
print(embeddings.shape)  # torch.Size([2, 1024]) for Large v1
print(F.cosine_similarity(embeddings[0:1], embeddings[1:2]).item())

embed_text returns a CPU tensor of shape (number_of_texts, embedding_dimension), including for a single string. The dimension is 768 for Base v1 and 1024 for Large v1. The model cards do not report embedding benchmark results; evaluate similarity quality on your own data.

Inference Settings

Setting	Purpose
threshold	Confidence cutoff for predictions; defaults to 0.5
batch_size	Number of texts processed together; defaults to 8
flat_ner	Enforces non-overlapping spans when True
multi_label	Allows multiple labels per entity span when True
objectness_threshold	Separate relation/structuring anchor cutoff; uses threshold when omitted

Tune labels and thresholds on representative examples. Larger batches, longer texts, and larger schemas increase memory use. Text and schema prompts share the encoder budget; the configured maximum length is not a measured guarantee of extraction quality at that length.