Potato의 모델 트레이너, 작업별 정리

v2.14.0의 새 기능

Potato의 모델 학습에는 트레이너 38개가 있으며, 각 트레이너는 한 종류의 어노테이션 스키마가 낸 답에 한 종류의 모델을 맞춥니다. 이 페이지의 표는 모든 트레이너를 작업별로 나열하고, 트레이너가 학습하는 스키마, 트레이너가 읽는 항목, 트레이너에 필요한 설치, 트레이너가 되쓰는 사전 레이블, 실행마다 보고하는 홀드아웃 점수를 보여 줍니다. 이 페이지는 첫 실행에 앞서 트레이너를 고르거나 어떤 스키마를 학습시킬 수 있는지 확인하려는 연구 책임자를 위한 것입니다. 설정 키, 백엔드, 되쓰기 규칙은 설정 페이지에 있습니다. 각 트레이너의 전체 파라미터 표는 업스트림 레퍼런스의 해당 트레이너 섹션에 있으며, 아래의 각 트레이너 이름은 그 섹션으로 연결됩니다.

스키마마다 제공되는 트레이너

/admin/training의 Training 페이지는 각 스키마에 대해 스키마의 종류와 스키마 항목의 모달리티(예: 텍스트, 이미지, 오디오)에 맞는 트레이너만 제공합니다. 프로젝트에서 실행할 수 없는 트레이너는 이유와 함께 목록에 남으며, 예를 들어 decision-calibrate는 프로젝트에 결정 모델이 생기기 전까지 "no decision model is configured"를 표시합니다. 패키지가 없는 트레이너는 "not installed"로 표시되며 패키지를 설치하는 명령이 함께 나옵니다. 트레이너를 고르기 전에는 sklearn-text가 맞는 모든 곳에서 sklearn-text가 선택되어 있습니다. 존재하지 않는 스키마나 트레이너가 학습할 수 없는 스키마로 시작한 실행은 아무것도 만들어지기 전에 HTTP 400으로 거부됩니다.

각 실행은 스키마 하나로 학습합니다. Training 페이지는 스키마 하나를 보내고, 학습 API는 스키마 목록을 받지만 모든 트레이너는 목록의 첫 번째 스키마만 학습합니다. 스키마 두 개를 학습시키려면 실행을 두 번 시작하십시오.

아래 표에서 사전 레이블 열은 스키마가 writeback.schemas에 나열된 뒤 실행이 항목에 써 넣는 내용을 알려 줍니다. 실행의 train 분할에 있는 항목에는 사전 레이블이 붙지 않으며, 사전 레이블은 어노테이터가 수정하거나 다음으로 넘어갈 때에만 어노테이터의 답이 됩니다. 홀드아웃 점수 열은 실행의 대표 지표를 나타내며, val 항목과 test 항목에서 어노테이터가 통합한 레이블과 비교해 계산합니다. 레이블은 있는데 예측이 없는 항목은 틀린 것으로 계산됩니다. 따라서 트레이너는 어려운 항목을 건너뛰어 점수를 올릴 수 없습니다. 업스트림 레퍼런스의 홀드아웃 점수가 모든 지표를 정의합니다.

트레이너 설치하기

sklearn-text는 scikit-learn이 핵심 의존성이므로 Potato 기본 설치 외에 아무것도 필요 없습니다. 텍스트, 이미지, 오디오, LLM 트레이너에는 PyTorch와 transformers가 필요합니다. 엑스트라 하나로 네 그룹의 패키지를 모두 설치합니다.

pip install "potato-annotation[train]"

범위가 더 좁은 엑스트라 [train-text], [train-vision], [train-audio], [train-llm]은 각각 한 그룹을 설치하며, 아래 설치 열은 pip install "potato-annotation[train-vision]"처럼 각 트레이너를 포괄하는 가장 좁은 엑스트라를 알려 줍니다. PyTorch 설치가 수 기가바이트이므로 학습용 엑스트라는 어느 것도 potato-annotation[all]에 들어 있지 않습니다. 일부 트레이너에는 [train] 밖의 패키지가 필요합니다.

