내 어노테이션으로 모델 학습하기

v2.14.0의 새 기능

모델 학습은 어노테이터가 이미 달아 둔 레이블로 모델을 학습시키고, 학습에서 제외해 둔 항목으로 모델에 점수를 매기며, 모델의 답을 사전 레이블로 어노테이터에게 보여 주어 확인하거나 고치게 할 수 있습니다. 이 페이지는 학습 루프, 관리자 Training 페이지, 작업 유형별로 묶은 트레이너, 각 부분을 자세히 다루는 페이지와 튜토리얼을 설명합니다. 대상 독자는 자체 호스팅 Potato 서버를 운영하는 연구 책임자와 관리자입니다. Training 페이지와 sklearn-text 트레이너는 Potato 2.11부터 있었습니다. 2.14.0 버전은 트레이너 37개, GPU 서버와 SLURM 클러스터에서의 원격 학습, 실행 표의 홀드아웃 점수, Hugging Face Hub 게시를 추가합니다.

학습 루프

루프의 각 라운드는 지금까지 모인 사람의 레이블로 모델을 학습시키고, 다음 어노테이터에게 모델의 답을 출발점으로 줍니다. 루프는 여섯 단계로 돌아갑니다.

1. 어노테이션. 어노테이터는 평소처럼 항목에 레이블을 달고, Potato는 한 항목에 여러 어노테이터가 단 레이블을 하나의 레이블로 통합합니다. 기본값은 Dawid-Skene이며, 다수결도 쓸 수 있습니다.
2. 학습. 실행은 레이블이 달린 항목을 train, val, test 세트로 나누고 별도 프로세스에서 모델을 학습시킵니다. 분할은 항목 ID의 시드가 있는 해시이므로 모든 항목은 실행이 바뀌어도 같은 분할에 남습니다.
3. 점수화. 실행은 홀드아웃 val 항목과 test 항목으로 모델에 점수를 매깁니다.
4. 되쓰기. 실행의 예측은 선택한 스키마의 사전 레이블로 각 항목의 데이터에 들어갑니다. 최소 신뢰도에 못 미치는 예측과 train 분할 항목의 예측은 제외됩니다.
5. 수정. 다음 어노테이터는 모델의 답이 이미 채워진 화면을 보고 그 답을 확인하거나 바꿉니다. 검토자는 모델이 맞았는지도 기록할 수 있습니다.
6. 재학습. 다음 실행은 새 레이블로 학습하며, 검토자가 고친 항목은 모두 train 분할에 들어갑니다.

학습 켜기

모델 학습은 기본적으로 꺼져 있고, 설정 키 하나로 켭니다. 기존 설정에 이 블록을 추가합니다.

model_training:
  enabled: true

서버를 다시 시작하고 관리자 세션이나 관리자 API 키로 /admin/training을 엽니다. enabled: true가 없으면 학습 라우트가 존재하지 않습니다. 사전 레이블은 writeback.schemas에 나열한 스키마에만 나타나고 그 목록은 기본적으로 비어 있으므로, 학습을 켜도 어노테이터에게 보이는 화면은 달라지지 않습니다.

Training 페이지 맨 위의 Start a run 패널에 실행 하나를 위한 설정이 모두 들어 있습니다. Schema는 연구의 어노테이션 스키마를 나열하고, Trainer는 선택한 스키마의 유형과 항목에 맞는 트레이너를 나열하며, Runs on은 실행이 돌 수 있는 위치를 나열합니다. Parameters 필드는 JSON을 받고, 선택한 트레이너의 model_training.trainer_params 항목에서 시작합니다. 필드 아래 안내문은 해당 트레이너가 받는 모든 파라미터의 이름을 알려 줍니다. Train now를 누르면 실행이 시작됩니다. 다른 실행이 진행 중일 때 시작한 실행은 대기열에서 기다리며, 실행 표에 waiting #N으로 표시되고 Cancel run 버튼이 붙습니다.

sentiment 스키마에 대한 sklearn-text 실행 두 건. 각 실행의 점수는 모델이 학습에 쓰지 않은 리뷰로 측정했습니다

실행 표의 각 실행 ID를 누르면 /admin/training/runs/<run_id>의 실행 페이지가 열립니다. 실행 페이지에는 실행의 상태, 트레이너, 백엔드, 분할 크기, 홀드아웃 점수, 파라미터가 나오고, 이어서 실행이 기록한 모든 지표와 실행 로그가 나옵니다. 실패한 실행에는 What went wrong 섹션이 추가됩니다. 실행 페이지에서 그 실행의 val, test, train 항목을 데이터셋 버전으로 저장할 수 있고, 모델을 Hugging Face Hub에 게시할 수도 있습니다. GPU 없이 샘플 프로젝트에서 처음부터 끝까지 한 번 실행해 보려면 첫 모델 학습시키기를 따라 하십시오.

