# Chuẩn bị mô hình với modelctl

> Dùng CLI modelctl trên máy trạm để chuyển đổi, xác thực, lượng tử hóa và đóng gói mô hình ML thành một bundle ONNX ngoại tuyến cho Xisom edge box.

Runtime Xisom thực thi mô hình ở định dạng **ONNX**. `modelctl` là một công cụ
dòng lệnh bạn chạy **trên máy trạm của lập trình viên** — không phải trên box — để
biến một mô hình PyTorch hoặc TensorFlow đã huấn luyện thành một bundle ONNX đã được
xác thực, tùy chọn lượng tử hóa, kèm checksum, để mang lên thiết bị biên air-gapped.

Nó bổ sung cho [cài đặt bundle ngoại tuyến](/vi/install-deploy/offline-bundle-install/):
quy trình đó cài đặt sản phẩm; còn `modelctl` tạo ra các artifact theo từng mô hình
mà bạn [triển khai](/vi/configure/models/) sau đó.

## Quy trình làm việc

```mermaid
flowchart LR
  subgraph WS["Máy trạm lập trình viên — modelctl"]
    direction LR
    SRC["Mô hình đã huấn luyện<br/>PyTorch .pt / TF SavedModel"] --> CV["convert<br/>→ ONNX"]
    CV --> VL["validate<br/>schema · opset · runtime · suy luận"]
    VL --> QZ["quantize<br/>INT8 động (tùy chọn)"]
    QZ --> PK["package<br/>bundle kèm checksum"]
  end
  PK -->|"sao chép bundle (USB / ngoại tuyến)"| BOX["Edge box<br/>tải lên + kích hoạt"]
```

## Cài đặt

`modelctl` yêu cầu **Python 3.11+**. Các framework ML nặng là tùy chọn — bản cài đặt
lõi chạy `validate`, `quantize` và `package` mà không cần PyTorch hay TensorFlow. Bạn
chỉ cần các extra để **chuyển đổi** từ những framework đó.

  
**Core**

    ```bash
    pip install modelctl
    ```
    Chuyển đổi từ PyTorch/TensorFlow chưa khả dụng cho đến khi bạn thêm một extra bên dưới.
  
  
**PyTorch**

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

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

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

    ```bash
    pip install 'modelctl[quantize]'
    ```
    Cần cho `quantize` và `package --quantize` (kéo `ml_dtypes`).
  

**quantize và tensorflow loại trừ lẫn nhau**

Extra `[quantize]` cần `ml_dtypes` mới hơn mức mà extra `[tensorflow]`/`[all]` cho
phép. Hãy cài một hồ sơ hoặc hồ sơ kia — xem
[Thực hành tốt nhất với modelctl](/vi/configure/modelctl-best-practices/).

## Chuyển đổi → xác thực → đóng gói

1. ### Chuyển đổi sang ONNX

   Đầu vào PyTorch là một **TorchScript `.pt`** (`torch.jit.save`) — tự chứa, nên máy
   chuyển đổi không cần lớp mô hình. Đầu vào TensorFlow là một thư mục **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
       ```
     
     
**Cấu hình YAML**

       ```bash
       modelctl convert --config model.yaml
       ```
       Cờ CLI ghi đè YAML, YAML ghi đè giá trị mặc định.
     
   

2. ### Xác thực theo runtime biên

   Xác thực kiểm tra schema ONNX, **opset so với ONNX Runtime biên**, hợp đồng input
   của biên (một input · float32 · rank), tải runtime, và một suy luận thử. Ghim
   phiên bản ORT của thiết bị để một mô hình quá mới bị bắt **trước khi** đến được
   box air-gapped.

   ```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. ### Đóng gói thành bundle

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

   Lệnh này tạo ra một thư mục di động:

   ```
   pump-anomaly-v1/
   ├── model.onnx
   ├── metadata.json        # tên, phiên bản, framework, opset, cờ lượng tử hóa
   ├── input_schema.json    # tên / shape / dtype của tensor đầu vào
   ├── checksums.sha256     # SHA256 của model + metadata + schema
   └── README.md
   ```

   Sao chép thư mục sang box, rồi kiểm tra tính toàn vẹn trên thiết bị:

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

## Tinh chỉnh cho hiệu năng biên

`modelctl` có hai đòn bẩy ảnh hưởng đến cách mô hình chạy trên box:

- **Lượng tử hóa INT8 động** — `modelctl quantize --model model.onnx --output model.int8.onnx`
  (hoặc `--quantize` trên `convert`/`package`) tạo ra mô hình nhỏ hơn, thường tải và
  chạy nhanh hơn, đánh đổi một phần độ chính xác. Cần extra `[quantize]`. **Xác thực
  mô hình đã lượng tử hóa** và xác nhận chất lượng dự đoán trước khi đưa vào sử dụng.
- **Nhắm opset** — `--target-ort` xác thực opset của mô hình theo đúng ONNX Runtime
  trên thiết bị, nên một bản export quá mới sẽ thất bại trên máy trạm thay vì ngoài
  hiện trường.

**Kích thước cửa sổ và số đặc trưng vẫn áp dụng**

Lượng tử hóa hay export lại không thay đổi **kích thước cửa sổ** và **số đặc trưng**
của mô hình. Chúng phải khớp với nguồn dữ liệu đầu vào khi bạn ghép cặp mô hình trên
box — xem [Triển khai mô hình](/vi/configure/models/).

**Bundle tái lập được**

Truyền `--timestamp` (hoặc đặt `SOURCE_DATE_EPOCH`) cho `package` để `metadata.json`
và `checksums.sha256` giống hệt theo từng byte qua các lần build lại — hữu ích cho
việc soát xét thay đổi và kiểm toán.

## Bước tiếp theo

  - [Thực hành tốt nhất với modelctl](/vi/configure/modelctl-best-practices/) — Nên/không nên: hồ sơ, cổng validate, bundle tái lập, CI.
  - [Triển khai mô hình](/vi/configure/models/) — Tải lên ONNX, ghép cặp với datasource, kích hoạt.
  - [Cài đặt bundle ngoại tuyến](/vi/install-deploy/offline-bundle-install/) — Đưa sản phẩm lên một box air-gapped.