본문으로 건너뛰기

이미지 어노테이션으로 탐지와 분할 모델 학습하기

연구의 박스로 탐지기를 파인튜닝하고, 예측한 박스를 사전 레이블로 어노테이터에게 보여 주고, 수정본으로 재학습하며, 실행을 슬라이드와 세포에 맞춥니다.

v2.14.0의 새 기능

이 튜토리얼은 연구의 바운딩 박스로 객체 탐지기를 학습시키고, 탐지기의 박스를 다음 어노테이터에게 수정할 사전 레이블로 보여 줍니다. 대상 독자는 image_annotation 스키마를 가진 연구 책임자로, 첫 모델 학습시키기를 읽었거나 관리자 Training 페이지가 익숙한 사람입니다. 전반부는 torchvision-detect로 완전한 루프 하나(이미지의 박스, 학습 실행, 되쓰기, 수정, 두 번째 실행)를 돌리며, 그 모든 단계는 노트북 CPU에서 실행되었습니다. 후반부는 루프를 YOLO, 윤곽선, SAM 정제, 이미지 전체 클래스, 전체 슬라이드, 현미경 이미지, 지도, 세포, 문서 페이지, 비전-언어 모델에 맞추며 각각 한 섹션씩 다룹니다.

비전 트레이너 설치

torchvision-detect는 torchvision의 Faster R-CNN 탐지기를 파인튜닝합니다. 이 트레이너에는 torch와 torchvision이 필요합니다. torch는 수 기가바이트를 내려받아야 하므로 Potato는 기본 설치에서 둘 다 뺍니다. 학습하는 머신에 비전 extra를 설치하십시오.

bash
pip install "potato-annotation[train-vision]"

같은 extra가 torchvision-segment, hf-image-classification, sam-finetune, layoutlmv3, vlm-sft도 다룹니다. 패키지가 없는 트레이너는 Training 페이지에 "not installed"로 표시되며, 패키지를 설치하는 명령도 함께 나옵니다.

아래의 작은 프로젝트에는 GPU가 필요하지 않습니다. Apple silicon Mac에서 torchvision-detect와 torchvision-segment는 Metal(mps)이 아니라 CPU에서 학습하며, 실행 로그는 "torchvision-detect does not run on Apple's Metal (mps) with this torch; using the CPU"라는 경고로 전환을 기록합니다. Potato 팀의 측정에서 기본 이미지 크기의 Metal 학습 스텝 하나는 CPU의 전체 에포크 하나보다 오래 걸렸습니다. 더 큰 이미지나 더 큰 연구에서는 원격 학습에 설명된 대로 GPU 서버에서 학습시키십시오.

이미지 프로젝트 설정

프로젝트에는 이미지, 이미지를 나열하는 데이터 파일, 설정의 세 가지가 필요합니다. Potato는 기본적으로 <task_dir>/media/를 URL 경로 /media/로 제공하므로, 이미지를 프로젝트 폴더 안의 media라는 폴더에 넣으십시오. 설정에서 media_directory로 폴더를 지정하면 다른 폴더도 쓸 수 있습니다.

text
shapes/
  config.yaml
  data/images.jsonl
  media/img_001.png
  media/img_002.png
  ...

data/images.jsonl의 각 줄은 ID와 이미지의 URL 경로를 가진 항목 하나입니다.

json
{"id": "img_001", "image_url": "/media/img_001.png"}

설정은 bbox 도구와 레이블 두 개를 가진 image_annotation 스키마 하나를 정의하고, 되쓰기와 함께 모델 학습을 켭니다. 이 설정은 python -m potato.validate_cli --strict를 통과합니다.

yaml
annotation_task_name: "Shape detection (model training)"
task_dir: "."
data_files:
  - "data/images.jsonl"
item_properties:
  id_key: "id"
  text_key: "image_url"
output_annotation_dir: "annotation_output"
 
require_password: false
admin_api_key: "demo-admin-key"
num_annotators_per_item: 1
 
annotation_schemes:
  - annotation_type: "image_annotation"
    name: "objects"
    description: "Draw a box around every circle and every square."
    source_field: "image_url"
    tools: ["bbox"]
    labels:
      - name: "circle"
        color: "#e6194b"
      - name: "square"
        color: "#4363d8"
 
model_training:
  enabled: true
  writeback:
    schemas: ["objects"]
    include_unlabeled: true
    min_confidence: 0.5