• ultralytics-detect와 ultralytics-segment에는 pip install ultralytics가 필요합니다.
• cellpose에는 pip install cellpose가 필요하며 Cellpose 3과 Cellpose 4 모두에서 동작합니다.
• laya-finetune에는 [decision]이, openjev-finetune에는 pip install wev-ai가 필요합니다.
• rdkit-property에는 [chemistry]가, volume-unet에는 [volumes]가, video-track에는 opencv-python이 필요하고, WFDB나 Parquet 신호에는 [signals]가 필요합니다. 전체 슬라이드 이미지에는 openslide를 위한 [wsi]가 필요합니다.
• hf-text-classification과 hf-image-classification의 dp 옵션에는 pip install opacus가 필요합니다.

ultralytics-detect, ultralytics-segment, layoutlmv3는 첫 실행 전에 라이선스를 확인하라고 요청합니다. Ultralytics는 AGPL-3.0이므로 YOLO 트레이너 중 하나로 학습해 배포한 모델에는 AGPL 조건이 적용되고, 비공개 용도로 쓰려면 Ultralytics가 별도 라이선스를 판매합니다. LayoutLMv3 가중치는 CC BY-NC-SA 4.0이며 상업적 용도로 쓸 수 없습니다. 세 트레이너 모두 Training 페이지가 확인을 요청하고, API 실행에는 accept_licence: true가, 자동 재학습에는 auto_retrain.accept_licence: true가 필요합니다. Cellpose의 코드는 BSD-3-Clause이고, Cellpose 저자들은 Cellpose의 사전 학습 가중치를 별도 조건으로 공개합니다. model_name에 지정하는 체크포인트에 따라서도 라이선스가 다릅니다. 예를 들어 Qwen2.5-VL-3B는 Qwen 연구용 라이선스를 따르지만 Qwen2.5-VL-7B는 Apache-2.0입니다.

파라미터

실행의 파라미터는 세 곳에서 오며, 각 곳이 앞의 곳을 덮어씁니다.

1. 트레이너의 기본값. 업스트림의 해당 트레이너 섹션에 나열되어 있습니다.
2. 설정의 model_training.trainer_params.<trainer>.
3. 실행 자체의 params. 즉 Training 페이지의 Parameters 필드, API 실행의 params, auto_retrain.params입니다.

사용하는 트레이너마다 기본값을 정하려면 model_training 블록에 trainer_params를 추가하십시오.

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

Training 페이지의 Parameters 필드는 JSON이며, 선택한 트레이너의 trainer_params로 채워집니다. 트레이너가 받지 않는 파라미터 이름은 오류입니다. trainer_params 아래의 이름은 서버를 시작할 때 서버를 멈추게 하고, 실행의 params에 있는 이름은 실행이 시작되기 전에 실행을 멈추게 합니다. 어느 오류든 트레이너가 받는 이름의 목록을 보여 줍니다. 예를 들어 torchvision-detect 아래에 score_thresh로 잘못 쓰면 목록에 score_threshold가 들어간 오류가 보고됩니다. Potato는 각 값도 파라미터의 타입과 범위에 맞는지 검사합니다.

텍스트와 이미지 분류기

분류기는 선택형 스키마인 radio, select, likert, multiselect에서 학습합니다. radio, select, likert의 사전 레이블은 답 하나를 선택하고, multiselect의 사전 레이블은 레이블 집합에 체크합니다. sklearn-text는 추가 설치 없이 CPU에서 실행되며, 첫 모델 튜토리얼이 sklearn-text 실행을 안내합니다. 이미지 코퍼스에서 sklearn-text는 분류기를 CLIP 이미지 임베딩에 맞춥니다. setfit은 프로젝트 초반을 위해 만들어졌으며 레이블당 레이블이 달린 항목 8개 정도에서 시작해 동작합니다. 어노테이션 쪽은 radio와 multiselect, select, 리커트 척도 스키마 페이지에서 다룹니다.

hf-text-classification은 트랜스포머를 파인튜닝하며, lora: true를 주면 Qwen이나 Llama 같은 디코더 LLM도 파인튜닝합니다. soft_targets: true를 주면 hf-text-classification은 통합된 레이블 하나가 아니라 어노테이터들의 투표 분포를 목표로 학습합니다. hf-text-classification과 hf-image-classification은 acquisition 파라미터를 받아, 루프 안의 모델 튜토리얼에서 보듯 단일 레이블 스키마에서 다음에 레이블을 달 항목의 순서를 마진, 엔트로피, BALD, 코어셋 거리로 정합니다. 두 트레이너는 Opacus를 통한 DP-SGD 학습용 dp도 받으며, 차등 프라이버시 튜토리얼이 dp 실행을 안내합니다.