작업별 트레이너

Potato 2.14.0에는 트레이너 38개가 있으며, 각 트레이너는 Trainer 메뉴에 레지스트리 이름으로 표시됩니다. 아래 표는 트레이너가 학습하는 어노테이션 종류별로 트레이너를 묶었습니다.

마지막 행의 트레이너 다섯 개는 아무것도 학습하지 않습니다. 다섯 트레이너는 각각 홀드아웃 항목을 다른 곳에서 돌아가는 모델로 보내고, Potato는 그 답을 학습한 모델의 답과 똑같이 점수화하고 되쓰고 검토합니다. sklearn-text는 기본 Potato 설치 외에 아무것도 필요 없고, pip install "potato-annotation[train]"은 텍스트, 이미지, 오디오, LLM 트레이너에 필요한 것을 설치합니다. 설치되지 않은 트레이너는 Training 페이지에 "not installed"로 표시되며 설치 명령이 함께 나옵니다. 트레이너는 각 트레이너의 어노테이션 유형, 항목 유형, 설치 명령, 파라미터를 알려 줍니다.

실행이 돌아가는 곳

실행은 백엔드에서 실행되며, 백엔드는 Runs on 메뉴에서 실행마다 고르거나 model_training.backend로 기본값을 정합니다. Potato의 백엔드는 네 종류입니다.

• **local**은 Potato 서버에서 서브프로세스로 학습합니다. device: auto는 CUDA를 먼저, 다음으로 Apple의 Metal, 마지막으로 CPU를 선택합니다.
• **ssh**는 Potato가 키 기반 ssh로 접속하는 GPU 서버에서 학습합니다. Potato는 Potato 소스 코드를 서버로 복사하고 그곳에서 실행을 시작하며, 실행이 성공하면 모델을 다시 복사해 옵니다.
• **slurm**은 같은 방식으로 클러스터의 로그인 노드에 접속하고 sbatch로 학습 작업을 컴퓨트 노드에 제출합니다. 이 백엔드는 sbatch, squeue, scancel, scontrol만 호출하므로, srun이나 sacct가 없는 클러스터에서도 동작합니다.
• **agent**는 워크스테이션이 NAT 뒤에 있는 경우처럼 Potato가 접속할 수 없는 머신을 위한 백엔드입니다. 그 머신에서 potato training agent가 서버에 작업이 있는지 폴링하고, 모델 파일은 그 머신에 남습니다.

potato training check <backend> config.yaml은 첫 실행 전에 백엔드를 점검하며, Training 페이지의 Check 버튼도 같은 일을 합니다. 설정은 모든 백엔드 키를 나열하고, GPU 서버나 클러스터에서 학습하기는 원격 백엔드 세 종류를 단계별로 설정합니다.

홀드아웃 점수

모든 실행은 스키마의 어노테이션 유형에 맞게 고른 지표로 val 항목과 test 항목에 모델 점수를 매깁니다. 단일 레이블 분류기는 macro-F1, 스팬 태거는 스팬 F1, 박스 검출기는 IoU 0.5에서의 mAP, 전사 모델은 1에서 단어 오류율을 뺀 값을 받습니다. 실행 표는 실행마다 대표 점수 하나를 보여 주고, 실행 페이지는 val_macro_f1이나 test_f1처럼 지표 이름에 분할이 들어간 모든 지표를 나열합니다. 레이블은 있는데 예측이 없는 항목은 틀린 것으로 계산됩니다. 따라서 트레이너는 어려운 항목을 건너뛰어 점수를 올릴 수 없습니다. 트레이너가 val 항목에서 최적 체크포인트를 고르는 경우에는 val 점수가 이미 모델을 형성했으므로 대표 점수는 test 항목에서 나옵니다. sklearn-text처럼 val에서 아무것도 고르지 않는 트레이너는 대표 점수를 val 항목에서 가져옵니다. 설정은 모든 어노테이션 유형의 지표를 알려 줍니다.

사전 레이블과 모델 검토 대기열

