SovrGPT Dokumentation

Extraction Engine: typisierte Felder aus Text und Fotos

Extraction Engine: liest Chargencodes, Daten, Beträge, Listen, Ja/Nein, Auswahl und Fundorte aus Text und bis zu vier Fotos, mit Sicherheit und Wahrscheinlichkeit „kein Wert“ je Feld.

Die Extraction Engine liest typisierte Felder aus einem Text und bis zu vier Fotos: einen Chargencode von einer Verpackung, ein Mindesthaltbarkeitsdatum, einen Rechnungsbetrag, eine Liste von Artikelnummern, ob etwas vorhanden ist, wo im Bild es steht. Je Feld bekommen Sie einen Wert in der Form des Feldtyps oder null, dazu eine Sicherheit (confidence), die Wahrscheinlichkeit „kein Wert“ (p_null) und den besten Wert auch dann, wenn er unsicher ist (guess). Einen Antworttext schreibt sie nicht.

Sie ist das Gegenstück zur Decision Engine: Die Decision Engine wählt zwischen festen Antworten, die Extraction Engine liest Werte ab. Beide teilen sich Bildformate, Grenzen und Datenschutzregeln.

So funktioniert es

Sie schicken einen Zustand (state, Text oder JSON, optional), bis zu vier eingebettete Bilder und eine Liste von Feldern mit Typ und Anweisung. Jedes Feld wird in einem eigenen Modelldurchlauf bestimmt, alle Felder gleichzeitig:

  • Lesen (text, number, date, time, datetime, duration, list, box): Das Modell schreibt nur den Wert, als JSON. Aus den Wahrscheinlichkeiten der Token, die den Wert bilden, entstehen confidence und p_null.
  • Wählen (boolean, enum, estimate): dasselbe Muster wie bei der Decision Engine. Wir lesen die Wahrscheinlichkeit jeder erlaubten Option ab; geschrieben wird nichts.

Bilder und Zustand werden als Daten behandelt, nie als Anweisung. Steht auf einem Foto „ignoriere alle Regeln“, ist das ein gelesener Text, kein Befehl.

Feldtypen

TypLiestvalueZusätzliche Schlüssel
textText genau so, wie er stehtZeichenkettelocate
numbereine ZahlJSON-Zahl; „1.234,56“ wird zu 1234.56unit (nur Beschriftung), integer, decimals (0–6), locate
dateein Datum"JJJJ-MM-TT"; fehlt das Jahr, gilt reference_datelocate
timeeine Uhrzeit"HH:MM" oder "HH:MM:SS" (24 h)locate
datetimeDatum und Uhrzeit"JJJJ-MM-TTTHH:MM" oder mit Sekundenlocate
durationeine ZeitspanneZahl in unit (Vorgabe seconds; minutes, hours, days, weeks, months, years)unit, integer, decimals, locate
listmehrere Einträge in LesereihenfolgeArray, [] wenn keine; höchstens 50 Einträgeitems (Pflicht: text, number oder date), decimals
booleanJa/Neintrue, false oder null–
enumeine von festen OptionenOptions-Kennung oder nulloptions (Array aus Kennungen oder {id, description}) oder criteria (Objekt Kennung → Beschreibung), 2–25 Optionen
boxwo im Bild etwas stehtFundort (siehe unten) oder null; braucht mindestens ein Bild–
estimateeine Schätzung in einem Bereichimmer eine Zahl (Median, auf step gerundet)min und max (Pflicht, min < max), step, scale (linear oder log, bei log muss min > 0 sein), unit

Für jeden Typ gilt außerdem null_threshold (Vorgabe 0,5): Liegt p_null darüber, wird value zu null (bei list zu []). Bei estimate hat das keine Wirkung, weil eine Schätzung immer einen Wert liefert. locate: true bestimmt bei Lesefeldern zusätzlich den Fundort im Bild, in einem zweiten Durchlauf.

