CLI, REST API, strumenti MCP e SDK del motore di etichettatura

Il server di annotazione, la riga di comando, la REST API, gli strumenti MCP e il Python SDK pilotano tutti lo stesso motore di etichettatura sullo stesso file engine.sqlite nella directory del task. Puoi avviare uno studio dalla riga di comando, servire le richieste umane con il server e certificare da un notebook.

Un solo processo alla volta pilota uno studio. Il planner di un server in esecuzione detiene il lock di scrittura dello studio e, finché lo detiene, potato label run, potato label certify e Study.run() si rifiutano di procedere e lo dicono. In quel caso certifica tramite il server, con POST /api/engine/v1/certify o dalla pagina di amministrazione. Il lock esiste perché due processi estrarrebbero due campioni di calibrazione e certificherebbero ciascuno sulle etichette dell'altro. Il lock viene rilasciato quando il processo che lo detiene termina. Se quel processo viene ucciso sulla stessa macchina, il lock viene ripreso subito; se viene ucciso su un'altra macchina, dopo due minuti senza heartbeat. I comandi di sola lettura (status, certificate, calls, export) funzionano in qualsiasi momento.

Riga di comando

Ogni comando del motore accetta il file di configurazione dello studio:

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

I nove comandi coprono uno studio dalla prima chiamata a un modello fino al dataset esportato:

Controllare l'avanzamento non consuma nulla, perché status, certificate e la pagina di amministrazione leggono risultati memorizzati. Ogni nuovo test, che venga da certify su nuove etichette o da certify --retest, consuma una parte del budget di errore di un contratto.

File scritti dall'export

potato label export scrive quattro tipi di file nella directory di output:

Gli exporter normali (python -m potato.export e l'export dell'amministrazione) esportano le annotazioni delle persone, e la pagina dei formati di export li elenca. Tra questi, il formato labeling_engine scrive gli stessi file di potato label export, e si rifiuta di funzionare quando il motore non è attivo. Quando il motore è attivo, gli export CSV, Parquet e Hugging Face aggiungono due colonne che indicano a quale richiesta del motore ha risposto ogni annotazione. engine_purpose contiene lo scopo, per esempio calibration, e engine_request contiene un JSON con scopo, probabilità di inclusione, visibilità, partizione e id della richiesta. Usa queste colonne per separare il campione casuale in cieco dalle risposte di verifica.

REST API

Tutte le route del motore stanno sotto /api/engine/v1 e restituiscono JSON. Autenticati con la chiave di amministrazione nell'header X-API-Key o con una sessione di amministrazione. Le letture richiedono il permesso per la dashboard di amministrazione, certify e plan richiedono la gestione delle assegnazioni, e il certificato richiede il permesso di export.

Le route rispondono 404 quando il motore è disattivato per lo studio. Rispondono 400 con un errore JSON per un parametro non valido, come un limit che non è un numero, un purpose o uno status sconosciuto, o un format diverso da json, md o html.

Per esempio, questa richiesta recupera il certificato attuale in Markdown da un server sulla porta 8000:

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

Strumenti MCP

Il server MCP espone cinque strumenti del motore, con gli stessi permessi delle route REST:

• engine_status
• engine_requests
• engine_run, che esegue un passaggio del planner
• engine_certify, che accetta retest
• engine_certificate, in json, md o html

Concedere questi strumenti mentre il motore è disattivato produce un avviso di validazione. Tramite potato mcp connect, una chiamata rifiutata (un permesso mancante, un parametro errato) torna come errore dello strumento con il messaggio del server. La documentazione del server MCP spiega come concedere gli strumenti e collegare un client.

Python SDK

La classe Study pilota il motore da Python, per esempio in 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/")

Ogni metodo corrisponde a un comando o a una route:

L'esempio etichetta ogni richiesta aperta come "positive" solo per mostrare le chiamate. Un'etichetta registrata con Study.label che non risponde a nessuna richiesta viene conservata come etichetta organica, e le etichette organiche non certificano mai, quindi uno script che etichetta item che il motore non ha richiesto aggiunge etichette che nessun contratto legge.

Approfondimenti

• Il motore di etichettatura
• Configurazione del motore di etichettatura
• Contratti del motore di etichettatura
• Dashboard di amministrazione, che ha un link alla pagina di amministrazione del motore

Per i dettagli di implementazione, consulta la documentazione sorgente.