Operationen ‣ Attribut Extraktion

Die Attribut-Extraktion überträgt Daten aus einem Quelldatensatz in ein vordefiniertes Zielschema mithilfe eines KI-Sprachmodells (OpenAI / Azure OpenAI). Sie eignet sich besonders dann, wenn Quell- und Zielstruktur unterschiedliche Attributnamen verwenden oder wenn die Zuordnung inhaltlich interpretiert werden muss.

Voraussetzung: Es muss ein OPENAI_PROVIDER mit dem Anwendungsfall Attributextraktion konfiguriert sein.

1. Attribut-Extraktion anlegen

Die Operation wird wie jede andere Flow-Operation per Drag & Drop aus dem grafischen Flow-Editor auf die Editor-Oberfläche gezogen und mit einer Datenquelle verbunden.

2. Attribut-Extraktion konfigurieren

Basis

Feld Beschreibung
Name Bezeichnung der Operation
Schema (Zielschema) Das Schema, das die Zielattribute mit ihren Schlüsseln, Beschreibungen und optionalen Fixwerten definiert
Ergebnis auf Schemaattribute filtern Wenn aktiv, werden nur Attribute im Ergebnis behalten, die im Zielschema definiert sind. Zusätzliche Attribute, die die KI ggf. ergänzt, werden entfernt
Kommentar Optionaler Freitext

Erweitert

Feld Beschreibung
Quellattribute beibehalten (Präfix) Wird ein Präfix angegeben, werden alle Quellattribute zusätzlich unter <Präfix>_<Attributname> im Ergebnisdatensatz mitgeliefert
System-Prompt Optionales Handlebars-Template, das die Rolle der KI, das Eingabeformat und die Ausgaberegeln festlegt. Leer lassen, um den eingebauten Standard-Prompt zu verwenden (siehe unten)
User-Prompt Optionales Handlebars-Template, das die datensatzspezifische Nutzlast (Zielattribute + Quelldatensatz) trägt. Leer lassen, um den eingebauten Standard-Prompt zu verwenden (siehe unten)

Die Aufteilung zwischen System- und User-Prompt verfolgt zwei Ziele: Die Regeln lassen sich überschreiben, ohne die datensatzspezifische Nutzlast neu zu schreiben, und der OpenAI-Prompt-Cache kann das statische Präfix über alle Datensätze eines Laufs hinweg wiederverwenden.

Zielformat

Ein eigener Tab Zielformat zeigt das JSON, das in die {{targetFormat}}-Handlebars-Variable eingesetzt wird. Standardmäßig wird dieses JSON zur Laufzeit aus dem Zielschema erzeugt. Soll stattdessen eine feste, eingefrorene Version verwendet werden (oder einzelne Einträge per Hand ergänzt oder entfernt werden), kann das JSON im Editor bearbeitet und an der Operation gespeichert werden. Der Button neben dem Editor erzeugt das JSON neu aus dem aktuellen Zielschema und überschreibt den Editorinhalt. Bleibt der Editor leer, fällt die Operation auf die Laufzeit-Generierung zurück.

Ist Zielformat gesetzt, verwendet Ergebnis auf Schemaattribute filtern die Schlüssel aus dem Zielformat-JSON (nicht die Schlüssel des Schemas) — ein hier zusätzlich aufgenommener Schlüssel passiert also den Filter, ein hier entfernter Schlüssel wird aus der Ausgabe entfernt.

Quellattribute

Optionale Einschränkung: Nur die hier ausgewählten Attribute aus dem Quelldatensatz werden an die KI übergeben. Leer lassen, um alle Attribute zu übergeben. Je weniger Attribute, desto kürzer der Prompt — das verbessert Qualität und Geschwindigkeit.

Wie die KI das Zielschema nutzt

Für jedes Attribut im Zielschema werden folgende Felder an die KI übergeben:

  • key – der Zielattributschlüssel (wird als Property-Name im Ausgabe-JSON verwendet)
  • description – Name und Beschreibung des Attributs kombiniert (z. B. "Farbe — Die Hauptfarbe des Produkts"). Sind Name und Beschreibung identisch oder eine davon leer, wird nur der vorhandene Text verwendet
  • defaultValue – falls gesetzt, wird dieser Wert als Hinweis an die KI übergeben
  • fixedValues – falls gesetzt, darf die KI nur Werte aus dieser Liste verwenden
  • mandatory – falls true, muss die KI das Attribut in der Ausgabe liefern. Kann sie keinen Wert extrahieren, fällt sie auf defaultValue zurück, ansonsten auf den leeren String
  • pattern – falls gesetzt, muss die KI den extrahierten Wert so umformatieren, dass er diesem regulären Ausdruck entspricht