스팬, 관계, 구조

이 그룹의 트레이너는 문자 오프셋이 있는 스팬, 스팬 사이의 링크, 대화 트리의 노드에 단 답, 행간 글로스를 학습합니다. hf-relation은 인코더 하나가 스팬을 태깅하고 스팬 쌍을 분류하도록 학습시킵니다. 예측된 링크는 태거가 링크의 두 스팬을 올바른 경계로 함께 찾았을 때만 찾은 것으로 계산됩니다. span_link 스키마의 학습 답이 모두 의존 트리이면 hf-relation은 트리를 디코딩하고 점수에 UAS와 LAS를 더합니다. 실행은 첫 모델 튜토리얼과 같은 단계를 따르며, 선택하는 트레이너와 스키마만 다릅니다.

LLM과 보상 모델

LLM 트레이너는 자유 텍스트 답, 선호도, 순위, 수정된 에이전트 트레이스에서 학습합니다. llm-sft와 llm-dpo는 기본적으로 LoRA 어댑터를 학습시키며, lora: {quantize: 4bit}는 QLoRA로서 베이스 모델을 4비트로 불러옵니다. reward-model은 쌍별 비교, 순위, 최선-최악 답에서 스칼라 보상 모델을 학습시키고, 각 예측은 스키마의 답 옆에 옵션별 보상을 남깁니다. prm-reward는 에이전트 트레이스의 각 단계를 correct, neutral, wrong 중 하나로 평가합니다. max_length(기본값 1,024 토큰)를 넘는 단계는 학습에도 평가에도 쓰이지 않습니다. trajectory_edit 예측은 점수가 매겨지고 저장되지만 사전 레이블로는 보이지 않으며, writeback.schemas에 trajectory_edit 스키마가 있으면 서버가 시작을 거부합니다. LLM 파인튜닝 튜토리얼이 SFT, DPO, 보상 모델, 프로세스 보상 모델, QLoRA를 다룹니다.

이미지 검출과 분할

검출기와 분할 모델은 image_annotation 스키마에서 어노테이터가 그린 도형을 학습하며, 대부분은 현미경, 지도, 스펙트로그램 스키마도 읽습니다. 검출기는 각 도형의 경계 상자로 학습하므로, 폴리곤이나 마스크 연구에서도 박스 검출기가 학습됩니다. 분할 모델은 윤곽선으로 학습하고 박스는 쓰지 않으며, 어노테이터가 점 단위로 편집할 수 있는 최대 64개 꼭짓점의 폴리곤을 예측합니다. cellpose는 클래스 없이 분할하므로, 예측된 모든 세포에는 label 파라미터가 붙고 label이 설정되지 않으면 스키마에서 가장 흔한 레이블이 붙습니다.

sam-finetune은 이미지 인코더를 고정한 채 Segment Anything의 마스크 디코더를 파인튜닝해 박스를 윤곽선으로 바꿉니다. sam-finetune 실행은 이전 검출 실행이 되쓴 박스 사전 레이블의 윤곽선을 그리므로, 보통은 writeback.include_unlabeled: true로 검출 실행을 먼저 하고 같은 스키마에서 sam-finetune 실행을 합니다. Mac에서는 torchvision-detect와 torchvision-segment가 Metal이 아니라 CPU에서 학습합니다. 비전 모델 튜토리얼이 검출, 분할, 슬라이드, 현미경, 지도, Cellpose, SAM을 안내합니다.

이미지 트레이너는 작업 디렉터리나 media_directory 안의 로컬 파일을 읽습니다. 원격 http(s) 이미지는 내려받지 않으며, 이미지가 원격이거나 없는 행은 실행에서 제외되고 예측이 붙지 않습니다. 업스트림 레퍼런스의 이미지 항목은 Potato가 이미지 경로를 읽는 필드를 알려 줍니다.

슬라이드, 현미경, 지도, 스펙트로그램

검출과 분할 트레이너는 각 이미지를 몇백 픽셀로 줄입니다. 그래서 image_annotation, microscopy, geo_annotation 스키마에서 Potato는 실행의 번들을 만들 때 큰 이미지를 타일로 자릅니다. 타일링은 .svs, .ndpi 같은 슬라이드 형식과 긴 변이 4,096픽셀 이상인 이미지에 기본으로 켜져 있습니다. 한 슬라이드의 타일은 항상 한 분할에 들어가고, 예측된 도형은 딥 줌 뷰어가 저장하는 좌표로 전체 이미지에 다시 대응됩니다. tiling 표가 모든 키를 나열하고, 비전 모델 튜토리얼은 슬라이드의 타일 크기, 겹침, 해상도를 설정합니다.

