El motor de etiquetado

Etiqueta un conjunto de datos con modelos, pon a prueba las etiquetas de máquina frente a una muestra aleatoria y ciega de etiquetas humanas, y publica el conjunto de datos con un certificado de lo que se probó.

El motor de etiquetado etiqueta un conjunto de datos con modelos y recurre a personas para medir con qué frecuencia se equivocan los modelos. Declaras qué deben cumplir las etiquetas finales en un contrato, por ejemplo «como mucho el 5% de las etiquetas de máquina aceptadas son incorrectas, con un 90% de confianza». El motor pide a las personas las etiquetas que necesita para poner a prueba esa afirmación, acepta las etiquetas de máquina que la prueba respalda y envía los ítems restantes a personas. El resultado es el conjunto de datos más un certificado que registra qué se probó y con cuántas etiquetas humanas.

El motor está disponible desde Potato 2.11. El servidor de anotación, la línea de comandos potato label, la REST API, el servidor MCP y un Python SDK lo manejan todos sobre el mismo archivo engine.sqlite del directorio de la tarea.

Cuándo encaja el motor en un estudio

El motor compensa cuando las personas no pueden etiquetarlo todo y un modelo puede etiquetar la mayor parte. Si las personas van a etiquetar todos los ítems de todos modos, el motor no aporta nada, y una estrategia de asignación normal es mejor opción. Encajan tres situaciones:

Tienes más ítems de los que pueden etiquetar las personas, y un modelo que acierta la mayoría de las veces.
Necesitas informar de lo buenas que son las etiquetas, no solo de que las hizo un modelo, para un artículo, la publicación de un conjunto de datos o un conjunto de entrenamiento que usará otra persona.
Estás evaluando un modelo o un agente con un juez LLM y necesitas saber si el juez puede sustituir a las personas.

De la predicción del modelo a la etiqueta final

El motor guarda las predicciones de máquina, las peticiones a personas y los resultados de los contratos en un mismo almacén, y cada ítem pasa por los mismos seis pasos:

Las fuentes son los modelos. Una fuente puede ser un LLM, un modelo de visión y lenguaje, un modelo de decisión (Laya, Jev u OpenJev), un detector de objetos, un juez LLM, un modelo entrenado con las propias etiquetas del estudio, un jurado de otras fuentes o etiquetas que ya tengas. Cada fuente registra una confianza con cada predicción.
La cascada ordena las fuentes. Un ítem va a la primera fuente y, si el contrato no acepta esa respuesta, lo intenta la siguiente. Después de la última fuente, el ítem va a una persona.
Las peticiones son lo que el motor pide hacer a las personas. Cada petición registra por qué se hizo (por ejemplo, calibración, certificación, verificación o auditoría), la probabilidad de que su ítem saliera en la muestra y si la persona podía ver una respuesta de máquina. Las peticiones de calibración se extraen al azar y siempre son ciegas.
Los contratos ponen a prueba las etiquetas de máquina frente a las etiquetas humanas de la muestra aleatoria. La mitad de esa muestra (la partición dev) elige la regla de aceptación, y la otra mitad (la partición cert) la pone a prueba. El estado de un contrato es met, insufficient (hacen falta más etiquetas, con una estimación de cuántas), infeasible, violated o stale.
La resolución da a cada ítem su etiqueta final. La etiqueta es una etiqueta de máquina aceptada bajo un contrato cumplido, la etiqueta de una persona o queda pendiente.
El certificado registra el resultado de cada contrato, la cascada con las versiones de modelos y prompts, cuántas etiquetas humanas se dedicaron a cada propósito, el gasto en modelos y un resumen criptográfico del registro de llamadas.

Las reglas detrás de las garantías

Un contrato cumplido es una afirmación estadística sobre la muestra aleatoria que etiquetaron las personas, y se sostiene por cómo se extrae y se usa esa muestra. El motor impone cinco reglas:

