Triển khai trên Jetson

Xisom Edge AI Box chạy trên NVIDIA Jetson TX2 với JetPack 4.5. Stack gồm ba dịch vụ: frontend, backend và dịch vụ suy luận Python. Phần riêng cho Jetson là image suy luận. Image này được build dựa trên các thư viện CUDA do JetPack cung cấp, với một wheel ONNX Runtime dành cho JetPack 4.5.

Profile được hỗ trợ

Profile	Thiết bị / JetPack	Base image	ONNX Runtime	Execution provider
`jetson-gpu`	TX2, JetPack 4.5 (L4T r32.5)	`l4t-base:r32.5.0`	`onnxruntime-gpu 1.10.0` (cp36 wheel)	CUDA, dự phòng CPU

TX2 không dùng TensorRT. Bản build ONNX Runtime cho JetPack 4.5 cần một TensorRT mới hơn bản mà nền tảng cung cấp, nên suy luận chạy trên CUDA.

Hai hệ quả của profile này cần biết trước khi bắt đầu:

Giới hạn ONNX opset. ONNX Runtime 1.10 hỗ trợ tối đa opset 15. Hãy xuất các mô hình cho TX2 với --opset 15. Bundle kèm sẵn một mô hình opset-15 vì lý do này.
Bộ phụ thuộc Python 3.6 bị đóng băng. JetPack 4.5 bị khóa ở Python 3.6, nên image jetson-gpu dùng một bộ phụ thuộc cũ đã ghim phiên bản.

Điều kiện tiên quyết (trên Jetson)

Bạn build image trực tiếp trên một Jetson. Cross-build image L4T dưới QEMU không ổn định và không được hỗ trợ.

docker version              # >= 20.10
docker compose version      # Cần plugin Compose v2
sudo apt-get install -y zstd openssl
df -h ~                     # giữ trống vài GB (eMMC của TX2 nhỏ)
docker info | grep -i nvidia   # phải có NVIDIA container runtime

Chọn wheel ONNX Runtime GPU cho JetPack 4.5, Python 3.6 từ Jetson Zoo. Wheel onnxruntime-gpu thông thường trên PyPI không hoạt động trên Jetson. Lỗi “missing library” khi khởi động là triệu chứng kinh điển.

Build → đóng gói → cài đặt

flowchart LR
  A["build-release-images.sh\n(build + tag 3 images)"] --> B["build-release-bundle.sh\n(docker save → dist/&lt;profile&gt;-&lt;version&gt;/)"]
  B --> C["install.sh on the target\n(load images → compose up → seed admin)"]
  A -. "build host: Jetson, internet once" .-> B
  C -. "target host: air-gapped OK" .-> C

Build các image (trên Jetson dùng để build, cần internet một lần):

ORT_WHEEL_URL="https://<jetson-zoo-wheel-for-jetpack-4.5>.whl" \
  ./scripts/build-release-images.sh <version> --profile jetson-gpu

Đóng gói bundle offline:
Terminal window
```
./scripts/build-release-bundle.sh --profile jetson-gpu --version v<version>
```
Đầu ra dist/jetson-gpu-v<version>/ chứa kho image nén kèm manifest toàn vẹn, file compose cho Tegra, mô hình seed, và các script runbook install.sh / update.sh / uninstall.sh. Bố cục được mô tả trong Cài đặt từ gói offline.
Cài đặt trên thiết bị đích (sao chép thư mục bundle qua USB/scp):
Terminal window
```
cd dist/jetson-gpu-v<version>
sudo ./install.sh                    # phát hiện Jetson và chấp nhận bundle jetson-gpu
# sudo ./install.sh --with-systemd   # tùy chọn: khởi động cùng máy
```
Trình cài đặt xác minh checksum của kho, nạp image, đặt stack đang chạy vào /opt/aiboard, sinh JWT secret và mật khẩu admin duy nhất, khởi chạy stack và chờ trạng thái khỏe mạnh. Nó in URL bảng điều khiển và mật khẩu admin một lần. Hãy lưu lại ngay.
Xác minh suy luận GPU là thật:
Terminal window
```
docker ps --format '{{.Names}}  {{.Status}}'                              # inference và backend (healthy), frontend Up
docker inspect aiboard-inference-real --format '{{.HostConfig.Runtime}}'  # kỳ vọng: nvidia
docker exec aiboard-inference-real grep -E "resolved to CPU only|STRICT_EP" /data/logs/inference.log  # kỳ vọng: không có kết quả
```
Stack chạy từ /opt/aiboard và đọc cấu hình từ /opt/aiboard/.env, nên hãy kiểm tra bằng docker ps thay vì một lệnh docker compose từ thư mục bundle. Sau đó đăng nhập bảng điều khiển và xác nhận thẻ Suy luận Python hiển thị execution provider là CUDA, không phải CPU (fallback). Console của inference chỉ in lỗi, nên các dòng về provider không có trong docker logs; cảnh báo ở trên được ghi vào /data/logs/inference.log bên trong container. Xem Chạy trên CPU khi đáng lẽ phải dùng GPU.