microscopy 스키마의 ROI는 검출 및 분할 트레이너와 cellpose를 학습시킵니다. ROI가 있는 각 z 슬라이스와 시점은 스키마의 기본 채널과 대비로 렌더링되며, 예측은 각 ROI의 z와 t가 붙은 ROI로 돌아옵니다. geo_annotation 스키마는 항목의 래스터 베이스맵, 즉 GeoTIFF나 범위가 있는 이미지로 학습하고, 예측은 지도가 제안으로 보여 주는 EPSG:4326의 GeoJSON으로 돌아옵니다. 베이스맵이 타일 서버에서 오는 지도에는 학습할 래스터가 없으므로, 실행은 그런 항목을 경고와 함께 제외합니다. spectrogram_annotation 스키마는 각 녹음을 스펙트로그램으로 렌더링해 torchvision-detect와 ultralytics-detect를 학습시키며, 박스는 초와 헤르츠 단위로 돌아옵니다. 업스트림 레퍼런스의 현미경과 지도와 스펙트로그램에 렌더링 세부 사항이 있습니다.

문서와 비전 언어 모델

layoutlmv3는 페이지의 단어와 단어의 위치에서 문서 레이아웃을 학습하고, vlm-sft는 이미지에 대한 답으로 비전 언어 모델을 파인튜닝합니다. Potato는 OCR을 실행하지 않으므로 각 layoutlmv3 항목에는 각 단어의 텍스트와 박스가 담긴 words 필드가 필요합니다. regions 모드의 PAGE XML 가져오기가 words를 채우며, PDF의 텍스트 레이어나 다른 OCR 도구에서 나온 단어도 같은 방식으로 동작합니다. vlm-sft는 기본적으로 LoRA 어댑터를 학습시키며, 실제 체크포인트에는 GPU가 필요합니다. region_caption 실행은 점수는 매겨지지만 게시되지 않습니다. 캡션이 설명하는 영역이 어노테이터의 답이기 때문입니다. 비전 모델 튜토리얼이 두 트레이너를 다루고, VLM 그라운딩이 grounding_eval 스키마를 다룹니다.

오디오와 음성

오디오 트레이너는 WAV나 FLAC처럼 soundfile이 여는 로컬 파일에서 녹음을 읽으며, 오디오가 URL인 항목은 제외됩니다. hf-audio-tagger는 audio_annotation 스키마에서 레이블이 달린 시간 구간을 태깅합니다. whisper-asr는 어노테이터가 수정한 전사 턴으로 Whisper를 파인튜닝하고, 기본적으로 potato transcripts --transcribe와 faster-whisper에서 쓸 모델의 CTranslate2 사본도 만듭니다. diarization은 음성 인코더(기본값은 WavLM)를 파인튜닝해 누가 언제 말하는지 찾습니다. 화자 이름은 각 녹음 안에서만 유효합니다. 스펙트로그램 박스는 이미지 검출과 분할의 검출기를 학습시킵니다. 오디오 모델 튜토리얼이 Whisper, 화자 분리, 스펙트로그램 검출, 오디오 태깅을 안내합니다.

볼륨, 포인트 클라우드, 비디오

3D 및 비디오 트레이너는 칠해 둔 볼륨, 포인트 클라우드의 직육면체, 비디오 트랙에서 학습합니다. volume-unet은 어노테이터가 CT와 MR 볼륨에 칠한 마스크로 일반 PyTorch의 3D U-Net을 학습시키며, 실제 크기의 CT에는 사실상 GPU가 필요합니다. external-3d는 train_command와 predict_command 파라미터로 직접 만든 3D 검출기를 실행하고 직육면체를 다시 읽어 옵니다. OpenPCDet와 MMDetection3D 모두 맞으며, 둘 다 GPU 호스트에서 컴파일한 CUDA 연산자가 필요합니다. video-track은 주석이 달린 트랙에서 샘플링한 프레임으로 Faster R-CNN을 파인튜닝하고, 프레임 사이의 검출을 이어 트랙으로 만듭니다. 볼륨, 포인트 클라우드, 비디오 튜토리얼이 세 트레이너를 모두 안내합니다.

