Treinadores de modelos no Potato, agrupados por tarefa

Novo na v2.14.0

O treinamento de modelos do Potato tem 38 treinadores, e cada treinador ajusta um tipo de modelo às respostas de um tipo de esquema de anotação. As tabelas desta página listam cada treinador por tarefa, com os esquemas com que o treinador aprende, os itens que o treinador lê, a instalação de que o treinador precisa, o pré-rótulo que o treinador grava de volta e a pontuação em itens reservados que cada execução informa. A página é para o responsável por um estudo que escolhe um treinador antes de uma primeira execução ou verifica se um esquema pode ser treinado. As chaves de configuração, os backends e as regras de gravação de volta estão na página de configuração. A tabela completa de parâmetros de cada treinador está na seção do treinador na referência do projeto original, e cada nome de treinador abaixo leva a essa seção.

Treinadores oferecidos para cada esquema

A página Training em /admin/training oferece a cada esquema apenas os treinadores que se ajustam ao tipo do esquema e à modalidade dos itens do esquema, por exemplo texto, imagens ou áudio. Um treinador que o projeto não consegue executar permanece na lista com o motivo, como decision-calibrate, que mostra "no decision model is configured" até o projeto ter um modelo de decisão. Um treinador cujos pacotes estão ausentes aparece como "not installed", com o comando que instala os pacotes. Até você escolher um treinador, sklearn-text fica selecionado onde quer que sklearn-text se ajuste. Uma execução iniciada para um esquema que não existe, ou para um esquema que o treinador não consegue aprender, é recusada com HTTP 400 antes de qualquer coisa ser construída.

Cada execução treina em um esquema. A página Training envia um esquema, e a API de treinamento aceita uma lista de esquemas, mas todo treinador ajusta apenas o primeiro esquema da lista. Para treinar dois esquemas, inicie duas execuções.

Nas tabelas abaixo, a coluna Pré-rótulo diz o que uma execução grava em um item quando o esquema está listado em writeback.schemas. Itens da divisão train de uma execução nunca recebem um pré-rótulo, e um pré-rótulo só se torna a resposta de um anotador quando o anotador o edita ou passa adiante. A coluna Pontuação em itens reservados nomeia a métrica principal da execução, calculada nos itens val e test contra os rótulos resolvidos dos anotadores. Um item com rótulo e sem predição conta como erro. Um treinador portanto não consegue aumentar a pontuação pulando itens difíceis. Held-out scores, na referência do projeto original, define cada métrica.

Instalando treinadores

sklearn-text não precisa de nada além de uma instalação simples do Potato, porque o scikit-learn é uma dependência central. Os treinadores de texto, imagem, áudio e LLM precisam de PyTorch e transformers. Um extra instala os pacotes dos quatro grupos:

pip install "potato-annotation[train]"

Os extras mais restritos [train-text], [train-vision], [train-audio] e [train-llm] instalam cada um um grupo, e a coluna Instalação abaixo nomeia o menor extra que cobre cada treinador, como em pip install "potato-annotation[train-vision]". Nenhum dos extras de treinamento faz parte de potato-annotation[all], porque o PyTorch é uma instalação de vários gigabytes. Alguns treinadores precisam de pacotes fora de [train]:

• ultralytics-detect e ultralytics-segment precisam de pip install ultralytics.
• cellpose precisa de pip install cellpose e funciona com o Cellpose 3 ou o Cellpose 4.
• laya-finetune precisa de [decision], e openjev-finetune precisa de pip install wev-ai.
• rdkit-property precisa de [chemistry], volume-unet precisa de [volumes], video-track precisa de opencv-python, e sinais WFDB ou Parquet precisam de [signals]. Imagens de lâmina inteira precisam de [wsi] para o openslide.
• A opção dp de hf-text-classification e hf-image-classification precisa de pip install opacus.

ultralytics-detect, ultralytics-segment e layoutlmv3 pedem que você confirme uma licença antes da primeira execução. O Ultralytics é AGPL-3.0, então um modelo treinado e distribuído com qualquer um dos treinadores YOLO fica sob os termos da AGPL, e a Ultralytics vende uma licença separada para uso fechado. Os pesos do LayoutLMv3 são CC BY-NC-SA 4.0 e não servem para uso comercial. Para os três treinadores, a página Training pede confirmação, uma execução pela API precisa de accept_licence: true e um retreinamento automático precisa de auto_retrain.accept_licence: true. O código do Cellpose é BSD-3-Clause, e os autores do Cellpose publicam os pesos pré-treinados do Cellpose sob termos próprios. As licenças também diferem entre os checkpoints que você nomeia em model_name. O Qwen2.5-VL-3B está sob a licença de pesquisa da Qwen, por exemplo, enquanto o Qwen2.5-VL-7B é Apache-2.0.

