Entrenadores de modelos en Potato, agrupados por tarea

Novedad de la v2.14.0

El entrenamiento de modelos de Potato tiene 38 entrenadores, y cada entrenador ajusta un tipo de modelo a las respuestas de un tipo de esquema de anotación. Las tablas de esta página listan todos los entrenadores por tarea, con los esquemas de los que aprende cada uno, los ítems que lee, la instalación que necesita, la preetiqueta que escribe de vuelta y la puntuación sobre ítems reservados que informa cada ejecución. La página es para quien dirige un estudio y debe elegir un entrenador antes de una primera ejecución, o comprobar si un esquema puede entrenarse. Las claves de configuración, los backends y las reglas de escritura de vuelta están en la página de configuración. La tabla completa de parámetros de cada entrenador está en la sección de ese entrenador de la referencia upstream, y cada nombre de entrenador de abajo enlaza a esa sección.

Entrenadores que se ofrecen para cada esquema

La página Training de /admin/training ofrece a cada esquema solo los entrenadores que encajan con el tipo del esquema y con la modalidad de sus ítems, por ejemplo texto, imágenes o audio. Un entrenador que el proyecto no puede ejecutar permanece en la lista con el motivo, como decision-calibrate, que muestra «no decision model is configured» hasta que el proyecto tiene un modelo de decisión. Un entrenador al que le faltan paquetes aparece como «not installed», con el comando que instala los paquetes. Mientras no elijas un entrenador, sklearn-text queda seleccionado dondequiera que sklearn-text encaje. Una ejecución iniciada para un esquema que no existe, o para un esquema que el entrenador no puede aprender, se rechaza con HTTP 400 antes de construir nada.

Cada ejecución entrena con un solo esquema. La página Training envía un esquema, y la API de entrenamiento acepta una lista de esquemas, pero cada entrenador ajusta solo el primer esquema de la lista. Para entrenar dos esquemas, inicia dos ejecuciones.

En las tablas de abajo, la columna Preetiqueta dice qué escribe una ejecución en un ítem cuando el esquema figura en writeback.schemas. Los ítems de la partición train de una ejecución nunca reciben una preetiqueta, y una preetiqueta se convierte en la respuesta de un anotador solo cuando este la edita o pasa al siguiente. La columna Puntuación sobre ítems reservados nombra la métrica principal de la ejecución, calculada sobre los ítems val y test frente a las etiquetas resueltas de los anotadores. Un ítem con etiqueta y sin predicción cuenta como error. Un entrenador no puede, por tanto, subir la puntuación omitiendo los ítems difíciles. Held-out scores en la referencia upstream define cada métrica.

Instalar los entrenadores

sklearn-text no necesita nada más allá de una instalación básica de Potato, porque scikit-learn es una dependencia principal. Los entrenadores de texto, imagen, audio y LLM necesitan PyTorch y transformers. Un único extra instala los paquetes de los cuatro grupos:

pip install "potato-annotation[train]"

Los extras más acotados [train-text], [train-vision], [train-audio] y [train-llm] instalan cada uno un grupo, y la columna Instalación de abajo nombra el extra más acotado que cubre cada entrenador, como en pip install "potato-annotation[train-vision]". Ninguno de los extras de entrenamiento forma parte de potato-annotation[all], porque PyTorch es una instalación de varios gigabytes. Algunos entrenadores necesitan paquetes ajenos a [train]:

• ultralytics-detect y ultralytics-segment necesitan pip install ultralytics.
• cellpose necesita pip install cellpose y funciona con Cellpose 3 o Cellpose 4.
• laya-finetune necesita [decision], y openjev-finetune necesita pip install wev-ai.
• rdkit-property necesita [chemistry], volume-unet necesita [volumes], video-track necesita opencv-python, y las señales WFDB o Parquet necesitan [signals]. Las imágenes de portaobjetos completos necesitan [wsi] para openslide.
• La opción dp de hf-text-classification y hf-image-classification necesita pip install opacus.

ultralytics-detect, ultralytics-segment y layoutlmv3 piden que confirmes una licencia antes de la primera ejecución. Ultralytics es AGPL-3.0, de modo que un modelo entrenado y distribuido con cualquiera de los dos entrenadores YOLO queda sujeto a los términos de la AGPL, y Ultralytics vende una licencia aparte para uso cerrado. Los pesos de LayoutLMv3 son CC BY-NC-SA 4.0 y no son para uso comercial. En los tres entrenadores, la página Training pide confirmación, una ejecución por API necesita accept_licence: true y un reentrenamiento automático necesita auto_retrain.accept_licence: true. El código de Cellpose es BSD-3-Clause, y los autores de Cellpose publican los pesos preentrenados de Cellpose con sus propios términos. Las licencias también difieren entre los puntos de control que nombras en model_name. Qwen2.5-VL-3B tiene la licencia de investigación de Qwen, por ejemplo, mientras que Qwen2.5-VL-7B es Apache-2.0.

