Les modules d'entraînement de Potato, regroupés par tâche

Nouveauté de la v2.14.0

L'entraînement de modèles de Potato compte 38 modules d'entraînement, et chacun ajuste un type de modèle aux réponses d'un type de schéma d'annotation. Les tableaux de cette page listent chaque module par tâche, avec les schémas dont il apprend, les items qu'il lit, l'installation dont il a besoin, la pré-étiquette qu'il écrit en retour et le score sur items réservés que rapporte chaque exécution. La page s'adresse à un responsable d'étude qui choisit un module avant une première exécution, ou qui vérifie si un schéma peut être entraîné. Les clés de configuration, les backends et les règles d'écriture en retour se trouvent sur la page de configuration. Le tableau complet des paramètres de chaque module figure dans la section du module dans la référence amont, et chaque nom de module ci-dessous renvoie à cette section.

Modules proposés pour chaque schéma

La page Training à l'adresse /admin/training ne propose pour chaque schéma que les modules adaptés au genre du schéma et à la modalité de ses items, par exemple texte, images ou audio. Un module que le projet ne peut pas exécuter reste dans la liste avec la raison, comme decision-calibrate, qui affiche « no decision model is configured » tant que le projet n'a pas de modèle de décision. Un module dont les paquets manquent apparaît comme « not installed », avec la commande qui installe ces paquets. Tant que vous ne choisissez pas de module, sklearn-text est sélectionné partout où sklearn-text convient. Une exécution lancée pour un schéma qui n'existe pas, ou pour un schéma que le module ne peut pas apprendre, est refusée avec un HTTP 400 avant que quoi que ce soit soit construit.

Chaque exécution s'entraîne sur un seul schéma. La page Training envoie un schéma, et l'API d'entraînement accepte une liste de schémas, mais chaque module n'ajuste que le premier schéma de la liste. Pour entraîner deux schémas, lancez deux exécutions.

Dans les tableaux ci-dessous, la colonne Pré-étiquette indique ce qu'une exécution écrit sur un item une fois le schéma listé sous writeback.schemas. Les items de la partition train d'une exécution ne reçoivent jamais de pré-étiquette, et une pré-étiquette ne devient la réponse d'un annotateur que lorsque celui-ci la modifie ou passe à la suite. La colonne Score sur items réservés nomme la métrique principale de l'exécution, calculée sur les items val et test par rapport aux étiquettes résolues des annotateurs. Un item qui a une étiquette et aucune prédiction compte comme faux. Un module ne peut donc pas améliorer le score en sautant les items difficiles. Held-out scores dans la référence amont définit chaque métrique.

Installer les modules

sklearn-text ne demande rien de plus qu'une installation ordinaire de Potato, car scikit-learn est une dépendance de base. Les modules pour le texte, les images, l'audio et les LLM ont besoin de PyTorch et de transformers. Un seul extra installe les paquets des quatre groupes.

pip install "potato-annotation[train]"

Les extras plus étroits [train-text], [train-vision], [train-audio] et [train-llm] installent chacun un groupe, et la colonne Installation ci-dessous nomme l'extra le plus étroit qui couvre chaque module, comme dans pip install "potato-annotation[train-vision]". Aucun des extras d'entraînement ne fait partie de potato-annotation[all], car PyTorch pèse plusieurs gigaoctets. Certains modules ont besoin de paquets extérieurs à [train].

• ultralytics-detect et ultralytics-segment ont besoin de pip install ultralytics.
• cellpose a besoin de pip install cellpose et fonctionne avec Cellpose 3 ou Cellpose 4.
• laya-finetune a besoin de [decision], et openjev-finetune a besoin de pip install wev-ai.
• rdkit-property a besoin de [chemistry], volume-unet a besoin de [volumes], video-track a besoin de opencv-python, et les signaux WFDB ou Parquet ont besoin de [signals]. Les images de lames entières ont besoin de [wsi] pour openslide.
• L'option dp de hf-text-classification et de hf-image-classification a besoin de pip install opacus.

ultralytics-detect, ultralytics-segment et layoutlmv3 vous demandent de confirmer une licence avant la première exécution. Ultralytics est sous AGPL-3.0, si bien qu'un modèle entraîné et distribué avec l'un des deux modules YOLO relève des conditions de l'AGPL, et Ultralytics vend une licence distincte pour un usage fermé. Les poids de LayoutLMv3 sont sous CC BY-NC-SA 4.0 et ne sont pas destinés à un usage commercial. Pour ces trois modules, la page Training demande une confirmation, une exécution par l'API a besoin de accept_licence: true, et un réentraînement automatique a besoin de auto_retrain.accept_licence: true. Le code de Cellpose est sous BSD-3-Clause, et les auteurs de Cellpose publient les poids préentraînés de Cellpose sous leurs propres conditions. Les licences diffèrent aussi d'un point de contrôle à l'autre parmi ceux que vous nommez dans model_name. Qwen2.5-VL-3B est sous la licence de recherche de Qwen, par exemple, alors que Qwen2.5-VL-7B est sous Apache-2.0.

