CLI, REST API, MCP-Tools und SDK der Labeling-Engine

Der Annotationsserver, die Kommandozeile, die REST API, die MCP-Tools und das Python SDK steuern alle dieselbe Labeling-Engine über dieselbe Datei engine.sqlite im Aufgabenverzeichnis. Sie können eine Studie auf der Kommandozeile starten, die Anfragen an Menschen mit dem Server ausliefern und aus einem Notebook heraus zertifizieren.

Eine Studie wird immer nur von einem Prozess gesteuert. Der Planer eines laufenden Servers hält die Schreibsperre der Studie, und solange er sie hält, verweigern potato label run, potato label certify und Study.run() den Dienst und sagen das. Zertifizieren Sie dann über den Server, mit POST /api/engine/v1/certify oder über die Admin-Seite. Die Sperre gibt es, weil zwei steuernde Prozesse zwei Kalibrierungsstichproben ziehen und gegen die Labels des jeweils anderen zertifizieren würden. Die Sperre wird freigegeben, wenn ihr Halter endet. Ein abgebrochener Halter auf demselben Rechner wird sofort abgelöst, einer auf einem anderen Rechner nach zwei Minuten ohne Heartbeat. Lesende Befehle (status, certificate, calls, export) funktionieren jederzeit.

Kommandozeile

Jeder Befehl der Engine nimmt die Konfigurationsdatei der Studie:

potato label <command> <config.yaml> [options]

Die neun Befehle decken eine Studie vom ersten Modellaufruf bis zum exportierten Datensatz ab:

Den Fortschritt zu prüfen, kostet nichts, denn status, certificate und die Admin-Seite lesen gespeicherte Ergebnisse. Jeder neue Test, ob von certify auf neuen Labels oder von certify --retest, verbraucht einen Teil des Fehlerbudgets eines Vertrags.

Vom Export geschriebene Dateien

potato label export schreibt vier Arten von Dateien in das Ausgabeverzeichnis:

Die regulären Exporter (python -m potato.export und der Admin-Export) exportieren die Annotationen der Menschen, und die Seite Exportformate führt sie auf. Unter ihnen schreibt das Format labeling_engine dieselben Dateien wie potato label export und läuft nicht, wenn die Engine nicht aktiviert ist. Ist die Engine aktiv, fügen die Exporte nach CSV, Parquet und Hugging Face zwei Spalten hinzu, die angeben, auf welche Anfrage der Engine eine Annotation geantwortet hat. engine_purpose enthält den Zweck, zum Beispiel calibration, und engine_request enthält JSON mit Zweck, Einschlusswahrscheinlichkeit, Sichtbarkeit, Split und Anfrage-ID. Mit diesen Spalten trennen Sie die verblindete Zufallsstichprobe von den Antworten auf Prüfanfragen.

REST API

Alle Routen der Engine liegen unter /api/engine/v1 und geben JSON zurück. Authentifizieren Sie sich mit dem Admin-Schlüssel im Header X-API-Key oder mit einer Admin-Sitzung. Lesezugriffe brauchen die Berechtigung für das Admin-Dashboard, certify und plan brauchen die Verwaltung von Zuweisungen, und das Zertifikat braucht die Exportberechtigung.

Die Routen antworten mit 404, wenn die Engine für die Studie aus ist. Mit 400 und einem JSON-Fehler antworten sie auf einen ungültigen Parameter, etwa ein limit, das keine Zahl ist, einen unbekannten purpose oder status oder ein anderes format als json, md oder html.

Diese Anfrage holt zum Beispiel das aktuelle Zertifikat als Markdown von einem Server auf Port 8000:

curl -H "X-API-Key: $ADMIN_API_KEY" \
  "http://localhost:8000/api/engine/v1/certificate?format=md"

MCP-Tools

Der MCP-Server stellt fünf Tools der Engine bereit, mit denselben Berechtigungen wie die REST-Routen:

• engine_status
• engine_requests
• engine_run, das einen Durchlauf des Planers ausführt
• engine_certify, das retest nimmt
• engine_certificate, als json, md oder html

Diese Tools freizugeben, während die Engine aus ist, ergibt eine Validierungswarnung. Über potato mcp connect kommt ein abgelehnter Aufruf (eine fehlende Berechtigung, ein fehlerhafter Parameter) als Tool-Fehler zurück, der die Meldung des Servers enthält. Wie Sie Tools freigeben und einen Client verbinden, beschreibt die Dokumentation des MCP-Servers.

Python SDK

Die Klasse Study steuert die Engine aus Python, zum Beispiel in einem Notebook:

from potato.labeling_engine.sdk import Study
 
study = Study("examples/labeling-engine/text-certified-sentiment/config.yaml")
study.run()                                   # label, sample, certify, resolve
for req in study.requests(status="open")[:5]:
    study.label(req.item_id, req.schema, "positive", user="me")
study.certify()
print(study.certificate(fmt="md"))
study.export("out/")

Jede Methode entspricht einem Befehl oder einer Route:

Das Beispiel labelt jede offene Anfrage nur deshalb mit „positive“, um die Aufrufe zu zeigen. Ein über Study.label gespeichertes Label, das keine Anfrage beantwortet, wird als organisches Label behalten, und organische Labels zertifizieren nie. Ein Skript, das Items labelt, die die Engine nicht angefordert hat, fügt also Labels hinzu, die kein Vertrag liest.

Weiterführende Lektüre

• Die Labeling-Engine
• Konfiguration der Labeling-Engine
• Verträge der Labeling-Engine
• Admin-Dashboard, das auf die Admin-Seite der Engine verlinkt

Implementierungsdetails stehen in der Quelldokumentation.