과학

과학 트레이너는 화학, 분광학, 생리 신호, 로봇 에피소드에서 학습합니다. rdkit-property는 분자의 Morgan 핑거프린트와 RDKit 기술자로 분자에 대한 질문에 답하며, 선택형에는 scikit-learn 분류기를, 슬라이더에는 회귀기를 씁니다. peak-cnn은 스펙트럼의 피크 위치를 예측하며 피크 레이블이나 할당은 예측하지 않습니다. signal-cnn은 EEG, ECG 같은 신호에서 고정 길이 에포크의 단계를 정하거나 레이블이 달린 구간을 찾습니다. episode-model은 로봇 에피소드의 관절 및 센서 시계열에서 단계, 결과, 보상 곡선을 예측합니다. 에피소드의 비디오는 읽지 않습니다. 피크, 구간, 에피소드 답은 답 자체가 아니라 어노테이터가 검토할 제안으로 표시됩니다. 과학 모델 튜토리얼이 네 트레이너를 모두 안내하며, 어노테이션 쪽은 화학 구조, 스펙트럼, 시계열, 로봇 에피소드 스키마 페이지에서 다룹니다.

결정 모델

결정 모델은 질문의 각 옵션에 대한 확률을 반환하며, Potato는 결정 모델을 레이블링 엔진 소스로 쓰거나 Solo Mode의 레이블링 모델로 씁니다. 결정 모델 트레이너는 radio, select, likert, slider 스키마에서 연구의 레이블에 결정 모델을 맞추며, 레이블링 엔진이 질문하는 방식 그대로 각 질문을 던집니다. slider는 위치마다 옵션 하나가 있는 평점(최대 21개 위치)으로 질문합니다. decision-calibrate는 아무것도 학습시키지 않습니다. 이 트레이너는 Jev, OpenJev, laya-serve, Laya가 낸 확률에 보정을 맞추고, 엔진 소스가 적용하도록 보정을 calibration.json에 씁니다. decision-calibrate는 local 백엔드에서만 실행됩니다. laya-finetune은 Laya를 파인튜닝하고, openjev-finetune은 wev의 LoRA 학습으로 8B OpenJev 모델을 파인튜닝합니다. OpenJev 모델 카드는 OpenJev 학습 데이터 일부가 연구용으로만 쓸 수 있다고 밝힙니다. 상업적으로 쓰기 전에 그 조건을 확인하십시오.

추론 브리지

추론 브리지는 이미 다른 곳에서 돌아가는 모델을 쓰며 아무것도 학습시키지 않습니다. 브리지 실행은 홀드아웃 항목을 서비스로 보내고 답을 다시 읽어 옵니다. writeback.include_unlabeled: true이면 실행은 레이블이 없는 항목도 보냅니다. 그러면 그 답은 학습한 모델의 답과 똑같이 어노테이터에 대한 홀드아웃 점수, 되쓰기, 검토를 받습니다. 브리지는 설정에 API 키를 받지 않습니다. 대신 파라미터가 키가 든 서버의 환경 변수 이름을 지정합니다. label-studio-ml은 Label Studio ML 백엔드의 /predict를 호출하며 어노테이션 이벤트를 백엔드의 /webhook으로 보내지 않습니다. hf-inference와 roboflow는 local 백엔드에서만 실행됩니다. 비전 언어 모델이 점수를 반환하지 않으므로 openai-vlm-boxes의 박스에는 신뢰도가 없습니다. 내 모델 가져오기 튜토리얼이 각 브리지를 설정합니다.

더 읽어보기

• 모델 학습 개요는 어노테이션에서 사전 레이블에 이르는 루프와 Training 페이지를 설명합니다.
• 설정 페이지는 모든 model_training 키, 백엔드, 되쓰기, 라우트를 문서화합니다.
• 첫 모델 튜토리얼은 GPU 없이 sklearn-text를 처음부터 끝까지 실행합니다.
• 원격 학습 튜토리얼은 실행을 ssh로 GPU 서버에, SLURM 클러스터에, 또는 폴링 에이전트에 보냅니다.
• 모델 지원 레이블링 가이드는 직접 만든 모델의 사전 레이블이 어노테이터에게 도움이 되는 경우와 어노테이터를 고착시키는 경우를 논의합니다.
• 업스트림 모델 학습 레퍼런스에는 모든 트레이너의 파라미터 표가 있습니다.