Paramètres

Les paramètres d'une exécution viennent de trois endroits, et chacun remplace le précédent.

1. les valeurs par défaut du module, listées dans la section amont du module ;
2. model_training.trainer_params.<trainer> dans la configuration ;
3. les params propres à l'exécution, c'est-à-dire le champ Parameters de la page Training, les params d'une exécution par l'API ou auto_retrain.params.

Ajoutez trainer_params au bloc model_training pour fixer une valeur par défaut pour chaque module que vous utilisez.

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

Le champ Parameters de la page Training est du JSON, rempli à partir de trainer_params pour le module choisi. Un nom de paramètre que le module n'accepte pas est une erreur. Un nom sous trainer_params arrête le serveur au démarrage, et un nom dans les params d'une exécution arrête l'exécution avant qu'elle ne démarre. Chaque erreur liste les noms que le module accepte. Par exemple, un score_thresh mal orthographié sous torchvision-detect est signalé avec score_threshold dans la liste. Potato vérifie aussi chaque valeur par rapport au type et à l'intervalle du paramètre.

Classifieurs de texte et d'images

Les classifieurs apprennent des schémas à choix radio, select, likert et multiselect. Une pré-étiquette radio, select ou likert sélectionne une réponse, et une pré-étiquette multiselect coche un ensemble d'étiquettes. sklearn-text tourne sur un processeur sans installation supplémentaire, et le tutoriel du premier modèle déroule une exécution avec sklearn-text. Sur un corpus d'images, sklearn-text ajuste le classifieur à des plongements d'images CLIP. setfit est conçu pour les premiers jours d'un projet et fonctionne à partir d'environ huit items étiquetés par étiquette. Les pages de schémas radio et multiselect, select et échelles de Likert couvrent le côté annotation.

hf-text-classification affine un transformer et, avec lora: true, affine aussi un LLM décodeur comme Qwen ou Llama. Avec soft_targets: true, hf-text-classification s'entraîne vers la répartition des votes des annotateurs plutôt que vers une seule étiquette résolue. hf-text-classification et hf-image-classification acceptent un paramètre acquisition qui ordonne les prochains items à étiqueter d'un schéma à étiquette unique par marge, entropie, BALD ou distance de core-set, comme le montre le tutoriel du modèle dans la boucle. Les deux modules acceptent aussi dp pour un entraînement par DP-SGD avec Opacus, et le tutoriel sur la confidentialité différentielle déroule une exécution dp.

Empans, relations et structure

Les modules de ce groupe apprennent des empans avec décalages de caractères, des liens entre empans, des réponses sur les nœuds d'un arbre de conversation et des gloses interlinéaires. hf-relation entraîne un seul encodeur à étiqueter les empans et à classer des paires d'empans. Un lien prédit ne compte comme trouvé que si l'étiqueteur a aussi trouvé les deux empans du lien avec les bonnes limites. Quand chaque réponse d'entraînement d'un schéma span_link est un arbre de dépendances, hf-relation décode des arbres et ajoute UAS et LAS au score. Une exécution suit les mêmes étapes que le tutoriel du premier modèle, avec un autre module et un autre schéma choisis.

LLM et modèles de récompense

Les modules pour LLM apprennent de réponses en texte libre, de préférences, de classements et de traces d'agent corrigées. llm-sft et llm-dpo entraînent par défaut un adaptateur LoRA, et lora: {quantize: 4bit} charge le modèle de base sur 4 bits comme QLoRA. reward-model entraîne un modèle de récompense scalaire à partir de réponses par paires, de classements et de meilleur-pire, et chaque prédiction garde les récompenses par option à côté de la réponse du schéma. prm-reward note chaque étape d'une trace d'agent comme correcte, neutre ou fausse. Les étapes au-delà de max_length (1 024 jetons par défaut) ne sont ni utilisées pour l'entraînement ni notées. Une prédiction trajectory_edit est évaluée et enregistrée, mais jamais montrée comme pré-étiquette, et le serveur refuse de démarrer avec un schéma trajectory_edit sous writeback.schemas. Le tutoriel d'affinage de LLM couvre SFT, DPO, les modèles de récompense, les modèles de récompense de processus et QLoRA.

Détection et segmentation sur images

