Die Labeling-Engine

Die Labeling-Engine labelt einen Datensatz mit Modellen und misst mithilfe von Menschen, wie oft die Modelle falschliegen. In einem Vertrag legen Sie fest, was die fertigen Labels erfüllen müssen, etwa „höchstens 5 % der akzeptierten Maschinenlabels sind falsch, bei 90 % Konfidenz“. Die Engine fordert bei Menschen die Labels an, die sie zum Testen dieser Aussage braucht, akzeptiert die Maschinenlabels, die der Test stützt, und gibt die übrigen Items an Menschen weiter. Das Ergebnis ist der Datensatz und dazu ein Zertifikat, das festhält, was getestet wurde und an wie vielen menschlichen Labels.

Die Engine gibt es ab Potato 2.11. Der Annotationsserver, die Kommandozeile potato label, die REST API, der MCP-Server und ein Python SDK steuern sie alle über dieselbe Datei engine.sqlite im Aufgabenverzeichnis.

Wann die Engine zu einer Studie passt

Die Engine lohnt sich, wenn Menschen nicht alles labeln können und ein Modell den Großteil labeln kann. Wenn Menschen ohnehin jedes Item labeln, bringt die Engine nichts, und eine gewöhnliche Zuweisungsstrategie ist die bessere Wahl. Drei Situationen passen:

• Sie haben mehr Items, als Menschen labeln können, und ein Modell, das meistens richtig liegt.
• Sie müssen angeben, wie gut die Labels sind, und nicht nur, dass ein Modell sie erzeugt hat, etwa für ein Paper, eine Datensatzveröffentlichung oder ein Trainingsset, das jemand anderes verwenden wird.
• Sie evaluieren ein Modell oder einen Agenten mit einem LLM-Judge und müssen wissen, ob der Judge Menschen ersetzen kann.

Von der Modellvorhersage zum endgültigen Label

Die Engine hält Maschinenvorhersagen, Anfragen an Menschen und Vertragsergebnisse in einem Speicher, und jedes Item durchläuft dieselben sechs Schritte:

1. Quellen sind die Modelle. Eine Quelle kann ein LLM sein, ein Vision-Language-Modell, ein Entscheidungsmodell (Laya, Jev oder OpenJev), ein Objektdetektor, ein LLM-Judge, ein auf den eigenen Labels der Studie trainiertes Modell, eine Jury aus anderen Quellen oder Labels, die Sie bereits haben. Jede Quelle speichert zu jeder Vorhersage eine Konfidenz.
2. Die Kaskade legt die Reihenfolge der Quellen fest. Ein Item geht an die erste Quelle, und wenn der Vertrag deren Antwort nicht akzeptiert, versucht es die nächste Quelle. Nach der letzten Quelle geht das Item an einen Menschen.
3. Anfragen sind das, worum die Engine Menschen bittet. Jede Anfrage speichert, warum sie gestellt wurde (z. B. Kalibrierung, Zertifizierung, Verifikation, Audit), mit welcher Wahrscheinlichkeit ihr Item gezogen wurde und ob die Person eine Maschinenantwort sehen konnte. Kalibrierungsanfragen werden zufällig gezogen und sind immer verblindet.
4. Verträge testen die Maschinenlabels an den menschlichen Labels der Zufallsstichprobe. Die eine Hälfte dieser Stichprobe (der dev-Split) wählt die Akzeptanzregel, die andere Hälfte (der cert-Split) testet sie. Der Status eines Vertrags ist met, insufficient (mehr Labels nötig, mit einer Schätzung, wie viele), infeasible, violated oder stale.
5. Die Auflösung gibt jedem Item sein endgültiges Label. Das Label ist ein Maschinenlabel, das unter einem erfüllten Vertrag akzeptiert wurde, das Label einer Person oder noch ausstehend.
6. Das Zertifikat hält das Ergebnis jedes Vertrags fest, die Kaskade mit Modell- und Prompt-Versionen, wie viele menschliche Labels in welchen Zweck flossen, die Modellkosten und einen Digest des Aufrufprotokolls.

Regeln hinter den Garantien

Ein erfüllter Vertrag ist eine statistische Aussage über die Zufallsstichprobe, die Menschen gelabelt haben, und er gilt, weil diese Stichprobe auf eine bestimmte Weise gezogen und verwendet wird. Die Engine setzt fünf Regeln durch:

• Verblindete Anfragen zeigen keine Maschinenantwort. Solange eine Person eine Kalibrierungs-, Zertifizierungs- oder Audit-Anfrage hält, hält der Server jede Maschinenantwort für dieses Item zurück. Vorannotationen, der Inline-Judge, der KI-Assistent (der mit 403 antwortet) und die KI-Hilfe-Schaltflächen sind alle aus. Ein Label, das nach dem Anblick der Maschinenantwort vergeben wurde, ist keine unabhängige Prüfung dieser Antwort.
• Auswahl und Test verwenden verschiedene Labels. Schwellenwerte werden an dev-Labels gewählt und an cert-Labels getestet. Jeder neue Test an den cert-Labels läuft auf einem strengeren Niveau, sodass wiederholtes Zertifizieren, bis ein Test besteht, die Konfidenz nicht aufbläht.
• Nur Menschen zertifizieren. Maschinelle Annotierende dürfen an der Bestimmung der endgültigen Labels mitwirken, nie aber an den Labels, an denen ein Vertrag getestet wird.
• Eine Änderung macht das Zertifikat veraltet. Wenn sich eine Quelle, ein Prompt, ein Schwellenwert oder das Schema ändert, wird jeder betroffene Vertrag als stale markiert, und seine akzeptierten Labels wandern nach pending_recert, bis der Vertrag erneut getestet ist. Die menschlichen Labels bleiben erhalten.
• Maschinenvorhersagen belegen keine Plätze von Annotierenden. Vorhersagen der Engine zählen nicht gegen die Obergrenzen für Annotierende pro Item.

Ob die menschlichen Labels richtig sind, prüft die Engine nicht. Jeder Vertrag misst die Maschinen an den Menschen, die die Stichprobe gelabelt haben. Ein Vertrag, der an unzuverlässigen Menschen getestet wurde, bescheinigt also Übereinstimmung mit unzuverlässigen Menschen. Prüfen Sie mit Qualitätskontrolle, Mehrfachannotation (humans.overlap) und dem Vertrag no_worse_than_human auch die Menschen.

Eine erste Studie

Potato liefert unter examples/labeling-engine/ drei Beispielstudien mit, je eine für Text, Bilder und Agenten-Traces. Die Tabelle zeigt, welche Quellen und Verträge jede davon verwendet:

Das Textbeispiel läuft mit vier Befehlen. Der erste labelt jedes Item mit der Kaskade und zieht die erste verblindete Stichprobe, der zweite liefert diese Stichprobe an Menschen aus, und die letzten beiden testen die Verträge und geben das Zertifikat aus, sobald Menschen die Stichprobe gelabelt haben:

potato label run examples/labeling-engine/text-certified-sentiment/config.yaml
potato start examples/labeling-engine/text-certified-sentiment/config.yaml -p 8000
potato label certify examples/labeling-engine/text-certified-sentiment/config.yaml
potato label certificate examples/labeling-engine/text-certified-sentiment/config.yaml --format md

Um die Engine in Ihre eigene Studie einzubauen, ergänzen Sie diese Schlüssel in einer Konfiguration, die bereits data_files und ein Annotationsschema namens sentiment hat. Der Vertrag verlangt, dass höchstens 10 % der akzeptierten Maschinenlabels falsch sind, bei 90 % Konfidenz, und budgets.human_labels begrenzt, wie viele Anfragen an Menschen die Engine öffnen darf:

assignment_strategy: engine
 
labeling_engine:
  enabled: true
  sources:
    - id: gemma
      kind: llm
      endpoint_type: vllm
      model: google/gemma-4-12B-it-qat-w4a16-ct
      base_url: http://localhost:8001/v1
      confidence: {method: logprob}
  contracts:
    - id: accuracy
      kind: selective_risk
      schema: sentiment
      error: 0.1
      confidence: 0.9
  budgets:
    human_labels: 400

Die Quelle gibt ihre Konfidenz aus den Log-Wahrscheinlichkeiten der Tokens an (method: logprob). Das kostet einen Aufruf pro Item und ist unter den Konfidenzmethoden meist am besten kalibriert. Konfiguration listet jeden Schlüssel auf, und Verträge erklärt, was jeder Vertrag testet.

Anfragen auf der Annotationsseite

Mit assignment_strategy: engine erhalten Annotierende die Anfragen der Engine, die mit der höchsten Priorität zuerst. Die Reihenfolge ist Adjudikation, Zertifizierung, Kalibrierung, zusätzliche Bewertende für distributionelle Verträge, Items, die keine Maschine labeln konnte, Verifikation und Audits. Kalibrierungsanfragen werden in einer festen Zufallsreihenfolge ausgeliefert, dev- und cert-Anfragen abwechselnd. Eine Person erhält alle offenen Anfragen zu einem Item auf einmal, eine pro Schema, und nie zwei Anfragen für dasselbe Schema auf demselben Item.

Ein kurzer Hinweis über dem Item sagt, um welche Art von Anfrage es sich handelt, und auf einer Seite mit mehreren Fragen nennt er die Frage:

• Verblindet. Der Hinweis lautet „Label this one yourself. Suggestions are off for this item.“ Das Item bleibt für diese Person verblindet, auch nachdem sie es gespeichert hat, beim Neuladen und beim Zurückgehen.
• Prüfen. Die Antwort der Maschine ist eingetragen, und der Hinweis sagt, sie zu behalten, wenn sie stimmt, und sie zu ändern, wenn nicht. Die Seite speichert die vorausgefüllte Antwort, sodass Sie messen können, wie oft Menschen sie übernehmen. Gespeichert wird erst, wenn die Person handelt, sodass eine offen gelassene Seite nicht für sie antwortet. Schemata, deren Antworten die Seite nicht vorausfüllen kann (Zeitsegmente, 3D-Objekte, Agenten-Traces), werden stattdessen verblindet ausgeliefert.
• Entscheiden. Kein Maschinenlabel konnte akzeptiert werden, also ist die Antwort der Person das Label.

Eine Anfrage, die jemand runtime.hold_minutes lang (standardmäßig 60) hält, ohne zu antworten, geht zurück in den Pool und verschwindet von der Seite dieser Person. Ein Label, das auf einem Item gespeichert wird, das die Engine dieser Person nicht ausgeliefert hat, schließt nie die Anfrage einer anderen Person, und die Engine behält es als organisches Label. Wenn eine neue Zertifizierung Maschinenlabels akzeptiert, storniert die Engine offene Prüf- und Entscheidungsanfragen für die Items, die sie jetzt abdeckt. Anfragen, die eine Person bereits hält, bleiben bei ihr, und ihre Antwort ersetzt das Maschinenlabel.

Der Fortschrittszähler zählt die Anfragen, die eine Person noch übernehmen kann, nicht das Korpus. Wenn es noch nichts zu tun gibt, sieht die annotierende Person eine kurze Warteseite und erhält neue Anfragen, sobald der Planer sie öffnet. Wenn nichts mehr kommen wird, weil jedes Item ein Label hat, das Budget für menschliche Labels aufgebraucht ist oder die eigene Obergrenze der Person erreicht ist, endet ihr Teil wie gewohnt mit den Seiten nach der Studie und, auf einer Crowd-Plattform, mit dem Abschlusscode. Vor dem ersten Durchlauf des Planers ist niemand fertig.

Der Pocket-Modus liefert ebenfalls Anfragen der Engine aus, jeweils einen vollen Batch, und fordert weitere an, bevor er „All caught up“ anzeigt. Der Pocket-Modus zeigt nie eine Maschinenantwort, daher wird eine dort ausgelieferte Prüfanfrage als verblindet gespeichert, es sei denn, die Desktop-Seite hatte dieser Person die Antwort bereits gezeigt. Auf Karten zum Entscheiden und Adjudizieren zeigt er denselben Hinweis wie die Desktop-Seite.

Die Admin-Seite

Wenn die Engine aktiv ist, verlinkt das Admin-Dashboard auf Labeling engine unter /admin/labeling-engine. Jedes Diagramm auf der Seite hat auch eine Tabellenansicht. Die Seite zeigt:

• Status, Abdeckung, Look-Nummer jedes Vertrags und wie viele Labels er noch braucht, mit der vollständigen Aussage, die er trifft (ein nicht erfüllter Vertrag nennt sein Ziel, keine Garantie);
• die Intervalle jedes ppi-Vertrags neben den Intervallen, die sich allein aus den Menschen ergeben;
• eine Warnung für eine Quelle, deren letzter Lauf fehlgeschlagen ist oder deren Antworten allesamt Fehler waren;
• die Kurve aus Fehler und Abdeckung für die letzte Stufe der Kaskade, mit der garantierten oberen Schranke und dem Ziel;
• ein Zuverlässigkeitsdiagramm pro Stufe, das die angegebene Konfidenz gegen den Anteil richtiger Antworten auf menschlichen Labels aufträgt, mit ECE und Brier-Score, wobei Bins mit wenigen Labels blasser gezeichnet sind;
• die Audits der akzeptierten Labels als Fehler gegenüber dem Ziel und ob es zu wenige Audits für eine Aussage gibt;
• die Anfragen an Menschen nach Zweck und Status;
• das Protokoll der Modellaufrufe, die neuesten zuerst, mit Tokens, Latenz und Kosten; und
• Schaltflächen, um einen Durchlauf des Planers zu starten, sofort zu zertifizieren und das Zertifikat zu öffnen.

Ohne Admin-Sitzung geöffnet, leitet die Seite zum Schlüsselformular des Dashboards weiter. Ist die Engine aus, sagt die Seite das und nennt den Schlüssel, der sie einschaltet.

Weiterführende Lektüre

• Verträge der Labeling-Engine: die sechs Vertragsarten und was jede testet
• Konfiguration der Labeling-Engine: jeder Schlüssel in labeling_engine
• Kommandozeile, REST API, MCP-Tools und SDK
• Migration zur Labeling-Engine von icl_labeling, judge_calibration und pre_annotation
• Solo Mode, wenn eine einzelne Fachperson mit einem LLM arbeitet
• Vorannotation mit LLMs und Übereinstimmung zwischen LLM-Judge und Menschen

Implementierungsdetails stehen in der Quelldokumentation.