네 가지 설정이 루프를 결정합니다.

  • **source_field: "image_url"**은 이미지 위젯과 트레이너에게 어느 항목 필드가 이미지를 담는지 알려 줍니다.
  • **num_annotators_per_item: 1**은 모든 이미지에 어노테이터를 한 명씩 배정하므로, 시드 레이블이 가능한 한 많은 서로 다른 이미지를 덮습니다.
  • **writeback.include_unlabeled: true**는 각 실행이 아직 아무도 레이블을 달지 않은 이미지에서 예측하게 합니다. 이 설정이 없으면 실행은 홀드아웃 val과 test 이미지에서만 예측하는데, 그 이미지에는 이미 사람의 박스가 있습니다.
  • **writeback.min_confidence: 0.5**는 이미지의 박스들의 평균 점수가 0.5 미만이면 그 이미지의 예측을 보류합니다. 최소 신뢰도는 이미지 전체에 적용되므로 어노테이터는 한 이미지의 박스를 절반만 보는 일이 없습니다.

프로젝트 폴더 안에서 서버를 시작하십시오.

bash
potato start config.yaml -p 8000

시드 세트에 레이블 달기

torchvision-detect는 train 분할에 어노테이션된 이미지가 20장보다 적으면 학습을 거부하고, 기본 분할은 레이블이 달린 이미지의 70%를 train에 둡니다. 이미지 30장 이상에 레이블을 다십시오. 객체가 다양하면 더 많이 다십시오. http://localhost:8000에서 박스를 직접 그립니다. 박스가 없는 이미지는 학습에서 제외되는데, 탐지기는 객체가 없는 이미지와 아무도 끝내지 않은 이미지를 구분할 수 없기 때문입니다. 제출하는 이미지에서는 모든 객체를 그리십시오.

사람이 레이블을 달기 전에 루프를 시험해 보려면 사용자 시뮬레이터가 정답 파일에서 박스를 그릴 수 있습니다. 정답 항목마다 이미지 ID와 스키마의 도형이 정규화된 좌표로 들어 있습니다.

json
[
  {"id": "img_001", "objects": [
    {"type": "bbox", "label": "circle",
     "coordinates": {"x": 0.158, "y": 0.849, "width": 0.106, "height": 0.146}}
  ]}
]
bash
python -m potato.simulator --server http://localhost:8000 --users 3 \
  --strategy gold_standard --competence good=1.0 --max-annotations 20 \
  --gold-file data/gold.json --sequential --fast-mode --no-export

시뮬레이터는 정답 박스마다 몇 픽셀의 흔들림을 주어 다시 그리며, good 수준에서는 신중한 어노테이터가 가끔 그러듯 일부 객체를 놓치거나 잘못 레이블링합니다. 합성 이미지 80장으로 한 시험에서 시뮬레이션된 어노테이터 세 명이 이미지 60장에 약 1초 만에 레이블을 달았습니다.

torchvision-detect 학습

http://localhost:8000/admin을 열고 관리자 키 demo-admin-key를 입력한 뒤 http://localhost:8000/admin/training을 여십시오. 스키마로 objects를, 트레이너로 torchvision-detect를 고르고, Parameters는 비워 둔 채 Train now를 누르십시오. 같은 실행을 스크립트에서 시작하려면 다음과 같이 합니다.

bash
curl -X POST -H "X-API-Key: demo-admin-key" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "torchvision-detect", "schemas": ["objects"]}'

실행은 torchvision의 COCO 가중치에서 시작하며, 스키마의 레이블 두 개에 맞춰 탐지기에 새 박스 헤드를 붙입니다. torch는 첫 실행 때 COCO 가중치를 torch의 캐시로 내려받습니다. 기본값은 작은 fasterrcnn_mobilenet_v3_large_fpn 아키텍처, 15 에포크, 스텝당 이미지 4장이고, val mAP가 개선되지 않은 채 4 에포크가 지나면 조기 종료합니다. 모든 도형은 그 도형의 바운딩 박스로 학습되므로, 어노테이터가 다각형을 그린 연구도 박스 탐지기를 학습시킵니다. 이미지당 어노테이터가 여럿이면, 두 사람의 박스는 정확히 일치하는 일이 드물기 때문에 실행은 model_training.aggregation이 그 이미지에서 고른 하나의 완전한 답으로 학습합니다.

