Tổng quan API

Backend phơi bày hai bề mặt REST trên cổng 5000, cộng với một service gRPC và một hub SignalR:

Bề mặt	Đường dẫn gốc	Xác thực	Đối tượng
API nội bộ	`/api/…`	JWT bearer (phiên đăng nhập)	Giao diện bảng điều khiển; dùng được để scripting trên box
API bên ngoài	`/api/external/v1/…`	Header `X-AiBoard-ApiKey`	Tích hợp bên thứ ba (SCADA, historian)
gRPC Inference	cổng 50051	không (chỉ mạng nội bộ)	Backend ↔ runtime suy luận
Hub SignalR	`/hub/realtime`	JWT (`?access_token=`)	Cập nhật bảng điều khiển trực tiếp

Mọi endpoint nội bộ đều yêu cầu xác thực theo mặc định (chính sách deny-by-default); chỉ POST /api/auth/login và GET /api/system/health là ẩn danh. Có hai vai trò: admin (toàn quyền) và viewer (bảng điều khiển chỉ-đọc). Tài liệu API tương tác (Swagger UI) được phục vụ tại http://<box>:5000/.

Xác thực

POST /api/auth/login

Đổi username/password lấy một JWT (thời hạn 8 giờ). Đăng nhập thất bại bị giới hạn tốc độ theo từng IP (5 lần / 60 giây).

Authorization: Bearer <jwt>

Không có refresh token — hãy đăng nhập lại khi token hết hạn. GET /api/auth/me trả về danh tính đằng sau một token. Tài khoản admin được tạo lúc cài đặt bởi trình cài đặt bundle (seed-admin); không có thông tin đăng nhập mặc định.

Bản đồ API nội bộ

Datasource

Các datasource đầu vào (đường đọc) và đầu ra (đường ghi) được quản lý riêng dưới /api/datasources/input và /api/datasources/output — cả hai đều chỉ-admin. Mỗi loại hỗ trợ cùng vòng đời:

Verb + đường dẫn (tương đối)	Mục đích
`GET /` · `GET /{id}`	Liệt kê / chi tiết (các trường secret được che thành `***`)
`POST /` · `PUT /{id}` · `DELETE /{id}`	Tạo / cập nhật / xóa
`GET /plugins` · `GET /plugins/{type}/schema`	Các plugin giao thức khả dụng + schema biểu mẫu cấu hình của chúng
`POST /test-connection` · `POST /{id}/test-connection`	Dò khả năng kết nối
`POST /{id}/tags` · `POST /{id}/browse-tags`	Thay thế ánh xạ tag / hỏi thiết bị danh sách tag của nó

Datasource giờ thuần là quản lý kết nối: có những gì và kết nối tới ra sao. Mô hình nào chạy trên đầu vào nào, và pipeline nào đang sống, thuộc về luồng — xem bảng bên dưới. Datasource đầu ra còn hỗ trợ POST /{id}/test-write — xem Datasource đầu ra.

Luồng

Đường dẫn gốc /api/flows. Một luồng gắn một datasource đầu vào, một phiên bản mô hình và bao nhiêu datasource đầu ra tuỳ ý. Luồng chính là phép ghép cặp, và bật luồng là hành động nạp sẵn pipeline.

Động từ + đường dẫn (tương đối)	Mục đích
`GET /` · `GET /{id}`	Danh sách / chi tiết
`POST /` · `PUT /{id}` · `DELETE /{id}`	Tạo / sửa / xoá
`POST /{id}/enable`	Đưa luồng này về Ready (thân `{ "enabled": true \| false }`)

Tại một thời điểm chỉ một luồng được bật; bật luồng mới sẽ tắt luồng cũ. Sửa một luồng đang bật trả về 409 disable_flow_first — một pipeline đang chạy không bị đổi hướng ngay dưới chân nó.

Bật chỉ đưa luồng về Ready, không bắt đầu streaming. Việc bắt đầu vẫn là POST /api/inference/start, nên “luồng nào được chọn” và “có đang streaming không” là hai sự thật tách biệt.

Mô hình

GET /api/models

Liệt kê mọi phiên bản mô hình (bất kỳ người dùng đã xác thực nào).