Parámetros

Los parámetros de una ejecución vienen de tres lugares, y cada lugar sustituye al anterior:

1. los valores predeterminados del entrenador, listados en la sección upstream del entrenador;
2. model_training.trainer_params.<trainer> en la configuración;
3. los params propios de la ejecución, es decir, el campo Parameters de la página Training, los params de una ejecución por API o auto_retrain.params.

Añade trainer_params al bloque model_training para fijar un valor predeterminado para cada entrenador que uses:

model_training:
  enabled: true
  trainer_params:
    hf-text-classification:
      model_name: answerdotai/ModernBERT-base
      epochs: 4
    torchvision-detect:
      model_name: fasterrcnn_resnet50_fpn_v2
      score_threshold: 0.4

El campo Parameters de la página Training es JSON, rellenado a partir de trainer_params para el entrenador elegido. Un nombre de parámetro que el entrenador no admite es un error. Un nombre bajo trainer_params detiene el servidor al arrancar, y un nombre en los params de una ejecución detiene la ejecución antes de que empiece. Ambos errores listan los nombres que admite el entrenador. Por ejemplo, un score_thresh mal escrito bajo torchvision-detect se informa con score_threshold en la lista. Potato también comprueba cada valor frente al tipo y el rango del parámetro.

Clasificadores de texto y de imagen

Los clasificadores aprenden de los esquemas de elección radio, select, likert y multiselect. Una preetiqueta de radio, select o likert selecciona una respuesta, y una preetiqueta de multiselect marca un conjunto de etiquetas. sklearn-text se ejecuta en una CPU sin ninguna instalación adicional, y el tutorial del primer modelo recorre una ejecución con sklearn-text. Sobre un corpus de imágenes, sklearn-text ajusta el clasificador a embeddings de imagen de CLIP. setfit está pensado para los primeros días de un proyecto y funciona con unos ocho ítems etiquetados por etiqueta. Las páginas de esquemas de radio y multiselect, select y escalas Likert cubren el lado de la anotación.

hf-text-classification ajusta un transformer y, con lora: true, también ajusta un LLM de solo decodificador como Qwen o Llama. Con soft_targets: true, hf-text-classification entrena hacia el reparto de votos de los anotadores en lugar de hacia una sola etiqueta resuelta. hf-text-classification y hf-image-classification admiten un parámetro acquisition que ordena los siguientes ítems de un esquema de una sola etiqueta por margen, entropía, BALD o distancia de coreset, como muestra el tutorial del modelo en el ciclo. Ambos entrenadores admiten también dp para entrenar con DP-SGD mediante Opacus, y el tutorial de privacidad diferencial recorre una ejecución con dp.

Spans, relaciones y estructura

Los entrenadores de este grupo aprenden spans con desplazamientos de caracteres, enlaces entre spans, respuestas sobre los nodos de un árbol de conversación y glosas interlineales. hf-relation entrena un único codificador para etiquetar los spans y para clasificar pares de spans. Un enlace predicho cuenta como encontrado solo cuando el etiquetador también encontró los dos spans del enlace con los límites correctos. Cuando todas las respuestas de entrenamiento de un esquema span_link son un árbol de dependencias, hf-relation decodifica árboles y añade UAS y LAS a la puntuación. Una ejecución sigue los mismos pasos que el tutorial del primer modelo, con otro entrenador y otro esquema elegidos.

LLM y modelos de recompensa

Los entrenadores de LLM aprenden de respuestas de texto libre, preferencias, clasificaciones y trazas de agente corregidas. llm-sft y llm-dpo entrenan por defecto un adaptador LoRA, y lora: {quantize: 4bit} carga el modelo base en 4 bits como QLoRA. reward-model entrena un modelo de recompensa escalar a partir de respuestas por pares, clasificaciones y mejor-peor, y cada predicción conserva las recompensas por opción junto a la respuesta del esquema. prm-reward califica cada paso de una traza de agente como correcto, neutro o incorrecto. Los pasos que pasan de max_length (1024 tokens por defecto) ni se entrenan ni se califican. Una predicción de trajectory_edit se puntúa y se guarda, pero nunca se muestra como preetiqueta, y el servidor se niega a arrancar con un esquema trajectory_edit bajo writeback.schemas. El tutorial de ajuste fino de LLM cubre SFT, DPO, modelos de recompensa, modelos de recompensa por procesos y QLoRA.

Detección y segmentación de imágenes