우리가 사용한 Apple M4 Pro CPU에서 320×240 픽셀의 학습 이미지 37장은 약 106초 만에 학습되었고 실행은 5 에포크 뒤에 멈췄습니다. 실행의 파일은 annotation_output/training/runs/<run_id>/에 저장되며, 학습된 탐지기는 artifacts/model/detector.pt에 있습니다. 실행의 설정과 실행이 사용한 장치는 artifacts/model_card.json에 있습니다.

홀드아웃 점수 읽기

모든 실행은 탐지기가 한 번도 학습하지 않은 이미지로 탐지기에 점수를 매깁니다. image_annotation 스키마의 대표 지표는 map_50이며, 예측 박스가 어노테이션된 객체의 바운딩 박스와 IoU 0.5 이상으로 겹칠 때 일치로 치는 COCO 평균 정밀도입니다. 실행 페이지에는 IoU 임계값 0.5에서 0.95까지의 평균인 map_50_95도 기록됩니다. 한 객체에 대한 두 어노테이터의 박스는 IoU 0.9로 겹치는 일이 드물므로, 더 엄격한 임계값은 부분적으로 사람들이 얼마나 일관되게 그리는지를 측정합니다. 그래서 Potato는 0.5 임계값을 앞세웁니다. 바운딩 박스 일치도 측정은 그 일관성을 직접 확인하는 방법을 보여 줍니다.

탐지기는 val 점수가 가장 좋은 에포크의 체크포인트를 유지하므로, test 분할에 이미지가 있으면 대표 지표는 test 분할에서 나옵니다. 실행 표는 Held-out score 열에 대표 지표를 보여 줍니다. 실행 페이지에는 n_train, n_boxes, 각 분할의 크기와 커버리지, val과 test에서 어노테이션된 객체와 예측된 객체의 수가 나옵니다. 색깔 있는 원과 사각형의 합성 이미지 80장으로 한 시험 실행에서 탐지기는 test map_50에서 0.99점을 받았습니다. 합성 도형은 실제 객체보다 훨씬 찾기 쉬우므로 점수는 자신의 이미지로 판단하십시오.

사전 레이블 확인

실행이 성공하면 Potato는 탐지기의 박스를 대상이 되는 각 이미지의 predictions 필드에 씁니다. GET /admin/training/api/status는 응답의 writeback 필드에 결과를 보고하며, 사전 레이블을 받은 이미지는 n_written으로, 이미지가 보류된 이유마다 개수를 세어 보여 줍니다. 예를 들어 min_confidence에 못 미친 이미지는 n_skipped_low_confidence, 실행이 학습에 쓴 이미지는 n_skipped_train_split입니다. train 분할 이미지는 사전 레이블을 받지 않는데, 모델이 자기 학습 데이터에서 보이는 신뢰도는 새 이미지에 대해 아무것도 알려 주지 않기 때문입니다.

새 사용자 이름으로 http://localhost:8000에 로그인하십시오. 되쓰기 점검을 통과한 레이블 없는 이미지는 탐지기의 박스가 이미 그려진 채로 열립니다. 각 박스는 source: ai와 confidence로서의 탐지기 점수와 함께 저장됩니다. 어노테이터는 박스를 옮기거나 크기를 바꾸고, 레이블을 바꾸고, 잘못된 탐지를 삭제하고, 탐지기가 놓친 객체를 그립니다. 박스는 어노테이터가 박스를 편집하거나 다음 이미지로 넘어갈 때 어노테이터의 답이 됩니다. 어노테이터가 이미지를 보기만 하는 동안에는 사전 레이블이 저장되지 않습니다. 모델 검토 대기열은 사전 레이블이 달린 이미지를 신뢰도가 낮은 순서로 제공하며, 검토자의 correct 판정은 그 이미지를 이후 모든 실행의 train 분할에 넣습니다.

수정된 박스로 재학습

수정된 이미지는 각각 다음 실행을 위한 사람의 레이블이 됩니다. 어노테이터가 사전 레이블이 달린 이미지 한 묶음을 처리하고 나면 Training 페이지에서 torchvision-detect 실행을 한 번 더 시작하십시오. 새 실행은 각 이미지에 대한 이전 실행의 예측을 대체하며, 새 실행이 학습에 쓴 이미지의 사전 레이블은 내려집니다.

