CLI, REST API, herramientas MCP y SDK del motor de etiquetado
Maneja el motor de etiquetado desde potato label, las rutas REST de /api/engine/v1, cinco herramientas MCP del motor o la clase Study de Python, todo sobre un único archivo engine.sqlite.
El servidor de anotación, la línea de comandos, la REST API, las herramientas MCP y el Python SDK manejan todos el mismo motor de etiquetado sobre el mismo archivo engine.sqlite del directorio de la tarea. Puedes iniciar un estudio desde la línea de comandos, servir las peticiones a personas con el servidor y certificar desde un notebook.
Solo un proceso maneja un estudio a la vez. El planificador de un servidor en marcha tiene el bloqueo de escritura del estudio y, mientras lo tiene, potato label run, potato label certify y Study.run() se niegan a ejecutarse y lo indican. En ese caso, certifica a través del servidor, con POST /api/engine/v1/certify o con la página de administración. El bloqueo existe porque dos procesos extraerían dos muestras de calibración y certificarían cada uno con las etiquetas del otro. El bloqueo se libera cuando su titular termina. Si el titular muere en la misma máquina, el bloqueo se toma de inmediato, y si muere en otra máquina, tras dos minutos sin señal de vida. Los comandos de solo lectura (status, certificate, calls, export) funcionan en cualquier momento.
Línea de comandos
Todos los comandos del motor reciben el archivo de configuración del estudio:
potato label <command> <config.yaml> [options]Los nueve comandos cubren un estudio desde la primera llamada a un modelo hasta el conjunto de datos exportado:
| Comando | Qué hace |
|---|---|
run | Etiqueta todos los ítems con la cascada, extrae la muestra ciega de calibración, certifica y resuelve. --until predicted (el valor por defecto) se detiene tras una pasada, y --until met continúa hasta que todos los contratos se cumplen o el motor queda esperando a las personas. También admite --max-items N, --budget-usd X (sustituye a budgets.model_usd en esta ejecución), --max-ticks N (20 por defecto) y --json. Una ejecución interrumpida se reanuda donde se detuvo sin repetir llamadas a modelos. Termina con estado 1, nombrando la fuente, cuando la última ejecución de una fuente falló o todas sus respuestas fueron errores, o cuando ninguna fuente puede etiquetar un esquema que nombra un contrato. |
status | Ítems, predicciones, peticiones por propósito, contratos, gasto, ítems todavía sin etiqueta y una línea por cada fuente con errores o con una ejecución fallida o en pausa. --json. |
certify | Pone a prueba todos los contratos con las nuevas etiquetas cert y las nuevas predicciones. Cuando solo cambiaron las etiquetas dev, vuelve el resultado guardado con una nota, y --retest pone a prueba la regla que elige ahora dev, en la siguiente inspección (consulta Inspecciones). --json. |
certificate | El certificado de calidad. --format md (el valor por defecto), html o json, y --out FILE. |
export | Etiquetas con su procedencia, el certificado (JSON, Markdown, HTML), una ficha del conjunto de datos y el registro de llamadas, en --out DIR (<output_annotation_dir>/labeling_engine por defecto). |
calls | El registro de auditoría de llamadas a modelos en líneas JSON. --out FILE. |
distill | Entrena un modelo con las etiquetas que hay hasta el momento y lo pone el primero en la cascada. |
optimize | Puntúa todos los subconjuntos de la cascada con las etiquetas dev e informa del más barato que mantiene la cobertura. Cuando ningún subconjunto mantiene cobertura alguna, no recomienda ninguno. --prompts N también pide a un nivel LLM N paráfrasis de su prompt y puntúa cada una en los ítems dev. Son llamadas a modelos, registradas y descontadas del presupuesto, y se guardan bajo sus propias versiones de fuente, mientras que el prompt actual se puntúa a partir de sus predicciones guardadas. La cascada y el certificado no cambian. |
migrate-config | Escribe una copia de la configuración con un bloque labeling_engine equivalente a sus claves de IA antiguas. --out FILE. Consulta Migrar al motor de etiquetado. |
Consultar el progreso no gasta nada, porque status, certificate y la página de administración leen resultados guardados. Cada prueba nueva, ya venga de certify con etiquetas nuevas o de certify --retest, gasta parte del presupuesto de error de un contrato.
Archivos que escribe la exportación
potato label export escribe cuatro tipos de archivo en el directorio de salida:
| Archivo | Contenido |
|---|---|
labels.jsonl, labels.csv | Una fila por ítem y esquema, con etiqueta o sin ella, con id, schema, label, label_origin (auto, human, adjudicated, ...), status (accepted, accepted_uncertified con threshold_legacy, pending, pending_recert), source, model, source_version, confidence, contract_version y request_ids. Una etiqueta de máquina cuya fuente ha cambiado desde que se aceptó figura como pending_recert hasta que la siguiente pasada la vuelve a certificar. |
certificate.json, .md, .html | El certificado. |
README.md | Una ficha del conjunto de datos con front matter de Hugging Face, generada a partir del certificado. |
model_calls.jsonl | Todas las llamadas a modelos, con el modelo, hashes del prompt y de la respuesta, tokens, latencia, coste, aciertos de caché y categorías enmascaradas. |
Los exportadores normales (python -m potato.export y la exportación de administración) exportan las anotaciones de las personas, y la página de formatos de exportación los enumera. Entre ellos, el formato labeling_engine escribe los mismos archivos que potato label export, y se niega a ejecutarse cuando el motor no está activado. Cuando el motor está activado, las exportaciones CSV, Parquet y Hugging Face añaden dos columnas que indican a qué petición del motor respondió cada anotación. engine_purpose contiene el propósito, por ejemplo calibration, y engine_request contiene un JSON con el propósito, la probabilidad de inclusión, la visibilidad, la partición y el id de la petición. Usa estas columnas para separar la muestra aleatoria ciega de las respuestas de verificación.
REST API
Todas las rutas del motor están bajo /api/engine/v1 y devuelven JSON. Autentícate con la clave de administración en la cabecera X-API-Key o con una sesión de administración. Las lecturas necesitan el permiso del panel de administración, certify y plan necesitan el de gestión de asignaciones, y el certificado necesita el permiso de exportación.
| Método y ruta | Devuelve |
|---|---|
GET /status | Ítems, predicciones, peticiones, totales de llamadas, presupuestos y, para cada esquema, su cascada, sus contratos y sus recuentos de etiquetas resueltas |
GET /schemes/<name>/contracts | El último resultado de cada contrato del esquema, marcado como stale si cambió la cascada |
GET /schemes/<name>/risk_coverage | Para cada umbral del último nivel, la proporción aceptada, el error observado y la cota superior garantizada, sobre las etiquetas cert |
GET /schemes/<name>/reliability | Intervalos de fiabilidad, ECE y puntuación de Brier por nivel, sobre las etiquetas de calibración |
GET /schemes/<name>/drift | El monitor de auditorías por contrato de riesgo selectivo |
GET /schemes/<name>/optimize | El informe de cascada más barata, puntuado con las etiquetas dev |
GET /requests | Recuentos de peticiones por propósito y estado, y las propias peticiones. Los filtros son purpose, status (repite el parámetro o separa los valores con comas), schema y limit (máximo 1000) |
GET /calls | El registro de llamadas, con las más recientes primero, y los totales por fuente. limit (máximo 500), offset |
GET /certificate | El certificado. format=json (el valor por defecto), md o html, y save=1 además lo guarda |
GET /crowd | El último plan de crowdsourcing del planificador, una simulación salvo que el gasto real esté activado |
POST /certify | Pone a prueba todos los contratos en ese momento. ?retest=1 (o {"retest": true}) también pone a prueba una regla en la que solo cambiaron las etiquetas dev |
POST /plan | Ejecuta una pasada del planificador en ese momento |
Las rutas responden 404 cuando el motor está desactivado en el estudio. Responden 400 con un error JSON ante un parámetro no válido, como un limit que no es un número, un purpose o un status desconocidos, o un format distinto de json, md o html.
Por ejemplo, esta petición obtiene el certificado actual en Markdown de un servidor en el puerto 8000:
curl -H "X-API-Key: $ADMIN_API_KEY" \
"http://localhost:8000/api/engine/v1/certificate?format=md"Herramientas MCP
El servidor MCP expone cinco herramientas del motor, con los mismos permisos que las rutas REST:
engine_statusengine_requestsengine_run, que ejecuta una pasada del planificadorengine_certify, que admiteretestengine_certificate, enjson,mdohtml
Conceder estas herramientas con el motor desactivado genera un aviso de validación. A través de potato mcp connect, una llamada rechazada (por falta de permiso o por un parámetro incorrecto) vuelve como error de herramienta con el mensaje del servidor. La documentación del servidor MCP explica cómo conceder herramientas y conectar un cliente.
Python SDK
La clase Study maneja el motor desde Python, por ejemplo en 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/")Cada método equivale a un comando o a una ruta:
| Método | Qué hace |
|---|---|
Study(config_path) | Carga la configuración y los ítems |
run(until="predicted", max_ticks=20) | Como potato label run, y toma el bloqueo de escritura |
label(item_id, scheme, value, user, request_id=None) | Registra la etiqueta de una persona. Cierra request_id o, si no, una petición que esa persona tiene asignada en el ítem, y si no hay ninguna se conserva como etiqueta orgánica, que nunca certifica. Una segunda etiqueta de la misma persona en el mismo ítem actualiza la primera |
status() | Como GET /status |
requests(status=None, purpose=None, ...) | El registro de peticiones |
certify(retest=False) | Como potato label certify |
certificate(fmt="json") | json, md o html |
export(out_dir) | Como potato label export |
El ejemplo etiqueta como "positive" todas las peticiones abiertas solo para mostrar las llamadas. Una etiqueta registrada con Study.label que no responde a ninguna petición se conserva como etiqueta orgánica, y las etiquetas orgánicas nunca certifican, así que un script que etiqueta ítems que el motor no pidió añade etiquetas que ningún contrato lee.
Lecturas adicionales
- El motor de etiquetado
- Configuración del motor de etiquetado
- Contratos del motor de etiquetado
- Panel de administración, que enlaza a la página de administración del motor
Para los detalles de implementación, consulta la documentación del código fuente.