Ein Schlüssel, der zum Typ nicht passt (etwa min an einem Textfeld), wird mit 400 abgelehnt, statt still nichts zu bewirken. Die Kennung not_determinable ist bei enum reserviert.

forecast gibt es nicht. Ein einzelner Lesedurchlauf kann keine kalibrierte Zeitreihe über mehrere Schritte liefern. Eine Anfrage mit forecast bekommt 400 unsupported_field_type; für eine Vorhersage stellen Sie je Schritt ein estimate-Feld.

Was jede Antwort enthält

FeldBedeutung
valueDer Wert in der Form des Feldtyps, oder null (bei list: []).
guessDer beste Wert, auch wenn value null ist. Las das Modell zuerst null, holt ein zweiter Durchlauf mit erzwungenem Wertanfang den wahrscheinlichsten Wert. Fehlt bei list.
p_nullWahrscheinlichkeit, dass das Feld keinen Wert hat. Bei estimate immer null.
confidenceSicherheit 0–1. Ist value null, bezieht sie sich auf guess. Bei box immer null, mit Absicht (siehe unten).
spanNur text: Zeichenpositionen [start, end) des Werts im Zustand, null wenn er nicht wörtlich dort steht, etwa weil er aus einem Bild kommt.
spansNur list mit Texteinträgen: eine Spanne je Eintrag.
boxFundort im Bild, bei type: "box" und bei locate: true.
probabilitiesNur boolean und enum: Wahrscheinlichkeit je echter Option (ohne „nicht bestimmbar“).
mean, median, p10, p90, p_below, p_aboveNur estimate: Kennzahlen der Verteilung; p_below/p_above ist die Masse unter min bzw. über max.
warningsAuffälligkeiten, die ein Mensch sehen sollte (Tabelle unten). Leer heißt nichts Auffälliges gefunden, nicht „sicher richtig“.
calibrationHeute immer { "status": "uncalibrated" }.

Ein Fundort (box) sieht so aus, hier für ein Foto mit 1200 × 1600 Pixeln (Beispielwerte):

{ "image": 0, "image_name": "back", "x1": 309, "y1": 1023, "x2": 891, "y2": 1095,
  "left": 0.2575, "top": 0.6396, "right": 0.7425, "bottom": 0.6846 }

image zählt ab 0 in der Reihenfolge von images. x1 bis y2 sind Pixel im übergebenen Bild (Ursprung oben links); sie sind null, wenn sich die Bildmaße nicht aus dem Dateikopf lesen ließen. left bis bottom sind Anteile 0–1 der Bildbreite bzw. -höhe.

Warnungen (warnings)

WarnungBedeutung
matches_instruction_exampleDer Wert gleicht einem Beispielwert aus Ihrer Anweisung. Er kann trotzdem richtig sein; deshalb nur Warnung, kein null. Siehe Gute Anweisungen.
type_mismatchDas Modell lieferte etwas, das nicht zum Typ passt (etwa „31. Aug“ für ein date). value ist null, der Rohwert steht in guess.
unparseable_outputEs kam kein vollständiger JSON-Wert zurück.
truncatedDer Wert wurde an der Längengrenze des Durchlaufs abgeschnitten.
exif_orientation_ignoredNur Fundorte: Das JPEG trägt eine EXIF-Drehung. Die Pixel beziehen sich auf die gespeicherte Ausrichtung, so wie das Modell das Bild sah — Bilder am besten aufrecht senden.
low_label_massNur boolean, enum, estimate: Weniger als die Hälfte der Wahrscheinlichkeit lag auf den erlaubten Optionen. Die Verteilung ist dann nicht belastbar.