클릭 없이 재학습하려면 auto_retrain 블록을 추가하십시오. 이 조각은 위의 model_training 블록을 확장하며, 새 어노테이션 25개마다, 최대 10분에 한 번 실행을 시작합니다.

yaml
model_training:
  enabled: true
  auto_retrain:
    enabled: true
    trainer: torchvision-detect
    schemas: [objects]
    update_frequency: 25
    min_interval_s: 600
  writeback:
    schemas: [objects]
    include_unlabeled: true
    min_confidence: 0.5

사전 레이블은 어노테이터를 모델의 박스에 앵커링합니다. 홀드아웃 점수가 사전 레이블을 뒷받침할 때 어노테이터에게 되쓰기를 켜십시오. 어노테이터가 박스를 보지 않고 수락하는지 확인하는 방법은 무심코 수락된 사전 레이블 탐지를 참고하십시오.

Ultralytics YOLO로 더 빠른 탐지

ultralytics-detect는 같은 박스로 COCO 사전 학습 체크포인트(기본값은 yolo11n.pt)에서 Ultralytics YOLO 탐지기를 학습시킵니다. YOLO는 torchvision-detect보다 빠르게 학습하고 예측하며, 사전 레이블은 같은 편집 가능한 박스입니다. Ultralytics는 AGPL-3.0 라이선스이며, Ultralytics로 학습하고 배포한 모델에는 AGPL의 조건이 따릅니다. Ultralytics는 비공개 용도를 위한 별도의 엔터프라이즈 라이선스를 판매합니다. Potato의 extras에는 Ultralytics가 없으므로 패키지를 직접 설치하십시오.

bash
pip install ultralytics

Potato는 실행 때마다 라이선스를 확인하도록 요청합니다. Training 페이지는 확인 창을 보여 주고, API 실행은 요청 본문에 "accept_licence": true가 필요하며, 자동 재학습에는 auto_retrain.accept_licence: true가 필요합니다. 확인이 없으면 API는 HTTP 400, needs_licence_ack: true, 메시지 "ultralytics-detect is licensed AGPL-3.0"으로 실행을 거부합니다. 아래 요청은 라이선스를 확인하고 실행을 시작합니다.

bash
curl -X POST -H "X-API-Key: demo-admin-key" -H "Content-Type: application/json" \
  http://localhost:8000/admin/training/api/runs \
  -d '{"trainer": "ultralytics-detect", "schemas": ["objects"], "accept_licence": true}'

실행 중에 트레이너는 Ultralytics의 사용 분석, Ultralytics HUB, 실험 추적기 연동, 자동 패키지 설치를 끕니다. 변경은 실행 프로세스의 메모리에서만 적용되며 사용자의 Ultralytics 설정 파일은 그대로 남습니다. 체크포인트는 ~/.cache/potato/ultralytics로 내려받습니다. 기본값은 640픽셀에서 50 에포크이고 10 에포크 뒤에 조기 종료합니다.

박스 대신 윤곽선

torchvision-segment는 다각형, 타원, 자유곡선, 브러시 마스크 윤곽선으로 torchvision Mask R-CNN을 학습시킵니다. 박스는 분할 학습에서 제외되는데, 박스는 어느 픽셀이 객체에 속하는지 알려 주지 않기 때문입니다. 어노테이터에게 polygon이나 brush 같은 윤곽선 도구를 주십시오. 이미지 분할 마스크 어노테이션 방법은 각 도구가 언제 맞는지 다룹니다.

예측된 각 마스크는 꼭짓점이 최대 64개인 다각형으로 추적되므로 어노테이터는 사전 레이블을 점 단위로 수정합니다. 마스크가 조각으로 나오면 가장 큰 조각을 유지합니다. 기본 score_threshold는 탐지기의 0.25가 아니라 0.5입니다. Mask R-CNN이 한 객체에 대해 내놓는 두 번째 추측은 0.25에서 0.6 사이의 점수를 받으며, 추측 하나하나가 어노테이터가 삭제해야 할 도형 하나가 됩니다. 홀드아웃 점수는 예측된 다각형을 어노테이션된 윤곽선과 비교합니다. Mac에서 torchvision-segment는 CPU에서 학습합니다. torch 2.8에서 Potato 팀은 256픽셀 이미지에서 학습 스텝 하나가 Metal에서 57초, CPU에서 2.3초 걸리는 것을 측정했습니다. 실제 연구에는 GPU 서버를 쓰십시오. ultralytics-segment는 YOLO 쪽 짝(yolo11n-seg.pt)이며, 같은 64개 꼭짓점 다각형과 같은 AGPL-3.0 라이선스 확인을 갖습니다.

