# modelctl로 모델 준비하기

> 워크스테이션에서 modelctl CLI로 ML 모델을 변환·검증·양자화·패키징하여 Xisom 엣지 박스용 오프라인 ONNX 번들을 만듭니다.

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

이는 [오프라인 번들 설치](/ko/install-deploy/offline-bundle-install/)를 보완합니다.
해당 절차는 제품을 설치하고, `modelctl`은 그 이후 [배포](/ko/configure/models/)할
모델별 아티팩트를 생성합니다.

## 작업 흐름

```mermaid
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 없이
동작합니다. 해당 프레임워크에서 **변환**할 때만 추가 익스트라가 필요합니다.

  
**Core**

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

    ```bash
    pip install 'modelctl[pytorch]'
    ```
  
  
**TensorFlow**

    ```bash
    pip install 'modelctl[tensorflow]'
    ```
  
  
**Both**

    ```bash
    pip install 'modelctl[all]'
    ```
  
  
**Quantize**

    ```bash
    pip install 'modelctl[quantize]'
    ```
    `quantize`와 `package --quantize`에 필요합니다(`ml_dtypes` 설치).
  

**quantize와 tensorflow는 상호 배타적입니다**

`[quantize]` extra는 `[tensorflow]`/`[all]` extra가 허용하는 것보다 더 새로운
`ml_dtypes`가 필요합니다. 한 프로필 또는 다른 프로필을 설치하세요 —
[modelctl 모범 사례](/ko/configure/modelctl-best-practices/)를 참조하세요.

## 변환 → 검증 → 패키징

1. ### ONNX로 변환

   PyTorch 입력은 **TorchScript `.pt`**(`torch.jit.save`)로, 자체 완결형이라 변환
   박스에 모델 클래스가 필요 없습니다. TensorFlow 입력은 **SavedModel** 디렉터리입니다.

   
     
**PyTorch**

       ```bash
       modelctl convert --source model.pt --format pytorch --output model.onnx \
         --input-shape 1,3,224,224 --opset 18
       ```
     
     
**TensorFlow**

       ```bash
       modelctl convert --source saved_model/ --format tensorflow --output model.onnx
       ```
     
     
**YAML 설정**

       ```bash
       modelctl convert --config model.yaml
       ```
       CLI 플래그가 YAML보다, YAML이 기본값보다 우선합니다.
     
   

2. ### 엣지 런타임 기준으로 검증

   검증은 ONNX 스키마, **엣지 ONNX Runtime 대비 opset**, 엣지 입력 계약(단일 입력 ·
   float32 · rank), 런타임 로드, 테스트 추론을 확인합니다. 장치의 ORT 버전을 고정하면
   너무 최신인 모델을 에어갭 박스에 도달하기 **전에** 잡아낼 수 있습니다.

   ```bash
   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
   ```

3. ### 번들로 패키징

   ```bash
   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
   ```

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

   ```bash
   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을 검증하므로, 너무 최신인 익스포트는 현장이 아니라 워크스테이션에서
  실패합니다.

**윈도우 크기와 피처 수는 그대로 적용됩니다**

양자화나 재익스포트는 모델의 **윈도우 크기**와 **피처 수**를 바꾸지 않습니다.
박스에서 모델을 페어링할 때 이 값들은 입력 데이터소스와 일치해야 합니다 —
[모델 배포](/ko/configure/models/)를 참조하세요.

**재현 가능한 번들**

`package`에 `--timestamp`를 전달하면(또는 `SOURCE_DATE_EPOCH` 설정) `metadata.json`과
`checksums.sha256`이 재빌드 간에 바이트 단위로 동일해집니다 — 변경 검토와 감사에
유용합니다.

## 다음 단계

  - [modelctl 모범 사례](/ko/configure/modelctl-best-practices/) — 해야 할 것/하지 말 것: 프로필, 검증 게이트, 재현 가능한 번들, CI.
  - [모델 배포](/ko/configure/models/) — ONNX 업로드, 데이터소스 페어링, 활성화.
  - [오프라인 번들 설치](/ko/install-deploy/offline-bundle-install/) — 에어갭 박스에 제품을 설치.