Las peticiones ciegas no muestran ninguna respuesta de máquina. Mientras una persona tiene asignada una petición de calibración, certificación o auditoría, el servidor retiene todas las respuestas de máquina de ese ítem. Las preanotaciones, el juez en línea, el asistente de IA (que responde 403) y los botones de ayuda de IA quedan todos desactivados. Una etiqueta dada después de ver la respuesta de la máquina no es una comprobación independiente de esa respuesta.
La selección y la prueba usan etiquetas distintas. Los umbrales se eligen con las etiquetas dev y se prueban con las etiquetas cert. Cada nueva prueba sobre las etiquetas cert se hace con un nivel más estricto, así que volver a certificar hasta que una prueba se supere no infla la confianza.
Solo las personas certifican. Los anotadores de máquina pueden intervenir en la inferencia de la etiqueta final, nunca en las etiquetas con las que se pone a prueba un contrato.
Un cambio deja obsoleto el certificado. Cambiar una fuente, un prompt, un umbral o el esquema marca como stale cada contrato afectado y pasa sus etiquetas aceptadas a pending_recert hasta que el contrato se vuelve a probar. Las etiquetas humanas se conservan.
Las predicciones de máquina no ocupan plazas de anotador. Las predicciones del motor no cuentan para los topes de anotadores por ítem.

El motor no comprueba que las etiquetas humanas sean correctas. Cada contrato mide las máquinas frente a las personas que etiquetaron la muestra, así que un contrato probado con personas poco fiables certifica el acuerdo con personas poco fiables. Usa el control de calidad, el solapamiento (humans.overlap) y el contrato no_worse_than_human para comprobar también a las personas.

Un primer estudio

Potato incluye tres estudios de ejemplo en examples/labeling-engine/, uno para texto, otro para imágenes y otro para trazas de agentes. La tabla indica las fuentes y los contratos que usa cada uno:

Ejemplo	Fuentes	Contratos
`text-certified-sentiment/`	Laya (modelo de decisión), un LLM de Ollama	riesgo selectivo al 10%, prevalencia con PPI
`image-objects-and-people/`	detector YOLOv8n, un modelo de visión de Ollama	riesgo selectivo en cajas (IoU) y en una etiqueta de si hay una persona
`agent-trace-judge/`	un juez LLM con intercambio del orden de las etiquetas	riesgo selectivo, no peor que un humano, éxito de la tarea con PPI

El ejemplo de texto se ejecuta con cuatro comandos. El primero etiqueta todos los ítems con la cascada y extrae la primera muestra ciega, el segundo sirve esa muestra a las personas, y los dos últimos ponen a prueba los contratos e imprimen el certificado una vez que las personas han etiquetado la muestra:

bash

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

Para añadir el motor a tu propio estudio, añade estas claves a una configuración que ya tenga data_files y un esquema de anotación llamado sentiment. El contrato pide que como mucho el 10% de las etiquetas de máquina aceptadas sean incorrectas, con un 90% de confianza, y budgets.human_labels limita cuántas peticiones a personas puede abrir el motor:

yaml

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

La fuente obtiene su confianza de las log-probabilidades de los tokens (method: logprob), que requiere una llamada por ítem y suele ser el mejor calibrado de los métodos de confianza. Configuración enumera todas las claves, y Contratos explica qué prueba cada contrato.

Las peticiones en la página de anotación

Con assignment_strategy: engine, los anotadores reciben las peticiones del motor, primero las de mayor prioridad. El orden es adjudicación, certificación, calibración, evaluadores adicionales para contratos distribucionales, ítems que ninguna máquina pudo etiquetar, verificación y auditorías. Las peticiones de calibración se sirven en un orden aleatorio fijo, con las peticiones dev y cert intercaladas. Una persona recibe a la vez todas las peticiones abiertas de un ítem, una por esquema, y nunca dos peticiones del mismo esquema sobre el mismo ítem.

Una nota breve encima del ítem indica qué tipo de petición es y, en una página con varias preguntas, nombra la pregunta:

