solvi.core.extract¶
@extract for long, general-purpose documents: a field defined by its description (LongSpanExtractor; torch to train, and torch or the solvi[onnx] extra — load(..., backend="onnx") — to predict).
@extract for real-world, general-purpose documents (the extractor protocol: fit(items), predict(text, description), field(name, description), save / load, fingerprint()): a field is defined by its DESCRIPTION, the document may be long (windows), and the field may be absent ("no answer"). ModernBERT: input "field description [SEP] document window", two pointer heads; "no answer" is position 0 (the special token). Prediction: the best span across all windows; an answer exists if its score is above the field's threshold (tuned on held-out examples). Also works for fields unseen in training, from the description alone ("new field").
Training (fit, save, embed) needs torch and transformers (solvi[model]). Prediction also runs without torch, on the
solvi[onnx] extra (onnxruntime + tokenizers): LongSpanExtractor.load(path_or_id, backend="onnx") reads the
checkpoint's onnx/model_fp16.onnx (the encoder and the span head in one graph, written by tools/export_onnx.py) and
its tokenizer.json; windows, "no answer" and span decoding are the same code as with torch.
LongSpanExtractor ¶
LongSpanExtractor(model_name='answerdotai/ModernBERT-large', max_len=1024, stride=128, max_span=96, device=None)
stride: overlap between adjacent windows in tokens (as in transformers); max_span: maximum answer length in tokens.
make_examples ¶
items: [(text, description, (start, end) | None[, neg])] → training windows: every window with the answer + up to neg_per_item (or the item's own neg) windows without it.
fit ¶
Fine-tune on [(text, description, (start, end) | None[, neg])]. Fitting on the CPU creates no CUDA context, so it works beside a GPU that is busy or full.
predict ¶
→ (start, end, span score, "no answer" score) — the best span across all windows.
tune_threshold ¶
tune_threshold(name, items, grid=(0.0003, 0.001, 0.003, 0.01, 0.02, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8))
Per-field "answer present" threshold from held-out examples: maximizes present/absent decision accuracy.
tune_default_threshold ¶
tune_default_threshold(items, grid=(0.0003, 0.001, 0.003, 0.01, 0.02, 0.05, 0.1, 0.2, 0.3, 0.4, 0.5))
One threshold from held-out examples of many fields — used for fields that have no examples of their own.
save ¶
Encoder weights (bf16 safetensors), tokenizer, span head and settings into a directory.
load
classmethod
¶
From a directory written by save(), or a Hugging Face model id (downloaded once and cached).
backend: "torch" (solvi[model]), "onnx" (solvi[onnx]: onnxruntime + tokenizers, no torch; prediction only —
predict, field, tune_threshold; it needs the checkpoint's onnx/ export, see tools/export_onnx.py) or "auto"
(torch when torch and transformers are installed, as before; ONNX otherwise). A Hugging Face id is downloaded in
full for torch, and only its JSON files and onnx/ for ONNX. onnx_file: the export to load (default: the first of
onnx/model_fp16.onnx, model.onnx, model_fp32.onnx). The two backends give the same spans up to fp16 rounding of
the scores; their fingerprints differ (a trace records which one answered).
embed ¶
Document embedding: the encoder's token states averaged over every window of the text (no field description). The ONNX export has the span scores only, not the token states: torch backend only.
embedder ¶
A catalog part: doc → embedding vector, usable as a feature of System.fit.
fingerprint ¶
A stable hash of this extractor: settings, thresholds, the span head, sampled encoder weights and the weight files it was loaded from (recorded in the trace; replay compares it with the catalog's current model). With the ONNX backend: sampled bytes of the ONNX export and of tokenizer.json instead of the weights.