Parâmetros

Os parâmetros de uma execução vêm de três lugares, e cada lugar substitui o anterior:

1. os padrões do treinador, listados na seção do treinador no projeto original;
2. model_training.trainer_params.<trainer> na configuração;
3. os params da própria execução, isto é, o campo Parameters da página Training, os params de uma execução pela API ou auto_retrain.params.

Adicione trainer_params ao bloco model_training para definir um padrão para cada treinador que você usa:

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

O campo Parameters da página Training é JSON, preenchido a partir de trainer_params para o treinador escolhido. Um nome de parâmetro que o treinador não aceita é um erro. Um nome em trainer_params impede o servidor de iniciar, e um nome nos params de uma execução impede a execução antes de ela começar. Os dois erros listam os nomes que o treinador aceita. Por exemplo, um score_thresh escrito errado em torchvision-detect é informado com score_threshold na lista. O Potato também verifica cada valor contra o tipo e o intervalo do parâmetro.

Classificadores de texto e de imagem

Os classificadores aprendem com os esquemas de escolha radio, select, likert e multiselect. Um pré-rótulo de radio, select ou likert seleciona uma resposta, e um pré-rótulo de multiselect marca um conjunto de rótulos. sklearn-text roda em uma CPU sem instalação extra, e o tutorial do primeiro modelo percorre uma execução com sklearn-text. Em um corpus de imagens, sklearn-text ajusta o classificador a embeddings de imagem do CLIP. setfit foi feito para os primeiros dias de um projeto e funciona a partir de cerca de oito itens rotulados por rótulo. As páginas dos esquemas radio e multiselect, select e escalas Likert cobrem o lado da anotação.

hf-text-classification ajusta um transformer e, com lora: true, também ajusta um LLM decodificador como Qwen ou Llama. Com soft_targets: true, hf-text-classification treina em direção à divisão de votos dos anotadores, e não em direção a um único rótulo resolvido. hf-text-classification e hf-image-classification aceitam um parâmetro acquisition que ordena os próximos itens a rotular de um esquema de rótulo único por margem, entropia, BALD ou distância de coreset, como mostra o tutorial do modelo no ciclo. Os dois treinadores também aceitam dp para treinar com DP-SGD por meio do Opacus, e o tutorial de privacidade diferencial percorre uma execução com dp.

Trechos, relações e estrutura

Os treinadores deste grupo aprendem trechos com deslocamentos de caracteres, ligações entre trechos, respostas nos nós de uma árvore de conversa e glosas interlineares. hf-relation treina um único codificador para marcar os trechos e classificar pares de trechos. Uma ligação prevista só conta como encontrada quando o marcador também encontrou os dois trechos da ligação com os limites certos. Quando toda resposta de treinamento de um esquema span_link é uma árvore de dependência, hf-relation decodifica árvores e acrescenta UAS e LAS à pontuação. Uma execução segue os mesmos passos do tutorial do primeiro modelo, com outro treinador e outro esquema escolhidos.

LLMs e modelos de recompensa

Os treinadores de LLM aprendem com respostas de texto livre, preferências, ranqueamentos e traços de agentes corrigidos. llm-sft e llm-dpo treinam um adaptador LoRA por padrão, e lora: {quantize: 4bit} carrega o modelo base em 4 bits como QLoRA. reward-model treina um modelo de recompensa escalar a partir de respostas pareadas, de ranqueamento e de melhor-pior, e cada predição guarda as recompensas por opção ao lado da resposta do esquema. prm-reward avalia cada passo de um traço de agente como correto, neutro ou errado. Passos além de max_length (1.024 tokens por padrão) não entram no treinamento nem são avaliados. Uma predição de trajectory_edit é pontuada e armazenada, mas nunca mostrada como pré-rótulo, e o servidor se recusa a iniciar com um esquema trajectory_edit em writeback.schemas. O tutorial de ajuste fino de LLMs cobre SFT, DPO, modelos de recompensa, modelos de recompensa por processo e QLoRA.

Detecção e segmentação de imagens