Les détecteurs et les segmenteurs apprennent les formes que les annotateurs dessinent dans un schéma image_annotation, et la plupart d'entre eux lisent aussi les schémas de microscopie, de cartes et de spectrogrammes. Un détecteur s'entraîne sur la boîte englobante de chaque forme, si bien qu'une étude à polygones ou à masques entraîne quand même un détecteur de boîtes. Un segmenteur s'entraîne sur des contours, laisse de côté les boîtes et prédit des polygones d'au plus 64 sommets que l'annotateur peut modifier point par point. cellpose segmente sans classes, si bien que chaque cellule prédite reçoit le paramètre label, ou l'étiquette la plus fréquente du schéma quand label n'est pas défini.

sam-finetune affine le décodeur de masques de Segment Anything pour transformer une boîte en contour, pendant que l'encodeur d'images reste gelé. Une exécution sam-finetune dessine le contour des pré-étiquettes de boîtes qu'une exécution de détection antérieure a écrites en retour, si bien que l'ordre habituel est une exécution de détection avec writeback.include_unlabeled: true, puis une exécution sam-finetune sur le même schéma. Sur un Mac, torchvision-detect et torchvision-segment s'entraînent sur le processeur plutôt que sur Metal. Le tutoriel sur les modèles de vision déroule la détection, la segmentation, les lames, la microscopie, les cartes, Cellpose et SAM.

Les modules pour images lisent des fichiers locaux situés dans le répertoire de la tâche ou dans media_directory. Une image http(s) distante n'est pas téléchargée, et une ligne dont l'image est distante ou absente est écartée de l'exécution et ne reçoit aucune prédiction. Image items dans la référence amont donne les champs dans lesquels Potato lit le chemin d'une image.

Lames, microscopie, cartes et spectrogrammes

Les modules de détection et de segmentation redimensionnent chaque image à quelques centaines de pixels. Pour un schéma image_annotation, microscopy ou geo_annotation, Potato découpe donc une grande image en tuiles au moment où le lot de l'exécution est construit. Le découpage est activé par défaut pour les formats de lames comme .svs et .ndpi et pour les images dont le grand côté fait au moins 4 096 pixels. Les tuiles d'une même lame tombent toujours dans une seule partition, et les formes prédites sont reportées sur l'image entière dans les coordonnées que stocke la visionneuse à zoom profond. Le tableau tiling liste chaque clé, et le tutoriel sur les modèles de vision règle la taille des tuiles, le chevauchement et la résolution pour une lame.

Les ROI d'un schéma microscopy entraînent les modules de détection et de segmentation ainsi que cellpose. Chaque coupe z et chaque point temporel qui a des ROI est rendu avec les canaux et le contraste par défaut du schéma, et les prédictions reviennent sous forme de ROI avec le z et le t de chaque ROI. Un schéma geo_annotation s'entraîne sur le fond de carte raster de l'item, c'est-à-dire un GeoTIFF ou une image avec une emprise, et les prédictions reviennent en GeoJSON en EPSG:4326 que la carte montre comme suggestions. Une carte dont le fond vient d'un serveur de tuiles n'a pas de raster sur lequel s'entraîner, et l'exécution écarte ces items avec un avertissement. Un schéma spectrogram_annotation entraîne torchvision-detect et ultralytics-detect sur chaque enregistrement rendu comme spectrogramme, et les boîtes reviennent en secondes et en hertz. Microscopy and maps et Spectrograms dans la référence amont donnent les détails du rendu.

Documents et modèles vision-langage

layoutlmv3 apprend la mise en page d'un document à partir des mots d'une page et de leurs positions, et vlm-sft affine un modèle vision-langage sur des réponses à propos d'images. Potato n'exécute aucun OCR, si bien que chaque item layoutlmv3 a besoin d'un champ words avec le texte et la boîte de chaque mot. Un import PAGE XML en mode regions remplit words, et des mots issus de la couche texte d'un PDF ou d'un autre outil d'OCR fonctionnent de la même façon. vlm-sft entraîne par défaut un adaptateur LoRA, et les vrais points de contrôle demandent un GPU. Une exécution region_caption est évaluée mais pas publiée, car les régions décrites par une légende sont une réponse d'annotateur. Le tutoriel sur les modèles de vision couvre les deux modules, et l'ancrage par VLM couvre le schéma grounding_eval.

Audio et parole

Les modules audio lisent des enregistrements dans des fichiers locaux que soundfile ouvre, par exemple WAV ou FLAC, et un item dont l'audio est une URL est écarté. hf-audio-tagger étiquette des segments temporels dans un schéma audio_annotation. whisper-asr affine Whisper sur les tours de transcription que les annotateurs ont corrigés et, par défaut, écrit aussi une copie CTranslate2 du modèle pour potato transcripts --transcribe et faster-whisper. diarization affine un encodeur de parole (WavLM par défaut) pour trouver qui parle quand. Les noms de locuteurs sont propres à chaque enregistrement. Les boîtes sur spectrogramme entraînent les détecteurs de Détection et segmentation sur images. Le tutoriel sur les modèles audio déroule Whisper, la diarisation, la détection sur spectrogramme et l'étiquetage audio.

