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

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: 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 sau đó.

Quy trình làm việc

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

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

pip install 'modelctl[pytorch]'

TensorFlow

pip install 'modelctl[tensorflow]'

Both

pip install 'modelctl[all]'

Quantize

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.

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

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

   TensorFlow

   modelctl convert --source saved_model/ --format tensorflow --output model.onnx

   Cấu hình YAML

   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.

   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

   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ị:

   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.

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 Nên/không nên: hồ sơ, cổng validate, bundle tái lập, CI.

Triển khai mô hình Tải lên ONNX, ghép cặp với datasource, kích hoạt.

Cài đặt bundle ngoại tuyến Đưa sản phẩm lên một box air-gapped.