modelctl로 모델 준비하기

Xisom 런타임은 ONNX 형식의 모델을 실행합니다. modelctl은 박스가 아니라 개발자 워크스테이션에서 실행하는 명령줄 도구로, 학습된 PyTorch 또는 TensorFlow 모델을 검증되고 선택적으로 양자화된, 체크섬이 포함된 ONNX 번들로 변환하여 에어갭(air-gapped) 엣지 장치로 옮길 수 있게 합니다.

이는 오프라인 번들 설치를 보완합니다. 해당 절차는 제품을 설치하고, modelctl은 그 이후 배포할 모델별 아티팩트를 생성합니다.

작업 흐름

flowchart LR
  subgraph WS["개발자 워크스테이션 — modelctl"]
    direction LR
    SRC["학습된 모델<br/>PyTorch .pt / TF SavedModel"] --> CV["convert<br/>→ ONNX"]
    CV --> VL["validate<br/>스키마 · opset · 런타임 · 추론"]
    VL --> QZ["quantize<br/>동적 INT8 (선택)"]
    QZ --> PK["package<br/>체크섬 번들"]
  end
  PK -->|"번들 복사 (USB / 오프라인)"| BOX["엣지 박스<br/>업로드 + 활성화"]

설치

modelctl은 **Python 3.11+**가 필요합니다. 무거운 ML 프레임워크는 선택 사항입니다. 코어 설치만으로 validate, quantize, package가 PyTorch나 TensorFlow 없이 동작합니다. 해당 프레임워크에서 변환할 때만 추가 익스트라가 필요합니다.

pip install modelctl

아래 익스트라를 추가하기 전까지는 PyTorch/TensorFlow 변환을 사용할 수 없습니다.

pip install 'modelctl[pytorch]'

pip install 'modelctl[tensorflow]'

pip install 'modelctl[all]'

pip install 'modelctl[quantize]'

quantize와 package --quantize에 필요합니다(ml_dtypes 설치).

변환 → 검증 → 패키징

ONNX로 변환
섹션 제목: “ONNX로 변환”

PyTorch 입력은 TorchScript .pt(torch.jit.save)로, 자체 완결형이라 변환 박스에 모델 클래스가 필요 없습니다. TensorFlow 입력은 SavedModel 디렉터리입니다.
Terminal window
modelctl convert --source model.pt --format pytorch --output model.onnx \ --input-shape 1,3,224,224 --opset 18
Terminal window
modelctl convert --source saved_model/ --format tensorflow --output model.onnx
Terminal window
modelctl convert --config model.yaml
CLI 플래그가 YAML보다, YAML이 기본값보다 우선합니다.
엣지 런타임 기준으로 검증
섹션 제목: “엣지 런타임 기준으로 검증”

검증은 ONNX 스키마, 엣지 ONNX Runtime 대비 opset, 엣지 입력 계약(단일 입력 · float32 · rank), 런타임 로드, 테스트 추론을 확인합니다. 장치의 ORT 버전을 고정하면 너무 최신인 모델을 에어갭 박스에 도달하기 전에 잡아낼 수 있습니다.
Terminal window
```
modelctl validate --model model.onnx --target-ort 1.18
# ✓ ONNX schema valid
# ✓ Opset supported
# ✓ Single input tensor
# ✓ Input dtype float32
# ✓ Input rank
# ✓ ONNX Runtime load successful
# ✓ Test inference successful
```

번들로 패키징

modelctl package --model model.onnx --name pump-anomaly-v1

다음과 같은 이식 가능한 디렉터리가 생성됩니다:

pump-anomaly-v1/
├── model.onnx
├── metadata.json        # 이름, 버전, 프레임워크, opset, 양자화 여부
├── input_schema.json    # 입력 텐서 이름 / 형태 / dtype
├── checksums.sha256     # 모델 + 메타데이터 + 스키마의 SHA256
└── README.md

디렉터리를 박스로 복사한 다음, 장치에서 무결성을 확인하세요:

cd pump-anomaly-v1 && sha256sum -c checksums.sha256

엣지 성능 튜닝

modelctl에는 모델이 박스에서 실행되는 방식에 영향을 주는 두 가지 레버가 있습니다:

동적 INT8 양자화 — modelctl quantize --model model.onnx --output model.int8.onnx (또는 convert/package의 --quantize)는 더 작은 모델을 생성하며 보통 로드와 실행이 더 빠르지만 정확도가 다소 떨어집니다. [quantize] extra가 필요합니다. 양자화된 모델을 검증하고 배포 전에 예측 품질을 확인하세요.
Opset 타게팅 — --target-ort는 장치의 정확한 ONNX Runtime 기준으로 모델의 opset을 검증하므로, 너무 최신인 익스포트는 현장이 아니라 워크스테이션에서 실패합니다.

다음 단계

modelctl 모범 사례 해야 할 것/하지 말 것: 프로필, 검증 게이트, 재현 가능한 번들, CI.

모델 배포 ONNX 업로드, 데이터소스 페어링, 활성화.

오프라인 번들 설치 에어갭 박스에 제품을 설치.