Configuración del motor de etiquetado

Todo lo que hace el motor de etiquetado se configura en un único bloque labeling_engine. Un bloque no válido detiene el servidor al arrancar y enumera todos los problemas a la vez. Para que los anotadores reciban las peticiones del motor, define también assignment_strategy: engine. Definir esa estrategia sin un motor activado es un error de validación.

El bloque tiene estas secciones, cada una explicada más abajo:

assignment_strategy: engine
 
labeling_engine:
  enabled: true
  schemas: [sentiment]            # default: every scheme a source can label
  sources: []
  cascade: [laya, gemma]          # default: the first source alone
  contracts: []
  humans: {}
  crowd: {}
  budgets: {}
  runtime: {}
  features: {}
  redaction: {}
  distill: {}

Claves de primer nivel

Cinco claves van directamente bajo labeling_engine:

Fuentes

Una fuente es un modelo, o un conjunto de etiquetas que ya existe, que propone una etiqueta y una confianza para cada ítem. Cada fuente tiene un id único y un kind, y una clave desconocida en una fuente es un error:

Todo lo que puede cambiar una respuesta (modelo, prompt, temperatura, opciones) entra en el hash de versión de la fuente. Una versión nueva marca como stale todos los contratos que dependen de la fuente.

Una respuesta que no es un valor que el esquema pueda contener, como una etiqueta que no está en su lista, un campo numérico que no es un número o una lista en un esquema de una opción entre N, se registra como error y nunca como etiqueta, y el mensaje de la ejecución cuenta esos errores. Un ítem cuyas llamadas fallan se vuelve a pedir en ejecuciones posteriores, como mucho tres veces por versión de la fuente, y después espera a que cambie la fuente (una clave o un prompt corregidos son una versión nueva). Una ejecución en la que falla una fuente no detiene los demás niveles. El siguiente nivel etiqueta todos los ítems, y potato label run termina con estado 1 y nombra la fuente que falló.

Métodos de confianza

Las reglas de aceptación del motor aplican umbrales a la confianza de cada predicción, así que la forma en que una fuente expresa su confianza decide cuánto puede aceptar el motor. confidence.method admite uno de cinco valores:

Opciones específicas de cada tipo

Cinco tipos de fuente leen opciones propias:

• decision cubre Laya dentro del proceso, o cualquier servidor /v1/systemone, como Jev alojado u OpenJev. Una sola pasada hacia delante devuelve una probabilidad para cada opción, y funciona con esquemas radio, select, likert y slider. endpoint_type tiene que ser laya o systemone, y systemone necesita base_url, la raíz del servidor (también se acepta una URL que termine en /v1/systemone). En ambos casos el estado se envía como {"text": ...}, así que un mismo checkpoint da las mismas respuestas dentro del proceso y detrás de laya-serve, y options: {state_key: ""} envía la cadena sin más. En las escalas de valoración (likert, slider), las puntuaciones de Laya apenas siguen la escala, así que revisa unos cuantos ítems antes de confiar en él. El endpoint laya dentro del proceso necesita pip install 'potato-annotation[decision]'.
• detector lee cajas de un detector de objetos en esquemas image_annotation. keep_threshold (0.35) fija la puntuación a partir de la cual, inclusive, una caja forma parte de la predicción. Las cajas entre candidate_threshold (0.05) y keep_threshold reducen la confianza de la imagen. label_map asigna las clases del detector a etiquetas del esquema, y las clases sin asignar se ignoran. image_field nombra el campo del ítem que tiene la ruta o la URL de la imagen. Las rutas se resuelven igual que en la página de anotación, con /media/x.jpg bajo el media_directory de la tarea y una ruta relativa bajo task_dir.
• judge admite rubric (por defecto, la descripción del esquema), fields (los campos del ítem que se muestran al juez, en orden) y swap_order, que pregunta dos veces con el orden de las etiquetas invertido y convierte un veredicto que cambia en una abstención. En los esquemas de trazas de agentes (process_reward, trajectory_eval, ...) el juez etiqueta cada paso.
• vlm usa un endpoint de visión (openai_vision, anthropic_vision, ollama_vision). Para un modelo autoalojado detrás de un servidor compatible con OpenAI, usa openai_vision con base_url.
• trained admite artifact_dir, trainer (sklearn-text por defecto) y run_id. Normalmente esta fuente la crea la destilación, no una configuración escrita a mano.

humans

El bloque humans define quién etiqueta y cómo los muestrea el motor:

crowd

El bloque crowd se aplica cuando crowd está en humans.pools, y Prolific es la única plataforma de crowdsourcing que puede manejar el motor:

El reclutamiento en crowdsourcing es una simulación por defecto, y el planificador informa de lo que haría. Gastar dinero necesita features.crowd_live_spend: true y un tope budgets.human_usd, y una configuración que activa el gasto real sin el tope se rechaza. Crowdsourcing explica cómo configurar el propio estudio de Prolific.

budgets

El bloque budgets detiene el gasto antes de que se supere un límite:

runtime

El bloque runtime controla los lotes, la concurrencia y cuánto tiempo puede tener una persona asignada una petición:

features

Todas las funciones están desactivadas por defecto excepto drift:

redaction

redaction.categories indica cuáles de email, url, ip, card, ssn, phone y handle se enmascaran, y por defecto son todas. El enmascaramiento solo se aplica con features.pii_redaction, y solo a las API de terceros. Los tipos de endpoint autoalojados (vllm, ollama, laya, yolo, ...) no se enmascaran se ejecuten donde se ejecuten, y tampoco ningún endpoint cuyo base_url esté en la misma máquina.

distill

Con features.distill activado, el motor entrena un modelo barato con las etiquetas del estudio y lo pone el primero en la cascada:

Los ítems de las particiones cert y de auditoría nunca entran en el conjunto de entrenamiento, así que el modelo destilado nunca se pone a prueba con etiquetas con las que se entrenó.

Validación

potato validate config.yaml comprueba el bloque labeling_engine junto con el resto de la configuración, y cada error nombra su clave, por ejemplo labeling_engine.sources[1].kind must be one of ... o labeling_engine.contracts[0].error is required for selective_risk. La validación también rechaza:

• una clave de contrato que el tipo de contrato no lee, como una errata en error;
• un contrato sobre un esquema que ninguna fuente de la cascada puede etiquetar, con el motivo de cada fuente;
• un contrato sobre un esquema que el motor no puede puntuar (texto libre, por pares);
• una fuente decision cuyo endpoint_type no es un modelo de decisión, y una fuente llm, vlm o judge cuyo endpoint_type sí lo es; y
• no_worse_than_human con humans.overlap_k por debajo de 3.

La validación también avisa cuando budgets.human_labels es demasiado pequeño para certificar un contrato selective_risk aunque todas las respuestas de la máquina fueran correctas. Sube el presupuesto, o relaja error, hasta que desaparezca el aviso.

Lecturas adicionales

• El motor de etiquetado
• Contratos del motor de etiquetado
• Línea de comandos, REST API, herramientas MCP y SDK
• Soporte de IA, para los tipos de endpoint que las fuentes comparten con el resto de Potato

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