Skip to content

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 (else model.onnx, model_fp32.onnx; or onnx_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, save and embed raise and name the torch backend. A model you fine-tuned gets its export with tools/export_onnx.py of the solvi repository (needs torch once); it writes onnx/ 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"
  • stride is the overlap between windows in tokens; max_span caps answer length in tokens.
  • Training uses every window that contains the answer plus up to neg_per_item windows 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 function doc -> Quote. When the score is below the threshold, it returns Quote("", 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.