sam-finetune으로 박스를 윤곽선으로 바꾸기

박스는 빨리 그리지만 윤곽선은 느리게 그립니다. sam-finetune은 Segment Anything(SAM)의 마스크 디코더를 파인튜닝하여, 박스를 어노테이터가 그렸을 윤곽선으로 바꿉니다. 이미지 인코더는 고정되고 각 이미지의 임베딩은 한 번만 계산되므로 에포크 하나의 비용이 적습니다. 학습은 어노테이션된 각 윤곽선을 그 윤곽선의 바운딩 박스로 프롬프트합니다. 실행은 각 프롬프트 박스를 최대 box_jitter(기본값 5%)만큼 옮기고 크기를 바꾸므로, 디코더는 탐지기의 박스만큼 느슨한 박스에서 학습합니다.

sam-finetune은 박스를 정제하므로 출발점이 될 박스가 필요합니다. 한 스키마에서 일반적인 순서는 실행 두 번입니다.

  1. torchvision-detect나 ultralytics-detect를 writeback.include_unlabeled: true로 실행하여 레이블 없는 이미지에 박스 사전 레이블이 달리게 합니다.
  2. 같은 스키마에서 sam-finetune을 실행합니다. 박스 사전 레이블은 각각 다각형 사전 레이블이 되고, 다각형이 박스를 대체합니다.

SAM이 학습할 윤곽선이 스키마에 필요하므로, bbox 옆에 윤곽선 도구를 어노테이터에게 주십시오. 홀드아웃 이미지에서는 어노테이터 자신의 박스가 프롬프트이므로 val_mask_iou는 박스가 맞을 때 윤곽선의 평균 IoU를 보고합니다. 그 홀드아웃 예측은 다른 어노테이터의 답으로 만들어졌기 때문에 점수만 매기고 저장하거나 게시하지 않습니다. 되쓰기 보고서는 홀드아웃 예측을 n_skipped_heldout_only로 셉니다. 기본 체크포인트는 facebook/sam-vit-base(Apache-2.0)입니다. 파인튜닝된 디코더는 사전 레이블만 제공합니다. 이미지 도구의 클릭하여 분할은 브라우저에서 별도의 ONNX 가중치를 실행하며, sam-finetune 실행이 그 가중치를 대체하지는 않습니다.

이미지 전체 분류

이미지 전체에 대한 질문, 예를 들어 사진에 어떤 동물이 있는지 묻는 radio 스키마에는 탐지기가 아니라 분류기를 쓰십시오. hf-image-classification은 Hugging Face의 AutoModelForImageClassification이 불러오는 모든 모델(ViT, DeiT, BEiT, ConvNeXt, Swin, DINOv2 등)을 파인튜닝합니다. 기본 모델은 google/vit-base-patch16-224-in21k입니다. 트레이너는 기본적으로 학습 이미지를 무작위로 뒤집습니다. 이미지 속 텍스트나 좌우처럼 뒤집으면 레이블이 바뀌는 경우에는 Parameters에서 flip을 false로 설정하십시오. lora: true는 모든 가중치 대신 LoRA 어댑터와 분류 헤드를 학습시킵니다.

선택형 스키마는 레이블이 달린 항목의 80% 이상이 .jpg, .jpeg, .png, .bmp, .webp, .tif, .tiff, .gif로 끝나는 이미지 경로를 가지면 이미지 코퍼스로 취급됩니다. 이런 코퍼스에서 벡터화기를 지정하지 않은 sklearn-text는 CLIP 이미지 임베딩에 선형 분류기를 맞춥니다. CLIP 기준선에는 GPU가 필요 없고 pip install "potato-annotation[embeddings]" pillow만 있으면 됩니다.

이미지 경로와 원격 이미지