3. Standardprompts

Wird kein eigener Prompt konfiguriert, verwendet die Operation zwei ineinandergreifende Prompts. Beide lassen sich unabhängig voneinander überschreiben — bleibt das jeweilige Feld leer, wird der untenstehende Standard verwendet.

System-Prompt (Rolle, Eingabevertrag, Ausgaberegeln)

You are a precise data extraction assistant.
You extract structured attributes from a single source data record according to a list of target attributes.

You will receive a user message with two JSON blocks:
1. "Target attributes" — a JSON array describing what to extract.
2. "Source record" — a JSON object containing the raw data.

Each target attribute is an object with these fields:
- "key" (required): the property name to use in your output.
- "description" (required): what this attribute represents and what to look for in the source record.
- "fixedValues" (optional): a list of allowed values. If present, the output MUST be exactly one of these values, copied verbatim.
- "defaultValue" (optional): the value to use when the source record contains no usable information for this attribute.
- "mandatory" (optional, default false): when true, the attribute MUST appear in the output. If you cannot extract a value, fall back to "defaultValue" if given, otherwise use an empty string. Do not invent data.
- "pattern" (optional): a regular expression the output value must match. Reformat the extracted value if needed so it satisfies the pattern.

Output rules:
- Respond with a single flat JSON object — no markdown fences, no commentary, no wrapping array.
- Each property name in the output is a "key" from the target attributes.
- Map as many attributes as possible. Non-mandatory attributes with no source information may be omitted.
- Never fabricate values not supported by the source record. When in doubt, omit (or, for mandatory attributes, fall back as described above).

User-Prompt (Datensatz-Nutzlast, Handlebars-Template)

Target attributes:
"""{{targetFormat}}"""

Source record:
"""{{sourceRecord}}"""

Die Variablen {{targetFormat}} und {{sourceRecord}} werden zur Laufzeit mit den (verdichteten) Schemadaten bzw. dem gefilterten Quelldatensatz befüllt. Beide Prompts laufen über denselben Handlebars-Kontext, sodass Variablen bei Bedarf zwischen ihnen verschoben werden können.

Der minimale User-Prompt ist Absicht: Wenn die statischen Regeln im System-Prompt bleiben und nur die datensatzspezifische Nutzlast in der User-Nachricht steht, kann der Prompt-Cache von OpenAI das Systempräfix über alle Datensätze eines Laufs hinweg wiederverwenden.

4. Vorschau

Bevor die Operation gegen den vollständigen Datenbestand läuft, lässt sich die Konfiguration mit einer Vorschau überprüfen. Die Vorschau wird manuell über den Button neben der Suchleiste oben im Quellbereich ausgelöst — sie startet nicht automatisch beim Öffnen der Detailansicht, da jeder KI-Aufruf langsam und kostenpflichtig ist.

Bei einem Vorschau-Lauf:

  • Extrahiert das Backend Attribute nur für die ersten zwei Datensätze und liefert die übrigen Datensätze als unbearbeitete Platzhalter zurück, sodass die Vorschauliste die gleiche Zeilenzahl behält und Hover-Highlights weiterhin mit dem Quellbereich übereinstimmen.
  • Wird der Prompt-Cache stets umgangen, sodass weder veraltete Antworten gelesen noch abgebrochene Läufe in den Cache geschrieben werden.
  • Erscheinen fehlgeschlagene Datensätze (z. B. wenn der Prompt das konfigurierte Kontextfenster überschreitet oder der Provider einen Fehler liefert) mit einem Ausrufezeichen-Indikator in der ersten Spalte. Beim Überfahren mit der Maus wird die Fehlermeldung angezeigt.
  • Platzhalterzeilen jenseits der zwei verarbeiteten Datensätze tragen keinen Validierungs-Indikator — sie wurden nicht verarbeitet, also gibt es nichts anzuzeigen.

So lassen sich vor einem realen Lauf typische Probleme erkennen: ein falscher Schemaverweis, ein angepasster Prompt, der nicht mehr ins Kontextfenster passt, ein nicht erreichbarer Provider oder ein Zielformat-Override mit ungültigem JSON.

5. Ausführung

Nach der Konfiguration wird die Operation über den Button Attribute extrahieren gestartet. Die KI verarbeitet jeden Datensatz der Quelle einzeln und erzeugt einen Ausgabedatensatz mit den Zielattributen.

Im Header der Ausführungskarte wird der aktuelle GPT-Status des konfigurierten Providers angezeigt:

Status Bedeutung
verfügbar Der Provider ist bereit
Rate Limit aktiv Das Anfrage-Kontingent ist ausgeschöpft, Reset in X Sekunden

6. Ergebnis

Der Ausgabedatensatz enthält die vom Zielschema definierten Attribute, befüllt mit den aus dem Quelldatensatz extrahierten Werten. Attribute, für die kein passender Wert gefunden wurde, können leer oder mit dem defaultValue belegt sein.

Falls Quellattribute beibehalten konfiguriert wurde, sind zusätzlich alle Originalattribute unter dem angegebenen Präfix im Ergebnis enthalten.

Ist Ergebnis auf Schemaattribute filtern aktiv, werden nur Attribute im Ergebnis behalten, deren Schlüssel im Zielschema definiert sind.

7. Beispiel

Das folgende Beispiel zeigt, wie unstrukturierte Katzenbeschreibungen mithilfe der KI auf ein sauberes Zielschema abgebildet werden können.

Quelldaten

Freitext-Beschreibungen von Katzen. Jeder Datensatz enthält lediglich den Namen der Katze sowie einen einzelnen beschreibenden Satz, in dem Rasse, Farbe, Alter, Körperlänge und Bild-URL natürlichsprachlich vermischt sind.

Quelldatensatz: JSON herunterladen

catName catDescription
Whisker A playful Siamese with a medium body length of 43cm, cream-colored coat, and dark chocolate points. Aged 2 years. URL: https://res.cloudinary.com/.../cat01.png
Mittens A cuddly Maine Coon, large(55cm) and fluffy with a gray tabby pattern and white paws. Aged 3 years. URL: https://res.cloudinary.com/.../cat02.png
Pumpkin An affectionate Abyssinian with a sleek, medium-length cinnamon coat(around 410 mm give or take). Aged 4 years. URL: https://res.cloudinary.com/.../cat03.png
Shadow A stealthy Bombay cat with a short, jet-black coat and bright yellow eyes. Aged 1 year. URL: https://res.cloudinary.com/.../cat04.png
Pearl A dainty Turkish Angora with a long, silky white coat and heterochromatic eyes. Aged 6 years. Unfortunately we do not have an image for this cat.

Zielschema

Bevor die Operation ausgeführt werden kann, muss ein Schema existieren, das die Zielattribute definiert. Die Attribut-Extraktion verwendet dieses Schema als Schema (Zielschema).

Definition des Zielschemas: JSON herunterladen

Das Schema enthält die folgenden Attribute:

key Beschreibung fixedValues defaultValue
id the unique id of the cat — —
breed the cat’s breed — —
age the age of the cat in years, a number between 0 and 20 — —
color the color of the cat’s fur BLUE, BLACK, GRAY, WHITE, GINGER, BROWN —
bodyLength the length of the cat’s body in cm — —
image the url of the cat’s image in jpeg format — https://picsum.photos/id/219/5000/3333
shortDescription summary of the description, max 200 Characters — —

Das Schema übernimmt hier die eigentliche Steuerungsarbeit:

  • color ist über fixedValues eingeschränkt; die KI muss einen der erlaubten Werte wählen (z. B. wird der Quellwert “cream-colored” zu WHITE normalisiert).
  • bodyLength beschreibt die Einheit (cm), sodass die KI “around 410 mm” in 41 umrechnet.
  • image definiert einen defaultValue, der genutzt wird, wenn die Quellbeschreibung keine URL enthält (z. B. bei Pearl).
  • shortDescription weist die KI an, die vollständige Beschreibung zusammenzufassen.

Erwartetes Ergebnis

Nach Ausführung der Operation auf den Quelldaten mit obigem Schema enthält jeder Ausgabedatensatz die Schema-Attribute, befüllt aus der Freitext-Beschreibung:

id breed age color bodyLength image shortDescription
Whisker Siamese 2 WHITE 43 https://res.cloudinary.com/.../cat01.png Playful Siamese, cream coat with dark chocolate points
Mittens Maine Coon 3 GRAY 55 https://res.cloudinary.com/.../cat02.png Cuddly Maine Coon, gray tabby with white paws
Pumpkin Abyssinian 4 BROWN 41 https://res.cloudinary.com/.../cat03.png Affectionate Abyssinian with cinnamon coat
Shadow Bombay 1 BLACK — https://res.cloudinary.com/.../cat04.png Stealthy Bombay with jet-black coat, yellow eyes
Pearl Turkish Angora 6 WHITE — https://picsum.photos/id/219/5000/3333 Dainty Turkish Angora with silky white coat

Die exakten Werte können zwischen Ausführungen leicht variieren, da das Ergebnis vom KI-Modell erzeugt wird.

