Potato 2.14: entrena modelos con tus propias anotaciones

Potato 2.14 entrena modelos con las propias anotaciones de un estudio. Una ejecución ajusta uno de los 38 entrenadores con las etiquetas que han dado los anotadores, puntúa el modelo sobre ítems reservados que quedan fuera del entrenamiento y escribe de vuelta las predicciones del modelo en los ítems como preetiquetas que los anotadores confirman o corrigen. La versión 2.13.1 tenía un solo entrenador, sklearn-text. La versión también importa archivos de diarización RTTM, exporta turnos de hablante corregidos, ejecuta WhisperX para transcripción local y corrige varios errores que cambiaban cifras de acuerdo y exportaciones, así que lee las notas de actualización antes de instalar.

pip install --upgrade potato-annotation

Notas de actualización

Ejecuta primero potato validate config.yaml --strict sobre cada configuración. Los siguientes cambios pueden alterar lo que hace un estudio de 2.13 que ya funcionaba:

• assignment_strategy: llm_confidence ahora ordena la cola. La estrategia sirve primero la preetiqueta de menor confianza y después los ítems sin preetiqueta. Las versiones anteriores aceptaban el valor y asignaban los ítems al azar.
• model_training se comprueba en la validación y al arrancar. Una clave desconocida bajo writeback o auto_retrain, una partición con un nombre distinto de train, val o test y una entrada de writeback.schemas que no es un esquema son errores que detienen el servidor.
• La página Training informa de una puntuación sobre ítems reservados. La columna de puntuación mostraba antes la exactitud de entrenamiento. La puntuación de una ejecución de 2.13 no es comparable con una puntuación sobre ítems reservados de 2.14.
• Los enlaces, las cadenas y los eventos aparecen en las exportaciones. Las respuestas de span_link, coreference y event_annotation faltaban en todas las exportaciones, y CSV y TSV añaden ahora las columnas <scheme>._links y <scheme>._events.
• Potato ya no lista ujson en install_requires. Un script propio que importe ujson desde el entorno de Potato necesita pip install ujson.

Entrenamiento de modelos

El entrenamiento de modelos es para un estudio con más ítems de los que etiquetarán los anotadores, donde un modelo entrenado con las primeras etiquetas puede proponer el resto. El ciclo tiene tres pasos. Primero, una ejecución resuelve las etiquetas de cada ítem en una sola respuesta y divide los ítems en train, val y test. Segundo, el entrenador ajusta un modelo con la partición train en un proceso aparte, y la ejecución puntúa el modelo sobre los ítems val y test. Tercero, la escritura de vuelta muestra las predicciones del modelo a los anotadores como preetiquetas, y las respuestas que guardan los anotadores se convierten en las etiquetas de la siguiente ejecución.

Para activar el ciclo en un estudio con un esquema sentiment, añade este bloque a la configuración del estudio:

model_training:
  enabled: true
  writeback:
    schemas: [sentiment]
    include_unlabeled: true
    min_confidence: 0.6

Los anotadores no ven nada de una ejecución hasta que se nombra un esquema bajo writeback.schemas. include_unlabeled: true predice sobre los ítems que nadie ha etiquetado, y min_confidence mantiene fuera de la página las predicciones por debajo de 0,6. Reinicia el servidor, abre /admin/training con la clave de administrador, elige un entrenador y un esquema, y haz clic en Train now.

El proyecto de ejemplo de Potato en examples/ai-assisted/model-training/ tiene 160 reseñas de productos y ejecuta sklearn-text, que no necesita GPU ni nada más allá de una instalación básica. La documentación del entrenamiento de modelos informa de una ejecución allí, sobre 120 reseñas etiquetadas, que obtuvo 0,84 de macro-F1 sobre las reseñas de validación y escribió 80 preetiquetas. Un anotador nuevo ve entonces cada una de esas reseñas con la respuesta del modelo ya seleccionada:

Entrena tu primer modelo recorre el ejemplo paso a paso.

Entrenadores para cada tipo de anotación

La página Training ofrece a cada esquema solo los entrenadores que encajan con él. El catálogo de entrenadores lista los 38 entrenadores con sus comandos de instalación, y la lista de abajo nombra los grupos principales:

• Texto. hf-text-classification, setfit y sklearn-text clasifican ítems. hf-token-classification etiqueta spans, hf-relation enlaza spans en relaciones, eventos y cadenas de correferencia, y byt5-gloss segmenta y glosa palabras para el glosado interlineal.
• Imágenes. torchvision-detect y ultralytics-detect entrenan detectores, y torchvision-segment, ultralytics-segment y cellpose entrenan segmentadores. Las ejecuciones de detección y segmentación dividen en teselas los portaobjetos completos y las imágenes grandes, y entrenan con planos de microscopía y mapas GeoTIFF. volume-unet segmenta volúmenes 3D, layoutlmv3 etiqueta diseños de página y vlm-sft ajusta un modelo de visión y lenguaje con pies de imagen, anclaje y pasos de GUI.
• Audio y vídeo. whisper-asr ajusta Whisper con turnos de transcripción corregidos, diarization entrena un modelo de hablantes con turnos de hablante, hf-audio-tagger etiqueta segmentos de audio y video-track sigue objetos entre fotogramas.
• LLM y agentes. llm-sft ajusta con respuestas de texto libre, llm-dpo con preferencias por pares, reward-model con respuestas por pares, clasificaciones y mejor-peor, y prm-reward con calificaciones de pasos de trazas de agente.
• Ciencia. rdkit-property predice respuestas sobre moléculas, peak-cnn predice posiciones de picos en espectros, signal-cnn etiqueta intervalos de señales de series temporales y episode-model etiqueta episodios de robots.

Los entrenadores de ultralytics son AGPL-3.0, y los pesos de LayoutLMv3 son CC BY-NC-SA 4.0. Una ejecución de cualquiera de los dos te pide aceptar antes la licencia. pip install "potato-annotation[train]" instala lo que necesitan los entrenadores de texto, imagen, audio y LLM, y el catálogo nombra las instalaciones aparte.

Puntuaciones sobre ítems reservados y preetiquetas

Cada ejecución puntúa sus predicciones sobre los ítems val y test con una métrica adecuada al esquema, como macro-F1 para etiquetas, mAP50 para cajas, tasa de error de palabras para transcripciones y Dice para volúmenes. Un ítem con etiqueta y sin predicción cuenta como error, y una cifra de cobertura informa de la proporción de ítems que recibieron una predicción. Los ítems de la partición train nunca reciben una preetiqueta, y un ítem que un revisor corrigió va siempre a la partición train de las ejecuciones posteriores.

Una preetiqueta se convierte en la respuesta del anotador solo cuando este la edita o pasa al siguiente ítem, y la escritura de vuelta nunca cambia una etiqueta humana. La cola de revisión del modelo sirve las preetiquetas empezando por las de menor confianza, y el informe de revisión nombra la ejecución que está detrás de cada preetiqueta. El modelo en el ciclo cubre el flujo de revisión.

Entrenar en un servidor con GPU o en un clúster

Una ejecución corre en un backend. El backend local entrena en el servidor de Potato y elige CUDA, Metal de Apple o la CPU. Un backend ssh inicia la ejecución en un servidor con GPU al que Potato puede llegar y devuelve el progreso y el modelo en flujo continuo. Un backend slurm envía la ejecución a un nodo de cómputo con sbatch desde el nodo de acceso, y necesita solo sbatch, squeue y scancel. Un backend agent sirve a una máquina a la que Potato no puede llegar, que ejecuta potato training agent y consulta al servidor si hay trabajos. Antes de una ejecución en un backend ssh, potato training check <backend> config.yaml informa del Python remoto, de las GPU remotas y de los paquetes de entrenamiento que faltan. Entrenar en un servidor con GPU, un clúster SLURM o una máquina tras NAT configura cada backend.

Elegir qué preguntar a continuación

