Extracting fields from documents¶
With pip install "solvi[model]", solvi provides a ModernBERT extractor, LongSpanExtractor. It predicts a start and an end
position in the text, so the extracted value is always a substring of the document with exact offsets. It gives you
plain functions doc -> Quote to register with cat.extract. Training needs torch; prediction also runs without it,
on solvi[onnx] (onnxruntime + tokenizers):
ex = LongSpanExtractor.load("solvi-ai/extract-base", backend="onnx") # downloads the JSON files and onnx/ only
cat.extract(ex.field("total", "the total amount paid"))
backend="auto"(the default) takes torch when torch and transformers are installed, as before, and the ONNX backend otherwise;"torch"and"onnx"choose one.- The ONNX backend reads the checkpoint's
onnx/model_fp16.onnx(elsemodel.onnx,model_fp32.onnx; oronnx_file=): the encoder and the span head in one graph. The windows, "no answer" and span decoding are the same code as with torch. On 50 SQuAD v2 questions (30 one-window, 20 multi-window) extract-base's fp16 export gave the same span as torch on all 50 (see the benchmarks). - It predicts only:
fit,saveandembedraise and name the torch backend. A model you fine-tuned gets its export withtools/export_onnx.pyof the solvi repository (needs torch once); it writesonnx/and the tokenizer files into a folder this backend loads, and compares the spans with torch on your texts. - Its fingerprint hashes the ONNX file and
tokenizer.json, not the torch weights: a trace answered with one backend does not replay as the same model with the other.
Labels are character spans: for each training document and field, (start, end) of the value in the text, or None if
the field is absent. extract-base's model card suggests labelling about 25–100 documents per task and fine-tuning. A
GPU is recommended for training and for fast inference.
MultiSpanExtractor (removed in 1.0)¶
0.9's solvi.core.extract.multi.MultiSpanExtractor (a fixed field list, one start/end head pair per field, one pass
per document) was used by nothing in solvi and is gone in 1.0. The published receipts model, solvi-ai/extract-receipts, is a
LongSpanExtractor (below); for a fixed list of fields over short documents, one LongSpanExtractor with a
description per field reads the same fields (one pass per field instead of one per document; predictions are
cached per text and field).
LongSpanExtractor: long documents, fields by description, "no answer"¶
solvi.core.extract.LongSpanExtractor is for long documents (contracts) and optional fields. The input is
[CLS] field description [SEP] window of the document [SEP], windows overlap, and position 0 means "no answer in this
window".
from solvi.core.extract import LongSpanExtractor
GOV_LAW = "the clause that says which state's or country's law governs the contract"
lx = LongSpanExtractor(max_len=1024, stride=128, max_span=96)
lx.fit([(text, GOV_LAW, span_or_none) for text, span_or_none in train], epochs=3, neg_per_item=3)
lx.tune_threshold("governing_law", [(text, GOV_LAW, span_or_none) for text, span_or_none in heldout])
cat.extract(lx.field("governing_law", GOV_LAW))
@cat.fn
def governing_state(governing_law):
for s in ["Delaware", "New York", "California"]:
if s.lower() in governing_law.lower():
return s
return "other"
strideis the overlap between windows in tokens;max_spancaps answer length in tokens.- Training uses every window that contains the answer plus up to
neg_per_itemwindows without it. One extractor can learn several fields: pass items with different descriptions. predict(text, desc)returns(start, end, span_score, no_answer_score), the best span over all windows.tune_threshold(name, items)picks the score threshold for "the field is present" that maximizes present/absent accuracy on held-out items.field(name, desc)returns a functiondoc -> Quote. When the score is below the threshold, it returnsQuote("", 0, 0), an empty value, so downstream functions should treat""as "not found" (e.g.has_tax = tax != "").- Cost grows with length: one pass per field per window, so a long contract with several fields takes many passes; use a GPU for long documents.
- Fields are specified by description, but a field that was never labeled in training is not extracted reliably from its description alone (extract-base's model card: 14% and 66% on two held-out fields for a model trained on other fields only). Label examples for every field you need. A universal extractor that handles new fields is in progress.
SpanExtractor (removed in 0.8)¶
solvi.extract_model.SpanExtractor, one field per pass with no field() helper and no save / load, had no caller and
is gone, and so is solvi.extract_model (in 0.8 importing SpanExtractor from it warned and gave
LongSpanExtractor; removed in 0.9). Use solvi.core.extract.LongSpanExtractor: it trains on the same items, fit([(text, description, (s, e) or None), ...]); predict(text,
description) returns one (start, end, score, no_answer_score), and field(name, description) is the @extract part.
Hardware notes¶
- A GPU is recommended for training and for long documents.
- On a CPU, use the fp32 ONNX export; no int8 export is provided. If you quantize one yourself, compare its spans with the fp32 export's on your own fields before using it.