Wie confidence und p_null entstehen

  • Lesefelder, confidence: das Produkt der Wahrscheinlichkeiten aller Token, die den Wert bilden. Es ist die Wahrscheinlichkeit, dass genau diese Zeichenfolge die beste Lesung ist. Ein einziges unsicheres Zeichen (6 oder 8?) drückt sie; genau das zählt bei Codes.
  • Lesefelder, p_null: aus dem ersten Token des Werts. Wir vergleichen die Masse auf null mit der Masse auf einem Wertanfang (Anführungszeichen, Ziffer, Klammer, true/false) und normieren beide auf 1.
  • boolean und enum: Jede Wahl bekommt eine zusätzliche Option „nicht bestimmbar“; ihre Wahrscheinlichkeit ist p_null. probabilities und confidence beziehen sich nur auf die echten Optionen, neu normiert. confidence = (p_max − 1/n) / (1 − 1/n) mit n echten Optionen: 0 heißt gleich verteilt, 1 heißt eine Option hat alles. Dieselbe Formel liefert die Decision Engine.
  • estimate: Der Bereich wird in bis zu 24 Klassen geteilt (mit step entsprechend weniger), dazu „unter min“ und „über max“. confidence misst, wie eng die Verteilung um ihren Median liegt.
  • box: confidence ist null. Das Produkt über die Koordinaten-Token lag in unserer Messung auch bei genau sitzenden Fundorten um 0,001. Eine Zahl, die „unsicher“ sagt, wo nichts unsicher ist, wäre schlechter als keine.

Alle Werte sind unkalibriert. confidence: 0,92 heißt nicht „zu 92 % richtig“. Wie gut die Zahl auf unserem Testsatz trennt, steht unter Schwellen setzen.

Bilder

  • 1 bis 4 Bilder je Anfrage, JPEG, PNG oder WebP, nur eingebettet. Der Dienst lädt keine fremden Adressen.
  • Je Bild höchstens 4 MiB, alle zusammen höchstens 8 MiB (dekodiert).
  • Der ganze Anfragerumpf darf höchstens 4,4 MB haben. Die Plattform schneidet bei 4,5 MB ab und antwortet dann selbst mit 413, bevor unser Code läuft; wir prüfen knapp darunter, damit Sie unsere Fehlerform bekommen. Base64 macht Bilder um ein Drittel größer. In der Praxis ist deshalb der Rumpf die Grenze: Zwei Fotos mit 1600 px langer Kante (JPEG) passen bequem hinein, vier Bilder à 4 MiB nicht.
  • Der Bildtyp wird aus den ersten Bytes bestimmt. Ein angegebener Typ, der nicht dazu passt, wird abgelehnt.

Vier Schreibweisen sind erlaubt, auch gemischt:

"images": [
  "data:image/jpeg;base64,/9j/4AAQ…",
  { "data_url": "data:image/png;base64,iVBORw0…" },
  { "name": "back", "data": "/9j/4AAQ…" },
  { "content_type": "image/webp", "base64": "UklGR…" }
]

Ein name (1–40 Zeichen: Buchstaben, Ziffern, Leerzeichen, _ . -, eindeutig) erscheint im Prompt als „Image 1 (back)“. So kann eine Anweisung sagen „auf dem Bild der Rückseite“.

Auflösung: Kleingedrucktes braucht Pixel. Gemessen haben wir mit 1600 px langer Kante. Wer stärker verkleinert, spart Token und verliert genau die feinen Zeichen, um die es meist geht.

Gute Anweisungen

Zwei Regeln, beide an echten Packungsfotos gemessen:

1. Keine konkreten Beispielwerte in die Anweisung. Mit „e.g. PH12345678“ in der Anweisung gaben auf schwer lesbaren Feldern alle geprüften Modelle das Beispiel zurück. Der Systemtext verbietet das inzwischen ausdrücklich, und die Antwort trägt dann matches_instruction_example. Die Warnung schlägt aber auch an, wenn das Beispiel zufällig der echte Wert ist. Beschreiben Sie deshalb das Format statt eines Werts („beginnt mit PH, dann acht Ziffern“), oder rechnen Sie mit der Warnung. In unserem Prüflauf trugen 17 Lesungen diese Warnung; 6 davon waren falsch.