hf-text-classification y hf-image-classification admiten un parámetro acquisition que escribe una puntuación en cada predicción, por margen, entropía, BALD o distancia de core-set. assignment_strategy: llm_confidence sirve entonces primero la puntuación más alta. auto_retrain inicia por defecto una ejecución nueva tras cada 25 anotaciones nuevas, y cada ejecución vuelve a puntuar los ítems sin etiquetar. Aprendizaje activo compara este ciclo con el bloque active_learning de Potato.

Modelos que ya tienes

Cinco entrenadores no ajustan nada y puntúan un modelo que se ejecuta en otro lugar: label-studio-ml para un backend ML de Label Studio, openai-vlm-boxes para un modelo de visión y lenguaje tras una API compatible con OpenAI, hf-inference para un Inference Endpoint de Hugging Face, roboflow y cvat-nuclio para una función serverless de CVAT. Las predicciones de esos modelos reciben la misma puntuación sobre ítems reservados, escritura de vuelta y revisión que las de un modelo entrenado. Preetiquetas y puntuaciones sobre ítems reservados de un modelo que ya ejecutas cubre cada puente.

Publicar un modelo

La página de una ejecución sube el modelo a Hugging Face Hub con una ficha del modelo que nombra el entrenador, el modelo base, los esquemas, el tamaño de las particiones y la puntuación sobre ítems reservados. Escribes el nombre del repositorio dos veces, el repositorio es privado por defecto y el token procede de una variable de entorno del servidor. Las predicciones y los datos de entrenamiento permanecen en el servidor. La misma página guarda la partición de una ejecución y las etiquetas humanas de esa partición como una versión de un conjunto de datos, para comparar modelos posteriores sobre los mismos ítems.

Transcripciones, importación y exportación

• WhisperX. potato transcripts --transcribe usa WhisperX cuando está instalado, con tiempos de palabra obtenidos por alineación forzada con --asr-word-timestamps, y recurre a faster-whisper en caso contrario. Una ejecución de whisper-asr escribe una copia CTranslate2 del modelo ajustado que carga --asr-model.
• Importación RTTM. potato import -f rttm convierte un archivo de diarización, o una carpeta de archivos de diarización, en un ítem por grabación con los turnos de hablante que corregir. --speaker-map cambia el nombre de los hablantes.
• Exportación segments. El formato escribe una fila JSONL por segmento de audio o de vídeo y un archivo RTTM por anotador.
• Dependencias CoNLL-U. HEAD y DEPREL proceden de un esquema span_link dirigido sobre los spans exportados. Las dos columnas valían siempre _ antes.

Correcciones que afectan a los resultados

El registro de cambios lista todas las correcciones. Las correcciones de abajo podían haber cambiado cifras que ya habías informado:

• Un empate de clasificación escrito como B,D=A,C se leía como un solo ítem llamado D=A, de modo que el tau de Kendall y la distancia de Spearman dejaban fuera los dos ítems empatados.
• Las preetiquetas de deslizador, de etiqueta suave y de escala por pares se guardaban como respuesta del anotador al cargar la página, de modo que un ítem contaba como terminado antes de que nadie respondiera. Abrir un ítem grounding_eval lo guardaba del mismo modo.
• /admin/iaa listaba la correferencia, los enlaces de spans y los eventos como spans sin puntuación. El informe ahora puntúa los tres tipos por F1 medio por pares.
• Fusionar o dividir un código del libro de códigos no reasignaba ninguna codificación, porque nada vinculaba las anotaciones guardadas con los ids de código.
• Los manifiestos de instantáneas congelaban cifras de acuerdo nulas, y ahora registran kappa y porcentaje de acuerdo.
• La revisión del modelo contaba un veredicto reject como un fallo y no contra la preetiqueta que el veredicto retiró, y la precisión del informe de revisión salía mal. Un par de anotador e ítem reservado también conservaba el campo de escritura de vuelta en los datos del ítem cuando writeback.field difería de pre_annotation.field, y los datos del ítem de un par así omiten ahora ambos campos.

Instalar 2.14

Actualiza, valida cada configuración e instala los entrenadores que necesites:

pip install --upgrade potato-annotation
potato validate config.yaml --strict
pip install "potato-annotation[train]"

Entrenamiento de modelos es el lugar por el que empezar, y Novedades lista el resto de la versión.