gRPC Inference API

Backend và runtime suy luận Python giao tiếp qua gRPC trên cổng 50051 (protos/inference.proto, service InferenceService). Operator hiếm khi gọi API này trực tiếp — backend là client — nhưng hợp đồng này quan trọng khi bạn gỡ lỗi pipeline, tích hợp một client tùy biến trên box, hoặc đọc log suy luận.

Các phương thức của service

RPC	Kiểu	Mục đích
`StreamInference`	stream hai chiều	Cửa sổ cảm biến vào, dự đoán ra — đường nóng thời gian thực
`LoadModel`	unary	Xác thực + đăng ký + hot-swap một mô hình ONNX (không thời gian chết)
`ValidateModel`	unary	Kiểm tra không thay đổi: shape + SHA-256, không nạp gì
`HealthCheck`	unary	Trạng thái service + số liệu CPU/GPU/bộ nhớ
`StreamLogs`	server stream	Đọc đuôi log suy luận, lọc theo mức tối thiểu

StreamInference

Mỗi InferenceRequest mang request_id, một timestamp (Unix epoch ms, được backend đóng dấu một lần tại thời điểm lấy mẫu cảm biến và trả về nguyên vẹn — nên không có vấn đề đồng bộ đồng hồ), một mảng features phẳng, và một map metadata.

Mỗi InferenceResponse trả về predictions và confidence_scores, model_id/model_version đang phục vụ, inference_time_ms, và ba timestamp:

Trường	Ý nghĩa
`window_start_timestamp`	Mẫu đầu vào cũ nhất trong cửa sổ của dự đoán
`window_end_timestamp`	Mẫu đầu vào mới nhất — thời điểm “tính đến” của dự đoán
`emitted_at`	Thời gian đồng hồ lúc phát; `emitted_at − window_end_timestamp` xấp xỉ độ trễ end-to-end

Trong lúc mô hình khởi động ấm (cửa sổ trượt chưa đầy), các response mang metadata["warming_up"] = "true"; backend chặn những response này khỏi bảng điều khiển.

LoadModel

Đăng ký một phiên bản mô hình và hot-swap nó vào session đang chạy bằng double-buffering — session mới được nạp và làm ấm bên ngoài lock, rồi tham chiếu được hoán đổi nguyên tử, nên streaming không bao giờ dừng.

Idempotent theo content hash: gửi lại cùng (model_id, version) với cùng SHA-256 là một no-op thành công. Cùng phiên bản với SHA-256 khác sẽ bị từ chối là version_conflict — các phiên bản là bất biến.
Response trả về input_shape, output_shape, registered_path, và sha256 đã tính.
Nếu (window_size, n_features) của mô hình mới khác mô hình trước, pipeline cửa sổ được dựng lại và khởi động ấm bắt đầu lại.

ValidateModel

Kiểm tra thuần túy được backend dùng trong lúc upload mô hình: mở một session runtime dùng-một-lần, trích xuất shape đầu vào/đầu ra và SHA-256, và trả về {valid, message, input_shape, output_shape, sha256} mà không đăng ký gì.

Việc xác thực áp đặt hợp đồng mô hình:

File ONNX ≤ 500 MB, nạp được, và vượt qua ONNX checker
Opset 13–18
Tensor đầu vào input có shape (batch, window_size, n_features) — bắt buộc 3 chiều; chiều batch có thể động
Tensor đầu ra output có shape (batch, 3) = [health_score, failure_probability, rul_normalized]

HealthCheck và StreamLogs

HealthCheck cấp dữ liệu cho panel tình trạng của bảng điều khiển (tải GPU, bộ nhớ, uptime). StreamLogs chuyển tiếp luồng log của service Python tới backend, backend lưu nó cho LogViewer — lọc bằng min_level.

Cấu hình runtime

Các biến môi trường mà container suy luận tuân theo (đặt trong file compose):

Biến	Mặc định	Tác dụng
`EXECUTION_MODE`	`auto`	Execution provider: `auto` (TensorRT → CUDA → CPU), `tensorrt`, `cuda`, `cpu`
`STRICT_EP`	tắt	`1` = từ chối khởi động thay vì âm thầm tụt một chế độ GPU đã ghim xuống CPU
`MODEL_PATH`	`/app/models/predictive_maintenance.onnx`	Mô hình seed nạp lúc khởi động
`MODEL_STORAGE_PATH`	`/data/models`	Nơi lưu các phiên bản mô hình đã đăng ký
`LOG_DIR`	không đặt	Bật file log xoay vòng trên đĩa (`inference.log`); không đặt = chỉ console
`FORCE_CPU`	tắt	Bí danh legacy cho `EXECUTION_MODE=cpu`

Bước tiếp theo

Tổng quan API Bề mặt REST API của backend.

Triển khai mô hình Upload, ghép cặp và kích hoạt các phiên bản mô hình từ UI.

Chuẩn bị mô hình với modelctl Soạn các bundle vượt qua xác thực ngay lần đầu.

Bảo mật Tư thế mạng và danh sách kiểm tra tăng cường.