8. Data Quality Index (DQI)

Nach der Ausführung einer Attribut-Extraktion wird die Ergebnisliste mit einem Data Quality Index (DQI) bewertet — eine einzelne Kennzahl von 0 bis 100, die angibt, wie gut die extrahierten Datensätze zum Zielschema passen. Mit dem DQI lassen sich Läufe nach Änderungen am Modell, am Prompt oder am Schema vergleichen.

Der Wert wird in der Karte Info Metriken des Ergebnisses angezeigt und zusätzlich pro Attribut in den Attribut-Metriken berechnet.

Was der DQI misst

Der DQI kombiniert pro Attribut zwei strukturelle Achsen:

  • Befüllungsrate (fill rate) — Anteil der Datensätze, in denen das Attribut befüllt ist. fillRate = 1 − nulls / totalRecords.
  • Konformitätsrate (conformity rate) — wie gut die befüllten Werte den Schema-Constraints entsprechen (aktuell Pflichtfeld und Werteliste; weitere Regeln können später ergänzt werden).

DQI pro Attribut:

dqi_a = fillRate_a · conformityRate_a

Gesamt-DQI (über alle Schema-Attribute), skaliert auf 0–100:

_chioroDqi = 100 · Σ_a (weight_a · dqi_a) / Σ_a weight_a

weight_a ist 2.0, wenn das Attribut im Schema als Pflichtfeld markiert ist oder wenn Ergebnis auf Schemaattribute filtern aktiv ist und das Attribut eine Werteliste besitzt. Andernfalls ist weight_a = 1.0. Treffen beide Bedingungen zu, bleibt der Wert bei 2.0 (keine Aufsummierung).

Wie die Konformität berechnet wird

Die Konformität ist ein Produkt aus Einzelregel-Bewertungen, wobei der Beitrag jeder Regel über einen Exponenten gewichtet wird:

conformityRate_a = Π_r  score_r ^ ruleWeight_r

Ein höheres Regelgewicht lässt Verstöße gegen diese Regel die Konformität schärfer drücken. Aktuell werden zwei Regeln ausgewertet, beide mit Regelgewicht 2.0:

Regel Wann sie greift Score
required Attribut ist im Schema Pflichtfeld filled / totalRecords (Nullwerte verletzen required)
valueList Schema definiert eine Werteliste, mindestens ein Datensatz ist befüllt inListCount / filled

Greift keine Regel (Freitext, keine Werteliste, kein Pflichtfeld), bleibt die Konformitätsrate bei 1.0.

Beispiel. Ein Pflichtfeld ohne Werteliste, in 90 % der Datensätze befüllt:

  • fillRate = 0,9
  • required-Score = 0,9, Gewicht 2,0 → conformityRate = 0,9² = 0,81
  • dqi_a = 0,9 · 0,81 = 0,729

Was der DQI nicht ist

Der DQI ist eine strukturelle Qualitätsheuristik. Er bewertet nicht, ob der Inhalt eines extrahierten Wertes inhaltlich korrekt ist — nur, ob der Wert vorhanden ist und den Schema-Regeln entspricht. Auch mit einem irreführenden Prompt kann der DQI hoch ausfallen: Die Attribute sind befüllt und stehen in der Werteliste, die Werte selbst können trotzdem falsch sein. Vor dem Vertrauen auf einen hohen DQI sollte stets eine Vorschau stichprobenartig geprüft werden.

Typ, Wertebereich, Länge und Muster werden noch nicht ausgewertet. Sie können später als zusätzliche Regeln eingebunden werden — die Formel deckt das ohne Anpassung der bestehenden Daten ab.

9. Hinweise

  • Die KI-Verarbeitung erfolgt pro Datensatz sequenziell. Bei großen Datenmengen und aktiven Rate Limits wartet die Operation automatisch, bis das Kontingent wieder verfügbar ist.
  • Ist kein OPENAI_PROVIDER mit dem Anwendungsfall Attributextraktion konfiguriert, schlägt die Ausführung mit einem entsprechenden Fehler fehl.
  • Ist kein Schema (Zielschema) konfiguriert, schlägt die Ausführung ebenfalls fehl.
  • Der GPT-Status im UI zeigt den serverseitig beobachteten Zustand seit dem letzten Backend-Start — nach einem Neustart ist der Status initial immer „verfügbar“.
  • Antworten der KI werden pro Provider gecacht. Identische Prompts (gleicher Quelldatensatz, gleiches Schema, gleicher Prompt-Text) liefern sofort das gecachte Ergebnis, ohne die API erneut zu belasten.