POST /api/models/upload

Upload một file .onnx (admin). Được xác thực qua runtime suy luận; các phiên bản là bất biến.

POST /api/models/{modelId}/activate/{version}

Kích hoạt một phiên bản (admin).

POST /api/models/{modelId}/rollback

Kích hoạt lại phiên bản hợp lệ trước đó (admin).

Ngoài ra: GET /{modelId}/active, GET /{modelId}/history, DELETE /{modelId}/{version}, và DELETE /{modelId}/cleanup (cắt tỉa các phiên bản cũ, số lượng giữ lại có thể cấu hình).

Vòng đời suy luận & khả năng quan sát

GET /api/inference/status

Trạng thái hiện tại: idle / ready / running, datasource đang hoạt động, mô hình đã nạp.

POST /api/inference/start

Bắt đầu streaming (admin). 409 nếu datasource chưa Ready.

POST /api/inference/stop

Dừng streaming một cách nhẹ nhàng — các dự đoán đã đệm được xả tới sink đầu ra trước (admin).

GET /api/inference/stats

Tổng hợp độ trễ cấp dữ liệu cho trang Inference Stats.

GET /api/inference/backpressure

Bộ đếm đường nóng: số bỏ, chặn sink, độ sâu kênh. Đơn điệu kể từ khi khởi động.

Ngoài ra: GET /api/inference/predictions/recent, GET /api/inference/payloads/{requestId}, và các ngưỡng cảnh báo độ trễ theo từng mô hình dưới /api/inference/thresholds (PUT/DELETE admin).

Hệ thống, log và tùy chọn

Endpoint	Mục đích
`GET /api/system/health` (ẩn danh)	Liveness — dùng bởi healthcheck của Docker
`GET /api/system/status` · `GET /api/system/metrics`	Trạng thái runtime; số liệu CPU/GPU/bộ nhớ
`GET /api/logs`	Log tập trung phân trang (backend + suy luận)
`GET/PUT /api/dashboard/layout`	Bố cục bảng điều khiển theo từng người dùng
`GET/PUT/DELETE /api/me/preferences`	Blob tùy chọn theo từng người dùng

Admin: nhập/xuất cấu hình

GET /api/admin/inference-config/export

Xuất toàn bộ pipeline — datasource, ánh xạ tag và flow — thành một phong bì JSON có phiên bản (secret được che).

POST /api/admin/inference-config/import

Nhập một phong bì theo giao dịch — bất kỳ mục nào lỗi cũng roll back toàn bộ file. Chế độ: merge (mặc định) hoặc replace.

API bên ngoài

Được thiết kế cho hệ thống bên thứ ba. Bị vô hiệu về mặt xác thực cho đến khi tồn tại một API key; các key được cấp trên CLI của box (issue-api-key), hiển thị một lần, và có thể thu hồi (list-api-keys, revoke-api-key). Các request bị giới hạn tốc độ (100 lần / 60 giây mỗi client).

X-AiBoard-ApiKey: ak_<your-key>

GET /api/external/v1/predictions/latest

Dự đoán mới nhất: giá trị đầu ra, độ tin cậy, phiên bản mô hình, các timestamp cửa sổ.

GET /api/external/v1/predictions/history?limit=&offset=

Các dự đoán gần đây (trong bộ nhớ, giữ ~1 giờ, limit ≤ 1000). 503 khi suy luận đang dừng.

Định dạng lỗi

Các lỗi xác thực trả về HTTP 400 với mã máy-đọc-được (ví dụ name_already_exists, shape_mismatch, model_not_paired, config_invalid:port:range). Các xung đột vòng đời trả về 409 (not_ready, version_exists). Bảng điều khiển ánh xạ các mã này thành thông báo được bản địa hóa.

Bước tiếp theo

gRPC Inference API Hợp đồng giữa backend ↔ runtime suy luận trên cổng 50051.

Sự kiện thời gian thực (SignalR) Luồng sự kiện trực tiếp cấp năng lượng cho bảng điều khiển.

Bảo mật Vai trò, giới hạn tốc độ và danh sách kiểm tra tăng cường.