← 종합 인덱스 | 말(馬) BestView·Keypoints·Segmentation·Detection 추론 워커 — 역분석

말(馬) BestView·Keypoints·Segmentation·Detection 추론 워커 — 역분석

대상 이미지(삭제됨): ghcr.io/sanchit2843/horse-bestview-keypoints-segmentation-detection-dino-worker:v6 digest sha256:3a796a4276168afedb8b18c40e4fb72f3d16445a14c20ca3b078ab4699151b26, 5.5GB, 2026-06-20 빌드 근거: 이미지 빌드 히스토리(rtx3-docker-leftover-detail.txt 1~90행)만으로 역분석. 소스 본문은 확보 못 함(이미지 삭제, ghcr 401). 따라서 "구조·파일·모델·실행방식"은 확실, 알고리즘 세부는 추정으로 구분 표기.

한 줄 요약

말 사진/영상을 입력받아 ① 말 탐지(detection) → ② 분할(segmentation) → ③ 자세 키포인트(pose keypoints) → ④ "베스트 뷰" 선별(best-view 분류) 까지 한 번에 수행하는, DINOv3 + YOLO 기반 멀티모델 추론 파이프라인. 상시 떠 있는 REST 서버가 아니라, 잡(run) 단위로 큐에서 작업을 받아 처리하는 클라우드 워커(Vast.ai cloud_docker 실행 모드).

1. 무엇을 하는 서버인가 (기능)

이름이 곧 기능 명세다: horse · bestview · keypoints · segmentation · detection · dino.

Detection — 프레임에서 말의 위치(바운딩박스)를 찾는다.
Segmentation — 말의 픽셀 단위 실루엣(마스크)을 분리한다.
Keypoints — 말의 신체 관절/부위 포인트(자세 추정, animal pose)를 찍는다.
BestView — 여러 프레임/뷰 중 "가장 좋은 한 장"(예: 깔끔한 측면 전신뷰)을 골라낸다. DINOv3 특징 + 학습된 분류기로 판정.
(dino) — DINOv3 ViT를 공통 특징 추출 백본으로 사용.

→ 전형적 용도(추정): 말 체형/외형 분석·정렬용 자동 전처리. 예) 말 매물 사진에서 최적 측면컷 자동 선정 + 마스킹 + 부위 측정용 키포인트 산출, 또는 컨포메이션(체형) 평가·바이오메카닉스 파이프라인의 프런트엔드.

2. 모델 구성 (4종 — 멀티모델 앙상블 파이프라인)

가중치 파일	정체	역할(추정)
`weights/horse22_yolo26x_best.pt`	말 전용 커스텀 학습 YOLO("horse22" 데이터셋, yolo26x, best 체크포인트)	1차 말 탐지/세그(도메인 특화)
`weights/yolo11l-seg.pt`	Ultralytics YOLO11-large 세그멘테이션(스톡, 56MB)	분할(segmentation) 보강
`weights/dinov3_vitb16_pretrain_lvd1689m-*.pth`	DINOv3 ViT-B/16(LVD-1689M 사전학습, 343MB)	공통 특징 백본(메인)
`weights/dinov3_vits16plus_pretrain_lvd1689m-*.pth`	DINOv3 ViT-S/16+(경량)	경량 특징 추출
`model/classifier_epoch_030_val0.1344.pt` + `model/config.json`	자체 학습 분류기(30 epoch, val loss 0.1344)	BestView 판정 헤드(DINOv3 임베딩 입력→뷰 점수)
`dinov3/hubconf.py`	DINOv3 repo(torch.hub 로더)	ViT 로딩 진입점

핵심: YOLO 계열(탐지·분할) + DINOv3 ViT(특징) + 경량 분류기(베스트뷰) 의 조합. 키포인트는 별도 모델 혹은 YOLO-pose/DINO 특징 기반(소스 미확보로 단정 불가).

3. 소스 구성 (커스텀 코드)

추론 패키지 /app/inference_bestview_keypoints/ (WORKDIR, ENV HORSE_DIR):

segdetdino.py — Seg + Det + DINO 통합 단계(이름 그대로 분할·탐지·DINO 특징을 묶음)
keypoints.py — 키포인트(자세) 추론
best_view.py — 베스트뷰 선별 로직(DINOv3 임베딩 + classifier)
model_server.py — 모델 로딩/인프로세스 서빙(여러 모델 상주)
run.py — 단독 실행 진입점(초기 ENTRYPOINT였음 → 이후 워커 방식으로 전환)
model/, weights/, dinov3/ — 가중치·DINOv3 repo