사전 레이블은 어노테이션 화면에 채워 넣은 모델의 답으로, 어노테이터가 확인하거나 바꿉니다. 되쓰기는 pre_annotation 블록 없이도 실행의 예측을 writeback.schemas에 나열한 스키마의 사전 레이블로 바꿉니다. model_training 아래에 writeback 블록을 추가하십시오.

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

이 블록에서는 신뢰도가 0.6 미만인 sentiment 예측이 저장되기만 하고 보이지 않습니다. include_unlabeled: true는 각 실행이 아직 아무도 레이블을 달지 않은 항목에 대해서도 예측하게 합니다. 이 설정이 없으면 실행은 홀드아웃 val 항목과 test 항목에 대해서만 예측합니다. 실행의 train 분할에 있는 항목에는 사전 레이블이 붙지 않으며, 되쓰기는 사람이 단 레이블을 바꾸지 않습니다. 사전 레이블이 어노테이터의 답이 되는 때는 어노테이터가 사전 레이블을 수정하거나 다음 항목으로 넘어갈 때뿐입니다.

새 어노테이터는 모델이 선택해 둔 답을 보고 그 답을 확인하거나 바꿉니다

assignment_strategy: model_review는 사전 레이블이 붙은 항목을 신뢰도가 낮은 순서로 검토자에게 제공합니다. 검토자는 각 항목에 accept, correct, reject 중 하나의 판정을 기록합니다. 거부된 사전 레이블은 항목에서 제거되고 다시 보이지 않습니다. 이후의 모든 실행은 correct 판정을 받은 항목으로 학습하며, 그 항목으로는 모델에 점수를 매기지 않습니다. 사전 레이블은 어노테이터를 모델의 답 쪽으로 끌어당깁니다. 홀드아웃 점수가 모델을 뒷받침하게 되면 include_unlabeled를 켜고, 사전 레이블을 읽지 않고 수락하는 어노테이터는 사전 레이블이 붙은 데이터에서 검토와 무심코 승인을 구별하는 방법으로 찾으십시오. 루프 안의 모델은 프로젝트 하나에서 되쓰기, 검토, 재학습을 차례로 보여 줍니다.

어노테이션이 들어오는 대로 재학습하기

auto_retrain은 어노테이션이 들어오는 대로 실행을 자동으로 시작하며, 새 실행은 이전 실행의 사전 레이블을 대체합니다. model_training 아래에 블록을 추가하십시오.

model_training:
  enabled: true
  auto_retrain:
    enabled: true
    trainer: sklearn-text
    schemas: [sentiment]
    update_frequency: 25
    min_interval_s: 600

이 값에서는 마지막 자동 실행 이후 어노테이션이 25개 들어오고 마지막 실행이 끝난 뒤 600초가 지나면 실행이 시작됩니다. 설정은 모든 auto_retrain 키와 점검이 실행을 건너뛰는 이유를 나열하고, 루프 안의 모델은 재학습을 켜야 할 때를 보여 줍니다.

모델을 Hugging Face Hub에 게시하기

모델이 Potato 서버에 있는 성공한 실행에는 실행 페이지에 Publish to the Hugging Face Hub 양식이 있습니다. 푸시하면 모델의 가중치, 설정, 토크나이저 파일과 함께 실행에서 작성한 README.md 모델 카드가 업로드됩니다. 모델 카드에는 트레이너, 베이스 모델, 스키마, 레이블, 분할 크기, 홀드아웃 점수가 적힙니다. 실행의 예측과 학습 데이터의 사본은 서버에 남습니다.

저장소 이름을 두 번 입력하며, 두 이름이 일치할 때만 푸시가 진행됩니다. Private은 기본으로 체크되어 있고, Hugging Face 토큰은 페이지가 아니라 서버의 환경 변수(기본값은 HF_TOKEN)에서 가져옵니다. 원격 호스트나 에이전트 머신에 남아 있는 모델은 실행 페이지에서 푸시할 수 없습니다. 설정은 업로드되는 파일과 API 라우트를 나열하고, 내 어노테이션으로 LLM 파인튜닝하기는 푸시를 처음부터 끝까지 실행해 봅니다.

모델 학습과 레이블링 엔진

레이블링 엔진은 같은 트레이너를 사용합니다. 증류를 켜면(features.distill) 엔진은 엔진의 사람 레이블과 계약이 인증한 기계 레이블로 트레이너(기본값은 sklearn-text)를 이용해 모델을 학습시키고, 그 모델을 설정된 캐스케이드 앞에 trained 소스로 둡니다. 엔진의 cert 분할과 audit 분할에 있는 항목은 증류 학습 세트에 들어가지 않습니다. trained 소스는 학습 실행의 모델 디렉터리를 artifact_dir로 지정해 그 실행의 모델을 불러올 수도 있습니다. 레이블링 엔진 설정은 증류 키를 나열합니다.