이미지 트레이너는 스키마의 source_field가 지정하는 필드를 읽습니다. source_field가 없으면 트레이너는 image_url, image, image_path, file_name, url, path와 오디오 및 비디오 대응 필드 중 비어 있지 않은 첫 항목 필드를 가져갑니다. 이미지는 프로젝트 안의 로컬 파일이어야 합니다.

  • 상대 경로는 task_dir을 기준으로 해석되며, 파일이 task_dir 아래에 없으면 media_directory를 기준으로 해석됩니다.
  • /media/img_001.jpg 같은 URL 경로는 media_directory를 기준으로 해석됩니다. 어노테이션 페이지도 같은 위치에서 이미지를 불러옵니다.
  • 절대 경로, ../, 심볼릭 링크로 작업 디렉터리와 media_directory 바깥에 놓인 파일은 경고와 함께 제외됩니다.
  • 원격 http(s) 이미지는 내려받지 않습니다. 실행은 이미지가 원격이거나 없는 모든 항목을 제외하고, 실행 로그가 그 수를 알려 주며, 그 항목들은 예측을 받지 않습니다.

이미지로 학습하려면 원격 이미지를 media_directory로 내려받으십시오. 비전 형식 페이지와 potato import는 기존 이미지 데이터셋을 프로젝트로 가져오는 방법을 다룹니다.

전체 슬라이드와 기타 큰 이미지

탐지 및 분할 트레이너는 각 이미지를 수백 픽셀로 리사이즈하며, 10만 픽셀짜리 병리 슬라이드나 위성 장면의 객체는 그 크기에서 사라집니다. 그래서 image_annotation, microscopy, geo_annotation 스키마에서는 Potato가 실행의 학습 데이터를 만들 때 큰 이미지를 타일로 자릅니다. 타일링은 슬라이드 형식(.svs, .ndpi, .mrxs, .scn 등)과 긴 변이 4,096픽셀 이상인 이미지에 자동으로 적용됩니다. 슬라이드에는 openslide가 필요합니다.

bash
pip install "potato-annotation[wsi]"

학습은 어노테이션된 객체가 있는 타일과 빈 타일의 표본을 쓰며, 각 객체는 그 객체의 타일에 맞게 잘립니다. 예측은 이미지당 최대 max_predict_tiles까지 조직 위의 모든 타일을 덮습니다. 각 이미지의 분할은 이미지를 자르기 전에 결정되므로 한 슬라이드의 타일이 두 분할에 나뉘어 들어가는 일이 없습니다. 타일 예측은 전체 이미지로 다시 합쳐지며, 겹친 두 타일이 모두 찾은 객체는 한 번만 유지됩니다. 사전 레이블은 딥 줌 뷰어가 저장하는 것과 같은 전체 이미지 좌표를 씁니다. 홀드아웃 점수는 전체 이미지에서 계산됩니다. 원격 백엔드는 슬라이드가 아니라 타일을 내려받습니다.

설정은 model_training.tiling 아래에 있습니다. 이 조각은 40x 슬라이드를 1,024픽셀 타일로 20x에서 학습시킵니다.

yaml
model_training:
  enabled: true
  tiling:
    tile_size: 1024
    overlap: 128
    downsample: 2

overlap은 객체만큼 크게 유지하십시오. 객체가 더 크면 타일마다 조각으로 발견됩니다. 슬라이드의 해상도를 기록하는 슬라이드에서는 mpp가 타일 픽셀당 마이크론을 설정하며 downsample보다 우선합니다. 일부 슬라이드에서는 두 가지 설정에 주의가 필요합니다. 학습용 빈 타일은 어노테이션된 이미지의 모든 객체가 그려졌다고 가정하므로, 어노테이터가 슬라이드의 일부 영역만 그렸다면 background: 0으로 설정하십시오. 조직은 슬라이드 썸네일에 대한 Otsu 임계값으로 감지되므로 빈 유리가 없는 슬라이드는 더 옅은 절반을 잃으며, tissue_threshold: 0은 모든 타일에서 예측합니다. tiling 표는 모든 키와 기본값을 나열합니다.

현미경 이미지와 지도

microscopy 스키마의 ROI는 torchvision-detect, ultralytics-detect, torchvision-segment, ultralytics-segment, cellpose를 학습시킵니다. ROI가 있는 각 z-슬라이스와 시점은 스키마의 기본 채널과 대비로 렌더링되어 별도의 학습 이미지가 됩니다. 렌더러는 뷰어가 쓰는 합성기입니다. 아직 아무것도 그려지지 않은 이미지는 뷰어가 열리는 위치인 가운데 z-슬라이스와 첫 시점에서 예측됩니다. 예측은 각 ROI의 z와 t를 가진 현미경 ROI로 돌아옵니다. 세포 분류는 도형이 아니라 레이블 이미지를 가리키므로, 트레이너는 세포 분류를 건너뜁니다.