Volumes, nuages de points et vidéo

Les modules 3D et vidéo apprennent de volumes peints, de cuboïdes de nuages de points et de pistes vidéo. volume-unet entraîne un U-Net 3D en PyTorch pur sur les masques que les annotateurs ont peints dans des volumes CT et IRM, et un CT pleine taille demande en pratique un GPU. external-3d exécute votre propre détecteur 3D par les paramètres train_command et predict_command et relit les cuboïdes. OpenPCDet et MMDetection3D conviennent tous deux, et tous deux ont besoin d'opérateurs CUDA compilés sur l'hôte GPU. video-track affine un Faster R-CNN sur des images échantillonnées à partir des pistes annotées et relie les détections d'une image à l'autre en pistes. Le tutoriel sur les volumes, les nuages de points et la vidéo déroule les trois modules.

Sciences

Les modules scientifiques apprennent de la chimie, de la spectroscopie, de signaux physiologiques et d'épisodes de robots. rdkit-property répond à une question sur une molécule à partir de l'empreinte de Morgan de la molécule et de descripteurs RDKit, avec un classifieur scikit-learn pour des choix ou un régresseur pour un curseur. peak-cnn prédit des positions de pics sur un spectre et ne prédit ni étiquettes de pics ni attributions. signal-cnn répartit des époques fixes en étapes ou trouve des intervalles étiquetés dans des signaux EEG, ECG et autres. episode-model prédit des phases, un résultat et une courbe de récompense à partir des séries d'articulations et de capteurs d'un épisode de robot. La vidéo de l'épisode n'est pas lue. Les pics, les intervalles et les réponses d'épisode apparaissent comme des suggestions que l'annotateur relit, et non comme la réponse elle-même. Le tutoriel sur les modèles scientifiques déroule les quatre modules, et les pages de schémas sur les structures chimiques, les spectres, les séries temporelles et les épisodes de robots couvrent le côté annotation.

Modèles de décision

Un modèle de décision renvoie une probabilité pour chaque option d'une question, et Potato utilise un modèle de décision comme source du moteur d'étiquetage ou comme modèle d'étiquetage dans le mode Solo. Les modules pour modèles de décision ajustent un modèle de décision aux étiquettes de l'étude sur des schémas radio, select, likert et slider, et posent chaque question comme la pose le moteur d'étiquetage. Un slider est posé comme une note avec une option par position, jusqu'à 21 positions. decision-calibrate n'entraîne rien. Le module ajuste une calibration aux probabilités de Jev, d'OpenJev, de laya-serve ou de Laya, et écrit la calibration dans calibration.json pour que la source du moteur l'applique. decision-calibrate ne tourne que sur le backend local. laya-finetune affine Laya, et openjev-finetune affine le modèle OpenJev de 8 milliards de paramètres avec l'entraînement LoRA de wev. La fiche du modèle OpenJev note qu'une partie des données d'entraînement d'OpenJev est réservée à la recherche. Vérifiez ces conditions avant un usage commercial.

Passerelles d'inférence

Les passerelles d'inférence utilisent un modèle qui tourne déjà ailleurs et n'entraînent rien. Une exécution de passerelle envoie les items réservés au service et relit les réponses. Avec writeback.include_unlabeled: true, l'exécution envoie aussi les items non étiquetés. Les réponses reçoivent alors un score sur items réservés par rapport à vos annotateurs, une écriture en retour et une relecture, comme les réponses d'un modèle entraîné. Une passerelle n'accepte jamais de clé d'API dans la configuration. Un paramètre nomme plutôt la variable d'environnement du serveur qui contient la clé. label-studio-ml appelle le /predict d'un backend ML de Label Studio et n'envoie pas d'événements d'annotation au /webhook du backend. hf-inference et roboflow ne tournent que sur le backend local. Les boîtes de openai-vlm-boxes n'ont pas de confiance, car le modèle vision-langage ne renvoie aucun score. Le tutoriel pour apporter votre propre modèle met en place chaque passerelle.

Pour aller plus loin

• La vue d'ensemble de l'entraînement de modèles explique la boucle qui va des annotations aux pré-étiquettes, ainsi que la page Training.
• La page de configuration documente chaque clé model_training, les backends, l'écriture en retour et les routes.
• Le tutoriel du premier modèle exécute sklearn-text de bout en bout sans GPU.
• Le tutoriel d'entraînement à distance envoie des exécutions à un serveur GPU par ssh, à un cluster SLURM ou à un agent qui interroge le serveur.
• Le guide de l'étiquetage assisté par modèle discute des cas où les pré-étiquettes de votre propre modèle aident les annotateurs et de ceux où elles les ancrent.
• La référence amont de l'entraînement de modèles contient le tableau des paramètres de chaque module.