Hành vi riêng của Tegra

File compose của bundle mang các thiết lập mà TX2 cần:

runtime: nvidia và chạy root bên trong container suy luận — bắt buộc để truy cập thiết bị GPU trên Tegra.
Mount /sys — tải và nhiệt độ GPU đến từ Tegra sysfs (Jetson không có nvidia-smi), cấp dữ liệu cho panel GPU của bảng điều khiển.
Ghim OPENBLAS_CORETYPE — tránh lỗi illegal-instruction của OpenBLAS trên các nhân Tegra.
Số liệu N/A theo từng trường — các trường tình trạng mà Jetson không báo cáo được sẽ hiển thị N/A thay vì số 0 giả.

Dịch vụ suy luận dùng execution provider CUDA. Nếu CUDA không khởi động được, nó tụt xuống CPU, ghi một cảnh báo, và bảng điều khiển hiển thị CPU (fallback). Để hộp từ chối khởi động thay vì tụt xuống CPU, xem Chạy trên CPU khi đáng lẽ phải dùng GPU.

Đánh phiên bản trên dòng Jetson

Các bản phát hành Jetson được đánh phiên bản bằng file VERSION, không phải bằng Git tag. Panel About của bảng điều khiển hiển thị phiên bản release của bundle đã cài. Nếu nó khác với điều bạn mong đợi, hãy so sánh với images/manifest.txt của bundle. Xem Phiên bản & Cập nhật.

Nếu có gì đó sai

Triệu chứng	Cách khắc phục
`unknown shorthand flag: 'f' in -f`	Thiếu plugin Compose v2 — `sudo apt-get install -y docker-compose-plugin`
`Cannot autolaunch D-Bus` khi build	Sự cố credential-helper ở chế độ headless — script build tự cô lập nó; với lệnh `docker` tùy biến, dùng thư mục `DOCKER_CONFIG` rỗng
Container GPU: `no CUDA-capable device`	Host thiếu NVIDIA container runtime, hoặc compose thiếu `runtime: nvidia` (compose của bundle đã đặt sẵn)
Suy luận thoát với lỗi thiếu thư viện	Sai wheel ONNX Runtime — chọn wheel cho JetPack 4.5 từ Jetson Zoo rồi build lại
`install.sh`: “does not match this bundle”	Máy này không phải Jetson. Sao chép bundle `jetson-gpu` sang TX2 và cài đặt ở đó
Mô hình không qua kiểm tra khi upload	Mô hình xuất với opset > 15 — xuất lại với `--opset 15` cho ONNX Runtime 1.10

Bước tiếp theo

Cài đặt từ gói offline Runbook cài đặt và cập nhật air-gapped đầy đủ.

Thiết lập phần cứng Các chế độ execution provider và điều kiện tiên quyết về mạng.

Chuẩn bị mô hình với modelctl Xuất mô hình ONNX với opset đúng cho TX2.

Lỗi GPU / CUDA Khắc phục khả năng nhìn thấy GPU và lỗi CUDA.