Ciega. La nota dice «Label this one yourself. Suggestions are off for this item.» El ítem sigue siendo ciego para esa persona después de guardarlo, al recargar y al volver atrás.
Verificación. La respuesta de la máquina aparece ya rellenada, y la nota dice que la mantengas si es correcta y la cambies si no lo es. La página registra la respuesta prerrellenada, así que puedes medir con qué frecuencia la aceptan las personas. No se guarda nada hasta que la persona actúa, así que una página que se queda abierta no responde por ella. Los esquemas cuyas respuestas la página no puede prerrellenar (segmentos temporales, objetos 3D, trazas de agentes) se sirven a ciegas.
Resolución. No se pudo aceptar ninguna etiqueta de máquina, así que la respuesta de la persona es la etiqueta.

Una petición que alguien tiene asignada sin responder durante runtime.hold_minutes (60 por defecto) vuelve a la reserva y desaparece de su página. Una etiqueta guardada en un ítem que el motor no sirvió a esa persona nunca cierra la petición de otra, y el motor la conserva como etiqueta orgánica. Cuando una nueva certificación acepta etiquetas de máquina, el motor cancela las peticiones abiertas de verificación y resolución de los ítems que ahora cubre. Las peticiones que una persona ya tiene asignadas se quedan con ella, y su respuesta sustituye a la etiqueta de máquina.

El contador de progreso cuenta las peticiones que una persona todavía puede tomar, no el corpus. Cuando todavía no hay nada que hacer, el anotador ve una breve página de espera y recibe nuevas peticiones a medida que el planificador las abre. Cuando ya no va a llegar nada más, porque todos los ítems tienen etiqueta, se ha agotado el presupuesto de etiquetas humanas o se ha alcanzado el tope propio de la persona, su parte termina como de costumbre con las páginas posteriores al estudio y, en una plataforma de crowdsourcing, el código de finalización. Nadie termina antes de la primera pasada del planificador.

Pocket Mode también sirve peticiones del motor, un lote completo cada vez, y pide más antes de mostrar «All caught up». Pocket Mode nunca muestra una respuesta de máquina, así que una petición de verificación servida allí se registra como ciega, salvo que la página de escritorio ya le hubiera mostrado la respuesta a esa persona. En las tarjetas de resolución y de adjudicación muestra la misma nota que la página de escritorio.

La página de administración

Cuando el motor está activado, el panel de administración enlaza a Labeling engine en /admin/labeling-engine. Cada gráfico de la página tiene también una vista de tabla. La página muestra:

el estado, la cobertura, el número de inspección de cada contrato y cuántas etiquetas más necesita, con la afirmación completa que hace (un contrato no cumplido indica su objetivo, no una garantía);
los intervalos de cada contrato ppi, junto a los intervalos obtenidos solo con personas;
un aviso para una fuente cuya última ejecución falló o cuyas respuestas fueron todas errores;
la curva de error frente a cobertura del último nivel de la cascada, con la cota superior garantizada y el objetivo;
un diagrama de fiabilidad por nivel, que representa la confianza declarada frente a la proporción de aciertos en etiquetas humanas, con ECE y puntuación de Brier, y con los intervalos con pocas etiquetas dibujados más claros;
las auditorías de las etiquetas aceptadas, como errores frente al objetivo, e indicación de si hay demasiado pocas auditorías para saberlo;
las peticiones a personas por propósito y estado;
el registro de llamadas a modelos, con las más recientes primero, con tokens, latencia y coste; y
botones para ejecutar una pasada del planificador, certificar en ese momento y abrir el certificado.

Si se abre sin una sesión de administración, la página lleva al formulario de clave del panel. Con el motor desactivado, lo indica y nombra la clave que lo activa.

Lecturas adicionales

Contratos del motor de etiquetado: los seis tipos de contrato y qué prueba cada uno
Configuración del motor de etiquetado: todas las claves de labeling_engine
Línea de comandos, REST API, herramientas MCP y SDK
Migrar al motor de etiquetado desde icl_labeling, judge_calibration y pre_annotation
Solo Mode, para un experto que trabaja con un LLM
Preanotación con LLM y acuerdo entre jueces LLM y personas

Para los detalles de implementación, consulta la documentación del código fuente.