Thực hành tốt nhất với modelctl

Hướng dẫn mang tính chỉ dẫn để đưa một mô hình từ máy trạm lên thiết bị biên air-gapped một cách đáng tin cậy. Về các lệnh từng bước, xem Chuẩn bị mô hình với modelctl — trang này nói về vì sao và nên/không nên trên nền quy trình đó.

Chọn hồ sơ cài đặt nhỏ nhất

modelctl giữ các framework ML nặng ở dạng tùy chọn. Bản cài lõi chạy validate và package mà không cần PyTorch hay TensorFlow — nên người vận hành có thể xác minh một bundle trên máy gọn nhẹ. Chỉ thêm extra mà tác vụ cần.

Validate / package

pip install modelctl            # chỉ onnx + onnxruntime + numpy

Convert

pip install 'modelctl[pytorch]'      # hoặc [tensorflow] / [all]

Quantize

pip install 'modelctl[quantize]'     # kéo ml_dtypes cho INT8

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 (TensorFlow giới hạn ml-dtypes<0.4). Hãy cài một hồ sơ hoặc hồ sơ kia — convert với TensorFlow ở một môi trường, quantize ở môi trường khác.

Bàn giao một nguồn tự chứa

Đưa cho máy convert một mô hình mà nó nạp được mà không cần mã huấn luyện của bạn:

• PyTorch → TorchScript .pt (torch.jit.save). Một state_dict trần bị từ chối (thiếu kiến trúc); một nn.Module pickle chỉ là phương án dự phòng tốt nhất có thể.
• TensorFlow → thư mục SavedModel (đường được hỗ trợ tốt; .keras/.h5 cũng chạy).

Vì sao: máy trạm chạy convert khi đó không cần định nghĩa lớp mô hình — bản export tái lập được chỉ từ artifact.

Luôn ghim --target-ort theo thiết bị

Opset được kiểm tra theo ONNX Runtime của biên, không phải của máy trạm. Ghim phiên bản của thiết bị để một bản export quá mới fail ngay trên bàn bạn, chứ không phải ngoài hiện trường:

modelctl validate --model model.onnx --target-ort 1.18

Một mô hình export ở opset mà runtime của thiết bị không chạy được chính là cái bẫy “chạy ở đây, fail ở kia” phổ biến nhất. Ghim đóng cái bẫy đó trước khi bundle rời đi.

Coi validate là cổng phát hành

Validate là fail-soft — nó chạy mọi kiểm tra và báo từng cái, thay vì dừng ở lỗi đầu tiên. Chặn việc ship nếu exit khác 0. Toàn bộ:

Kiểm tra	Khẳng định điều gì
ONNX schema valid	onnx.checker chấp nhận graph
Opset supported	opset ≤ mức tối đa của edge ORT
Single input tensor	engine feed đúng một input, theo vị trí
Input dtype float32	engine feed float32
Input rank	khớp shape đã khai (khi có)
ONNX Runtime load	runtime khởi tạo được session
Test inference	một forward pass điền-zero thành công

Ánh xạ exit code trong công cụ của bạn:

Exit	Ý nghĩa
0	mọi kiểm tra pass
1	một kiểm tra validation fail
3	framework converter (torch/TF) chưa được cài
5	validation sau convert fail
7	quantization fail (ví dụ thiếu ml_dtypes)

Lượng tử hóa có chủ đích, rồi validate lại

Dynamic INT8 (modelctl quantize, hoặc --quantize trên convert/package) đánh đổi độ chính xác lấy kích thước và tốc độ. Hai quy tắc:

1. Validate lại mô hình đã lượng tử hóa và xác nhận chất lượng dự đoán trên dữ liệu đại diện trước khi ship — lượng tử hóa có thể làm lệch output.
2. Đừng cho rằng nó co lại. Với mô hình rất nhỏ, các node scale/zero-point của INT8 có thể lớn hơn phần tiết kiệm; lợi ích thể hiện ở mô hình cỡ thật.

Quantize cần extra

quantize / package --quantize cần pip install 'modelctl[quantize]'. Thiếu nó, bạn nhận exit 7 rõ ràng nêu tên module thiếu — cài vào và chạy lại.

Ship bundle tái lập được, kiểm chứng được

Ghim timestamp để các lần build lại byte-identical — thiết yếu cho audit và rà soát thay đổi khi đưa lên hộp air-gapped:

modelctl package --model model.onnx --name pump-anomaly-v1 --timestamp 1700000000
# hoặc: export SOURCE_DATE_EPOCH=1700000000

Rồi kiểm tra toàn vẹn trên thiết bị trước khi kích hoạt:

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

checksums.sha256 phủ model.onnx, metadata.json, và input_schema.json — một thao tác giả mạo hay sao chép thiếu bị bắt ngay tại biên, không phải lúc inference.

Tôn trọng hợp đồng input của biên

Runtime feed một tensor float32, theo vị trí. Một mô hình nhiều input hoặc input khác float32 nạp được nhưng chết lúc inference trên hộp. validate bắt việc này trên máy trạm — hãy thiết kế mô hình export về một input float32 duy nhất, và giữ window size cùng số lượng đặc trưng khớp với datasource bạn ghép nó (xem Triển khai mô hình).

Đưa validate vào CI

Chạy validate trên mỗi lần build mô hình và chặn artifact theo exit 0. Kiểm tra này không cần torch/TF nên job vẫn gọn:

pip install modelctl
modelctl validate --model build/model.onnx --target-ort 1.18 || exit 1

Bắt một bản export hỏng ngay trong pipeline thay vì phát hiện trên thiết bị bạn không với tới được.

Bước tiếp theo

Chuẩn bị mô hình (cách làm) Các lệnh convert → validate → quantize → package.

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

Thực hành vận hành tốt nhất Vận hành box khỏe mạnh trong production.