모델 학습과 능동 학습

Potato의 능동 학습 기능도 연구의 레이블로 모델을 학습시키지만 모델 학습보다 목적이 좁습니다. 능동 학습은 update_frequency개의 어노테이션마다 서버 프로세스 안에서 scikit-learn 분류기를 학습시키고, 그 분류기로 가장 불확실한 항목이 먼저 오도록 대기열을 재정렬합니다. 재정렬된 대기열은 assignment_strategy: active_learning에서만 어노테이터에게 전달됩니다. 능동 학습 분류기는 그 분류기가 학습한 항목으로 점수가 매겨지며, 분류기의 예측은 어노테이터에게 보이지 않습니다.

모델 학습은 38개 트레이너 중 어느 것이든 별도 프로세스나 다른 머신에서 돌리고, 홀드아웃 항목으로 모델에 점수를 매기며, 모델의 답을 사전 레이블로 보여 줍니다. 모델 학습도 대기열 순서를 정할 수 있습니다. assignment_strategy: llm_confidence에서는 게시된 사전 레이블의 신뢰도가 가장 낮은 항목이 먼저 옵니다. hf-text-classification과 hf-image-classification의 acquisition 파라미터는 그 순서를 마진, 엔트로피, BALD, 코어셋 점수로 바꿉니다. 다음에 사람이 레이블을 달 항목을 정하려면 능동 학습을 쓰십시오. 홀드아웃 항목으로 점수를 매긴 모델, 어노테이터에게 줄 사전 레이블, 게시할 모델이 필요하면 모델 학습을 쓰십시오.

튜토리얼

각 튜토리얼은 설치부터 점수가 매겨진 실행까지 설정 하나를 처음부터 끝까지 실행합니다.

• 내 어노테이션으로 첫 모델 학습시키기는 GPU 없이 감성 연구에서 sklearn-text를 학습시킵니다.
• GPU 서버, SLURM 클러스터, NAT 뒤의 머신에서 학습하기는 ssh GPU 서버, SLURM 클러스터, 폴링 에이전트를 설정합니다.
• 사전 레이블과 재학습을 이용한 모델 인 더 루프 레이블링은 되쓰기, 검토, 획득, auto_retrain, 데이터셋 버전을 다룹니다.
• 내 어노테이션으로 LLM 파인튜닝하기는 SFT, DPO, 보상, 프로세스 보상 모델을 QLoRA와 Hub 푸시로 학습시킵니다.
• 이미지 어노테이션으로 검출 모델과 분할 모델 학습시키기는 이미지, 슬라이드, 현미경, 지도에서 검출기와 분할 모델을 학습시키고 Cellpose, SAM, LayoutLMv3, 비전 언어 모델도 다룹니다.
• 내 어노테이션으로 음성 모델과 오디오 모델 학습시키기는 Whisper, 화자 분리, 스펙트로그램 검출기, 오디오 태거를 RTTM 파일과 함께 학습시킵니다.
• 볼륨, 포인트 클라우드, 비디오에서 모델 학습시키기는 volume-unet, external-3d, video-track을 학습시킵니다.
• 분자, 스펙트럼, 신호, 로봇 에피소드에서 모델 학습시키기는 rdkit-property, peak-cnn, signal-cnn, episode-model을 학습시킵니다.
• 이미 돌리고 있는 모델의 사전 레이블과 홀드아웃 점수는 이미 서비스 중인 모델을 추론 브리지나 label-studio-ml로 연결합니다.
• Opacus를 이용한 차등 프라이버시 파인튜닝은 dp 파라미터와 Opacus로 분류기를 학습시킵니다.

더 읽어보기

• 트레이너 - 작업별로 묶은 트레이너 38개 전체
• 설정 - 모든 model_training 키, 백엔드, 라우트, 저장 경로
• 능동 학습 - scikit-learn 분류기로 대기열 재정렬하기
• LLM과 비전 사전 어노테이션 - 학습한 모델 대신 LLM이나 비전 모델이 만든 사전 레이블
• 레이블링 엔진 - 사람 레이블의 블라인드 표본으로 검증한 기계 레이블
• 사용자 시뮬레이터 - 실제 어노테이터가 시작하기 전에 루프를 시험해 보는 시뮬레이션 어노테이터

구현 세부 사항은 소스 문서를 참고하십시오.