# gRPC Inference API

> Hợp đồng gRPC giữa backend và runtime suy luận — suy luận streaming, nạp mô hình, xác thực, tình trạng và streaming log.

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.

Kênh này là **plaintext HTTP/2 (không TLS, không xác thực)** một cách có chủ đích:
nó được dự định ở lại trên mạng Docker nội bộ của box. Không bao giờ công bố cổng
50051 ra ngoài host hoặc một mạng quản lý tin cậy — xem [Bảo mật](/vi/security/).

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

`EXECUTION_MODE=auto` dò các thư viện native của TensorRT trước khi tin danh sách
provider của runtime, và ghi một cảnh báo lớn khi một chế độ GPU tụt xuống CPU. Hãy
để ý nó sau khi cập nhật driver hoặc JetPack — xem
[Execution provider tụt xuống CPU](/vi/troubleshooting/execution-provider-fallback/).

## Bước tiếp theo

  - [Tổng quan API](/vi/api-reference/overview/) — Bề mặt REST API của backend.
  - [Triển khai mô hình](/vi/configure/models/) — 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](/vi/configure/prepare-models/) — Soạn các bundle vượt qua xác thực ngay lần đầu.
  - [Bảo mật](/vi/security/) — Tư thế mạng và danh sách kiểm tra tăng cường.