Os detectores e segmentadores aprendem as formas que os anotadores desenham em um esquema image_annotation, e a maioria deles também lê esquemas de microscopia, de mapas e de espectrogramas. Um detector treina na caixa delimitadora de cada forma, então um estudo de polígonos ou máscaras ainda treina um detector de caixas. Um segmentador treina em contornos e deixa as caixas de fora, e prevê polígonos de no máximo 64 vértices que o anotador pode editar ponto a ponto. cellpose segmenta sem classes, então toda célula prevista recebe o parâmetro label, ou o rótulo mais comum do esquema quando label não está definido.

sam-finetune ajusta o decodificador de máscaras do Segment Anything para transformar uma caixa em um contorno, enquanto o codificador de imagens fica congelado. Uma execução de sam-finetune contorna os pré-rótulos de caixas que uma execução de detecção anterior gravou de volta, então a ordem usual é uma execução de detecção com writeback.include_unlabeled: true e depois uma execução de sam-finetune no mesmo esquema. Em um Mac, torchvision-detect e torchvision-segment treinam na CPU em vez de no Metal. O tutorial de modelos de visão percorre detecção, segmentação, lâminas, microscopia, mapas, Cellpose e SAM.

Os treinadores de imagem leem arquivos locais dentro do diretório da tarefa ou de media_directory. Uma imagem remota http(s) não é baixada, e uma linha cuja imagem é remota ou está ausente fica fora da execução e não recebe predição. Image items, na referência do projeto original, dá os campos de onde o Potato lê o caminho de uma imagem.

Lâminas, microscopia, mapas e espectrogramas

Os treinadores de detecção e segmentação redimensionam cada imagem para algumas centenas de pixels. Para um esquema image_annotation, microscopy ou geo_annotation, o Potato portanto corta uma imagem grande em blocos quando o pacote da execução é construído. A divisão em blocos vem ligada por padrão para formatos de lâmina como .svs e .ndpi e para imagens cujo lado maior tem pelo menos 4.096 pixels. Os blocos de uma mesma lâmina sempre caem em uma só divisão, e as formas previstas são mapeadas de volta à imagem inteira nas coordenadas que o visualizador deep-zoom armazena. A tabela tiling lista todas as chaves, e o tutorial de modelos de visão define o tamanho do bloco, a sobreposição e a resolução para uma lâmina.

As ROIs de um esquema microscopy treinam os treinadores de detecção e segmentação e o cellpose. Cada fatia z e cada ponto no tempo com ROIs é renderizado com os canais e o contraste padrão do esquema, e as predições voltam como ROIs com o z e o t de cada ROI. Um esquema geo_annotation treina no mapa base raster do item, isto é, um GeoTIFF ou uma imagem com uma extensão, e as predições voltam como GeoJSON em EPSG:4326 que o mapa mostra como sugestões. Um mapa cujo mapa base vem de um servidor de blocos não tem raster para treinar, e a execução deixa esses itens de fora com um aviso. Um esquema spectrogram_annotation treina torchvision-detect e ultralytics-detect em cada gravação renderizada como espectrograma, e as caixas voltam em segundos e hertz. Microscopy and maps e Spectrograms, na referência do projeto original, dão os detalhes da renderização.

Documentos e modelos de visão e linguagem

layoutlmv3 aprende o layout de documentos a partir das palavras de uma página e das posições delas, e vlm-sft ajusta um modelo de visão e linguagem em respostas sobre imagens. O Potato não executa OCR, então cada item de layoutlmv3 precisa de um campo words com o texto e a caixa de cada palavra. Uma importação PAGE XML no modo regions preenche words, e palavras da camada de texto de um PDF ou de outra ferramenta de OCR funcionam da mesma forma. vlm-sft treina um adaptador LoRA por padrão, e checkpoints reais precisam de uma GPU. Uma execução de region_caption é pontuada, mas não publicada, porque as regiões que uma legenda descreve são uma resposta do anotador. O tutorial de modelos de visão cobre os dois treinadores, e ancoragem em VLMs cobre o esquema grounding_eval.

Áudio e fala

Os treinadores de áudio leem gravações de arquivos locais que o soundfile abre, por exemplo WAV ou FLAC, e um item cujo áudio é uma URL fica de fora. hf-audio-tagger marca segmentos de tempo rotulados em um esquema audio_annotation. whisper-asr ajusta o Whisper nos turnos de transcrição que os anotadores corrigiram e, por padrão, também grava uma cópia CTranslate2 do modelo para potato transcripts --transcribe e o faster-whisper. diarization ajusta um codificador de fala (WavLM por padrão) para descobrir quem fala quando. Os nomes dos falantes são locais a cada gravação. As caixas de espectrograma treinam os detectores em Detecção e segmentação de imagens. O tutorial de modelos de áudio percorre Whisper, diarização, detecção em espectrogramas e marcação de áudio.