Los detectores y segmentadores aprenden las formas que dibujan los anotadores en un esquema image_annotation, y la mayoría de ellos también leen esquemas de microscopía, de mapas y de espectrogramas. Un detector entrena con la caja delimitadora de cada forma, de modo que un estudio de polígonos o de máscaras también entrena un detector de cajas. Un segmentador entrena con contornos, deja fuera las cajas y predice polígonos de 64 vértices como máximo que el anotador puede editar punto a punto. cellpose segmenta sin clases, así que cada célula predicha recibe el parámetro label, o la etiqueta más común del esquema cuando label no está fijado.

sam-finetune ajusta el decodificador de máscaras de Segment Anything para convertir una caja en un contorno mientras el codificador de imagen permanece congelado. Una ejecución de sam-finetune perfila las preetiquetas de caja que escribió de vuelta una ejecución de detección anterior, así que el orden habitual es una ejecución de detección con writeback.include_unlabeled: true y después una ejecución de sam-finetune sobre el mismo esquema. En un Mac, torchvision-detect y torchvision-segment entrenan en la CPU y no en Metal. El tutorial de modelos de visión recorre la detección, la segmentación, los portaobjetos, la microscopía, los mapas, Cellpose y SAM.

Los entrenadores de imagen leen archivos locales dentro del directorio de la tarea o de media_directory. Una imagen remota http(s) no se descarga, y una fila cuya imagen es remota o falta queda fuera de la ejecución y no recibe predicción. Image items en la referencia upstream da los campos de los que Potato lee la ruta de una imagen.

Portaobjetos, microscopía, mapas y espectrogramas

Los entrenadores de detección y segmentación redimensionan cada imagen a unos pocos cientos de píxeles. Para un esquema image_annotation, microscopy o geo_annotation, Potato corta por eso una imagen grande en teselas al construir el paquete de la ejecución. El teselado está activado por defecto para formatos de portaobjetos como .svs y .ndpi y para imágenes cuyo lado mayor mide al menos 4096 píxeles. Las teselas de un mismo portaobjetos caen siempre en una misma partición, y las formas predichas se proyectan de nuevo sobre la imagen completa en las coordenadas que guarda el visor de zoom profundo. La tabla tiling lista todas las claves, y el tutorial de modelos de visión fija el tamaño de tesela, el solapamiento y la resolución para un portaobjetos.

Las ROI de un esquema microscopy entrenan los entrenadores de detección y segmentación y cellpose. Cada plano z y cada instante con ROI se renderiza con los canales y el contraste predeterminados del esquema, y las predicciones vuelven como ROI con el z y el t de cada ROI. Un esquema geo_annotation entrena con el mapa base ráster del ítem, es decir, un GeoTIFF o una imagen con una extensión, y las predicciones vuelven como GeoJSON en EPSG:4326 que el mapa muestra como sugerencias. Un mapa cuyo mapa base viene de un servidor de teselas no tiene ráster con el que entrenar, y la ejecución deja esos ítems fuera con un aviso. Un esquema spectrogram_annotation entrena torchvision-detect y ultralytics-detect con cada grabación renderizada como espectrograma, y las cajas vuelven en segundos y hercios. Microscopy and maps y Spectrograms en la referencia upstream dan los detalles de renderizado.

Documentos y modelos de visión y lenguaje

layoutlmv3 aprende el diseño de un documento a partir de las palabras de una página y sus posiciones, y vlm-sft ajusta un modelo de visión y lenguaje con respuestas sobre imágenes. Potato no ejecuta OCR, así que cada ítem de layoutlmv3 necesita un campo words con el texto y la caja de cada palabra. Una importación PAGE XML en modo regions rellena words, y las palabras de la capa de texto de un PDF o de otra herramienta de OCR funcionan igual. vlm-sft entrena por defecto un adaptador LoRA, y los puntos de control reales necesitan una GPU. Una ejecución de region_caption se puntúa pero no se publica, porque las regiones que describe un pie de imagen son una respuesta del anotador. El tutorial de modelos de visión cubre los dos entrenadores, y VLM grounding cubre el esquema grounding_eval.

Audio y voz

Los entrenadores de audio leen grabaciones de archivos locales que soundfile abre, por ejemplo WAV o FLAC, y un ítem cuyo audio es una URL queda fuera. hf-audio-tagger etiqueta segmentos de tiempo en un esquema audio_annotation. whisper-asr ajusta Whisper con los turnos de transcripción que corrigieron los anotadores y, por defecto, escribe además una copia CTranslate2 del modelo para potato transcripts --transcribe y faster-whisper. diarization ajusta un codificador de voz (WavLM por defecto) para encontrar quién habla y cuándo. Los nombres de hablante son locales a cada grabación. Las cajas de espectrograma entrenan los detectores de Detección y segmentación de imágenes. El tutorial de modelos de audio recorre Whisper, la diarización, la detección sobre espectrogramas y el etiquetado de audio.