geo_annotation 스키마의 피처는 항목의 래스터 베이스맵에서 같은 탐지 및 분할 트레이너를 학습시킵니다. GeoTIFF는 파일 자체 태그에 있는 변환과 EPSG 코드로 배치되며, 투영된 경우 pyproj로 재투영됩니다. 범위가 있는 일반 이미지는 경도와 위도로 배치됩니다. 다각형, 직사각형, 선, 점은 래스터 위의 도형이 되며 다각형의 구멍은 채워집니다. 예측은 source: model을 가진 EPSG:4326의 GeoJSON 피처로 돌아옵니다. 지도는 피처를 제안으로 제공하며, 제안은 어노테이터가 하나를 편집하거나 수락할 때에만 답으로 셉니다. 베이스맵이 타일 서버나 GeoJSON 윤곽선인 지도에는 학습할 래스터가 없으므로, 실행은 그런 항목을 경고와 함께 제외합니다.

cellpose로 세포

cellpose는 image_annotation이나 microscopy 스키마의 세포 또는 핵 윤곽선으로 Cellpose를 파인튜닝합니다. Cellpose 3이나 4를 따로 설치하십시오.

bash
pip install cellpose

기본 베이스 모델은 cyto3입니다. nuclei와 cyto2도 Cellpose 3에서 작동하고, cpsam은 Cellpose 4에서 작동합니다. Cellpose 자체의 추정이 어긋나면 diameter를 일반적인 세포 지름(픽셀)으로 설정하십시오. Cellpose는 클래스 없이 분할하므로 예측된 모든 세포는 label 파라미터를 받으며, label이 설정되지 않으면 스키마에서 가장 흔한 레이블을 받습니다. 클래스의 모양이 서로 다르면 레이블마다 모델을 하나씩 학습시키십시오. 예측된 각 마스크는 세포의 평균 확률을 사전 레이블의 신뢰도로 하는 다각형으로 돌아옵니다. cellpose는 train 분할에 어노테이션된 이미지가 5장만 있으면 되며, 탐지기는 20장이 필요합니다. Cellpose의 코드는 BSD-3-Clause이며, 가중치는 Cellpose 저자들의 조건에 따라 저자들에게서 옵니다.

스펙트로그램

spectrogram_annotation 스키마의 박스는 스펙트로그램 이미지로 렌더링된 각 녹음에서 torchvision-detect와 ultralytics-detect를 학습시킵니다. 오디오 모델 튜토리얼은 렌더링 설정과 트레이너가 읽는 녹음 형식과 함께 스펙트로그램 탐지를 처음부터 끝까지 다룹니다.

layoutlmv3로 문서 레이아웃

layoutlmv3는 LayoutLMv3를 파인튜닝하여, 페이지의 단어와 단어의 위치로부터 어노테이터가 페이지 이미지에 그리는 영역을 찾습니다. 영역은 제목, 표, 합계처럼 레이블이 달린 모든 블록입니다. Potato는 OCR을 실행하지 않으므로 각 항목은 페이지 이미지의 픽셀 좌표나 0에서 1 사이의 좌표로 된 박스와 함께 페이지의 단어를 가져야 합니다.

json
{"id": "page_001", "image": "pages/page_001.png",
 "words": [{"text": "INVOICE", "bbox": [40, 52, 180, 82]},
           {"text": "Total", "bbox": [300, 700, 380, 730]}]}

regions 모드의 PAGE XML 가져오기는 파일의 Word 요소에서 words를 채웁니다. PDF의 텍스트 레이어나 다른 OCR 도구의 단어도 같은 방식으로 작동합니다. 각 단어는 그 단어의 중심이 놓인 영역으로 레이블이 달리고, 예측된 단어는 영역으로 다시 합쳐지며, 각 영역은 그 영역의 단어를 둘러싸는 박스 사전 레이블이 됩니다. 홀드아웃 점수는 박스 mAP입니다. 예측된 박스는 영역의 단어에서 끝나므로, 단어보다 훨씬 크게 그려진 영역은 박스가 받아야 할 점수보다 낮게 평가됩니다.