워커 측 /app/horse_worker/:

infer_one.py — 잡 1건 처리(입력 1개에 대해 전체 파이프라인 실행)
preflight.py — 기동 전 사전점검(모델/가중치/GPU 확인)

힌트: ENV BV_PYTHON, KP_PYTHON(둘 다 /opt/conda/bin/python) → BestView 와 Keypoints 를 별도 모델서버 프로세스로 띄울 수 있게 설계(파이썬 인터프리터를 단계별로 분리 호출). HORSE_FULL_PIPELINE=1 → 전체 파이프라인 모드 토글.

4. 실행/배포 아키텍처 — "서버"가 아니라 "워커"

기동 명령(CMD):

sh -c "python /app/horse_worker/preflight.py \
   && python -m worker_runtime.main --launch-mode cloud_docker \
        --run-id ${RUN_ID} --executor-id ${EXECUTOR_ID} --config ${RUN_CONFIG}"

worker_runtime.main 이 진짜 진입점. 잡 오케스트레이션 프레임워크의 워커로 동작.
--launch-mode cloud_docker : Vast.ai 클라우드 GPU에서 도커로 띄워지는 모드.
--run-id / --executor-id horse_bestview_keypoints / --config /app/run.yaml : 실행할 잡 식별 + 실행기 종류 + 설정.
즉 상시 HTTP 엔드포인트가 아니라, run-id로 식별되는 작업을 받아 infer_one 으로 처리하고 결과를 스토리지에 올린 뒤 종료하는 배치형 추론 워커.

동반된 프레임워크 패키지(범용 = 다른 모델에도 재사용되는 자체 플랫폼): worker_runtime(워커 본체) · orchestrator(오케스트레이션) · queues(잡 큐) · storage(입출력 아티팩트 저장) · providers(클라우드/리소스 공급자 추상화) · inferctl(추론 제어 CLI?) · local_agent(로컬 에이전트) · core · config. pip install -e /app 로 설치.

이 프레임워크가 이 워커의 가장 큰 학습 가치다 — "여러 모델 추론을 Vast 같은 임차 GPU에 잡 단위로 분산 실행하는 자체 오케스트레이션 플랫폼"의 레퍼런스 구현. 같은 골격에 executor만 바꿔 다른 추론도 돌렸을 것.

5. 기술 스택

베이스: conda + PyTorch 2.8.0, CUDA 12.8.1 (Ubuntu 22.04)
미디어 처리: ffmpeg, libgl1, libglib2.0-0, libgomp1 → 영상 입력(프레임 추출) 처리 정황
Ultralytics YOLO(YOLO_CONFIG_DIR=/tmp), matplotlib(MPLCONFIGDIR)
추론 백본: Meta DINOv3(torch.hub dinov3/hubconf.py)

6. 추정 파이프라인 흐름 (재구성)

입력(말 영상/이미지들)
  └─[ffmpeg 프레임 추출]
      └─ segdetdino.py
           ├─ horse22_yolo26x / yolo11l-seg → 말 탐지 + 분할 마스크
           └─ DINOv3 ViT-B/16 → 프레임 임베딩
      └─ keypoints.py → 말 자세 키포인트
      └─ best_view.py
           └─ classifier(epoch_030) + DINOv3 임베딩 → 프레임별 "뷰 점수" → 베스트 프레임 선정
  └─ infer_one.py 가 위를 한 잡으로 묶어 실행
  └─ worker_runtime → 결과(베스트뷰 이미지 + 마스크 + bbox + 키포인트)를 storage 로 업로드

7. 확실 vs 추정

확실: 4종 모델 파일·소스 파일 구성, 워커형(cloud_docker, run-id/executor) 실행 구조, 자체 오케스트레이션 프레임워크 존재, PyTorch2.8/CUDA12.8/ffmpeg 스택, executor_id=horse_bestview_keypoints.
추정: 각 단계 알고리즘 세부(키포인트 모델 종류, classifier 입출력 스펙, run.yaml 스키마), 최종 비즈니스 용도. → 소스 본문이 없어 단정 불가.

복구/재현 단서

원본 코드: GitHub 사용자 sanchit2843 의 비공개 repo(ghcr 패키지가 401이므로 동일 계정 소유). 자격증명 확보 시에만 재pull/재현 가능.
DINOv3(Meta), Ultralytics YOLO11 은 공개 — 백본은 재구성 가능하나, 커스텀 horse22_yolo26x·classifier_epoch_030·파이프라인 글루 코드는 원저자 자산.