Volúmenes, nubes de puntos y vídeo

Los entrenadores 3D y de vídeo aprenden de volúmenes pintados, cuboides de nubes de puntos y pistas de vídeo. volume-unet entrena una U-Net 3D en PyTorch puro con las máscaras que los anotadores pintaron en volúmenes de TC y RM, y una TC de tamaño completo necesita en la práctica una GPU. external-3d ejecuta tu propio detector 3D mediante los parámetros train_command y predict_command y lee de vuelta los cuboides. OpenPCDet y MMDetection3D encajan los dos, y ambos necesitan operadores CUDA compilados en el host con GPU. video-track ajusta un Faster R-CNN con fotogramas muestreados de las pistas anotadas y enlaza las detecciones entre fotogramas en pistas. El tutorial de volúmenes, nubes de puntos y vídeo recorre los tres entrenadores.

Ciencia

Los entrenadores científicos aprenden de química, espectroscopía, señales fisiológicas y episodios de robots. rdkit-property responde una pregunta sobre una molécula a partir de la huella de Morgan de la molécula y de descriptores de RDKit, con un clasificador de scikit-learn para elecciones o un regresor para un deslizador. peak-cnn predice posiciones de picos en un espectro y no predice etiquetas ni asignaciones de picos. signal-cnn clasifica épocas fijas o encuentra intervalos etiquetados en EEG, ECG y otras señales. episode-model predice fases, un resultado y una curva de recompensa a partir de las series de articulaciones y sensores de un episodio de robot. El vídeo del episodio no se lee. Los picos, los intervalos y las respuestas de episodio aparecen como sugerencias que el anotador revisa y no como la respuesta misma. El tutorial de modelos científicos recorre los cuatro entrenadores, y las páginas de esquemas de estructuras químicas, espectros, series temporales y episodios de robots cubren el lado de la anotación.

Modelos de decisión

Un modelo de decisión devuelve una probabilidad para cada opción de una pregunta, y Potato usa un modelo de decisión como fuente del motor de etiquetado o como modelo de etiquetado en el modo Solo. Los entrenadores de modelos de decisión ajustan un modelo de decisión a las etiquetas del estudio en esquemas radio, select, likert y slider, y formulan cada pregunta como la formula el motor de etiquetado. Un slider se pregunta como una valoración con una opción por posición, hasta 21 posiciones. decision-calibrate no entrena nada. El entrenador ajusta una calibración a las probabilidades de Jev, OpenJev, laya-serve o Laya, y escribe la calibración en calibration.json para que la aplique la fuente del motor. decision-calibrate se ejecuta solo en el backend local. laya-finetune ajusta Laya, y openjev-finetune ajusta el modelo OpenJev de 8B con el entrenamiento LoRA de wev. La ficha del modelo OpenJev señala que parte de los datos de entrenamiento de OpenJev son solo para investigación. Revisa esos términos antes de un uso comercial.

Puentes de inferencia

Los puentes de inferencia usan un modelo que ya se ejecuta en otro lugar y no entrenan nada. Una ejecución de puente envía los ítems reservados al servicio y lee las respuestas de vuelta. Con writeback.include_unlabeled: true, la ejecución envía también los ítems sin etiquetar. Las respuestas reciben entonces una puntuación sobre ítems reservados frente a tus anotadores, escritura de vuelta y revisión, igual que las respuestas de un modelo entrenado. Un puente nunca toma una clave de API en la configuración. En su lugar, un parámetro nombra la variable de entorno del servidor que contiene la clave. label-studio-ml llama al /predict de un backend ML de Label Studio y no envía eventos de anotación al /webhook del backend. hf-inference y roboflow se ejecutan solo en el backend local. Las cajas de openai-vlm-boxes no tienen confianza, porque el modelo de visión y lenguaje no devuelve ninguna puntuación. El tutorial de trae tu propio modelo configura cada puente.

Más información

• La descripción general del entrenamiento de modelos explica el ciclo que va de las anotaciones a las preetiquetas y la página Training.
• La página de configuración documenta todas las claves de model_training, los backends, la escritura de vuelta y las rutas.
• El tutorial del primer modelo ejecuta sklearn-text de principio a fin sin GPU.
• El tutorial de entrenamiento remoto envía ejecuciones a un servidor con GPU por ssh, a un clúster SLURM o a un agente que consulta al servidor.
• La guía de etiquetado asistido por modelo analiza cuándo las preetiquetas de tu propio modelo ayudan a los anotadores y cuándo los anclan.
• La referencia upstream del entrenamiento de modelos tiene la tabla de parámetros de cada entrenador.