LayoutLMv3 가중치는 CC BY-NC-SA 4.0 라이선스이며 상업적 용도로는 쓸 수 없습니다. YOLO 트레이너와 마찬가지로 Training 페이지는 실행 전에 확인을 요청하고, API 실행에는 accept_licence: true가 필요하며, 자동 재학습에는 auto_retrain.accept_licence: true가 필요합니다.

vlm-sft로 비전-언어 모델

vlm-sft는 이미지에 대한 어노테이터의 답으로 비전-언어 모델을 파인튜닝하며, 기본적으로 LoRA 어댑터를 쓰고 기본 모델은 Qwen/Qwen2.5-VL-3B-Instruct입니다. 트레이너는 네 가지 스키마에서 학습합니다.

스키마학습 예시 하나당모델이 만들도록 학습하는 것
이미지 항목의 text항목스키마의 질문에 대한 어노테이터의 답
region_caption캡션이 달린 영역빨간 박스로 그려진 영역의 캡션
grounding_eval답이 달린 표현JSON, 점, 또는 {"absent": true}로 된 영역
gui_trajectory클릭이 있고 correct로 판정된 단계{"point": [x, y]} 형태의 클릭

좌표는 이미지의 0에서 1,000까지의 격자 위에 있으므로 어떤 체크포인트든 예시에서 이 형식을 배울 수 있습니다. 텍스트 실행은 생성된 답을 텍스트 사전 레이블로 게시합니다. 그라운딩 실행은 모든 표현에 대해 영역이나 부재를 게시하며, VLM 그라운딩이 grounding_eval 스키마를 다룹니다. GUI 궤적 실행은 모델이 클릭할 위치로 각 단계의 판정을 제안하며, 컴퓨터 사용 에이전트 평가가 GUI 트레이스를 다룹니다. 캡션 실행은 토큰 F1과 BLEU-4로 점수를 매기지만 게시하지는 않는데, 캡션이 달린 영역은 어노테이터의 답이기 때문입니다.

실제 체크포인트에는 GPU가 필요합니다. Potato 팀이 Mac의 Metal GPU에서 이미지 26장으로 Qwen/Qwen3-VL-2B-Instruct를 LoRA로 2 에포크 학습시키는 데 46초가 걸렸습니다. Parameters의 {"lora": {"quantize": "4bit"}}는 4비트 기반 가중치 위에서 QLoRA 어댑터를 학습시킵니다. 고른 모델의 라이선스를 확인하십시오. Qwen2.5-VL-3B는 Qwen 연구 라이선스를 따르고 7B 모델은 Apache-2.0입니다. LLM 파인튜닝 튜토리얼은 LoRA, QLoRA, Hugging Face Hub에 모델 게시하기를 다룹니다.

더 읽어보기

참고문헌

  • Ren, S., He, K., Girshick, R., and Sun, J. (2017). Faster R-CNN: Towards Real-Time Object Detection with Region Proposal Networks. IEEE Transactions on Pattern Analysis and Machine Intelligence, 39, 1137–1149. doi:10.1109/TPAMI.2016.2577031
  • He, K., Gkioxari, G., Dollár, P., and Girshick, R. (2017). Mask R-CNN. 2017 IEEE International Conference on Computer Vision (ICCV), 2980–2988. doi:10.1109/ICCV.2017.322
  • Kirillov, A., Mintun, E., Ravi, N., Mao, H., Rolland, C., Gustafson, L., Xiao, T., Whitehead, S., Berg, A. C., Lo, W.-Y., Dollár, P., and Girshick, R. (2023). Segment Anything. 2023 IEEE/CVF International Conference on Computer Vision (ICCV), 3992–4003. doi:10.1109/ICCV51070.2023.00371
  • Stringer, C., Wang, T., Michaelos, M., and Pachitariu, M. (2021). Cellpose: a generalist algorithm for cellular segmentation. Nature Methods, 18, 100–106. doi:10.1038/s41592-020-01018-x
  • Huang, Y., Lv, T., Cui, L., Lu, Y., and Wei, F. (2022). LayoutLMv3: Pre-training for Document AI with Unified Text and Image Masking. Proceedings of the 30th ACM International Conference on Multimedia, 4083–4091. doi:10.1145/3503161.3548112