CLI, REST API, outils MCP et SDK du moteur d'étiquetage

Le serveur d'annotation, la ligne de commande, la REST API, les outils MCP et le Python SDK pilotent tous le même moteur d'étiquetage à travers le même fichier engine.sqlite, dans le répertoire de la tâche. Vous pouvez lancer une étude en ligne de commande, servir les demandes humaines avec le serveur et certifier depuis un notebook.

Un seul processus pilote une étude à la fois. Le planificateur d'un serveur en cours d'exécution détient le verrou d'écriture de l'étude, et tant qu'il le détient, potato label run, potato label certify et Study.run() refusent de s'exécuter et le disent. Certifiez alors par le serveur, avec POST /api/engine/v1/certify ou la page d'administration. Le verrou existe parce que deux pilotes tireraient deux échantillons de calibration et certifieraient chacun sur les étiquettes de l'autre. Le verrou est libéré quand son détenteur se termine. Un détenteur tué sur la même machine est remplacé immédiatement, et un détenteur sur une autre machine au bout de deux minutes sans signal de vie. Les commandes en lecture seule (status, certificate, calls, export) fonctionnent à tout moment.

Ligne de commande

Chaque commande du moteur prend le fichier de configuration de l'étude :

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

Les neuf commandes couvrent une étude du premier appel de modèle jusqu'au jeu de données exporté :

Suivre l'avancement ne dépense rien, car status, certificate et la page d'administration lisent des résultats enregistrés. Chaque nouveau test, qu'il vienne de certify sur de nouvelles étiquettes ou de certify --retest, consomme une partie du budget d'erreur d'un contrat.

Fichiers écrits par l'export

potato label export écrit quatre sortes de fichiers dans le répertoire de sortie :

Les exporteurs habituels (python -m potato.export et l'export de l'administration) exportent les annotations des personnes, et la page Formats d'export les liste. Parmi eux, le format labeling_engine écrit les mêmes fichiers que potato label export, et il refuse de s'exécuter quand le moteur n'est pas activé. Quand le moteur est activé, les exports CSV, Parquet et Hugging Face ajoutent deux colonnes qui indiquent à quelle demande du moteur chaque annotation a répondu. engine_purpose contient le motif, par exemple calibration, et engine_request contient un JSON avec le motif, la probabilité d'inclusion, la visibilité, la partition et l'identifiant de la demande. Utilisez ces colonnes pour séparer l'échantillon aléatoire en aveugle des réponses de vérification.

REST API

Toutes les routes du moteur se trouvent sous /api/engine/v1 et renvoient du JSON. Authentifiez-vous avec la clé d'administration dans l'en-tête X-API-Key ou avec une session d'administration. Les lectures exigent la permission du tableau de bord d'administration, certify et plan exigent la gestion de l'attribution, et le certificat exige la permission d'export.

Les routes répondent 404 quand le moteur est désactivé pour l'étude. Elles répondent 400 avec une erreur JSON pour un paramètre invalide, comme un limit qui n'est pas un nombre, un purpose ou un status inconnu, ou un format autre que json, md ou html.

Par exemple, cette requête récupère le certificat actuel en Markdown depuis un serveur sur le port 8000 :

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

Outils MCP

Le serveur MCP expose cinq outils du moteur, avec les mêmes permissions que les routes REST :

• engine_status
• engine_requests
• engine_run, qui lance un passage du planificateur
• engine_certify, qui accepte retest
• engine_certificate, en json, md ou html

Accorder ces outils alors que le moteur est désactivé provoque un avertissement de validation. Via potato mcp connect, un appel refusé (permission manquante, paramètre invalide) revient comme une erreur d'outil qui porte le message du serveur. La documentation du serveur MCP explique comment accorder des outils et connecter un client.

Python SDK

La classe Study pilote le moteur depuis Python, par exemple dans un 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/")

Chaque méthode correspond à une commande ou à une route :

L'exemple attribue « positive » à chaque demande ouverte uniquement pour montrer les appels. Une étiquette enregistrée par Study.label qui ne répond à aucune demande est conservée comme étiquette organique, et les étiquettes organiques ne certifient jamais, donc un script qui étiquette des items que le moteur n'a pas demandés ajoute des étiquettes qu'aucun contrat ne lit.

Pour aller plus loin

• Le moteur d'étiquetage
• Configuration du moteur d'étiquetage
• Contrats du moteur d'étiquetage
• Tableau de bord d'administration, qui renvoie vers la page d'administration du moteur

Pour les détails d'implémentation, consultez la documentation source.