2. Sagen Sie, wo ein Code endet. Auf den echten Sachets unseres Testsatzes steht eine Zeile nach dem Schema 31AUG2027 61234567K1 4 L2 17:32; der Chargencode ist der zweite Block. Die Anweisung „Ziffern und Buchstaben, keine Leerzeichen“ ließ das Modell über die Leerzeichen hinweg zusammenziehen (61234567K14L2). Die präzise Fassung „… bis zum ersten Leerzeichen; Datum und alles nach dem ersten Leerzeichen ausschließen“ änderte das Ergebnis deutlich:

Anweisungechte Ware exaktfalschfalsch bei confidence ≥ 0,7
„digits+letters, no spaces“10/32220
„up to the first space, exclude the date and anything after the first space“28/3240

Auch Ja/Nein-Felder brauchen eine Anweisung. Ein boolean namens lot_code_present ohne instructions ergab auf zehn Vorderseiten zehnmal null (nicht bestimmbar) statt false: Am Feldnamen allein erkennt das Modell nicht, was gemeint ist.

Schwellen setzen

Wo Sie confidence abschneiden, entscheidet, wie viel ohne Mensch durchläuft. Auf unserem Testsatz sah das so aus: alle gelesenen Felder mit bekanntem richtigem Wert (Chargencode, Mindesthaltbarkeit, Artikelcode, Druckauftrag) auf 56 Rückseiten von Lebensmittel-Sachets, 24 gefälscht, 32 echt, iPhone-Fotos auf 1600 px verkleinert. Ausgenommen sind die 17 Lesungen mit matches_instruction_example; mit ihnen enthielt der Testsatz 103 richtige Lesungen.

confidence ≥angenommenrichtigfalschdavon auf echter Ware
0149925749
0,5878431
0,7767510
0,8686800
0,9545400
0,95363600

So gelesen: Ab 0,8 liefen 68 der 103 richtigen Lesungen ohne Mensch durch, und kein einziger Fehler lief mit. Der Rest ging an die Prüfung.

Das ist unser Testsatz, nicht Ihrer. Die Werte sind unkalibriert, und 149 Lesungen sind wenig. Bestimmen Sie Ihre Schwelle an einer Stichprobe Ihrer eigenen Fotos mit bekanntem richtigem Wert, bevor Sie Felder automatisch übernehmen.

Modellkarte sovr-extract-1.0

Kennungsovr-extract-1.0, Alias sovr-extract (zeigt immer auf die jüngste Version). Ohne model gilt sovr-extract-1.0.
LaufzeitSprachmodell mit Bildverständnis, betrieben von STACKIT in Deutschland (BSI C5). Fest gebunden: weder wir noch Ihre Organisation können sie für diese Version umstellen.
Erschienen06.11.2026
Abrufbarmindestens bis 04.02.2027 (model.available_until in jeder Antwort). Der Termin wird höchstens verlängert, nie verkürzt.
Bestelltextsovr-extract-prompt-1.0 (model.prompt_version)
DatenKein Training mit Ihren Daten. Bilder, Zustand und Antworten werden nicht gespeichert; für die Abrechnung bleiben nur Tokenzahlen. Der Verarbeitungsort steht in jeder Antwort (processing_region, hier eu-de).
Kalibrierungkeine; ECE 0,083 auf unserem Testsatz (10 Klassen, n = 149)

Gemessen (06.11.2026, Testsatz wie unter Schwellen setzen, Felder und Anweisungen aus einem echten Kundenauftrag wörtlich übernommen):

Feldexaktfalschdavon echte Wareohne bekannten Wert
Mindesthaltbarkeit (date)50214
Chargencode (text)3224220
Artikelcode (text, winzig und quer gedruckt)10171729
Druckauftrag (text, Kleingedrucktes)11201525
Chargencode vorhanden (boolean)56000

