고밀도 예측과 비전 태스크¶
mlxcel predict는 깊이, 노멀, 세그멘테이션, 포인트 맵, 키포인트, 인스턴스별 마스크, 메시, 가우시안 스플랫을 반환하는 체크포인트를 위한 오프라인 파일 인터페이스입니다. 이런 출력은 generate의 토큰 스트림이나 detect의 박스 행에 맞지 않는 형태와 수명을 가지므로, 전용 서브명령어와 공통 파일 계약을 사용합니다.
mlxcel predict¶
mlxcel predict --model models/dinov2-small --image input.png --output outputs/features --task features
mlxcel predict --model models/video-depth --video clip.mp4 --output outputs/depth
mlxcel predict --model models/sapiens2-pose --image person.png --output outputs/pose \
--opts '{"boxes":[[140,90,920,700]],"flip_test":true}'
| 플래그 | 기본값 | 설명 |
|---|---|---|
-m, --model <PATH> | 필수 | 고밀도 예측 체크포인트 디렉터리. |
--image <PATH> | - | 입력 이미지. --video와 함께 쓸 수 없으며, 둘 중 정확히 하나가 필요합니다. |
--video <PATH> | - | 입력 비디오. |
-o, --output <DIR> | 필수 | 출력 디렉터리. 없으면 생성합니다. |
--task <NAME> | 패밀리 기본값 | 모델 태스크. 패밀리가 둘 이상을 지원할 때 필요합니다. |
--prompt <TEXT> | - | 텍스트 프롬프트. 반복 지정할 수 있습니다. 프롬프트를 지원하지 않는 패밀리는 이를 거부합니다. |
--boxes <X1,Y1,X2,Y2[;...]> | - | 픽셀 단위 xyxy 박스. 반복 지정할 수 있으며, 세미콜론으로 구분해 여러 박스를 한 플래그에 넣을 수 있습니다. |
--mask <PATH> | - | SAM 3D Objects용 객체 마스크. 생략하면 RGBA 알파를 사용합니다. |
--pointmap <PATH> | - | SAM 3D Objects용 HWC XYZ points 텐서를 담은 safetensors 파일. |
--max-frames <N> | 32 | 샘플링할 최대 비디오 프레임 수. |
--target-fps <FPS> | - | 연속 접두 구간 대신 시간 기준 균일 비디오 샘플링. |
--opts <JSON> | - | 모델별 옵션을 JSON 객체로 지정. |
이 명령은 예측기를 호출하기 전에 선택한 태스크를 task에, 프롬프트 문자열을 prompts에, 파싱한 숫자 박스를 boxes에 넣으므로 모델은 하나의 맵에서 모든 옵션을 읽습니다. 받지 않는 패밀리에 프롬프트나 박스를 주면 오류입니다.
--target-fps를 지정하지 않으면 Video Depth Anything과 SAM 3 / 3.1 track은 클립 시작부터 최대 --max-frames개의 연속 프레임을 유지하고, 다른 모든 계열은 2fps로 균일 샘플링하되 --max-frames를 상한으로 둡니다. --target-fps를 지정하면 앞의 두 경우도 시간 기준 균일 샘플링으로 바뀝니다. 디코딩한 RGBA의 최악 크기가 512 MiB를 넘을 샘플 집합은 ffmpeg가 디코딩하기 전에 거부됩니다. 표준 이름을 가진 기존 파일은 교체되고, 출력 디렉터리의 무관한 파일은 그대로 둡니다.
패밀리¶
| 패밀리 | 감지 | 태스크 | 주요 출력 파일 |
|---|---|---|---|
| DINOv2 | dinov2, dinov2_with_registers | features | result.safetensors, meta.json |
| Sapiens2 | sapiens2 | pose, seg, normal, pointmap, matting, backbone | keypoints.json, segmentation.png, normal.png |
| SAM 3 | sam3, sam3_video | detect, segment, track | instances.json, masks/000.png, masks/f000012_o003.png |
| SAM 3.1 | sam3.1, sam3.1_video | detect, segment, track | SAM 3와 동일 |
| Video Depth Anything | video_depth_anything | depth | depth.png, depth/000000.png, ... |
| MoGe3 | moge3 | geometry | depth.png, normal.png, mask.png |
| SAM 3D Objects | sam3d_objects | mesh | mesh.obj 또는 gaussian.ply |
| SAM 3D Body | sam3d_body | body_mesh | vertices, keypoints_3d, joint_coords, camera가 포함된 mesh.obj |
PP-DocLayoutV3와 RF-DETR Base, Seg Small은 박스를 반환하므로 predict가 아니라 detect에서 실행합니다. 세그멘테이션 체크포인트는 --masks-dir <DIR>를 추가하며, 이 옵션은 검출마다 원본 해상도의 8비트 마스크 PNG를 출력된 순서대로 하나씩 기록합니다. PP-DocLayoutV3는 박스를 읽기 순서로 내보내며, Falcon-OCR용 mlxcel generate --layout-detections가 이 순서를 그대로 사용합니다.
출력 계약¶
성공한 모든 실행은 다음을 기록합니다:
| 경로 | 내용 |
|---|---|
result.safetensors | masks는 u8로 유지하고 모든 출력 텐서는 연속 f32로 변환합니다. 인스턴스에는 boxes (N, 4)와 scores (N,)가 포함되며, masks는 원본 해상도의 (M, H, W)입니다. 비디오 맵은 축 0으로 쌓입니다. |
meta.json | 패밀리, 태스크, 소스 크기, MLX 평가 후 추론 시간, 모든 텐서의 유한 최솟값과 최댓값, 모델 메타데이터, 존재하는 경우 평탄화한 내부 파라미터. |
keypoints.json | 사람이 검출되었을 때 존재합니다. 각 항목에는 bbox, 원본 픽셀 단위의 (x, y, score) 포인트, 선택적 포인트 이름이 들어 있습니다. |
instances.json | 원본 픽셀 단위 bbox, label, mask_index, 선택적 비디오 object_id와 frame, 상대 경로 mask PNG 경로를 가진 점수 매긴 인스턴스입니다. 인스턴스가 없는 출력에서는 비어 있습니다. |
masks/000.png | 이미지 인스턴스 마스크. 8비트 단일 채널이며 값은 0과 255입니다. 번호는 masks 텐서의 행입니다. |
masks/f000012_o003.png | 프레임 12와 안정 객체 3에 대한 비디오 마스크. |
depth.png | 16비트 그레이스케일. 유한 최솟값과 최댓값이 0과 65535가 되고, NaN과 무한대는 0이 됩니다. |
normal.png | (normal + 1) / 2에서 만든 8비트 RGB이며 [0, 1]로 클램프합니다. |
mask.png | 8비트 그레이스케일. 0.5 이하에서는 0, 그보다 크면 255입니다. |
segmentation.png | 8비트 클래스 ID. |
Sapiens2는 고정된 1024x768 입력(높이 x 너비)을 사용합니다. 세그멘테이션과 매팅은 이 캔버스에 맞게 늘리고, 노멀과 포인트맵 추정은 대칭 패딩으로 종횡비를 유지한 뒤 원본 해상도로 되돌리기 전에 패딩을 제거합니다. 로더는 0.4B, 0.8B, 1B, 5B 아키텍처에 대해 이전의 중첩 backbone 스키마와 현재의 평탄한 Transformers 스키마를 모두 받습니다. 포즈는 최대 16개의 박스를 받아 최대 메모리를 제한하기 위해 하나씩 처리합니다. 사람 검출기를 실행하지 않으므로, 전체 이미지에 실행하려면 boxes를 생략하십시오.
Video Depth Anything은 원본 종횡비를 유지하고, 하한을 14픽셀 배수로 518에 맞추며, 업스트림의 32프레임 윈도, 10프레임 겹침, 키프레임 조건화, 8프레임 선형 블렌드를 사용합니다. 메트릭 체크포인트는 절대 스케일을 유지하고 units: "metres"를 보고하며, 상대 체크포인트는 units: "relative_disparity"를 보고합니다.
MoGe3는 이미지 하나에서 카메라 공간 포인트 맵, 깊이, 유효성 마스크, 표면 노멀, 정규화된 카메라 내부 파라미터를 추정합니다. --opts 필드는 resolution_level(0~9), num_tokens, refine_steps(0~16, 기본값 3), force_projection, apply_mask, fov_x, return_per_step입니다.