Volumes, nuvens de pontos e vídeo

Os treinadores de 3D e vídeo aprendem com volumes pintados, cuboides em nuvens de pontos e trilhas de vídeo. volume-unet treina uma U-Net 3D em PyTorch simples nas máscaras que os anotadores pintaram em volumes de TC e RM, e uma TC em tamanho real precisa de uma GPU na prática. external-3d executa o seu próprio detector 3D pelos parâmetros train_command e predict_command e lê os cuboides de volta. OpenPCDet e MMDetection3D se encaixam, e os dois precisam de operadores CUDA compilados no host com GPU. video-track ajusta um Faster R-CNN em quadros amostrados das trilhas anotadas e liga as detecções entre quadros em trilhas. O tutorial de volumes, nuvens de pontos e vídeo percorre os três treinadores.

Ciência

Os treinadores de ciência aprendem com química, espectroscopia, sinais fisiológicos e episódios de robôs. rdkit-property responde a uma pergunta sobre uma molécula a partir do fingerprint de Morgan e dos descritores do RDKit da molécula, com um classificador do scikit-learn para escolhas ou um regressor para um slider. peak-cnn prevê posições de picos em um espectro e não prevê rótulos nem atribuições de picos. signal-cnn classifica épocas fixas ou encontra intervalos rotulados em EEG, ECG e outros sinais. episode-model prevê fases, um desfecho e uma curva de recompensa a partir das séries de juntas e sensores de um episódio de robô. O vídeo do episódio não é lido. Picos, intervalos e respostas de episódios aparecem como sugestões para o anotador revisar, e não como a resposta em si. O tutorial de modelos para ciências percorre os quatro treinadores, e as páginas dos esquemas de estruturas químicas, espectros, séries temporais e episódios de robôs cobrem o lado da anotação.

Modelos de decisão

Um modelo de decisão devolve uma probabilidade para cada opção de uma pergunta, e o Potato usa um modelo de decisão como fonte do motor de rotulagem ou como modelo de rotulagem no Modo Solo. Os treinadores de modelos de decisão ajustam um modelo de decisão aos rótulos do estudo em esquemas radio, select, likert e slider, e fazem cada pergunta do jeito que o motor de rotulagem a faz. Um slider é perguntado como uma avaliação com uma opção por posição, até 21 posições. decision-calibrate não treina nada. O treinador ajusta uma calibração às probabilidades do Jev, do OpenJev, do laya-serve ou do Laya e grava a calibração em calibration.json para a fonte do motor aplicar. decision-calibrate roda apenas no backend local. laya-finetune ajusta o Laya, e openjev-finetune ajusta o modelo OpenJev de 8B com o treinamento LoRA do wev. O cartão do modelo OpenJev observa que parte dos dados de treinamento do OpenJev é só para pesquisa. Verifique esses termos antes de uso comercial.

Pontes de inferência

As pontes de inferência usam um modelo que já roda em outro lugar e não treinam nada. Uma execução de ponte envia os itens reservados ao serviço e lê as respostas de volta. Com writeback.include_unlabeled: true, a execução envia também os itens não rotulados. As respostas então recebem uma pontuação em itens reservados contra os seus anotadores, gravação de volta e revisão, como as respostas de um modelo treinado. Uma ponte nunca recebe uma chave de API na configuração. Em vez disso, um parâmetro nomeia a variável de ambiente no servidor que contém a chave. label-studio-ml chama o /predict de um backend de ML do Label Studio e não envia eventos de anotação ao /webhook do backend. hf-inference e roboflow rodam apenas no backend local. As caixas de openai-vlm-boxes não têm confiança, porque o modelo de visão e linguagem não devolve pontuação. O tutorial de traga o seu próprio modelo configura cada ponte.

Leitura adicional

• A visão geral do treinamento de modelos explica o ciclo das anotações aos pré-rótulos e a página Training.
• A página de configuração documenta todas as chaves de model_training, os backends, a gravação de volta e as rotas.
• O tutorial do primeiro modelo executa sklearn-text de ponta a ponta sem GPU.
• O tutorial de treinamento remoto envia execuções a um servidor com GPU por ssh, a um cluster SLURM ou a um agente que consulta o servidor.
• O guia de rotulagem assistida por modelo discute quando pré-rótulos do seu próprio modelo ajudam os anotadores e quando os ancoram.
• A referência de treinamento de modelos do projeto original tem a tabela de parâmetros de cada treinador.