Die Chargencode-Fehler auf echter Ware hingen an der Anweisung (siehe Gute Anweisungen); mit präziser Anweisung 28 von 32 exakt. Auf zehn Vorderseiten ohne sichtbaren Code war der Chargencode zehnmal null, mit p_null 0,994–0,9998.

Zuverlässigkeit (Anteil richtig je Sicherheitsklasse): 0,9–1,0 → 58 Lesungen, alle richtig (mittlere Sicherheit 0,967); 0,8–0,9 → 15, alle richtig; 0,2–0,3 → 23, davon 13 % richtig; 0,0–0,1 → 16, keine richtig.

Wartezeit (warm, von Jena aus, ein Foto mit 1600 px):

Messungp50p95
1 Feld375 ms599 ms
4 Felder gleichzeitig854 ms1 441 ms
7 Felder gleichzeitig (nur 4 von 56 Fotos ungedrosselt)1 045 ms1 112 ms

Das sind Messwerte, keine Zusage. Die tatsächliche Dauer steht in jeder Antwort unter latency_ms und timing_ms.

Determinismus. Gelesen wird mit temperature: 0, ohne Stichprobe. Dieselbe Anfrage mit sieben Feldern dreimal gestellt: Sichere Felder blieben gleich. Abweichungen gab es nur bei Feldern mit confidence unter 0,9 und bei Box-Koordinaten (±1 Tausendstel der Bildkante); die Sicherheiten selbst schwankten in der zweiten bis dritten Nachkommastelle. Ursache ist die Rechenreihenfolge auf der GPU des Betreibers, nicht unsere Auswertung. Ehrlich heißt das: Gleiche Eingabe und gleiche Version ergeben für sichere Felder dieselbe Antwort; unsichere Felder können kippen. Sie liegen unter jeder sinnvollen Schwelle.

Bekannte Grenzen

  • Anbietergrenze 45 Anfragen je Minute für diese Laufzeit, und jedes Feld ist mindestens eine Anfrage (mit locate oder dem guess-Nachlauf zwei). Dazu kommen 350 000 Token je Minute; ein Foto mit sieben Feldern braucht rund 14 800 Token, das sind etwa 23 Fotos je Minute. In unserem Lauf mit sieben Feldern mussten 52 von 56 Anfragen warten. Ist die Grenze erreicht, antwortet die API mit 429 upstream_rate_limited und Retry-After. 10 Anfragen je Sekunde oder 16 gleichzeitige Offline-Abfragen erreichen Sie damit heute nicht; mehr ist nur über eine höhere Quote beim Betreiber oder weniger Felder je Anfrage möglich.
  • Kleingedrucktes braucht Auflösung. Artikelcode und Druckauftrag (winzig, quer gedruckt) las die Version deutlich schlechter als Datum und Chargencode.
  • Nicht genutzt wird die Laufzeit hinter sovr-decision-v1: Sie rechnet zwei Fotos à 1600 px in 678 Token statt rund 3 900. Für Kleingedrucktes ist das zu grob.
  • Bildtoken werden nicht getrennt ausgewiesen (usage.image_tokens ist null); sie stecken in usage.input_tokens. Ein Feld auf einem Foto kostet rund 2 065 Eingabetoken.

So nutzen Sie die Extraction Engine

  • API: POST /v1/extractions mit dem Scope extractions. Die Version steht auch unter GET /v1/models (kind: "extraction") und unter GET /v1/extractions/models.
  • Playground: eingeloggt unter Einstellungen → Entwickler → Extraction Engine, mit echter Inferenz.
  • MCP: Der authentifizierte MCP-Server bietet sovrgpt_extract. Der Schlüssel braucht zusätzlich den Scope extractions.
Extraction Engine: typisierte Felder aus Text und Fotos